doc:thememinihowto
no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Next revision | |||
— | doc:thememinihowto [2019/01/12 17:53] – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Theme Mini-HowTo ====== | ||
+ | |||
+ | Well, my suggestion is always to start [[http:// | ||
+ | |||
+ | |||
+ | Ok, let's see how it works [[http:// | ||
+ | |||
+ | ===== What is Smarty ? ===== | ||
+ | |||
+ | [[http:// | ||
+ | |||
+ | |||
+ | However, there are some things people should know [[http:// | ||
+ | |||
+ | |||
+ | ===== Structure of a theme ===== | ||
+ | |||
+ | **index.tpl** is your " | ||
+ | |||
+ | First of all [[http:// | ||
+ | |||
+ | you could create a index.tpl like this | ||
+ | |||
+ | |||
+ | <file html index.tpl> | ||
+ | < | ||
+ | html PUBLIC " | ||
+ | " | ||
+ | |||
+ | <html xmlns=" | ||
+ | < | ||
+ | < | ||
+ | Hello world | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Now, you would probably be all "I know how to write an html page, you idiot!", | ||
+ | |||
+ | Save, and refresh. Now **you' | ||
+ | |||
+ | Well, that's a good start. | ||
+ | |||
+ | |||
+ | ===== Populating with entries ===== | ||
+ | |||
+ | Ok, let's go on. Now you would probably like to populate your (naked) page with some content, don't you? Well, I'm assuming you already have some entries, so let's go on. | ||
+ | |||
+ | <code smarty> | ||
+ | < | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id=" | ||
+ | |||
+ | {entry} | ||
+ | < | ||
+ | < | ||
+ | {$content} | ||
+ | {/entry} | ||
+ | |||
+ | </ | ||
+ | |||
+ | {/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}, | ||
+ | |||
+ | We could call this tag a // | ||
+ | |||
+ | 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 <div> for instance. That's the most typical use. | ||
+ | |||
+ | Why is a preamble needed? You may want to hide some tags if there are no entries, because wouldn' | ||
+ | |||
+ | > **The content (and the tags) within a preamble WON'T be displayed if there is no content to show for the inner tag (so, if the {entry} block returns no content).** | ||
+ | |||
+ | ===== Iterator tags: entry ===== | ||
+ | Now, an {entries} (or {entry_block}) block expects to contain a {entry} block. An entry block is | ||
+ | an _iterator_ . Which means that is a " | ||
+ | block. | ||
+ | |||
+ | Usually you have an N number of entries for each page. You just put a | ||
+ | sample for ONE, and Smarty/FP will repeat it N times. | ||
+ | |||
+ | ===== Dollar tags ===== | ||
+ | |||
+ | Dollar tags are actually the way smarty handles output for a variable. Variables are set by the programmer, | ||
+ | who exposes some parts to be printed on screen so that the designer can put them where he wants. | ||
+ | |||
+ | So, when a tag contains a dollar, it means it contains a variable; this is the same as doing actually something like | ||
+ | |||
+ | <code php> | ||
+ | <?php echo $var ?> | ||
+ | </ | ||
+ | |||
+ | 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:// | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | ===== 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 | ||
+ | |||
+ | <code smarty> | ||
+ | {$var|modifier} | ||
+ | </ | ||
+ | => | ||
+ | <code php> | ||
+ | <?php echo modifer($var); | ||
+ | </ | ||
+ | |||
+ | **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 : | ||
+ | |||
+ | <code smarty> | ||
+ | < | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id=" | ||
+ | |||
+ | {entry} | ||
+ | < | ||
+ | < | ||
+ | {$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: | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | Ok, let's change it into | ||
+ | |||
+ | <code smarty> | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | 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 " | ||
+ | * **static.tpl** static pages | ||
+ | * **admin.tpl** admin area | ||
+ | * **preview.tpl** which displays the preview in the admin panel "write entry" | ||
+ | |||
+ | | ||
+ | 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 " | ||
+ | as well. The important thing is that we can call them within our " | ||
+ | templates using the {include} directive. Ok, let's imagine you have now: | ||
+ | |||
+ | <file html header.tpl> | ||
+ | < | ||
+ | html PUBLIC " | ||
+ | " | ||
+ | |||
+ | <html xmlns=" | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | and the rest of the page: | ||
+ | |||
+ | <file smarty index.tpl> | ||
+ | {* | ||
+ | hi I'm a comment, and what follows | ||
+ | is an include directive | ||
+ | *} | ||
+ | |||
+ | {include file=header.tpl} | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id=" | ||
+ | {entry} | ||
+ | < | ||
+ | < | ||
+ | | ||
+ | {/entry} | ||
+ | </ | ||
+ | |||
+ | {/entries} | ||
+ | |||
+ | </ | ||
+ | </ | ||
+ | |||
+ | This will tell smarty "hey, in the same dir of the templates look for a file | ||
+ | called header.tpl and put it here!" | ||
+ | dir in your theme dir: | ||
+ | |||
+ | <code smarty> | ||
+ | {include file=tpl/ | ||
+ | </ | ||
+ | |||
+ | However, we conventionally put tpls in the " | ||
+ | in res/; images should go in imgs/ (yes flatmaas2 called it " | ||
+ | |||
+ | file= admin also a special " | ||
+ | |||
+ | file=shared: | ||
+ | in fp-interface/ | ||
+ | |||
+ | This is used to display special administrative controls/ | ||
+ | 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: | ||
+ | |||
+ | <code smarty> | ||
+ | <div id=" | ||
+ | |||
+ | {widgets pos=left} | ||
+ | <div id=" | ||
+ | < | ||
+ | {$content} | ||
+ | </ | ||
+ | {/widgets} | ||
+ | |||
+ | </ | ||
+ | |||
+ | <div id=" | ||
+ | |||
+ | {widgets pos=right} | ||
+ | <div id=" | ||
+ | < | ||
+ | {$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/ | ||
+ | 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 ===== | ||
+ | |||
+ | {{: | ||
+ | |||
+ | This picture show the main structure of Leggero. All boxes are divs, the div " | ||
+ | |||
+ | See this code, which is shared in the theme template files, as example to get overview about the used CSS " | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | <html xmlns=" | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | |||
+ | <div id=" | ||
+ | |||
+ | <div id=" | ||
+ | < | ||
+ | <p class=" | ||
+ | </ | ||
+ | |||
+ | <div id=" | ||
+ | |||
+ | <div id=" | ||
+ | | ||
+ | <div id=" | ||
+ | |||
+ | <h2 class=" | ||
+ | < | ||
+ | | ||
+ | <div class=" | ||
+ | <a href=" | ||
+ | <a href=" | ||
+ | </ | ||
+ | | ||
+ | < | ||
+ | | ||
+ | <ul class=" | ||
+ | <li class=" | ||
+ | <li class=" | ||
+ | </ul> | ||
+ | | ||
+ | </ | ||
+ | | ||
+ | <div class=" | ||
+ | <div class=" | ||
+ | <div class=" | ||
+ | </ | ||
+ | | ||
+ | </ | ||
+ | | ||
+ | <div id=" | ||
+ | <div id=" | ||
+ | < | ||
+ | <ul> | ||
+ | < | ||
+ | </ul> | ||
+ | </ | ||
+ | </ | ||
+ | | ||
+ | </ | ||
+ | |||
+ | <div id=" | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | </ | ||
+ | |||
+ | </ | ||
+ | </ | ||
+ | </ |
doc/thememinihowto.txt · Last modified: 2024/02/01 23:30 by fraenkiman