User Tools

Site Tools


doc:thememinihowto

This is an old revision of the document!


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 ?

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

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>

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.

<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

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.

Current Flatpress 0.909.1 Arioso theme structure

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.

<!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>	
doc/thememinihowto.1588260732.txt.gz · Last modified: 2020/04/30 17:32 by eagleman

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki