This shows you the differences between two versions of the page.
— |
it:doc:thememinihowto [2019/01/12 17:53] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Theme Mini-HowTo ====== | ||
+ | Bene, il mio suggerimento è di partire sempre da un tema già fatto, ed in particolar modo in questo momento dall' ultima versione //unstable// (basta usare il tema //flatmaas// e cambiare il CSS); infatti quando verrà rilasciato il nuovo pacchetto il tema risulterà un po' cambiato (comunque anche quelli vecchi funzioneranno) [[https://goo.gl/Kh6ih6|d'lemonie harga]]. | ||
+ | |||
+ | Ok, vediamo come funziona. | ||
+ | |||
+ | ===== Cos' è Smarty ? ===== | ||
+ | |||
+ | |||
+ | [[http://smarty.php.net|Smarty]] è un sistema che traduce //template// contenenti speciali //tags// in php; la maggior parte dei blog usa semplicemente PHP, perché php è in effetti un linguaggio di template. Usare Smarty ci permette di astrarre dalla logica di programmazione di php, e dovrebbe rendere più facile progettare un template anche a chi non è un programmatore. | ||
+ | |||
+ | Tuttavia ci sono alcune cose da conoscere. | ||
+ | |||
+ | |||
+ | ===== Struttura di un tema ===== | ||
+ | |||
+ | **index.tpl** è il file "principale" per la costruzione di un tema. Questo contiene tutto ciò che che comparirà nella pagina index.php. | ||
+ | |||
+ | Prima di tutto create una nuova directory in //fp-interface/themes/// e copiate da //flatmaas2// il file theme.conf.php, o il file theme_conf.php (dipende dalla versione), nella nuova directory. | ||
+ | |||
+ | Ora scrivete il file index.tpl, un esempio è il seguente: | ||
+ | |||
+ | <code> | ||
+ | <!DOCTYPE | ||
+ | html PUBLIC "-//W3C//DTD XHTML 1.1//EN" | ||
+ | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> | ||
+ | |||
+ | <html xmlns="http://www.w3.org/1999/xhtml"> | ||
+ | |||
+ | |||
+ | |||
+ | <head><title>hello</title></head> | ||
+ | |||
+ | <body> | ||
+ | |||
+ | Hello world | ||
+ | |||
+ | </body> | ||
+ | |||
+ | </html> | ||
+ | |||
+ | </code> | ||
+ | |||
+ | |||
+ | Bene, probabilmente eravate già a conscenza di come scrivere una pagina in html... ok aspettate. Ora che avete la vostra pagina, salvatela col nome index.tpl, controllate che nella nuova directory vi siano i permessi di lettura per tutti gli utenti, puntate con il browser su http://yourweb/flatpress/, andate nel pannello di controllo e selezionate dalla pagina di configurazione il nome del tema appena creato! | ||
+ | |||
+ | Salva e ricarica la pagina. Ora **è probabile che riscontriate un errore** perché al tema mancano alcuni file. Non c'è problema comunque, puntate nuovamente il browser su http://yourweb/flatpress/ e dovreste vedere la scritta "hello world". | ||
+ | |||
+ | Bene, questo è un buon inizio. | ||
+ | |||
+ | ===== 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> | ||
+ | |||
+ | <body> | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id="entry-container"> | ||
+ | |||
+ | {entry} | ||
+ | <h2>{$subject}</h2> | ||
+ | |||
+ | <p><em>Published on {$date|date_format}</em></p> | ||
+ | |||
+ | {$content} | ||
+ | |||
+ | {/entry} | ||
+ | |||
+ | </div> | ||
+ | |||
+ | {/entries} | ||
+ | |||
+ | </body> | ||
+ | |||
+ | |||
+ | |||
+ | </code> | ||
+ | |||
+ | |||
+ | 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 <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't want to have an empty container div. | ||
+ | |||
+ | > **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 "template" for an entry | ||
+ | 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 | ||
+ | |||
+ | <?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://smarty.php.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} ---> <?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> | ||
+ | <body> | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id="entry-container"> | ||
+ | |||
+ | {entry} | ||
+ | |||
+ | <h2>{$subject}</h2> | ||
+ | |||
+ | <p><em>Published on {$date|date_format}</em></p> | ||
+ | |||
+ | {$content} | ||
+ | |||
+ | {/entry} | ||
+ | |||
+ | |||
+ | </div> | ||
+ | |||
+ | {nextpage}{prevpage} | ||
+ | |||
+ | |||
+ | {/entries} | ||
+ | |||
+ | </body> | ||
+ | |||
+ | </code> | ||
+ | |||
+ | 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: | ||
+ | |||
+ | <head><title>hello</title></head> | ||
+ | |||
+ | |||
+ | |||
+ | ok, let's change it into | ||
+ | |||
+ | <head>{header}</head> | ||
+ | |||
+ | |||
+ | |||
+ | 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: | ||
+ | |||
+ | |||
+ | <code> | ||
+ | header.tpl | ||
+ | |||
+ | ----------------------- | ||
+ | |||
+ | <!DOCTYPE | ||
+ | html PUBLIC "-//W3C//DTD XHTML 1.1//EN" | ||
+ | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> | ||
+ | |||
+ | <html xmlns="http://www.w3.org/1999/xhtml"> | ||
+ | |||
+ | <head><title>hello</title></head> | ||
+ | |||
+ | <body> | ||
+ | |||
+ | </code> | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | and the rest of the page: | ||
+ | |||
+ | |||
+ | <code> | ||
+ | index.tpl | ||
+ | |||
+ | ------------------------- | ||
+ | |||
+ | {* | ||
+ | |||
+ | hi I'm a comment, and what follows | ||
+ | |||
+ | is an include directive | ||
+ | |||
+ | *} | ||
+ | |||
+ | |||
+ | {include file=header.tpl} | ||
+ | |||
+ | {entries} | ||
+ | |||
+ | <div id="entry-container"> | ||
+ | |||
+ | {entry} | ||
+ | |||
+ | <h2>{$subject}</h2> | ||
+ | |||
+ | <p><em>Published on {$date|date_format}</em></p> | ||
+ | |||
+ | {$content} | ||
+ | |||
+ | |||
+ | |||
+ | {/entry} | ||
+ | |||
+ | </div> | ||
+ | {/entries} | ||
+ | |||
+ | </body> | ||
+ | |||
+ | |||
+ | </code> | ||
+ | |||
+ | |||
+ | |||
+ | This will tell smarty "hey, in the same dir of the templates look for a file | ||
+ | called header.tpl and put it here!". | ||
+ | you can even use relative (or absolute) paths; let's imagine you have a tpl | ||
+ | dir in your theme dir: | ||
+ | |||
+ | {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: | ||
+ | |||
+ | <code> | ||
+ | |||
+ | <div id="left-bar"> | ||
+ | |||
+ | {widgets pos=left} | ||
+ | |||
+ | <div id="{$id}"> | ||
+ | |||
+ | <h4>{$subject}</h4> | ||
+ | |||
+ | {$content} | ||
+ | |||
+ | </div> | ||
+ | |||
+ | {/widgets} | ||
+ | |||
+ | |||
+ | </div> | ||
+ | |||
+ | <div id="right-bar"> | ||
+ | |||
+ | {widgets pos=right} | ||
+ | |||
+ | |||
+ | <div id="{$id}"> | ||
+ | |||
+ | <h4>{$subject}</h4> | ||
+ | |||
+ | {$content} | ||
+ | |||
+ | </div> | ||
+ | |||
+ | {/widgets} | ||
+ | |||
+ | |||
+ | |||
+ | </div> | ||
+ | |||
+ | </code> | ||
+ | |||
+ | 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. |