$CMS_INCLUDE(...)$

Using $CMS_INCLUDE(...)$

The instruction $CMS_INCLUDE(...)$ can be used to insert contents of a file from the Media Store into a template.

On insertion it is possible to specify with which coding (“encoding”) the content is to be inserted and whether the FirstSpirit expressions are to be analysed or not.

Syntax of $CMS_INCLUDE(...)$

The basic structure of $CMS_INCLUDE(...)$ is as follows:

$CMS_INCLUDE(
  IDENTIFIER,
  parse:BOOLEAN_VALUE,
  encoding:ENCODING,
  language:LANGUAGEABBREVIATION
)$

Within a $CMS_INCLUDE(...)$ statement, multiple parameters are passed comma separated, e.g.:

$CMS_INCLUDE(media:"css", parse:true, language:#global.project.masterLanguage)$

IDENTIFIER

Within $CMS_INCLUDE(...)$ the reference name of an object within FirstSpirit is given with the identifier.

If the object is specified manually the identifier consists of two parts:

1. Object type
2. Reference name of the object

The object type depends on the type of an object. The following object types are valid for the $CMS_INCLUDE(...)$ instruction:

• File or picture from the Media Store: media
• File from the Media Store: file

Wenn eine Datei aus der Medien-Verwaltung mit dem Referenznamen “stylesheet” eingebunden werden soll, so ist folgender Bezeichner für $CMS_INCLUDE(...)$ anzugeben:

file:"stylesheet"

If a file from the Media Store is to be integrated with the reference name “suedsee” the following identifier must be given for $CMS_INCLUDE(...)$:

medium:"suedsee"

Alternatively a variable name can be given.

parse

The attribute parse can be used to specify whether, on inserting the contents of the file - irrespective of the “Parse File” setting of a file (see File level (→Documentation FirstSpirit SiteArchitect)) - FirstSpirit expressions are to be replaced (value: true) or not (value: false).

If the parse parameter is not given the “Parse File” setting of the file in the Media Store is used.

encoding

The attribute encoding is used to specify with which coding the content of the file - irrespective of the coding of the file in the Media Store (see Creating media (→Documentation FirstSpirit SiteArchitect)) - is to be output.

If the encoding parameter is not given the coding setting of the file in the Media Store is used.

All codings available for Java are allowed to be used to specify the coding (cf. Java API Documentation).

lang / language

Using the attribute lang or language you can take into account a project language when outputting the file. If the parameter is omitted, the file will be used in the current language.

Use of this parameter is only reasonable for language-dependent media.

A valid language abbreviation for the project must be given in double inverted commas as the value for the attribute, (e.g. lang="DE"):

$CMS_INCLUDE(file:"stylesheet", lang:"DE")$

As an alternative, a language instance can be passed. For example, you can use #global.project.masterLanguage to define that the master language version of the file is to be used:

$CMS_INCLUDE(file:"stylesheet", lang:#global.project.masterLanguage)$

Examples of $CMS_INCLUDE(...)$

Several examples of use of the instruction within templates are shown in the following. The examples are intended to clearly show the specific effect of the instruction and provide help for the template developer when creating their own templates.

The examples displayed here must be adjusted for use within a project! For example, variable names must be changed to the specific variable names of the project in which the instruction is to be used.

1st Example: (Parsed output)

Code example:

$-- content of the "css" file in the Media Store --$
<pre>
  Example of a parsed/unparsed, included file:
  The value of the "output" variable is: $CMS_VALUE(output)$.
</pre>

$-- template content --$
$CMS_SET(output,"This is an output")$$CMS_INCLUDE(media:"css",parse:true)$

Description:

In the code example given above the content of the “css” file from the Media Store is output parsed or is inserted in a template.

Output:

<pre>
  Example of a parsed/unparsed, included file:
  The value of the "output" variable is: This is an output.
</pre>

2nd Example: (Unparsed output)

Code example:

$-- content of the "css" file in the Media Store --$
<pre>
  Example of a parsed/unparsed, included file:
  The value of the "output" variable is: $CMS_VALUE(output)$.
</pre>

$-- template content --$
$CMS_SET(output,"This is an output")$$CMS_INCLUDE(media:"css",parse:false)$

Description:

In the code example given above the content of the “css” file from the Media Store is output unparsed or is inserted in a template.

Output:

<pre>
  Example of a parsed/unparsed, included file:
  The value of the "output" variable is: $CMS_VALUE(output)$.
</pre>