Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Developer Applications

Transformation Callbacks

Transformation callbacks offer one of the most powerful ways to modify and customize the Movable Type user interface. These callbacks allow developers to intercept any page or template at a specific phase during the rendering process and to modify it in some way. To better understand when these callbacks are invoked, it may help to understand at a high level the process Movable Type goes through in converting a template into HTML that is displayed in the browser. Here is the basic sequence of events:

  1. Movable Type loads the template from the file system.

  2. Movable Type compiles the template’s source code into a machine readable equivalent.

  3. Movable Type loads the data provided by the backend that will later be used as input into the compiled template.

  4. Movable Type renders the template by inputting the data from step 3 into the compiled template from step 2.

  5. Movable Type returns the HTML returned by the system in step 4 to be displayed in the visitor’s browser.

Three main callbacks are invoked at specific points in the process outlined above to give developers a variety of ways and mechanisms by which they can influence, customize and modify the HTML returned by Movable Type to the user’s browser. These callbacks are:

  • MT::App::CMS::template_source is invoked between steps 1 and 2 and allows developers to modify the raw template source code prior to it being compiled into a machine readable form. With this callback, transformations are achieved using basic string manipulation functions like regular expressions.

  • MT::App::CMS::template_param is invoked between steps 3 and 4 and allows developers to modify the input parameters to the template. It is fired just prior to processing a template. At this point, developers can no longer modify the raw source of the template, but they can however, modify the compiled version by traversing the template’s DOM using an interface very similar to javascript.

  • MT::App::CMS::template_output is the last callback invoked and is called just prior to step 5. It allows developers to inject content into the final HTML just before it is sent to the browser.

Targeting a Callback to a Specific Template

In order for any of these callbacks to work, you need to know the filename of the template you wish to transform. The file name of the template you are targeting for your transformation is then appended to the end of the name of the callback you are attaching your handler to.

For example, let’s say you wanted to transform the template used to create the Edit Entry screen in Movable Type. A little sleuthing (or a good guess) reveals that the template you want to transform is located at the following path:

/path/to/mt/tmpl/cms/edit_entry.tmpl

To target this template, use just the file’s name, sans extension (e.g. edit_entry) in your config.yaml like so: 

name: Example Plugin for Movable Type
id: Example
description: This plugin is an example plugin for Movable Type.
version: 1.0
callbacks:
    MT::App::CMS::template_param.edit_entry: $Example::Example::Plugin::xfrm

Note: You can also target templates provided by your own plugin, or another plugin on the system. It does however require that the filename of the template being targeted end in .tmpl. Any template ending in another extension cannot be targeted by Movable Type’s transformation callback system.

Handling Includes

Movable Type templates have the ability to include other templates. The process outlined above for rendering templates is followed and the corresponding callbacks are invoked whenever an include is processed while the template is being rendered. In other words, template includes are processed on demand as they are encountered, as opposed to be handled up front before templates are even compiled.

Therefore, it is important to know whether or not the template code you wish to influence in some way with a transformation callback is found in an include or the base template itself. This may take some detective work on your part as you trace a template, following various includes while looking for the precise area you want to transform.

Back