include

Written by Balazs Halasy, 02/06/2004 Updated 04/28/2005 by Balazs Halasy

Summary

Includes a file.

Usage

{include uri='path_to_file' [ name='namespace' ] [ parameter(s)='value(s)'  ]}

Parameters

Name	Type	Description	Required
uri	string	Path + name of the file that should be included.	Yes.
name	string	Alternative namespace for the included template.	No.
other parameters	any	Parameters that will be passed to the included template.	No.

Description

This function includes a file in the template from where the function was called. The "uri" parameter must be used to specify the target file. In most cases, the value of this parameter starts with a "design:", which tells the system to look for the desired template within the current (and fallback) design resources. The "name" parameter can be used to specify an alternative namespace for the included template, this is useful for avoiding variable name clashes when including other templates. All other parameters will be passed to the included template as template variables. This function makes it possible to share template code among different parts of the solution.

Examples

Example 1

{include uri='design:example/menu.tpl' something='Hello world'}

This example demonstrates how to include a template called "menu.tpl" (which is located within the "example" subdirectory of the "templates" directory. If Exponential is unable to find the template in the current design, it will automatically attempt to locate it in one of the fallback designs or the standard design. The value of the "something" parameter will be available through a variable called $something within the template that is included.

Contributors

Balazs Halasy Author 02/06/2004 Updated 04/28/2005
James Robertson Commenter 09/26/2005
Gaetano Commenter 11/01/2009
James Ward Commenter 02/21/2006
Bertrand Dunogier Commenter 02/27/2006
P. Renaud Commenter 02/28/2007
Seb Commenter 05/17/2008
André Rømcke
Adrien Commenter 07/28/2009
Pike Commenter 01/28/2010
Claudio B. Commenter 04/01/2009
test Commenter 12/02/2009
GX Admin Commenter 12/30/2009

Comments (12 historical)

Written by readers of the earlier documentation sites, kept as they were.

What schemas does the URI attribute support

James Robertson · 09/26/2005 01:52 am

'In most cases, the value of this parameter starts with a "design:"...'
What are the 'other' cases? Does this function support other URI schemas such as 'http:'?
1. Re: What schemas does the URI attribute support
  
  Gaetano · 11/01/2009 11:35 pm
  
  At the moment the only other allowed case if 'file'. When used, the path to the desired template needs to be specified starting from the Exponential root dir. Afaik, neither the design fallback chain nor the override system will be triggered by such an include.
Include limits

James Ward · 02/21/2006 10:48 pm

What are the limits on includes? Can I include within an included file? Can I include within an override? Can I include the same file within itself?
1. Re: Include limits
  
  Bertrand Dunogier · 02/27/2006 07:16 pm
  
  - Can I include within an included file?
  Yes
  - Can I include within an override?
  Yes
  - Can I include the same file within itself?
  Yes

Can I use include with...

P. Renaud · 02/28/2007 03:33 pm

You cannot guess this by reading the doc, so I tried,and :
- an array as parameter value ? Yes !

{def $my_param=array(10, 20, 30)}
{include uri='design:display_array.tpl' param=$my_param}

- a hash array as parameter ? Yes !

{def $my_param=hash('abc', 'ABC', 'de', 'DE', 'fghi', 'FGHI')}
{include uri='design:miscellaneous/display_array.tpl' param=$my_param}

- a node ? Yes !

{def $my_param=$node}
{include uri='design:miscellaneous/display_array.tpl' param=$my_param}

Inlude templates located into override

Seb · 05/17/2008 03:57 pm

Hi,
Is there anyway to include a template located into mydesign/override/templates/... by using this function ?
I do not succeed although I tried several syntax...
1. Re: Inlude templates located into override
  
  André R. · 08/28/2008 10:44 am
  
  You could in 3.x but not in 4.0 and higher. Now overrides/ are for overrides.
  1. Re: Re: Inlude templates located into override
    
    Adrien · 07/28/2009 04:15 pm
    
    And include follow overrides. So you can't include the original template into an override template. Which could have been useful. Now to factorize design (same design, different data_map) I often write a generic template at the root of design and include it into the view and her overrides.
  2. Re: Re: Inlude templates located into override
    
    pike · 01/28/2010 02:13 pm
    I've been able to include a template located in the design/override folder in a template located in the design/templates folder, if that is the question. in ezp 4.0.3,
    {include uri="file:design/yourdesignhere/override/templates/yourstuff.tpl"}
    worked,
    *-pike
Name spaces

Claudio B. · 04/01/2009 03:40 pm

Do you mean that any variable I declare with def is global?
Maybe it's because any include literaly inject code in template?
Should I edit any included files from admin.

test · 12/02/2009 06:30 am

Should I edit any included files from admin.
Please suggest.
Not really agree with 'includes a file'

GX Admin · 12/30/2009 03:36 pm

In reality, this function tries to execute a TPL file and then inserts the result. Not all kind of file...
If you want to include the content of a CSS file for example, all css brackets { } will be executed like template instructions (and a template engine crash will occur... blank page...).
There is no way to indicate that the file is not a tpl one (so a literal content instead) ?
I want to include the content of a file (like a CSS one) which has no {literal} tag inside (I cannot add it myself).

Comments

Add a comment