Differences

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

@@ 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.

FlatPress Wiki

User Tools

Site Tools

Differences

Page Tools