Not a developer? Go to MovableType.com

Documentation

Registering Template Sets

Template Sets provide developers the ability to package up a set of templates that constitute the entire design and structure for a site into a plugin. That template set is then made available to users as a option when creating a new blog. When the blog is created, it will be initialized using all of the templates contained by the selected template set.

Here are some of the things a developer can specify when a template set is registered through the API:

  • the name of the template set
  • the display name for each template in the set
  • the archive type for archive templates
  • the file mapping for archive templates
  • the filename of index templates

The following is an excerpt of a code sample to register a template set. A more complete example is provided below.

sub init_registry {
    my $plugin = shift;
    $plugin->registry({
        template_sets => {
            my_set => {
                label => "My Template Set",
                base_path => 'plugins/MyPlugin/templates',
                order => 100,
                templates => {
                     # templates specified here
                },
            },
        },
    });
};

Template Set Options

Values for the following options should be provided when registering a template set.

  • label - the display name of the template set
  • base_path - the relative path pointing to where the files for each template can be found
  • order - the sort order of the template set in the template set pull down menu
  • templates - a list of the templates contained by the set

Base Path and Linking to Template Files

The base_path option determines where the actual template code for each template will be specified. Each template within a template set should be placed in a separate file within the directory identified by base_path. The name of each file should correspond to the keys used to identify each template followed by the .mtml file extension.

Ok, now to provide an example that should hopefully make that clear. Using the sample code below, a designer should create the following files:

  • plugins/MyPlugin/templates/homepage.mtml
  • plugins/MyPlugin/templates/entry.mtml
  • plugins/MyPlugin/templates/entry_listing.mtml
  • plugins/MyPlugin/templates/search_results.mtml
  • plugins/MyPlugin/templates/foo.mtml

Template Options

When you register a template set you specify a list of template that are included in the set. This list of templates is segmented by template type. Under each template type, you list all of the templates under that type. Listed below are the supported template types:

Template Types

  • index
  • individual
  • archive
  • system
  • module
  • widget

Index Template Options

  • label - the display name of the index template
  • outfile - the name of the file this index template outputs
  • rebuild_me - 1 if this template should be rebuilt with indexes, 0 otherwise

Individual Template Options

  • label - the display name of the index template

Archive Template Options

  • label - the display name of the archive template
  • mappings - a list of all the template mappings for the template

Template Mapping Options

  • archive_type - the display name of the index template
  • file_template - the file/path template to use when generating the output file for this template
  • preferred - when multiple template mappings exist of the same type, the “preferred” mapping will be used when composing links to that archive.

Allowed Archive Types

  • Individual
  • Page
  • Monthly
  • Category-Monthly
  • Author-Monthly
  • Category

System Template Options

  • label - the display name of the index template

Module Template Options

  • label - the display name of the index template

Example

sub init_registry {
    my $plugin = shift;
    $plugin->registry({
        template_sets => {
            my_set => {
                label => "My Template Set",
                base_path => 'plugins/MyPlugin/templates',
                order => 100,
                templates => {
                    index => {
                        'homepage' => {
                            label => 'My Homepage',
                            outfile => 'index.php',
                            rebuild_me => '1',
                        },
                    },
                    individual => {
                        'entry' => {
                            label => 'Blog Entry',
                            mappings => {
                                entry_archive => {
                                    archive_type => 'Individual',
                                },
                            },
                        },
                    },
                    archive => {
                        'entry_listing' => {
                            label => 'Blog Entry Listing',
                            mappings => {
                                monthly => {
                                    archive_type => 'Individual',
                                    preferred => '1',
                                },
                                category => {
                                    archive_type => 'Category',
                                    file_template => '%c/index.html',
                                    preferred => '0',
                                },
                            },
                        },
                    },
                    system => {
                        'search_results' => {
                            label => 'Search Results',
                            description_label => '',
                        },
                    },
                    module => {
                        'foo' => {
                            label => 'Foo Module',
                        },
                    },
                },
            },
        },
    });
}
Back

4 Comments

Su

Su on February 6, 2008, 4:48 a.m. Reply

The explanatory text for the “label” field keeps referencing “index template” for most types. So does the text for “archive_type” under Template Mapping Options.

The allowed archive types list leaves out several MT archiving options(*-Daily, *-Weekly, etc). Is this actually a limitation of template sets, or just oversight?

There’s no Widget Template Options section. I assume it’s probably no different from modules, but checking.

The example code specifies a (blank) description_label field for the system template. What’s that for? It’s not mentioned above, and adding one to a template set I was working on produced no visible result.

Include a YAML example, like the Universal set uses?

http://ericschrijver.nl/about on May 22, 2009, 5:30 a.m. Reply

Very nice this code to reference my template files and make them available to the movable type installation, but where does this code itself go?

In what kind of file and where to put it? Also, this section mentions ‘the API’ without mentioning which API.

nicolas_m on June 2, 2009, 7:20 p.m. Reply

Very nice, but How do I do it? Where does this code go? Is it perl? Is there a plugin with this functionality?

zandaleph on March 15, 2010, 2:23 p.m. Reply

Having spent 4 hours digging through the source to find this: The documentation of the “base_path” parameter is out of date. MT 4.3 (at least) starts from the plugin’s directory, not from /path/to/cgi-bin/mt/ . Just omit “plugins/MyPlugin” from the above examples to get them to work. Failing to do so will result in a lot of empty templates.