User Tools

Site Tools


it:doc:thememinihowto
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


it:doc:thememinihowto [2019/01/12 17:53] (current) – created - external edit 127.0.0.1
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"
 +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'
 +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.
it/doc/thememinihowto.txt · Last modified: 2019/01/12 17:53 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki