FlatPress Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Theme Mini-HowTo ======


Well, my suggestion is always to start from an already made theme, and at this moment I would start from latest unstable version (using flatmaas theme, and changing the css); when I'll release the new package themes will be a bit changed (even though old ones should still work).


Ok, let's see how it works.

===== What is Smarty ? =====

[[http://www.smarty.net|Smarty]] is a system which translates //templates// containing special //tags// into php; most of the blogs you see around just use PHP as php itself works actually like a templating language. Using Smarty let us **abstract** more from the php programming logic, and should make easier for non-programmers to design a template.


However, there are some things people should know.


===== Structure of a theme =====

**index.tpl** is your "main" file. It must contain all of the stuff which will go in index.php

First of all create a new dir in your fp-interface/themes/ dir, and copy from flatmaas2 the theme.conf.php (or theme_conf.php depending on your version) to the new directory.

you could create a index.tpl like this


<file html index.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>
    Hello world
</body>
</html>
</file>

Now, you would probably be all "I know how to write an html page, you idiot!", well wait. Now that you have your dumb hello world page save this index.tpl, check whether you really have reading permissions for all users on that directory, and then point your browser to flatpress, go to control panel and select from the config page the name you chose for the dir of your theme.

Save, and refresh. Now **you'll probably have an error** because the new theme lacks some stuff. No problem, just browse to [[http://yourweb/flatpress/]] as an index you should see your hello world.

Well, that's a good start.


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

<code php>
  <?php echo $var ?>
</code>

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://www.smarty.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

<code smarty>
  {$var|modifier}
</code>
=>
<code php>
<?php echo modifer($var); ?>
</code>

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

<code html>
   <head><title>hello</title></head>
</code>

Ok, let's change it into

<code smarty>
  <head>{header}</head>
</code>

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:

<file html 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>
</file>

and the rest of the page:

<file smarty 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>
</file>

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:

<code smarty>
{include file="tpl/header.tpl"}
</code>

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

===== Current Flatpress 0.909.1 Arioso theme structure =====

{{:res:themes:fp09091-structure.jpg|}}

This picture show the main structure of Leggero. All boxes are divs, the div "admincontrols" only appears if you logged in. Please, take a deeper look into the "id" and "class" elements for designing a theme with CSS. 

See this code, which is shared in the theme template files, as example to get overview about the used CSS "id" and "class" elements.

<code html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>FlatPress</title>
</head>

<body>

<div id="body-container">

  <div id="head">
    <h1><a href="...">FlatPress 0.909.1 Arioso</a></h1>
    <p class="subtitle">a few words...</p>
  </div>

  <div id="outer-container">

    <div id="main">
      
      <div id="entry..." class="entry ...">

        <h2 class="date">dateformat</h2>    
        <h3><a href="...">entry head line</a></h3>
          
        <div class="admincontrols">
          <a href="...">edit...</a>
          <a href="...">delete...</a>
        </div>
          
        <p>entry text...</p>
        
        <ul class="entry-footer">
          <li class="entry-info">Posted by ... at ... in <a href="...">category</a></li>
          <li class="link-comments"><a href="...">comments...</a></li>
        </ul>
        
      </div>
      
      <div class="navigation">
	<div class="alignright"><a href="...">next...</a></div>
	<div class="alignleft"><a href="...">previous...</a></div>
      </div>
      
    </div>
      
    <div id="column">
      <div id="widget-...">
        <h4>Widget head line</h4>
        <ul>
          <li>something lists</li>
        </ul>
      </div>
    </div>
          
  </div>

  <div id="footer">
    <p>This blog is powered by <a href="http://www.flatpress.org/">FlatPress</a>.</p>
  </div>

</div>

</body>
</html>	
</code>