====== Theme Mini-HowTo ======
Well, my suggestion is always to start from an already made theme, and at this moment I would start from latest unstable version (using flatmaas theme, and changing the css); when I'll release the new package themes will be a bit changed (even though old ones should still work).
Ok, let's see how it works.
===== What is Smarty ? =====
[[http://www.smarty.net|Smarty]] is a system which translates //templates// containing special //tags// into php; most of the blogs you see around just use PHP as php itself works actually like a templating language. Using Smarty let us **abstract** more from the php programming logic, and should make easier for non-programmers to design a template.
However, there are some things people should know.
===== Structure of a theme =====
**index.tpl** is your "main" file. It must contain all of the stuff which will go in index.php
First of all create a new dir in your fp-interface/themes/ dir, and copy from flatmaas2 the theme.conf.php (or theme_conf.php depending on your version) to the new directory.
you could create a index.tpl like this
Published on {$date|date_format}
{entries}
Well, there you go, you're already done. Save and reload. You should see
your posts.
But let's see what all of this mess does.
===== Preamble tags: entries =====
First of all we have this outer smarty tag called **{entries}** (0.703+ will call it {entry_block}, "entries" it's too similar to the inner "entry", but let's go with some order...).
We could call this tag a //preamble//. We have this approach with other FP tags, which I'm not gonna show you now because they're similar in behaviour but really it's because I have no time (the suggestion is looking at the other themes, once you've finished with this reaaaaally quick tutorial).
What is a preamble? well, from the point of view of the designer a preamble has really little meaning, actually :P
> **A preamble marks an area on your page where you want an auto-generated content to appear.**
In this case we're telling flatpress that there we want to put a group of entries. In {entries} we can put a container {$subject}
There are many predefined variables you can use, and most of them come from Smarty itself; you can read more about them on the [[http://www.smarty.net|manual]]. Some are generate by flatpress, and are globally available like the special {$flatpress} array, of which the fields contains config informations.
Some tags are **not** globally available and can be reached only from within an iterator tag; these variables are proper of the iterator itself.
For instance {entry} generates {$subject}, {$date}, {$content}, and some others; you can see all of them opening a complete theme; we're not going to explain them all here.
* **$subject** contains, guess it, the title of your post
* **$content** is the html-formatted post (this will change a bit with the next version, we will use a lot of modifiers, read below and the ML for more info)
* **$date** contains a UNIX timestamp
a UNIX timestamp is an integer which counts time in seconds, starting from
January, 1st 1970 +000;
We can extract a readable date using the smarty "modifier" |date_format.
===== Smarty modifiers =====
A **modifier** is a function which takes as argument the var it follows and
returns a string. The PHP homologue is something like
{$var|modifier}
=>
**date_format** follows the php time format rules, and you can find more on its
syntax on the smarty manual as well.
Now you have a barebone template. Let's spicy it up a bit.
===== Other useful entry-related tags =====
You may want for instance to have next/back links :
{entries}
{entry}
{$subject}
Published on {$date|date_format}
{$content}
{/entry}
{nextpage}{prevpage}
{/entries}
Here they are, before the {/entries} closing tag and after the iterator
block. There are technical reasons for it to be there, but we won't explain
them now.
Our header is still a bit boring:
hello
Ok, let's change it into
{header}
This way FP will auto generate an appropriate title for each page.
===== The include tag =====
All of your
* **comments.tpl** which display the post+comment page
* **default.tpl** which displays the "dialog-like" pages, like login
* **static.tpl** static pages
* **admin.tpl** admin area
* **preview.tpl** which displays the preview in the admin panel "write entry"
etc... you will understand that if some "central" content is always going to change in your templates, some will
not, and that's why we usually remove the header and the footer and we create a header.tpl and footer.tpl
These are just conventional names, we could choose "foo.tpl" and "bar.tpl"
as well. The important thing is that we can call them within our "master"
templates using the {include} directive. Ok, let's imagine you have now:
Published on {$date|date_format}
{$content} {/entry}
{include file="tpl/header.tpl"}
However, we conventionally put tpls in the "root" dir, and we put misc stuff
in res/; images should go in imgs/ (yes flatmaas2 called it "images" I should change it ;))
file= admin also a special "URL-like" syntax.
file="shared:my_template.tpl" will look for a template called my_template.tpl
in fp-interface/sharedtpls/
This is used to display special administrative controls/links or the comment
form.
===== Adding some color =====
let's move back to the theme dir; create a res/ directory and put there a
style.css; now you can open it and and style a bit your page. Of course you
can add divs (and tags) as you like to be able to style whatever and in
whichever way you want.
===== Adding widget bars =====
Finally, let's go with the final important reason for which you're going
crazy: how the heck can I have a three-column layout?
Ok, to start put in the end your index.tpl the widget code:
{widgets pos=left}
{$subject}
{$content}
{/widgets}
{widgets pos=right}
{$subject}
{$content}
{/widgets}
Notice you don't have a preamble as you usually always want to see the divs
of the right/left bar
Now you'll probably have an empty bar on the left, because FP uses just the
right one :p Once you're done with the admin panel you can populate the left
bar as well (if you don't want to wait you can edit the plugins.conf.php and
widgets.conf.php you find in fp-content/config/ by hand because that's
actually what the admin panel does...).
Finally you will probably want to have the widgets on each page of your
design (excepted maybe the control panel) so move the whole bar in a
widgets.tpl and put in index.tpl the directive {include file=widgets.tpl}
Here you go.
Now you're almost ready to start exploring th FP theme engine.
===== Current Flatpress 0.909.1 Arioso theme structure =====
{{:res:themes:fp09091-structure.jpg|}}
This picture show the main structure of Leggero. All boxes are divs, the div "admincontrols" only appears if you logged in. Please, take a deeper look into the "id" and "class" elements for designing a theme with CSS.
See this code, which is shared in the theme template files, as example to get overview about the used CSS "id" and "class" elements.
FlatPress
FlatPress 0.909.1 Arioso
a few words...
Widget head line
- something lists