FirstSpirit maintains different object types in separate stores. This concept fulfils the Separation of the content, structure and layout of a website. For example, all editorially entered contents are in the Page Store of the project, all media (pictures and files) are in the Media Store, the structure in the Site Store and the display, i.e. the layout of the pages and the contents are in the Template Store.

This concept is consistently pursued, for example when an object from a store is accessed from another store, only references to the object are created. If an editor integrates a picture from the Media Store, for example, into a page of the Page Store via an input component (FS_REFERENCE), only a reference to the picture is saved in the page.

The behavior in the Template Store is analogous to this: For example, for a picture from the Media Store to be output in the browser, a reference within the Template Store must be resolved to a path with the help of the $CMS_REF(..)$ tag. To this end the tag is output in an <img> tag in the HTML template set (“HTML” tab), in the HTML area of the template. The name of the variable to be referenced is given within the brackets, in this case the name of the picture input component, for example

<img src="$CMS_REF(st_picture)$" alt="alternative_text">

$CMS_REF(...)$ resolves a reference to any object node to a path and at the same time ensures that the referenced object is available in the generated status of the project or in the preview.

The instructions $CMS_REF(...)$ and $CMS_VALUE(...)$ should not be nested in each other, e.g. $CMS_REF($CMS_VALUE(...)$)$. Method invocations can also be used in $CMS_REF(...)$, just like for $CMS_VALUE(...)$ in the identifier (see Syntax).

Syntax of $CMS_REF(...)$

The following syntax must be adhered to when using $CMS_REF(...)$:

$CMS_REF(IDENTIFIER,
  abs:VALUE,
  contentId:VALUE,
  index:VALUE,
  lang:"LANGUAGE ABBREVIATION",
  language:"LANGUAGE ABBREVIATION",
  postfix:IDENTIFIER,
  remote:IDENTIFIER,
  res:"RESOLUTION",
  resolution:"RESOLUTION",
  template:IDENTIFIER,
  templateSet:"CHANNEL NAME",
  version:CHANNEL NUMBER
)$

All parameters, apart from the IDENTIFIER are optional.

If you would like to use more than one parameter within the $CMS_REF(...)$ instruction separate them by commas, for example:

$CMS_REF(pageref:"firstspirit", lang:"EN")$

Parameters of $CMS_REF(...)$

$CMS_REF(...)$ has the following parameters:

IDENTIFIER

Within $CMS_REF(...)$ 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:

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 or document group from the Site Store: pageref
Menu level from the Site Store: pagefolder

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 $CMS_REF(...)$:

media:"suedsee"

Use pageref to create a link to the specified page reference, for example

<a href="$CMS_REF(pageref:"detail")$">more...</a>

If the page reference specified by pageref is a content projection (page reference basing on a data section) so that more than one page will be rendered, by default the page with the dataset with the highest ID will be always returned. Also filters and sortings defined on the tab “Content” will be taken into account.

When using pagefolder, by default the start page reference on the highest level below the specified structure folder (menu level) will always be used.

Alternatively a variable name or even system objects can be given, e.g. the current page (with #global.node) and method invocations can be used on these objects.

abs

As a default, the paths determined by $CMS_REF(...)$ depend on the project property Absolute Links . If this property is activated, $CMS_REF(...)$ 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 $CMS_REF(...)$ specification. The following details 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.
abs:3	Returns an internal URL for use in internal processors (e.g. creation of PDFs in FirstSpirit). Important: The specification of abs:3 is only reasonable for media.
abs:4	Returns an external URL for use in external processors. Important: The specification of abs:4 is only reasonable for media.

Absolute path details are always absolute to the root of the web application. This is in the generation the generation directory (e.g. FirstSpirit-Server/web/fs4staging/project_1234/2345).

To complete the URL of abs:1 the 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 given 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 $CMS_REF(...)$ invocations.

contentId

The contentId parameter can be used to determine the URL for the given dataset.

As a value the parameter contentId expects the ID of a dataset.

The object with the identifier given for $CMS_REF(...)$ must be a content projection (page reference basing on a page with data section).

When the parameter contentId is to be reflected in the URL, the value on the tab “Content” of the content projection for “Number of entries per page” must be 1 (i.e. only one dataset will be represented on each page).

Example:

$CMS_REF(pageref:"data_source", contentId:374)$

In the example the page reference data_source is a content projection. Here the dataset with the ID 374 is to be taken into account to determine the URL.

The result is roughly as follows:

/preview/1/site/DE/current/2/3/contentId=374

Using the parameter template the search for the dataset can be restricted to a special table template.

index

The index parameter can be used to determine the URL 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_REF(pageref:"data_source", index:3)$

In the example the page reference data_source is a content projection. The 4th sub-page generated by the projection (index = 3) is to be taken into account to determine the URL.

The result is roughly as follows:

/preview/1/site/DE/current/2/3/contentId=374

lang / language

When the optional attribute lang or language is given, the given project language is additionally taken into account in the resolution of a reference. If the parameter is omitted the current language (preview and generation) is used for the resolution.

Use of the parameter is reasonable for language-dependent pictures and files or for a required language change.

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_REF(media:"suedsee", lang:"EN")$

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. Further, there could be a “fallback picture” which does not contain the suffix.

The reference determination 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 double inverted commas can be given for the parameter or alternatively a variable name (e.g. from the Site Store).

Example:

$CMS_REF(media:"suedsee", postfix:"_A")$

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 Specification 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 _GANZZAHL (integer).

remote

Using the parameter remote links pointing to Remote projects can be generated (information about how to configure Remote projects or Remote media see page Remote access or documentation about the functionality FirstSpirit Remote-Media).

A valid licence for the Remote media access is required to be able to use the parameter remote.

As a value the parameter expects the Symbolic name assigned in the configuration of the Remote project (in the project properties).

Example:

$CMS_REF(pageref:"pagereference_test", remote:"remoteproject")$

In this example the page reference with the UID pagereference_test from the Remote project with the Symbolic identifier remoteproject will be resolved.

References to Remote projects are output analogously to those to the current local project, for example:

<a href="$CMS_REF(lt_reference_remote)$" title="$CMS_VALUE(lt_comment)$">$CMS_VALUE(lt_text)$</a>

In this example a link to the page reference selected by the input component lt_reference_remote will be generated. If the input component provides remote access (e.g. FS_REFERENCE with <PROJECTS> / <REMOTE>) and if the user selected a page reference of the remote project, this will simply be output by means of $CMS_REF(lt_reference_remote)$. (See also Chapter Link templates.)

res / resolution

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

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

$CMS_REF(media:"suedsee", res:"SCALED")$

When using remote media projects:

Using the instruction $CMS_REF(...)$ not only pictures from the same project (“target project”) can be referenced but also from remote projects. (In this case the attribute remote must be given.) When referencing pictures from remote projects it must be taken into account that remote and target projects can have different resolutions.

If the template developer specifies a special resolution by using res or resolution which does not exist in the remote project requesting a preview or generating can cause errors. The medium is displayed in the original resolution in this case.

If there are different resolutions in remote and target project with the same name (e.g. target project: resolution “thumbnail” with width 10 px, remote project: resolution “thumbnail” with width 50 px) only the resolutions of that project are evaluated the medium is selected from. If a picture from a remote Media Store is selected, only resolutions which have been configured for the remote project are used. If a picture from the locale Media Store is selected, the resolutions of the target project will be used.

Example:

the target project has got a resolution “thumbnail” (width 10 px)
the remote project A has got a resolution “thumbnail” (width 50 px)
the remote project B has got a resolution “thumbnail” (width 75 px)

In the target project then

a medium deriving from the locale Media Store of the target project with the resolution “thumbnail” will be displayed with a width of 10 px,
a medium deriving from the remote Media Store of remote project A with the resolution “thumbnail” will be displayed with a width of 50 px,
a medium deriving from the remote Media Store of remote project B with the resolution “thumbnail” will be displayed with a width of 75 px.

It is therefore advisable, when using remote projects, to define a specific resolution parameter res or resolution within templates if the resolution in target and remote projects are identical or if it is definitely sure which Media Store the selected media come from, e.g. if the selection has been restricted before by

...
 <PROJECTS>
         <REMOTE name="remoteproject">
            <SOURCES>
                 <FOLDER name="root" store="mediastore"/>
            </SOURCES>
         </REMOTE>
 </PROJECTS>
...

(see for example FS_REFERENCE).

Controlling automatically generated images in projects

Images can occur in different file types (such as JPEG) and resolutions in a project. Each image is initially stored unchanged in the project, i.e. in the format in which it was uploaded to the Media Store (resolution ORIGINAL).

Some actions trigger an automatic generation of new image files, based on the original image data, for example:

generating a preview image
creating new resolutions
using an automatically generated resolution
cropping an image in ContentCreator or in SiteArchitect

This generation process can be controlled via parameters.

Examples of use:

influencing the compression rate of JPG images in order to achieve increased image quality or reduced file size when generating images
preset the image type (e.g. WebP)

Project configuration

The calculation can be influenced with the custom ImageWriterParams project property.

Custom project properties (CUSTOM_PROPERTIES) can exclusively be added via the FirstSpirit Access-API (using setCustomProperties) and can not be defined with the FirstSpirit ServerManager (see Project interface in package: de.espirit.firstspirit.access.project, FirstSpirit Access API).

Beanshell example script for creating a new configuration:

project = context.getProject(); 
project.lock(); 
properties = new java.util.LinkedHashMap(); 
properties.put("thumbnail.jpg.compressionQuality", "0.75"); 
properties.put("default.jpg.compressionQuality", "0.75"); 
properties.put("resolution.HeaderPicture.jpg.compressionQuality", "0.95"); 
properties.put("resolution.HeaderPicture.png.compressionQuality", "0.95"); 
project.setCustomProperties("ImageWriteParam", properties); 
project.save(); 
project.unlock();

The parameters should be passed via a LinkedHashMap.
The script must be executed with administrator permissions in the desired project.
The respective configuration is applied to all images from which corresponding resolutions are used.

Using the methods of the ImageWriteParam class
All methods of the ImageWriteParam class can be configured (see https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/imageio/ImageWriteParam.html). Since some methods depend on each other, the parameters should be added in the desired sequence.

resolution.<RESOLUTION_NAME>.<FILE_TYPE>.<SETTER_METHOD_NAME>

(with the keyword set being optional)

Preview images use thumbnail instead of resolution.<RESOLUTION_NAME>, as depicted in the example above.

The default value for compressionMode is MODE_EXPLICIT, but other values can be if desired.

Using the parameter targetType
Furthermore, the targetType parameter can be used. It can be used to specify the image format of automatically generated images.
Example script that creates all automatically generated image files in WebP format:

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
properties.put("default.targetType", "webp");
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock();

In addition, corresponding definitions can be defined for individual image formats and/or resolutions.
Here, the setting for the current specific image type is used. If not available, the global setting is used for the resolution and as a fallback.
Example script that keeps the type PNG for PNG images, uses the type JPG for the resolution “Icon” and applies the type WebP for all other scaled images:

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
properties.put("default.targetType", "webp");
properties.put("default.png.targetType", "png");
properties.put("resolution.Icon.targetType", "jpg");
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock();

Each image format has a specific ImageWriteParm implementation that may differ from other image formats in terms of possible parameters (the parameters are generically mapped to setter methods of ImageWriteParm) and behaviour.

Using the parameter discardMetadata

The project property ImageWriteParam can be used to discard metadata of the original image (e.g., EXIF information) when generating images. By default, these are taken over.

In the following example, the property is configured to discard metadata for all images expect for PNG files.

project = context.getProject(); 
project.lock(); 
properties = new java.util.LinkedHashMap(); 
properties.put("default.discardMetadata", "true"); 
properties.put("default.png.discardMetadata", "false"); 
project.setCustomProperties("ImageWriteParam", properties); 
project.save(); 
project.unlock();

Reading out an existing configuration
Use the following method to read the current configuration:

context.project.getCustomProperties("ImageWriteParam");

If no configuration is set, the return value will be <null>.

Deleting / resetting an existing configuration
Overwriting an existing configuration with an empty configuration removes the existing configuration, e.g.

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock();

template

The parameter template provides the possibility to confine the parameter contentId and must be given together with this parameter. With template the search, accomplished by contentId, can be narrowed to a specific table template by specifying the UID of this table template, if e.g. two table templates represent the same dataset. The use of template is e.g. reasonable to link a dataset in a specific representation / layout, e.g. in a detailed view.

As a value the parameter template expects the UID of a table template.

The search is started in this case from a structure folder (object type pagefolder). Here, always the start page reference which lies on the highest level below the specified structure folder (menu level) will be returned. This start page reference must be a content projection if the definition of contentId is expected to have an impact.

If you would like another page reference than the start page reference to be respected you should use the parameter template.
Example:

$CMS_REF(pagefolder:"root", contentId:322, template:"products.product_group")$

n this example a page of a content projection is searched for, beginning at the root node of the Site Store, which is rendering the dataset with the ID 322 on the basis of the table template products.product_group.

templateSet

If more than one template set is defined in a project it may, e.g. be useful or required to switch between two channels of a page (display of a print version).

This is done using the optional parameter templateSet.

The value of templateSet must be given as a valid identifier of a template set 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.

Using JSP Includes

Identifying the preview URL for ContentCreator

Addition HTML or JSP fragments may be inserted into a (FirstSpirit) page by using JSP includes. For example, content that should be used in many places in a project (e.g. “header” and “footer” definitions that should be consistent across all pages) can be outsourced to separate (FirstSpirit) pages, and these separate pages can then be included in actual content pages using JSP includes. The JSP engine inserts the outsourced content during run-time and executes it in the context of the including page. The evaluated output of the outsourced content is projected into the generation result of the including page.

In order to use this functionality in the ContentCreator preview as well, it is necessary to adhere to the following syntax:

 <%
 final String fullUrl = "$CMS_REF(pageref:"jspinclude")$";           
 // 'fullUrl' contains the contextPath (and sub session id template in ContentCreator)           
 // => The jsp:include tag expects the servlet path without the prefix           
 final String includeUrl = fullUrl.substring(fullUrl.indexOf("/preview"));       
 %>       
 <jsp:include page="<%= includeUrl %>" />

Note: Use of request.getContextPath() is not possible here. Although this method's output contains the correct context path, it is slightly different from the context path given by the return value of $CMS_REF(...)$ in ContentCreator due to the cross-session nature of the preview cache and the identifying attribute for the sub-session ID in ContentCreator URLs (e.g. /fs5webedit/s=df15).

Examples of $CMS_REF(...)$

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: Display of a print version

Code example:

$CMS_REF(#global.node, templateSet:"print")$

Description:

By specifying #global.node the currently generate page reference (preview, deployment, etc.) is determined.
By specifying print for the parameter templateSet, the URL for the generated page reference is to be resolved in the template set with the identifier print.

Output:

e.g. ../../de_1/suedsee.html

2nd Example: Picture with another resolution

Code example:

$CMS_REF(media:"suedsee", res:"100_HOCH")$

Description:

Instead of the original resolution of the picture suedsee, the reference to the picture is to be determined with the resolution 100_HOCH. The resolution 100_HOCH scales the picture to a height of 100 pixels.

Output:

e.g. ../../media/suedsee_100_HOCH.png

Print version | Page start