FlatPress Wiki

Everything you need to know :)

User Tools

Site Tools


it:doc:thememinihowto

Differences

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

Link to this comparison view

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.
it/doc/thememinihowto.txt · Last modified: 2019/01/12 17:53 (external edit)