Default Theme Variables

From Habari Project

Jump to: navigation, search

The Theme class in Habari is initially responsible for creating variables that can be used by templates to output data. User-activated themes can override this behavior, altering, removing, or adding to the variables that are provided by default.

This is a list of variables that Habari's core Theme class provides before being processed by any active theme.


Overridden Variables

These variables only apply if they are not overridden

A User Object containing a reference to the current user.
The page number requested in the URL or the name of the page as passed via a rewrite rule's page parameter.
A boolean containing the logged in status of the current user.

Post Variables

Post variables contain one or more posts, base on the criteria provided in the requested URL.

A Post object with the first post (if multiple posts are returned) or the single requested post.
A Posts object (functions like an array) containing multiple Post objects.

Request Variable

The $request variable is an object that contains members that correspond to the names of all the rewrite rules. If the current page matches a specific rewrite rule, then the value of the property with that name is true, otherwise it's false.

A list of default request members, based on the names of core rewrite rules at the time of this writing:

The home page.
A specific page of Entries.
A date-based page of Entries.
A tag-based page of Entries.
A single Entry's page.
A single Page's page.
A search results page.
A post-not-found page.
An admin page.
A user-based page of Entries.
The admin page for a user profile.
The Really Simple Discovery page.

A complete list of core rewrite rules can be found in system/classes/rewriterules.php, in the RewriteRules::add_system_rules() method.

Commenter Info Variables

A set of variables contains the personal information stored in a cookie about a user who has commented previously, which is used in the comment form both as a convenience to return commenting users and to fill the form fields in the case of a validation error.

The name of the commenter.
The email of the commenter.
The URL of the commenter.
The content of a comment that was rejected in validation (perhaps because the commenter did not supply a value for a required field).
True if a commenter must include email for a comment to be accepted.

Handler Variables

Each rewrite rule that maps a URL to an output page may capture data in the process of mapping to that page. This data is supplied to the template using the same variable names used in the capture.

For example, when requesting a date-based URL, Habari's handlers capture the year information into the $year handler variable. This value is passed on to the template directly in a variable of the same name.

The following are values that can be captured from rewrite rules. Not all of these variables may be present on every request. Only the variables that are captured by the applicable rewrite rule will be present in the template.

The page number of requested Entries.
The requested year of a chronological Entry listing.
The requested month of a chronological Entry listing.
The requested day of a chronological Entry listing.
The requested tag for a tag-based listing.
The slug of the requested Post.
The requested search criteria.

A complete list of core rewrite rules can be extrapolated from system/classes/rewriterules.php, in the RewriteRules::add_system_rules() method.

Additional Variables

Plugins and Themes can provide additional variables to templates by implementing the plugin action add_template_vars. To do this, create the Plugin or Theme class as usual. Within it, implement the following method:

function action_add_template_vars( $theme, $handlervars ) 
  $theme->my_variable = 'my value';

This adds a new template variable named $my_variable to the templates with the value 'my value'. Multiple variables may be added in this way. Values of existing variables can also be overridden here.

This method can be used to produce more complex and useful results:

function action_add_template_vars( $theme, $handlervars ) 
  $theme->asides = Posts::get('tag=asides&count=5');

This assigns the last 5 Posts tagged with "asides" into the template variable $asides. This variable can then be used in the theme in a foreach() loop, and each Post can be output appropriately.

Variables as Objects

Be aware that many of the variables provided to templates are objects, and should not be output directly. Instead, these objects provide properties that can be output.

For example, this code would generate unexpected/undesirable results, because the value of $post is a Post object:

<?php echo $post; ?>

Instead, use the properties of the $post variable to output the parts of the post that are required, such as the title:

<h3 id="title"><?php echo $post->title; ?></h3>

Many Habari objects have properties that are themselves objects. This allows, for example, a post to contain the comments that are associated to it. Theme developers are encouraged to peruse the class reference documentation to find the properties that are available within each class object.

Personal tools