FlatPress Wiki

Everything you need to know :)

User Tools

Site Tools


it:doc:thememinihowto

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) d'lemonie harga.

Ok, vediamo come funziona.

Cos' è Smarty ?

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:

<!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>

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.

<body>

{entries}

<div id="entry-container">

    {entry}
        <h2>{$subject}</h2>

        <p><em>Published on {$date|date_format}</em></p>

        {$content}

    {/entry}

</div>

{/entries}

</body>


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 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 :

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

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:

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>

and the rest of the page:

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>

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:

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

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)