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',
                        },
                    },
                },
            },
        },
    });
}