Your web pages

From podhawk

Themes

PodHawk has eight built-in "themes". You can choose in your admin settings page which theme you want to use. If you develop your own theme, you should upload it to the podhawk/custom/themes directory. It will then appear as one of the choices in the settings page.

In LoudBlog, themes were called "templates". However, "templates" has a specific meaning in Smarty, so for clarity PodHawk calls the old LoudBlog templates "themes".

Languages

On the admin settings page, you can also choose which language you want to appear on your web page. The current choices are English and German. You can translate the web-page into your own language by translating one of the existing language files. And if you want to change an individual word or phrase in your web-page eg if you want your page to say "Back to base" instead of "Return to Home Page", simply find the relevant phrase in your language file and change it.

Creating a new language file

You can use a language other than English or German by creating a new language file. Open the file podhawk/custom/themes/[your theme]/lang/english.php in a text editor. You will see that the file contains a list of language definitions, like this :

'home_return' => 'Return to Home Page',

This is an instruction to PodHawk to place the words Return to Home Page on the screen whenever it finds $trans.home_return in your template.

To create a new language file, go through the English file (or the German file, if it is easier), and replace the words on the right hand side of the => symbol with the corresponding words in your language. Note that the words must be enclosed in single or double quotation marks (as in the example above) and also that all lines in the language array except the last line must end with a comma (,).

Then save your translated file to the lang folder associated with your theme with an appropriate name such as francais.php or espagnol.php. The new language option will be listed in your admin settings page. If you want to use your new language file with a different theme, simply copy it to the lang folder associated with the theme.

Finally, please post a copy of your new language file in the PodHawk forum, so that other people can download and use it, and I can incorporate it in future versions of PodHawk.

The Smarty template engine

PodHawk uses the Smarty template engine to make its web pages. If you intend to modify any of the "themes" built in to PodHawk , or create your own "theme", you will need to have a basic understanding of how Smarty templates operate. Read the first two parts of the Smarty manual (Introduction, and Smarty for Template Designers). The later stuff on Smarty for Developers is for advanced users only.

In PodHawk, all the html code needed to put your postings on the web page is in template files. The html can be edited freely without the need to alter any of the underlying php. The Smarty template files are written as html with additional Smarty variables and functions. These are contained in curly braces {like this}. Smarty variables all begin with a dollar sign. Some of them are simple values e.g $next_page (which is either "true" or "false"); but more often Smarty variables are arrays. You can access the different levels of the arrays by separating them with a period sign e.g. $settings.url contains the url of your web site. There are powerful conditional ("if....") and looping ("foreach...") functions in Smarty which make it possible to control the detail of what appears on your web page.

If you open up one of the PodHawk "theme" folders (podhawk/custom/themes), you will see that it contains several different sorts of file:

some Smarty template files, with the file termination .tpl.
a configuration file, with the file termination .conf.
two (at least) cascading style sheets (css), which tell the web browser how you want the web page to be displayed, what colours and fonts you want to use etc. The main css is screen.css. The other - images.css - is used by the PodHawk images manager, when you ask it to create the html needed to display an image on your web-page.
a couple of flash objects, with the file termination .swf. These are the classic LoudBlog Flash players for the theme. The other Flash players (eg the 1 Pixel Out player and the EMFF players) can be used by any of the themes and are stored in their own directory in podhawk/custom/players.
an images folder. This contains images used directly by the templates (eg background images, icons). The images which you load to use in your postings are not here, but in the images folder in the root of your PodHawk installation.
a lang folder which contains the language translation files (see above).

Understanding your template files

The file index.tpl controls the structure of your web page - what things are on the page and in what order. If you open it in a text editor, you will see that it contains almost no code itself. Instead, it 'includes' other .tpl files, with statements which look like this:

{include file='common:head.tpl'}
{include file='posting_title.tpl'}

The templates with names which begin 'common:' are not in your theme folder. PodHawk finds these templates in a special folder called 'common_templates'. This means that the same template can be used across all the themes without having to put copies of it in each theme folder. The other templates (without 'common:' at the beginning) are in your theme folder.

Your 'index.tpl' template will contain a 'postings loop'. This controls the information displayed about each posting on your webpage. It will include a comments file (comments.tpl) which controls the list of comments and the form for sending new comments on your posts. If your theme includes a sidebar, index.tpl will 'include' sidebar.tpl (or sidebar_left.tpl and sidebar_right.tpl if there are two sidebars).

You will also see 'comments', which look like this

{*   begin postings loop  *}

The comments will help you to understand what job each bit of the template does. The modular structure of index.tpl and sidebar.tpl makes it easy to move webpage features, and remove unwanted features and add new ones.

Editing Smarty Templates

Most PodHawk users use one of the built-in themes without making any changes to it. Others like to customise the theme, eg by adding a new background image for the header, or re-arranging some of the page elements. A few write a completely new set of templates, css files etc for their site. The following sections provide a brief introduction to template editing.

Using comment tags

First, a hint about editing Smarty templates. Smarty will ignore anything which you place between comment tags. The opening comment tag is

{*

and the closing tag is

*}

Instead of deleting something from a template, place it between Smarty comment tags until you are quite sure you want to remove it. That way, you can easily go back to the original template design if you change your mind.

{*
Smarty will ignore all Smarty code and html which you place between comment tags
*}

Editing the sidebar

Open sidebar.tpl in a text editor. It 'includes' further template files for each sidebar feature. For example, it may 'include' sidebar_recent_postings.tpl, which contains a list of the titles of recent postings; or sidebar_calendar, which contains a calendar. Most of these sidebar templates are 'common' templates (see above). If you want to remove one of these features, simply delete it from sidebar.tpl; if you want to change the order of the sidebar features, just move them around. Several of the available sidebar features allow you to pass parameters eg to control the number of recent postings shown in the 'recent postings' feature. This gives you a lot of control over the way your sidebar looks. A full list of the sidebar features and their parameters is here.

Your sidebar.tpl template contains only some of the available sidebar features. The 'common_templates' folder contains a complete library. If your theme sidebar does not contain a calendar, you can add one like this:

{include file='common:sidebar_calendar.tpl'}

Editing the postings loop

The 'postings loop' is clearly indicated in your index.tpl file. It controls what information about your postings you want to display on your web page. It lies between the Smarty tag

{foreach from=$postingdata key=key item=posting name=postings_loop}

and

{/foreach}

You can remove or re-arrange elements within the posting loop in exactly the same way as elements within the sidebar. Some of the elements allow you to pass parameters to the included files - details here.

Editing other template files

You can open and edit any of the .tpl files in your theme if you really want to. However, you will find that many of them are complex and difficult to understand, and you may like to ask for help on the PodHawk forum before proceeding. Cases where you might want to edit one of these files are:

to add a link to a favicon in head.tpl
to add meta tags with information about site content to head.tpl
to add a block of JavaScript to head.tpl
to add your own beautifully designed header or footer to your web page

Adding html to your template file

You can add sections of html directly into any of the template files. If you like, you can place the html in a separate template file called e.g. my_html.tpl, and then place {include file='my_html.tpl'} in index.tpl or sidebar.tpl at the place where you want the html to appear.

Adding JavaScript

This is more complicated than adding html. JavaScript uses curly braces { and }. So does Smarty, so there are obvious possibilities for confusion. If you want to add a section of JavaScript, surround it with {literal} tags, like this :

{literal}
<script    ......  your JavaScript .....
</script>
{/literal}

Changing the Flash player

You can change which design of Flash player appears on your web page, and (in some cases) the colours and other attributes of the player, from the backend players page in your PodHawk site. If you want to use the JW Player, read this note.

Additional templates

By default, PodHawk will use the template called index.tpl in your chosen theme directory. So, the URL

http://www.mypodhawksite.com

will call the default template.

You can add as many other templates as you like to your theme directory. You call them by including "atp=[template]" in the query section of the URL. ("atp" stands for "alternative template".) Like this :

http://www.mypodhawksite.com/index.php?atp=springtime

This will display your posts using the springtime.tpl template.

You can of course combine "atp" with other attributes. So, for example, suppose you have two sorts of music on your site - cool jazz and classic rock and roll. You could display all the posts in your "cool jazz" category with a special "cool" template, by including a link like this in your sidebar :

http://www.mypodhawksite.com/index.php?cat=cool_jazz&atp=cool

And the link to your classic rock postings might be :

http://www.mypodhawksite.com/index.php?cat=rock_n_roll&atp=classic

In both of the above examples, you should of course write "& a m p ;" (without the spaces) instead of "&" - I cant get WikiMedia to display "& a m p ;" literally!

Note that atp names can contain only the characters a to z, A to Z, 0 to 9 and underscore (_).

Advanced topics (PodHawk 1.7 and later)

If you are amending a theme, or writing a new one, and you need some JavaScript to make all the features work correctly, write the necessary JavaScript code to a file with the name 'theme.js' and put the file in the theme directory. PodHawk will call this file in the head section of your web page. Since the head section already calls jquery, you can use jquery in 'theme.js'.

If your theme needs to run some php before the webpage is computed (eg to find or calculate some extra data), you can place the code in a file 'template_functions.php' and place it in your theme directory. It will be 'included' and run by PodHawk after all the other page data has been collected. Code in 'template_functions.php' can do anything, including ruining your PodHawk installation, so take care!

Common mistakes in Smarty

If you misspell a Smarty variable, eg if you type {$postling} instead of {$posting}, Smarty will not return an error message. It will simply assume that the misspelled variable has a null value. Check your web page carefully for unexpected blank spaces - a misspelled Smarty variable may be the reason.

If you forget the braces { or } around a Smarty variable, the template will generally reproduce exactly what you have written e.g if you type $tag instead of {$tag}, Smarty will print $tag instead of the tag name. Again, check your web page carefully.

If you forget the $ at the beginning of a Smarty variable, Smarty will think that you are asking for a function and, since it probably will not be able to find a function of this name, Smarty will stop with a "fatal error" message.

Finally, don't forget that {if}, {foreach} and various other looping/conditional tags need to be closed (with {/if}. {/foreach} etc). If you forget, Smarty may stop with an error message, but may sometimes simply produce a misformed web page. Remember to close the loops or conditional sections in the right order.

{if ....some condition.....}
       {foreach ........}
        .....content of your foreach loop..
       {/foreach}
{else}
.......do something else...
{/if}

Hint : if Smarty puts "wrong" values on your web page, and you cannot understand why, try placing a {debug} tag near the top of the template file. When you next run the page, you will get a pop-up window with details of all the variables which Smarty has available.

Configuration files

The configuration file (.conf) in your theme folder contains instructions to Smarty about how to display certain of the 'common:' templates. For example, it may tell Smarty to display an icon at the beginning of a list of categories. If you open a template file in the 'common_templates' folder, you will find a short explanation of any configuration variables which the template will accept. (If the explanation isn't there, it means that the template does not accept any configuration variables). Each configuration variable has a default value which the template will use if the configuration file contains no relevant instructions.

Template Precedence

If you want to write your own theme, you need to know how PodHawk finds templates. Suppose your new index.tpl template has a line;

{include file='my_new_template_feature.tpl'}

Smarty will look first in your theme folder for a file called 'my_new_template_feature.tpl'. If it can't find it, it will look in the 'common_templates' folder for a file called 'common_my_new_template_feature.tpl'. If it can't find the template in the 'common_templates' folder, Smarty will display a short error message where the template would normally be displayed, but it will not crash the web-page.

Similarly, if your index.tpl file contais:

{include file='common:my_new_webpage_feature.tpl'}

Podhawk will look first for 'common_my_new_template_feature.tpl' in the 'common_templates' folder, then for 'my_new_template_feature.tpl' in your theme folder, and display an eror message if the file is in neither place.