Not a developer? Go to MovableType.com

Documentation

Include

Includes the contents of a template module or external file into the current template where is it used.

<$mt:Include module="Sidebar"$>

Attributes

Note: One of the following attributes is required and not more than one may be used:


blog_id

Used to include a template from another blog in the system. Use in conjunction with the module, widget, or identifier attributes.

<$mt:Include module="Sidebar" blog_id="1"$>

Using a value of “0” will include a global template module, same as if the global attribute is used.

cache

Enables caching of the contents of the include. Used in conjunction with the ‘cache_key’ attribute. Suitable for module, widget, or identifier includes. Default value is “0”.

<mt:SetVarBlock name="cache_key"><mt:EntryCategory></mt:SetVarBlock>
<$mt:Include widget="Related Entries" key="$cache_key" ttl="3600" cache="1"$>

cache_key

Unique cache id use the template module. Used in conjunction with the ‘cache’ attribute. Suitable for module, widget, or identifier includes.

See cache for example.

file

NOTE: In Movable Type 5.13, 5.07, 4.38, and later versions, this attribute is disabled in default settings. You can enable it by specifying AllowFileInclude configuration directive.

The path to an external file on the system. The path can be absolute or relative to the Local Site Path. This file is included at the time your page is built. It should not be confused with dynamic server side includes like that found in PHP.

<$mt:Include file="/var/www/html/some-fragment.html"$>

global

Forces an Include of a globally defined template even if the template is also available in the blog currently in context. Default value is “0”.

<$mt:Include module="Sidebar" global="1"$>

(For module, widget, and identifier inc. Doesn’t have any effect on including file attribute.)

parent

Forces an Include of a template in the parent website. Default value is “0”.

<$mt:Include module="Sidebar" parent="1"$>

(For module, widget, and identifier inc. Doesn’t have any effect on including file attribute.)

identifier

For selecting Index templates by their unique identifier.

<$mt:Include identifier="main_index"$>

key

Alias of cache_key.

module

The name of a template module in the current blog.

<$mt:Include module="Sidebar"$>

name

For application template use: identifies an application template by filename to load.

ssi

Causes the include to be handled as a server-side include. Default value is “0”. If “1” is specified instead, mt:Include tag generates a SSI file with the format which you set in the blog settings ( [Settings] > [General] > Module Settings ).

For example if you have set it to “PHP Includes”

<$mt:Include module="Tag Cloud" ssi="1"$>

This tag outputs a php include tag:

<?php include("/path/to/blog/includes_c/tag_cloud.php") ?>

Suitable for module, widget, and identifier includes.

ttl

Specifies the lifetime in seconds of a cached template module. Suitable for module, widget or identifier includes.

See cache for example.

widget

The name of the widget in the current blog to include.

<$mt:Include widget="Search Box"$>

Examples

Also, other attributes given to this tag are locally assigned as variables when invoking the include template.

Variables in Attribute Values

Variables may be passed into the values. If various template modules were created for each category (such as “Foo Sidebar” for category “Foo” and “Bar Sidebar” for category “Bar”) then you could include the templates like this on an Entry archive template. This example also includes a default template if there is no category:

<mt:SetVarBlock name="sidebar_template"><$mt:EntryCategory$> Sidebar</mt:SetVarBlock>
<mt:If tag="EntryCategory">
    <$mt:Include module="$sidebar_template"$>
<mt:Else>
    <$mt:Include module="No Category Sidebar"$>
</mt:If>

Passing Parameters

Parameters may be defined before including a template or may be passed to the included template module as custom attribute. One variable (section_subtitle) is defined using the Var tag and the second variable (section_title) is defined as an attribute of the mt:include tag:

<$mt:Var name="section_subtitle" value="I am the subtitle"$>
<$mt:Include module="Section Header" section_title="Elsewhere"$>

The “Section Header” template module uses the values set by the include:

<h1><$mt:Var name="section_title" _default="Default Title Here"$></h1>
<h2><$mt:Var name="section_subtitle" _default="Default Subtitle Here"$></h2>
Back

6 Comments

Jason

Jason on August 3, 2007, 5:18 p.m. Reply

This should document the new parameters to MTInclude that we now see in the default Header template module:

<$mt:Include identifier="styles" trim_to="0"$>

As far as I can tell, there’s not one lick of documentation about these two parameters, identifier and trim_to.

Matt Jacobs

Matt Jacobs on December 20, 2007, 7:56 a.m. Reply

I’m not sure if it’s supposed to, but I could not get identifier to work with multiblog using either the <mt:multiblog> tag or blog_id/include_blogs in the <mt:include]>tag.

Papi Chulo

Papi Chulo on July 24, 2009, 12:04 p.m. Reply

When passing parameters via mt:include, don’t use dashes in the parameter name, as they are interpreted as operators.

Dashes are bad:

<$mt:Include module="foo" my-variable="bar"$>

CamelCase is good:

<$mt:Include module="foo" myVariable="bar"$>

Underscores are also good:

<$mt:Include module="foo" my_variable="bar"$>

Inside the included template module you can use the variable you set.

Template Module “foo”:

<div>
    <$mt:Var name="myVariable"$>
    <$mt:Var name="my_variable"$>
</div>
Jay Allen

Jay Allen on July 25, 2009, 3:44 a.m. Reply

@Papi Chulo: Welcome to “How Perl sometimes infiltrates the templates 101”. Your template variable name has to be a valid hash key so spaces and crazy ass characters are also out.

@Jason, @Matt - Identifier works perfectly well. @jason are you sure that your stylesheet HAS the template identifier “styles”? That what the default MT templates do but, for example, you’ve applied another template set, there’s no requirement that they use that convention.

select template_name, template_identifier from mt_template where template_identifier like '%[A-Za-z]%"
Jay Allen

Jay Allen on October 30, 2009, 3:13 a.m. Reply

I just noticed that there’s no mention of the local attribute to mt:include. This is an important attribute which tells MT to first place to look for a module matching the given name is in the blog that contains the template being produced. This is sometimes different from the default action of looking in the blog currently in context. This is better explained with code…

If you create an index template with only the following code, the two lines below are identical in their behavior:

<mt:include module="Blah">
<mt:include module="Blah" local="1">

However, if the blog context changes during the template build, they diverge. Below, the mt:include with the local attribute acts exactly the same as above. The one without the local attribute looks for the module in the parent blog of the entry in context in the mt:entries loop:

<mt:entries include_blogs="all">
    <mt:include module="Blah">
<mt:entries>

<mt:include module="Blah" local="1">

Perhaps even more mind-bending, let’s say the template above is in blog ID 1 and an index or archive template in Blog ID 2 includes the above code like so (or equivalent):

<mt:include module="Main index" blog_id="1">

The include within the mt:entries loop still looks in each entry’s parent blog for the module, but the include with the local attribute looks in blog ID 2!

The way to think about it is that “local” means the blog containing the index, archive or system template being produced.

Anne Hegset

Anne Hegset on September 3, 2012, 8:20 p.m. Reply

So, should we use dashes or not?

Leave a Comment