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>
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:
As far as I can tell, there’s not one lick of documentation about these two parameters, identifier and trim_to.
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 orblog_id
/include_blogs
in the<mt:include]>
tag.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:
CamelCase is good:
Underscores are also good:
Inside the included template module you can use the variable you set.
Template Module “foo”:
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.
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:
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 thelocal
attribute looks for the module in the parent blog of the entry in context in themt:entries
loop: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):
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 on September 3, 2012, 8:20 p.m. Reply
So, should we use dashes or not?