Skip to content

designguide theme systemtemplates

Jump to bottom Edit New page
mikert edited this page Jul 24, 2011 · 7 revisions

MTDG: System Templates

"System templates" within Melody are templates designated for specific purposes. They are templates that are always rendered dynamically by the system by virtue of the fact that their contents depend upon user input, e.g. search results, comment previews, etc.

How System Templates are Loaded

System templates are loaded by the system by name. As with all templates, when the system wants to load the search results template, for example, the system first looks for the template named "Search Results" within the current blog. If no template by that name can be found there, the system then looks in the list of global system templates for a template with the same name. If a template cannot be found there, then an error occurs. Otherwise, the corresponding template is used.

This is useful because it allows individual blogs to override what is effectively the system default, customizing it with a unique look and feel.

Taking a look again at the search results example, a user can load the search results template only by invoking the search results handler or application like so:

http://somedomain.com/melody/search.cgi?search=star+wars

If you want to load the blog specific system template you need to specify the blog ID in the query string as well, like so:

http://somedomain.com/melody/search.cgi?search=star+wars&blog_id=1

Creating System Templates

To create a system template, you need to register one in your theme. That is done by adding a template definition under the system template key, like so:

template_sets:
  name: 'My Theme'
  templates:
    system:
      new_password_reset_form:
        label: 'New Password Reset Form'

The above will create a system template called "New Password Reset Form."

Limitations of System Templates

Currently in Melody, system templates can only be created through the process of applying a theme. They cannot be created through the user interface (although in the future we hope to remove this restriction).

Furthermore, because system templates are often required in order for a theme to operate, they cannot be removed either.

Reserved System Template IDs

There are a number of template IDs reserved for system templates that have a predetermined meaning within the context of a website. By utilizing one of these template IDs for one of your system templates you will be able to customize the presentation of a number of important screens within your website. These IDs are:

Tip: If a template with one of these IDs cannot be found within a theme, then a default template will be used.

  • comment_listing - A template with this ID is used for generating a list of comments in a JSON (Javascript Object Notation) format. The template is used by Melody's entry pagination feature that allows readers to fetch a range of comments associated with an entry.

  • comment_preview - A template with this ID is used to render the screen that results from a user clicking on the preview button from the commenting form associated with an entry.

  • comment_response - A template with this ID is used to display a message to a user subsequently to submitting a comment on a website. This template and the message it contains will only be used if the "Use Comment Confirmation Page" option has been selected under your website's preferences.

  • dynamic_error - A template with this ID will be used to present errors to the user. Without this template users will be greeted with a default system error message styled with the Melody logo.

  • login_form - A template with this ID is used to prompt a visitor for a set of credentials (usually a username/password combination) to login to the website.

  • new_password - A template with this ID is used to prompt a user who has initiated the password recovery process with a form to choose a new password.

  • new_password_reset_form - A template with this ID is used to prompt a visitor of a website for an email address for which to recover a password. If a user is found with that email address they will be sent a link to a form to reset their password.

  • popup_image - This rarely used template is used by Melody to present to render the screen that results from a user clicking on a image inserted into an entry with the option "Link image to full-size version in a popup window" selected from the Insert Image wizard.

  • search_results - A template with this ID is used to display search results on a website.

System Template Variables and Context

All templates make use of template tags in order to customize the output of the template. Some system templates make use of template "variables" as well. Template variables are those values accessed via the <mt:var> template tag. Each system template has its own list of template variables that it utilizes.

Search Results Template

  • datebased_archive - Set to "1" if the query string parameter archive_type refers to an date based archive type, e.g. Weekly, Daily, Monthly and Yearly.
  • author_archive - Set to "1" if the query string parameter archive_type refers to an author based archive type.
  • category_archive - Set to "1" if the query string parameter archive_type refers to a category based archive type.
  • system_template - Set to "1". This is helpful within the context of a template module that could operate in both static and dynamic modes. For example, you may have a template module that has PHP embedded within it, and because PHP does not work within system templates, you may need to invoke an alternative code block accordingly.
  • search_results - Set to "1". This is helpful within the context of a template module that might need to alter its behavior based upon the type of system template it is included by.

Comment Listing

  • commentTotal
  • commentLimit
  • commentOffset
  • commentDirection

Comment Preview

  • body_class - Contains a CSS class name. Default value is "mt-comment-preview."
  • comment_preview - A boolean value that lets you detect if a comment preview is in effect.
  • comment_preview_template - A boolean value that lets you detect if you are in the comment preview template.
  • system_template - A boolean value that lets template modules know that they are being called from a system template.

Comment Response

  • body_class - A CSS class that will have one of two values:
    • mt-comment-error - In the event of an error.
    • mt-comment-pending - In the event of the comment being held for moderation.
  • comment_response_template - A boolean value set that can be used to let template modules they are in a comment response context.
  • comment_error - A boolean value set when an error has occurred.
  • comment_pending - A boolean value set when the comment is held for moderation.
  • return_to - A string denoting the URL where the user should be sent after they see the message.
  • system_template - A boolean value denoting that this is a system template.

Dynamic Error

  • blog_id - The current blog id.
  • dynamic_error - A boolean value set to let template modules know that they are in a dynamic error context.
  • error_code - PHP error code.
  • error_file - In which file the PHP error occurred.
  • error_line - Where the PHP error occurred.
  • error_message - The PHP error message.
  • http_error - The HTTP error.
  • system_template - A boolean value denoting that this is a system template.

Login Form

  • auth_loop - A loop of external authenticators enabled on the blog.
    • logo - The logo image for the authenticator.
    • name - The name of the authenticator
  • blog_id - The id of the blog.
  • default_signin - The default authenticator.
  • entry_id - The id of the entry in context.
  • return_url - The URL to return to after a successful login event at the commenter login screen.
  • static - Set when static publishing is in use.

New Password

  • blog_id - The id of the current blog.
  • email - The user's email address.
  • token - A unique token created by Melody when a password reset is requested. It is used to help validate that a password reset should happen.
  • password - The submitted password.
  • password_again - The confirmation of the submitted password.
  • system_template - Set to 1, this identifies the template in context as a system template.

New Password Request

  • blog_id - The id of the current blog where the password request is being made.
  • can_signin - A boolean value that is set true or false depending on whether or not the password request is made from the CMS.
  • email - The email address submitted into the new password request form.
  • return_to - The URL to return to after the request has been made.
  • system_template - A boolean identifier set to true to indicate that this is a system template.

Popup

  • blog_id - The id of the current blog.
  • image_height - The height of the image.
  • image_url - The URL of the image.
  • image_width - The image's width.

Search Results

  • blog_id - The id of the blog in the search results.
  • author_archive - A boolean identifier set to true when the search results are the pagination of an author archive (see archive pagination for details).
  • category_archive - A boolean identifier set to true when the search results are the pagination of a category archive (see archive pagination for details).
  • datebased_archive - A boolean identifier set to true when the search results are the pagination of a date-based archive (see archive pagination for details).
  • search_results - A boolean identifier set to true to indicate that this is the search results template.
  • system_template - A boolean identifier set to true to indicate that this is a system template.

Continue Reading

 

Category: Guide

Tags: theme design


Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

  • Author: Byrne Reese
  • Edited by: Violet Bliss Dietz
Add a custom footer
Add a custom sidebar
Clone this wiki locally