Convert HTML to a Habari Theme

From Habari Project

Jump to: navigation, search

This tutorial assumes that you have already created an HTML page that you would like to convert into a Habari theme. If you do not yet have an HTML page ready, you can download this one and follow along in the tutorial.

Contents

Step 1: Create the Theme Directory

Habari stores all of its themes in a particular place on the server. If you can edit files directly on the server, you could create the directory you need there, or you can create a directory on your computer to upload to your web server later.

In either case, the directory you want to create is this: /user/themes/themename

Be sure to replace "themename" with the name of your theme.

Step 2: Theme XML File

To begin your theme, you must create a file that describes to Habari the basic information needed to list it as an option on the theme page.

To do this, you create a file named theme.xml and in it place the following content:

 <?xml version="1.0" encoding="UTF-8" ?>
 <pluggable type="theme">
 	<name>Sample</name>
 	<license url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software License 2.0</license>
 	<author url="http://asymptomatic.net/">Owen Winkler</author>
 	<url>http://asymptomatic.net</url>
 	<version>1.0</version>
 	<template_engine>rawphpengine</template_engine>
 	<description><![CDATA[This is a sample theme.]]></description>
 </pluggable>

Obviously, replace the relevant bits of content with values that are more applicable for you. One thing that is often unclear about the URLs in the theme xml file is the "author" url value is used to reference the author, and the main "url" value is used to reference the theme.

After you save this file into your theme directory in the Habari installation, you should see your theme listed on Habari's theme page. Of course, it won't do anything yet if you activate it, so on to Step 3....

Step 3: Copy your HTML

The theme directory is the place to put all of your HTML and CSS. You can create additional directories inside of the theme directory for CSS, images, or javascript, although the sample HTML does not do this.

Copy the HTML file and the files it requires into the theme directory. When copying, rename the main HTML file to home.php within the theme directory.

You should now be able to activate the theme and see some content, although it probably doesn't look perfect. It's very likely that the references to CSS and other assets are incorrect.

Step 4: Build a Theme Class

There is an easy way to get the correct reference to the stylesheets in your theme. Adding this code to your home.php file will do it:

<link rel="stylesheet" href="<?php Site::out_url('theme', '/style.css'); ?>style.css" media="screen,projection">

But don't do this! If you include the stylesheet directly in your theme, then Habari can't modify, optimize, or add to the CSS of your theme from plugins. Instead, you need to create a theme class.

If your theme has a theme class, it can provide not only the correct references to the CSS files, but also supply additional custom values to the templates as might be required.

To create a theme class, create a new file named theme.php in your theme directory, and save this code to it:

<?php
class SampleTheme extends Theme
{
	public function action_template_header( $theme )
	{
		Stack::add(
			'template_stylesheet',  // Add this stylesheet to the header
			array(
				Site::get_url('theme', '/style.css'),  // Get it from the theme directory
				'screen,projection'  // Use this file for these media types
			), 
			'site'  // The alias of this item
		);
	}
}
?>

You will want to change the name of the class in this file from SampleTheme to use your own theme name so that it doesn't conflict with other themes. While reviewing the files in future steps of this sample, you may see that the theme name has changed to "Wazi" and the class name in this file has become WaziTheme.

The code in this function is spread over several lines to add comments, but can usually be fit into a single line. Add an additional call to Stack:add() for each stylesheet you want to add, and change the name and alias (a name that Habari uses to refer to the stylesheet internally) of the stylesheet file as appropriate.

After you have created your theme.php file, you must edit your home.php template to make use of the stylesheets you have added. Remove the stylesheet declarations from your home.php and replace them with this:

<?php $theme->header(); ?>

The above line will output all of the stylesheets you've defined in the theme class.

Personal tools