Start page / Template development / Template syntax / Functions / in instructions / ref

ref(...)

The ref(...) function provides the opportunity to directly apply methods to a medium or a page reference specified via the identifier. This is particularly useful if, e.g. a design element is to be manually specified in a page template.

Syntax of ref(...)

When using ref(...) the following syntax must be adhered to:

$CMS_VALUE(ref(IDENTIFIER,
  contentId:VALUE,
  index:VALUE,
  lang:"LANGUAGE ABBREVIATION",
  language:"LANGUAGE ABBREVIATION",
  postfix:IDENTIFIER,
  res:"RESOLUTION",
  resolution:"RESOLUTION",
  templateSet:"CHANNEL NAME",
  version:CHANNEL NUMBER
).METHOD)$

All parameters, apart from the IDENTIFIER are optional.

Parameters of ref(...)

ref(...) has the following parameters:

IDENTIFIER
abs
lang/language
postfix
res/resolution
templateSet
version

IDENTIFIER

Within ref(...) the reference name of an object is specified within FIRSTspirit with the identifier.

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

Object type
Reference name of the object

The object type depends on the type of an object. The following object types exist:

File or picture from the Media Store: media
Page reference from the Site Store: pageref

If the URL of a picture from the Media Store with the reference name "suedsee" is to be determined, the following identifier must be given for ref(...):

media:"suedsee"

Alternatively a variable name or even a system object can be specified, e.g. the current page (with #global.node). Method invocations can be applied to the objects.

abs

As a default the paths determined by ref(...) (.getUrl() method) depend on the project property Absolute links. If this property is enabled ref(...).getUrl() returns absolute path details (corresponds to abs:1). If the property is deactivated, it returns relative path details (corresponds to abs:0).

The optional parameter can be used to overwrite the project property for a ref(...) specification. The following specifications can be given:

Specification	Meaning
abs:0	Returns relative path details (= default).
abs:1	Returns absolute path details with prefix
abs:2	Returns absolute path details without prefix.

Absolute path details are always absolute to the root of the web application. In generation, this is the generation directory (e.g. FIRSTspirit-Server/web/fs4staging/project_1234/2345).

To complete the URL of abs:1 the specification prefix for absolute paths is used in the schedule management. The given prefix (e.g. http://meinServer) is placed in front of the absolute path details.

Alternatively the prefix can also be specified in a template. To this end the $CMS_SET(...)$ must be used to set the value of the system object #global.urlCreator.urlPrefix accordingly:

$CMS_SET(#global.urlCreator.urlPrefix,"http://meinServer")$

This prefix is then used for all the following ref(...).getUrl() invocations.

contentId

The contentId parameter can be used to determine the reference object for the given data record.

As a value the parameter contentId expects the ID of a data record.

In the case of the identifier specified for ref(...) IDENTIFIER it must be a content projection.

Example:

$CMS_VALUE(ref(pageref:"datasource", contentId:374).METHOD)$

In the example the page reference datasource (data source) is a content projection. Here the data record with the ID 374 is to be taken into account to determine the reference object.

index

The index parameter can be used to determine a reference object for a specific sub-page, e.g. a content projection. As a value the parameter index expects the number of the required sub-page. The sub-page counting begins with 0.

Example:

$CMS_VALUE(ref(pageref:"datasource", index:3).METHOD)$

In the example the page reference datasource (data source) is a content projection. Here the 4th sub-page generated by the projection (index = 3) is to be taken into account to determine the reference object.

lang / language

When the optional attribute lang and/or language is specified the given project language is additionally taken into account in the determination of the reference object. If the parameter is not specified the current language (preview and generation) is used for the resolution.

Use of the parameter is useful for language-dependent pictures and files.

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

$CMS_VALUE(ref(media:"suedsee", lang:"EN").METHOD)$

postfix

In the case of theme-based sub-areas of the Site or Media Store it sometimes happens that all objects of a sub-area contain the same suffix (e.g. _d).

An example of a theme-based area is a teaser picture, which is to look different depending on the menu item. The reference name for the picture for this purpose could contain the common name component "teaser" and have a different suffix for each menu item. In addition a "fallback picture" can be given, which does not contain a suffix.

The determination of a reference object for use of the option parameter postfix is as follows:

First an attempt is made to find an object with the reference name and the given postfix (IDENTIFIER + postfix)
If no object is found an attempt is made to find an object without the given postfix (IDENTIFIER)

Either a fixed value enclosed in inverted commas can be given for the parameter or alternatively a variable name (e.g. from the Site Store).

Example:

$CMS_VALUE(ref(media:"suedsee", postfix:"_A").METHOD)$

In this case an attempt is first made to find a picture or file in the Media Store with the reference name suedsee_A . If a picture or file is not found an attempt is made to determine a picture or a file with the reference name suedsee .

Numerical information should not be selected for the suffix (e.g. _1) as otherwise overlapping can occur with the automatic unification of reference names. E.g. if a page reference is created in the Site Store with the reference name meineReferenz and if a page reference with the same name already exists a suffix is appended to the reference name in the form _INTEGER.

res / resolution

If, for the determination of the reference object from the Media Store a resolution other than the original resolution is to be used (resolution with the identifier ORIGINAL) the parameter res and/or resolution must be given.

A valid identifier of a resolution available in the project, enclosed in double inverted commas, is to be given as the parameter value (e.g. SCALED).

$CMS_VALUE(ref(media:"suedsee", res:"SCALED").METHOD)$

templateSet

If more than one presentation channel is defined in a project it can be useful or required to determine a reference object to another presentation channel.

The optional parameter templateSet can be used for this.

The value of templateSet must be specified as a valid identifier of a presentation channel in the project, enclosed in double inverted commas.

version

The optional parameter version corresponds to the parameter templateSet, however the number of the presentation channel is given as the value.

The presentation channel numbering in a project begins with 0, i.e. the first presentation channel has the number 0, the second has the number 1 etc.

Reference object

The ref(...) function returns a reference object which, depending on the reference type, makes available methods.

The following reference objects can be returned by the ref(...) function:

ContentProducerReference for page references
MediaReference for media

ContentProducerReference (Site Store)

The following methods can be applied to the ContentProducerReference reference object:

Method	Meaning	Return data type
ref(...).filename	Determines the file name	string
ref(...).page	Returns (if available) the referenced page from the Page Store.	Page
ref(...).target	Returns the actual element from the store, e.g. the page reference.	Element dependent, e.g. PageRef
ref(...).url	returns the URL equivalent to the $CMS_REF(...)$ instruction.	string

Output of the file name:

$CMS_VALUE(ref(pageref:"unternehmen").filename)$

Output of the unique identification number of a page reference (PageRef):

$CMS_VALUE(ref(pageref:"unternehmen").target.id)$

MediaReference (Media Store)

The following methods can be applied to the MediaReference reference object:

Method	Description	Return data type
ref(...).crc	Returns the CRC value of the picture.	Long
ref(...).description	Returns the description of a picture.	string
ref(...).extension	Returns the extension of a picture.	string
ref(...).extension("RESOLUTION")	Returns the extension of a picture for the given resolution.	string
ref(...).height	Returns the height of a picture in pixels. Note: .height can only be used for pictures.	Integer
ref(...).height("RESOLUTION")	Returns the height of a picture in pixels for the given resolution. Note: .height(...) can only be used for pictures.	Integer
ref(...).size	Returns the file size of a picture.	Long
ref(...).size("RESOLUTION")	Returns the file size of a picture for the given resolution.	Long
ref(...).target	Returns the actual element from the store, e.g. the medium.	Element dependent, e.g. Media
ref(...).url	Returns the URL equivalent to the $CMS_REF(...)$ instruction.	string
ref(...).width	Returns the width of a picture in pixels. Note: .width can only be used for pictures.	Integer
ref(...).width("RESOLUTION")	Returns the width of a picture in pixels for the given resolution. Note: .width(...) can only be used for pictures.	Integer

Output of the width:

$CMS_VALUE(ref(media:"suedsee").width)$

Output of the height:

$CMS_VALUE(ref(media:"suedsee").height)$

Output of the width for the resolution W100:

$CMS_VALUE(ref(media:"suedsee").width("W100"))$

Output of the height for the resolution H100:

$CMS_VALUE(ref(media:"suedsee").height("H100"))$

Output of the unique identification number of a page reference (Media):

$CMS_VALUE(ref(media:"suedsee").target.id)$

Print version | Page start