Dev:HiEngine

From Habari Project

Jump to: navigation, search

The HiEngine is a template engine specifically designed to offer a simple alternative to writing PHP into template files, as is done with the RawPHPEngine.

The HiEngine may look like other template engines, but because it was written from scratch in-house it is license-compatible with Habari.

"Hi" comes from the first and last letters of Habari.

Contents

What it does and why

Essentially, the engine simply converts codes in the template into PHP like that used in the standard RawPHPEngine, and executes it. It does this to make things easier for people who prefer a simpler tag syntax to what they might consider "arcane PHP".

There is a small performance penalty for using the HiEngine, since it needs to parse the code and convert it to its PHP counterpart.

Should I use this?

If you're looking to start building themes in Habari, and you're not accustomed to building templates using a syntax similar to this, then you should most definitely not use HiEngine. Instead, you should look into the native PHP support provided by RawPHPEngine, which is faster and better at teaching you real PHP, which can be useful when creating more complex themes.

Can I use PHP in a HiEngine theme?

Yes. Provided that you are aware that the HiEngine does some extra things to convert your {hi:*} tags into PHP code, and understand a bit about what it's doing, you can even code PHP to be "aware" of the special tags and make better use of them.

Available Tags

All HiEngine tags are in the format {hi:command} where command corresponds to one of the options below.

Template Variable Output

To output any template variable, simply include it as the entire content of the tag.

For example, if you wanted to output the template variable title, then use this tag:

{hi:title}

Object properties can also be referenced for output. For example, to output the content property of a post, use this tag:

{hi:post.content}

Different themes may provide different variables for output, but this wiki contains a list of variables that are published by default. Convert the PHP counterparts into HiEngine-compatible names by omitting the dollar sign, and converting the -> into a dot. Ergo, $post->title becomes post.title

Loops

Habari often has the need to output multiple posts based on a request. Loops are used in Habari to display the multiple posts sequentially. To loop over multiple values, the HiEngine uses an opening and closing tag to specify both the variable to loop over and mark a range of HTML to repeat for each element:

{hi:posts}
<h3>{hi:title}</h3>
<div class="content">{hi:content}</div>
{/hi:posts}

This example loops over the template variable posts. Inside the loop, the value of each item inside posts (each is a Post object) is given context. When an object has context, its properties can be accessed directly. So instead of using {hi:post.title}, the tag {hi:title} will output the title of each Post object.

If PHP must be used inside the loop block, the variable assigned to the individual items is the name of the array plus a _1 postfix. For example, the above might also be accessed like this:

{hi:posts}
<h3>{hi:title}</h3>
<div class="content"><?php echo $posts_1->content; ?></div>
{/hi:posts}

Site URL Output

Habari provides a number of URLs that are related to specific static locations of the site. To output one of these location, use the siteurl command.

For example, to output the URL of the root of the Habari installation, use this tag:

{hi:siteurl:habari}

Option Output

It is sometimes useful to directly output the value of a Habari option within a theme. To output an option, use the option command.

For example, to output the title of the site, use this tag:

{hi:option:title}

Include Other Templates

It is often necessary to include other files within the current template for output. This makes it possible to create a single header file that is used consistently across all templates, reducing the overall code produced and maintenance required.

To include another template from within a template, use the display command within a tag:

{hi:display:header}

Theme Functions

Habari makes a great deal of use of theme functions. Using the RawPHPEngine, these are called using

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

HiEngine relies even more on theme functions than the RawPHPEngine. To use theme functions in HiEngine, replace the PHP markers with HiEngine markers, replace $this-> with an '@' sign, and drop the parentheses.Thus, theme functions are output using this tag:

 {hi:@function}

There are two important items to note. First, when using PHP one can pass parameters to functions. This is not possible with HiEngine. Second, and this is related to the fact that parameters can't be passed to theme functions when using HiEngine, the theme's class definition will probably be used more in a HiEngine theme than a RawPHPEngine theme as functions are defined for easy output in the theme's templates.

Dates and Times

Internally, Habari stores dates and times as Unix-style integers. As a result, the default output of a date or time is in this format. There are two ways to get a human readable date and time.

The first is to create an output filter in the theme's theme.php file with PHP and instead of using, for example, {hi:post.pubdate}, use {hi:post.pubdate_out}. This will allow you to output a date or time in any format you wish.

The second is to use the default date and time formats for the site. To output a post's publication date with the default format, use {hi:post.pubdate.date}. To output a post's publication time with the default format, use {hi.pubdate.time}. The same technique can be used for all dates and times.

Beginning in Habari 0.7 it is possible to use formatter strings to output human readable dates and times in any format you wish without having to create an output filter. The syntax is

{hi:post.pubdate dateformat="format-string"}

For instance, for a post published on January 4, 2010 at 3:15PM {hi:post.pubdate dateformat="F j, Y"} would output Jan 4, 2010.

The modifiers available for use are those listed for PHP's date() function.

Personal tools
This is a cached copy of the requested page, and may not be up to date.

Sorry! This site is experiencing technical difficulties.
Try waiting a few minutes and reloading.

(Cannot contact the database server: Access denied for user 'habari'@'localhost' to database 'habari_wiki' (localhost))


You can try searching via Google in the meantime.
Note that their indexes of our content may be out of date.