Type DATABASE

Using the type DATABASE data sets of an external table can be inserted automatically into a set-valued input component (e. g. CMS_INPUT_COMBOBOX).

If a data source with many data sets (>100) is referenced, we recommend to use FS_INDEX (with DataAccessPlugin implementation) instead for performance reasons.

As of FirstSpirit 5.2R4, the display is limited to 100 entries. If more than 100 datasets are available, the following message will be shown in the form: “The list of available entries has been truncated due to browser limitiations. This input component is not suitable for lists of this size.” Please note that rules will only be applied to the entries displayed in the form.

Parameter

The CMS_INCLUDE_OPTIONS tag is a container with which configurations can be specified to automatically insert entries in an input component.

Overview

type

The mandatory parameter type is used to give the type of value or content inclusion.

The following types are supported:

• LANGUAGE: output of project languages
• TEMPLATESET: output of the project's template sets
• DATABASE: output of the content of data sources
• PUBLIC: output of the content which is made available via a public interface

• Optional parameters
  Further optional and mandatory parameters or tags can be used with these types (see below).

Type LANGUAGE

Using the type LANGUAGE the languages, defined in the project, can be inserted automatically into set-valued input components (which allow to select from several values, e.g. CMS_INPUT_COMBOBOX).

• Mandatory parameters
  The tag LANGUAGE does not need any other parameter.
• Optional parameters
  You can use the tags LABELS / LABEL with the tag LANGUAGE (see below).

Type TEMPLATESET

Using the type TEMPLATESET the output template sets which are defined in the project can be inserted automatically into a set-valued input component (e.g. CMS_INPUT_COMBOBOX).

• Mandatory parameters
  The tag TEMPLATESET does not need any other parameter.
• Optional parameters
  You can use the tags LABELS / LABEL with the tag TEMPLATESET (see below).

Type DATABASE

Using the type DATABASE data sets of an external table can be inserted automatically into a set-valued input component (e.g. CMS_INPUT_COMBOBOX).

• Mandatory parameters
  The data source from which the data sets are to be selected must be specified by the tag TABLE (see below).
• Optional parameters
  You can use the tags KEY and LABELS / LABEL with the tag DATABASE (see below).

Type PUBLIC

With FirstSpirit you can develop and implement own modules. Using the type PUBLIC interfaces ("HotSpots") of the type "Public" can be addressed (for further information about this component type and about the development of modules in FirstSpirit please see Module Architecture / Component Model.

• Mandatory parameters
  The name of the HotSpot class must be specified by the tag NAME (see below).
• Optional parameters
  You can use the tags PARAMS / PARAM and LABELS / LABEL with the tag PUBLIC (see below).

Overview

LABELS

A language-dependent label for the values of one type can be defined by using the tag LABELS.

One LABEL tag must be specified for each language.

WARNING: At least a definition for the fall back labelling ("*") must be given:

<LABELS>
 <LABEL lang="*">...</LABEL>
</LABELS>

LABEL

A flexible, language-dependent labelling can be defined for the individual options in each language using the tag LABEL.

For defining the labelling for a language, the abbreviation of the respective project language must be given with the parameter lang:

...
<LABEL lang="DE">...</LABEL>
<LABEL lang="EN">...</LABEL>
...

Return values are specified by using the special language abbreviation * ("for all languages"):

...
<LABEL lang="*">...</LABEL>
...

The parameter lang is a mandatory parameter.

The labelling text is given within an opening and closing <LABEL> tag (see place holder TEXT).

Overview

lang

The lang parameter is used to give the language abbreviation which is entered in the server properties see Language templates (→Documentation for Administrators)) to specify for which project languages the definitions are to apply, e.g. DE for German, EN for English, FR for French etc. The following characters can be used as often as required: -, _, 0-9 and A-Z. Lower case letters are transformed automatically into upper case letters after having saved the template. In addition * can be used for fallback values.

Overview

TEXT

At this point the labelling text of the values, from which the editor can select, is defined.

For this purpose the system object #item is at your disposal. The labelling can be output dynamically by using this system object.

In the case of the data type DATABASE #item specifies e.g. which row of the database, which is defined by the tag TABLE, is to be displayed. One column of the database row can be used for the labelling, separated by a dot, e.g. #item.Headline_EN.

Furthermore, language-specific endings are added automatically by means of the expression mechanism, if they are existing. I.e. the following definition can be given:

<CMS_INCLUDE_OPTIONS type="DATABASE">
 <TABLE>Products.press_releases</TABLE>
 <LABELS>
 <LABEL lang="*">#item.Headline + ", " + #item.Subheadline</LABEL>
 </LABELS>
</CMS_INCLUDE_OPTIONS>

Here, first attributes with language extension are looked for, depending on the language in which the project is to be generated (e.g. #item.Headline_EN for the language EN), and then, if no language extension can be found, attributes with a given name are looked for.

Please pay attention that the column name is specified correctly and that the columns really exist in the specified table. Otherwise there will not be displayed any values for selection. If using KEY please pay attention that the labelling, which is defined dynamically via LABEL and #item, fits to the column, which is defined via KEY. Otherwise, the editor gets a corresponding error message when selecting an option.

KEY

The optional tag KEY specifies the column of the data source, which is to be used for storing the selected value. The name of the column must be given as it has been specified in the datenbase schema editor. For example, this name can be found on the tab "Mapping" of the respective table template in the language-dependent columns (DE, EN etc.). If any labelling of the values is defined by using the common tags LABELS / LABEL the labelling of the column, specified via KEY, will be displayed.

If the tag is omitted the primary key will be used (default).

This parameter should only be used if the users themselves can guarantee the uniqueness of the data when maintaining the column given for KEY!

TEXT

Here, the table row must be specified, between an opening and a closing KEY tag:

<KEY>TABLEROW</KEY>

QUERY

The QUERY tag can be used to define a query, on the basis of which the quantity of data sets from which a selection can be made with the help of the input component is limited.

If the query contains the placeholder %lang% within an ORDERCRITERIA tag, the ORDERCRITERIA tag is ignored and a corresponding message is displayed in the log.

Overview

name

The name parameter is used to provide the reference name of the query, e.g.

<QUERY name="query_products"/> 

Overview

PARAM

If parameters are available for the query defined via QUERY ("Parameter" tab of the query), a value can be transferred to these parameters with the PARAM tag.

Overview

name

The name parameter is used to provide the name of the query parameter.

Overview

TEXT

The value of the query parameter is given within an opening and closing PARAM tag, e.g.

<QUERY name="query_products">
 <PARAM name="category">1088</PARAM>
</QUERY>

where "category" is a parameter defined for the query and "1088" is the value.

TABLE

The TABLE tag is used to give the reference to the table template.

The value given must be the unique identifier of the table template.

The reference is required to specify from which table selections can be made and which input components are to be displayed.

TEXT

Here, the table template must be specified, between an opening and a closing TABLE tag:

<TABLE>TABLETEMPLATE</TABLE>

IncludeType	Type of value or content inclusion TEMPLATESET List of the template sets defined in the project LANGUAGE List of the project languages DATABASE Data sets from an external table PUBLIC Data via interfaces ("HotSpots") of the type "Public"
String	A random character string

Examples

Example for the use of CMS_INCLUDE_OPTIONS, type DATABASE:

<CMS_INPUT_COMBOBOX name="IDENTIFIER" useLanguages="no">
    <CMS_INCLUDE_OPTIONS type="DATABASE">
      <LABELS>
        <LABEL lang="*">#item.COLUMN</LABEL>
        <LABEL lang="EN">#item.COLUMN_EN</LABEL>
      </LABELS>
      <TABLE>UNIQUE_NAME_TABLETEMPLATE</TABLE>
      
    </CMS_INCLUDE_OPTIONS>
        <LANGINFOS>
            <LANGINFO lang="*" label="TEXT" description="TEXT"/>
            <LANGINFO lang="EN" label="TEXT" description="TEXT"/>
        </LANGINFOS>
  </CMS_INPUT_COMBOBOX>

This example returns a combobox with the label TEXT from which the data sets of the data source, basing on the table template, which is indicated by TABLE, can be selected. The selection is language dependent and depends on the column COLUMN.

Example of use in the template syntax

The following example compares the use of CMS_INCLUDE_OPTIONS and the use of CMS_INCLUDE_CONTENT.

You can create a combobox, from which the press releases of a data source (in this case: "Products.press_releases") can be selected language-dependent on the basis of the headline (in this example column "Headline"), using CMS_INCLUDE_CONTENT in this way:

<CMS_INPUT_COMBOBOX name="cs_pressReleases" useLanguages="no">
   <CMS_INCLUDE_CONTENT table="Products.press_releases" type="entries">
      <LABEL lang="*">#row.Headline</LABEL>
   </CMS_INCLUDE_CONTENT>
   <LANGINFOS>
      <LANGINFO lang="EN" label="Press release"/>
      <LANGINFO lang="*" label="Press release"/>
   </LANGINFOS>
 </CMS_INPUT_COMBOBOX> 

The syntax using CMS_INCLUDE_OPTIONS:

<CMS_INPUT_COMBOBOX name="cs_pressReleases" useLanguages="no">
    <CMS_INCLUDE_OPTIONS type="DATABASE">
      <LABELS>
        <LABEL lang="*">#item.Headline</LABEL>
      </LABELS>
      <TABLE>Products.press_releases</TABLE>
    </CMS_INCLUDE_OPTIONS>
    <LANGINFOS>
      <LANGINFO lang="EN" label="Press release"/>
      <LANGINFO lang="*" label="Press release"/>
    </LANGINFOS>
  </CMS_INPUT_COMBOBOX>

Depending on the specific needs of your project, even more than one column can be specified using LABEL, e.g.:

<CMS_INPUT_COMBOBOX name="cs_pressReleases2" useLanguages="no">
    <CMS_INCLUDE_OPTIONS type="DATABASE">
      <LABELS>
        <LABEL lang="*">#item.Date.format("dd.MM.yyyy") + ": " + #item.Headline</LABEL>
      </LABELS>
      <TABLE>Products.press_releases</TABLE>
    </CMS_INCLUDE_OPTIONS>
    <LANGINFOS>
      <LANGINFO lang="EN" label="Press release"/>
      <LANGINFO lang="*" label="Press release"/>
    </LANGINFOS>
  </CMS_INPUT_COMBOBOX>

This example returns a combobox with the label "Press release", from which the datasets of the data source, basing on the table template "Products.press_releases", can be selected language-dependently by means of the headline (in this example column "Headline") and of the date (in this example column "Date"). Date and headline are separated by a colon, e.g.

07/08/2020: e-Spirit partnerships on the rise due to demand for rapid delivery ... 
05/18/2020: e-Spirit partners with Commercetools to deliver immersive e-Commerce ... 
04/21/2020: e-Spirit integrates with SAP Commerce Cloud's decoupled PWA ...
...