Themes and templates

Introduction

PodHawk has eight built-in themes, which determine the appearance of your PodHawk website. You select which theme you want to use on the backend settings page.

In addition, there is a repository of additional themes which you can download. Simply unzip the download package, and place the contents in the folder podhawk/custom/themes in your site. The name of the new theme will appear automatically in the dropdown list in the settings page.

You can modify any of the themes, or create a completely new theme if you wish.

Smarty

PodHawk uses version 2 of the Smarty template engine to make its web pages. If you intend to modify an existing theme or create a new one, 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; 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.
  • one or more 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.
  • a couple of flash objects, with the file termination .swf. These are the classic LoudBlog Flash players for the theme.
  • 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.

Modular templates

The main template file is index.tpl. If you open it (in a text editor, never in a word processor), you will see that it ‘includes ‘ other template files. In other words, it is constructed of modules. It is possible to move these modules around in the template, or to remove them or to add new modules.

Some of the module files are .tpl files in your theme folder. Most of them however are in a separate folder “common_templates”, where they can be accessed by any of the themes. (Where index.tpl has statements like {include file=“common:posting_categories.tpl”}, it is calling a module from the common_templates folder). Template files in the common_template folder all have names which start “common_” eg “common_head.tpl”. This is simply to stop Smarty from confusing them with files in the theme folder.

index.tpl contains a posting loop. This begins with

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

and ends with

{/foreach}

The posting loop takes each of the postings to be displayed on the page and places information about it – such as the title, the author, the text of the posting and any tags attached to the posting – on the web page. Most of the modules within the posting loop have a name which begins “posting_” eg “posting_title.tpl”.

If your theme contains a sidebar, index.tpl will “include” a file called “sidebar.tpl” (or two files “sidebar_left.tpl” and “sidebar_right.tpl” if there are two sidebars in your theme). sidebar.tpl in turn “includes” modules, generally from the common_templates folder, with names that begin with “sidebar_” eg sidebar_authors.tpl.

In many cases, it is possible to pass parameters to modules, which affect how they behave or what information they place on the webpage. For example:

{include file=‘common:sidebar_tagcloud.tpl’ number=5}

places a tagcloud in the sidebar. The “number” parameter tells the module how many tags (starting with the most important) to display.

For fuller descriptions of the modules available in the common_templates folder, click the links below.

Modules to use inside the posting loop:

Modules to use in a sidebar
I could not find any posts with tag tpl_sidebar

Modules outside the posting loop and the sidebar

Other postings about themes and Smarty templates

 

PodHawk and HTML5

HTML5 is the new standard for the markup language for webpages. Most modern web browsers support at least some features of HTML5.

Before HTML5, the normal way to place an audio or video player on a webpage was to use Adobe Flash. The audio players used by PodHawk (the classic Loudblog players, the emff players and the OnePixelOut player) all use Flash.

With HTML5, however, it is possible to place an audio or video player on the webpage using HTML <audio> and <video> tags. The player can then be styled using a normal cascading style sheet, and Javascript can be used to control the player and its appearance.

Some devices (iPhones, iPads, tablets running on the most recent versions of Android) do not support Flash. Displaying a web page player on these devices requires HTML5.

However, different browsers support different audio and video formats. Fortunately, HTML5 allows several source files to be attached to a single <audio> or <video> tag. The browser goes down the list of files until it find one that it is able to play. So, for example, you might attach two audio files to an <audio> tag – one in mp3 format for those browsers which support mp3, and one in ogg format for browsers which support ogg but not mp3. For <video>, you might attach a file in mp4 format and another in webm format.

The latest versions of the JW Player use a combination of Flash and HTML5. In Podhawk the player is configured to use Flash where this is available on the user’s browser, and HTML5 where Flash is not available.

PodHawk 1.83 and later include a plugin for the MediaElement audio and video player, which uses HTML5, with a fallback to Flash on older browsers.

PodHawk 1.83 and later also tests for the presence of a Flash plugin in the user’s browser. If you have chosen a Flash-based audio player, PodHawk will automatically replace it with the browser’s default HTML5 player where a Flash plugin is not detected. You can therefore continue to use your favourite Flash-based player while still allowing users without Flash to play your podcasts on the webpage.

Recording page 2 now contains an option to add further files to a posting so that HTML5 players can give a choice of files from which the browser will choose the first that it can play. This option appears only where the main file attached to the posting is in a format which HTML5 supports.

 

jPaRSS RSS Feed Plugin

This Plugin allows you to display RSS feeds – as many as you want – on your PodHawk webpage. It works by loading a javascript-based RSS feed reader to the head section of the page. You can then add the following to your sidebar template where you want the feed items to appear:

{include file="plugins:jPaRSS/rss_reader.tpl" feedURL='http://url/of/feed' id='feed1' number='5' description='true'}

The parameters you can pass are:

  • url (required) – the url of the RSS feed you want to display eg http://www.my_podhawk_site.com/podcast.php
  • id (required) – a unique id for this feed. It can be almost anything you want, but to avoid possible conflicts with other elements on your page, it is recommended that you use ‘feed1’ as the id for the first feed you want to show, ‘feed2’ for the second, and so on.
  • number (optional) – the number of feed items you want to display. If you omit this parameter, the plugin will display the 4 most recent items.
  • description (optional) – description=‘true’ will display the first part of the text of each feed item.
  • description=‘content’ will display the full text of each feed item.
    description=‘image’ will display the first image associated with each feed item, plus a short section of the text
  • description=‘false’ or omitting the ‘description’ parameter, will display no text.
  • show_date (optional) – show_date=‘true’ displays the date of each feed item in the ‘preferred date format’ which you set on the backend settings page. show_date=‘false’ or omitting the date parameter will display no date.

Example – the main BBC News feed:

  • Loading feed.....

This plugin requires PodHawk 1.8 or later.

 

 Get ZIP Archive (0.1 MB | 0:00 min)

Plugins

A growing number of plugins are available for PodHawk. Up to Podhawk 1.82, available plugins were part of the standard PodHawk installation. From PodHawk 1.83, plugins are no longer included in the install package; instead you can download the plugins you want from this site.

Plugins live in the folder podhawk/custom/plugins. To install a new plugin, simply download the required zip file from this site, unzip it and upload the contents to the plugins folder of your site.

Admin users can use the backend Plugins page (Manage > Plugins) to manage the plugins on your site.

plugins

The Plugins page, where you can install, configure and enable plugins.

When a new plugin is first uploaded to the plugins folder, it will appear in the lower part of the Plugins page, “not installed plugins”. In this context, “not installed” simply means that you have not chosen to create a database entry for the plugin. To install, simply click on “install now” beside the name of the plugin to install.

The plugin will then appear in the top part of the Plugins page. However, before it wil work, it needs to be “enabled” (activated), and in many cases you will need to configure it ie tell it exactly how you want it to work and/or give it information that it needs. You do this by clicking “edit status and settings” beside the name of the plugin you want to enable or configure.

You will then be taken to the relevant plugin page. This contains a brief description of what the plugin does, and details of the version and author. There is a set of radio buttons for enabling/disabling the plugin. The plugin will not work until you have enabled it.

plugins2

A typical plugin page, for the Ping plugin.

Then there is a set of radio button for setting the run-order of the plugin. There are five run-order levels, 1 to 5. By default the run order is set to 3. PodHawk will run plugins with a low run-order first, and with a high run-order later. Sometimes, you get unexpected results when two or more plugins access the same event calls in the system; these can sometimes be solved by adjusting the run-order of the plugins concerned.

Then for most, though not all, plugins there is a section where you can set the various parameters which the plugin needs. There are explanations of the options in the right hand column. When you add or change parameters, don’t forget to click “save” at the bottom of the page.

The following plugins are currently available:

 

Utilities

The Utilities page is accessed (admin users only) via Manage > Utilities.

The contents of the page will vary depending on your PHP installation, and the type of database which you have:

  • check for updates. Your PodHawk installation will read the contents of an XML file on the PodHawk website, and tell you whether a newer version of PodHawk is available. (The ‘Check for Updates’ button will not appear if PodHawk cannot find a PHP method for reading remote files).
  • Database. This section tells you what type of database your PodHawk installation uses, and whether it communicates with it via the PHP PDO Extension (default) or ADODB_lite (if PDO is not available).
  • If you have a MySQL database and PHP is able to run shell commands on your server, there is a facility for creating a backup of the database. This will be sent to you as an e-mail attachment; or if your server cannot send emails, it will be placed in the ‘audio’ folder for you to download using FTP. If you have a Windows server, or if PHP shell commands are disabled, the backup button will not appear. If your server administrator has given you access to PHPMyAdmin, you can use that programme to make a backup of a MySQL database.
  • If you have an SQLite database, there is a facility for making the database readable by an external SQLite management tool. (Normally, only PodHawk can read the database). There is also a button for creating a backup copy of the database and sending it to you as an e-mail attachment.
  • There is a facility for clearing all the caches in your PodHawk installation – the caches where Smarty stores web pages and compiled templates, as well as PodHawk’s own cache folders. Sometimes, clearing caches can resolve problems with your webpages.
  • If you have a Unix/Linux server and PHP on your server runs as an Apache module, you will not normally be able to access or remove the cache folders in your PodHawk installation with your FTP programme. Clicking the “Make Cache Directories Removable” button will change the permissions on your cache folders to ‘0777’. Normally, the only time you would want to do this is if you wish to delete PodHawk entirely.
  • The Utilities page shows you the last 10 entries in the PodHawk log files (the error log and the events log). These give you information about any errors recorded by the PodHawk programme, and about events such as logins to the backend pages. Note that these are the log files which PodHawk itself generates, not the Apache logs or other system logs on your server. Speak to your server administrator if you need access to these.
  • Finally, the page allows you to cancel all cookies which allow access to the backend pages. (These are the cookies set when an admin user or author checks the “remember me” button on the login page). If you do this, all authors/admin users will need to enter their username and password the next time they want to log in.