Snippets

The “Snippet” tab can be used for some template types to define how FirstSpirit objects are to be displayed based on these templates (e.g., pages, sections, datasets) in SiteArchitect and in ContentCreator (abbreviated, “teasers”).

The aim is to display FirstSpirit objects not just with their names (i.e., depending on the object type: the page name, section name, dataset ID, etc.), but with:

• an image (in the “Thumbnail” area)
• a title (in the “Label” area)
• a text excerpt (in the “Extract” area)

which represent the respective object as accurately as possible. This gives the editor a clear idea of what the objects contain so that, in the case of searches, for example, he or she can identify the most relevant hit more easily and access the object he or she is searching for more quickly.

Schema of referenced objects (click to enlarge)

This means that content from

1. input components of the associated template (“Form” tab) or
2. objects referenced in the template input components (e.g., pages referenced using FS_REFERENCE, page references, media, or datasets referenced using FS_DATASET)

can be used.

The schema opposite shows for case 2. the form of an element (here: section; Page 1 / Section 1) in which a page reference (Page 2) has been selected using FS_REFERENCE (identifier st_link). Content from the selected page reference (Page 2) can be used for the snippet definition of the section template on which Section 1 of Page 1 is based. This particularly affects link templates in which FS_REFERENCE is frequently used to select page references (for more information, also see the Snippets in link templates section). See also the table below, examples of FS_REFERENCE, object type “Page reference”.

If snippets are to be used, consideration should be paid in advance regarding which content from the available input components of the associated template best characterizes the FirstSpirit object in question (e.g., section, page, dataset) and how it can be used to distinguish between objects and / or object types. It is important for the user to be able to quickly enter the object that is represented by the snippet. Attention should also be paid to the fact that with this type of display, structural information (e.g., What object type is it? Where is the object located in the hierarchy?) becomes a secondary priority.

The definitions on the “Snippet” tab are currently used, for example, as follows:

• In SiteArchitect:
  • For outputting search results from the global search
  • For displaying datasets in the detail view (Data sources Store)
• In ContentCreator:
  • For outputting search results from the global search
  • For selecting templates (creating new pages, sections, and datasets, selecting internal references)
  • For displays in search dialogs
  • For displaying bookmarks, tasks, related objects, My changes in the report area
  • For tooltips in CMS_INPUT_DOM and CMS_INPUT_DOMTABLE (for more information, see the "Snippets in link templates" section)

The following figure shows a global search result in SiteArchitect and in ContentCreator:

General syntax information

As many characters as are required can be entered in the fields on the “Snippet” tab. If more characters are present than the text field can display, the text field is provided with a scroll bar.

Fallback output
If no definition is specified in the fields on the “Snippet” tab, the name of the object and the path to the object are generally displayed by default at the relevant locations; in the case of links, no tooltip is displayed in ContentCreator (see section Snippets in link templates). The same applies if the input components accessed by the snippet definition have not been filled by the editor.

Output methods
The content is output by specifying a variable name from an input component defined in the template. In order to be able to handle the returned object, methods that can be used with $CMS_VALUE(...)$ can be implemented. In the process, the usable methods are dependent on the returned object type. This means that the individual list entries are usually output using the map(String) method (for more information, see the List data type, for example).

Empty and type checks
Empty checks should always be used to enable a response to be made if an input component is not filled in by the editor (as this can lead to generation errors at other points)
Example:

if(!cs_name.isEmpty, cs_name, "N/A")

In this example, N/A would be output if the input component with the variable identifier cs_name was not filled in; otherwise, the value of cs_name is output.

Particularly when using input components that allow different FirstSpirit object types to be selected (e.g., FS_REFERENCE, FS_LIST), and when accessing fields of referenced objects in snippets (see Schema of referenced objects), a type check also enables a flexible response to be made to entries from the editor, for example:

if(
   st_ref.get.elementType == "Page", 
       st_ref.get.displayName(#global.language),

   st_ref.get.elementType == "PageRef", 
        bold(st_ref.get.displayName(#global.language)) +
            italic(truncate(st_ref.pageRef.page.formData.pt_text.toText(false),100)),

    !st_ref.media.file(#global.language).isNull, 
        st_ref.get.displayName(#global.language) + " (" +
            st_ref.media.file(#global.language).extension.toUpperCase + ", " +
            st_ref.media.file(#global.language).size.humanReadable("kB",",000 kB") + ")",

    !st_ref.media.picture(#global.language).isNull, 
        st_ref.get.displayName(#global.language) + " [Picture]",

    "---")

In this example, a check is carried out for an FS_REFERENCE input component (identifier st_ref) to determine whether the editor has selected a page (Page Store), page reference (Site Store), file, or image (Media Store). Different information is output depending on the result of the check. In this example:

• Page = the display name
• Page reference = the display name and text from a DOM editor with the identifier pt_text of the corresponding page from the Page Store
• File = the display name and the file type and size
• Image = the display name and the suffix [Picture]

If none of these object types have been selected, --- is output.

Example outputs:

Start page

Mithras-Homepage Solar energy is the energy of the future, and we have dedicated ourselves to this future. With our…

Letter template (DOC, 522 kB)

Headquarters [Picture]

• For the if(...) function, also refer to this page.
• For #global.language, also refer to this page. Alternatively, the abbreviated form #language can be used instead of #global.language.

Individual input components for snippet information
It is conceivable that, instead of just using input components whose content will later be used in the presentation channels, special input components may be defined in the forms where editors could store descriptive text, keywords, and other information that is only intended for output within the project (i.e., as “snippet”) and not for output on the website.

Preview of snippets

You can obtain a preview of the snippet output in the integrated preview on the “Snippet” tab (exception: link templates). To do this, a preview page must be selected on the “Properties” tab.

Images ("Thumbnail" field)

The image input component that is to be used for the teaser image can be defined using this field.

In the case of search hits, this image is displayed on the right edge of the search hit, for example (see figures above).

The following input components are available for referencing images, in addition to other uses:

• FS_REFERENCE
• CMS_INPUT_IMAGEMAP

If no input component is present in the template for selecting an image or if no image is to be displayed in the search result display, the field can be left empty.

Examples

st_picture

The image from the st_picture input component is used for the search result display.

if(!st_picture.isEmpty, st_picture, st_imagemap)

If the input component with the st_picture identifier is filled, the image from this input component is used for the search result; otherwise the image from the st_imagemap input component is used.

Alternatively, an image can be specified statically from the Media Store using

medium("REFERENCENAME")

or, for short,

"REFERENCENAME"

Where the placeholder REFERENCENAME has to be the reference name for the image to be displayed.

Images from remote projects

Images from remote projects can be output using

medium("REFERENCENAME", "REMOTEPROJECTNAME") 

where the placeholder REMOTEPROJECTNAME has to be the symbolic name of the requested remote project.

Images from datasets

Furthermore, images from datasets can also be used, such as those that have been embedded using FS_DATASET.

The use of objects of the Entity data type within snippets is not supported! The .getFormData() method should be used instead.

Example:

if(!pt_product.isEmpty, pt_product.dataset.formData.cs_picture)

Where pt_product is the identifier for the FS_DATASET input component used to select a dataset with an image, and cs_picture is the identifier of an input component in the table template where the image is saved.

For more information, see also the FormData data type.

Title and text excerpt ("Label" and "Extract" fields)

Using the

• Label field,
  an input component that is to be used for the title of the teaser can be specified.
  In ContentCreator, the name of the table template is automatically displayed in front of the content of the title in the title of datasets, e.g.,:
  “Press releases: [2010-12-30] Mithras Energy receives solar award from Sun City.”
• Extract field,
  the input component that is to be used for the text excerpt of the teaser can be specified.

Example of the output of content from an input component of type CMS_INPUT_DOM:

IDENTIFIER.toText(false)

There, IDENTIFIER is the variable name for an input component of CMS_INPUT_DOM type.

Examples for output

The following table lists examples of output options for some input components:

The use of objects of Entity data type is not supported in snippets.

The content of multiple input components can be linked using a plus sign (+).

Furthermore, static text can be specified between quotation marks (" "). When combining multiple outputs using a plus sign, a separator should be provided (e.g., a blank space: " "). See below for examples.

Formatting

By default, if nothing else is specified, all of the content in the “Label” and “Extract” fields is output from the specified input component. Therefore, we recommend, if possible, limiting the number of characters for text input components (e.g., using maxInputLength or maxCharacters).

Alternatively, the truncate parameter can be used to specify how many characters are to be displayed. If the text saved in the input component has more characters than those specified by truncate, three periods (...) are appended to the output.

truncate(IDENTIFIER, 25)

This specification shortens the text output of the input component with the identifier IDENTIFIER to 25 characters.

Text can be output in bold or italics using the bold(IDENTIFIER) and italic(IDENTIFIER) parameters. The bold parameter has no effect in the “Label” field since the title for output text is generally shown in bold.

Example

italic(truncate(if(!pt_headline.isEmpty, pt_headline), 30) +
    if(!pt_headline.isEmpty && !pt_subheadline.isEmpty, " /  ") +
truncate(if(!pt_subheadline.isEmpty, pt_subheadline), 15))

In this case, the content of the input components pt_headline and pt_subheadline are output in italics (if they are not empty), separated by a slash with spaces:

Willkommen bei Mithras Energy / Wo die Sonne z...

Depending on the respective object type, methods can be carried out, which can be used to provide additional formating in addition to these general attributes. The following table lists, for instance, formatting options for some input components:

Using labels from (referenced) tables ("label")

If values from a (referenced) table are selectable using CMS_INCLUDE_OPTIONS in CMS_INPUT_COMBOBOX, for instance, the identifier that originated from the (referenced) table can be displayed in the search result using label(#language). (For information on #language / #global.language, refer to this page.)

Form A example

<CMS_INPUT_TEXT name="cs_branch" singleLine="no" useLanguages="no">
    <LANGINFOS>
      <LANGINFO lang="*" label="City"/>
      <LANGINFO lang="DE" label="Stadt"/>
    </LANGINFOS>
</CMS_INPUT_TEXT>

<CMS_INPUT_COMBOBOX name="cs_country_choice" singleLine="no" useLanguages="no">
    <CMS_INCLUDE_OPTIONS type="database">
      <LABELS>
        <LABEL lang="*">#item.Name</LABEL>
      </LABELS>
      <TABLE>country</TABLE>
    </CMS_INCLUDE_OPTIONS>
    <LANGINFOS>
      <LANGINFO lang="*" label="Country"/>
      <LANGINFO lang="DE" label="Land"/>
    </LANGINFOS>
</CMS_INPUT_COMBOBOX>

Where country is a referenced table (see below). City names are saved via cs_branch; a country is selected from the referenced table using the cs_country_choice combo box.

Form B example (country table)

<CMS_INPUT_TEXT name="cs_country" singleLine="no" useLanguages="yes">
     <LANGINFOS>
       <LANGINFO lang="*" label="Country"/>
       <LANGINFO lang="DE" label="Land"/>
     </LANGINFOS>
</CMS_INPUT_TEXT>

Country names are saved under cs_country (Name column).

Snippet example

if(!cs_country_choice.isEmpty, cs_country_choice.label(#language))

With this expression, the text saved in the Name column of Form B for the selected entry is shown as a result when searching for a value that has been selected using the combo box with the identifier cs_country_choice in Form A.

If, for example, the value “Dortmund” is selected for cs_branch in Form A and the value “Germany” is selected via cs_country_choice, the value “Germany” can be displayed as the text excerpt for a search for “Dortmund” instead of the name from data source B.

Specifying the language

The following syntax can be used to specify a particular language for displaying the snippets:

#form.IDENTIFIER.LANGABBREVIATION

The placeholder IDENTIFIER is the variable name for the requested input component of the relevant template whose content is to be used for the output of the snippet.

LANGABBREVIATION is the abbreviation of the requested language which was defined in ServerManager in the server properties under “Language templates”, in the “Abbreviation” field. #master can also be used for the project master language (this is selected in the project properties in ServerManager, in the “Languages” area).

Example

truncate(if(!pt_headline.isEmpty, #form.pt_headline.EN), 30)

In this example, the text for the input component with the identifier pt_headline is output in the language EN, limited to the first 30 characters.

truncate(if(!pt_headline.isEmpty, #form.pt_headline.#master), 30)

In this example, the text for the input component with the identifier pt_headline is output in the master language of the project, limited to the first 30 characters.

Snippets in link templates

For links, snippets can be defined in link templates to display tooltips in ContentCreator. These tooltips are displayed in CMS_INPUT_DOM and CMS_INPUT_DOMTABLE forms and in InEdit mode (see figure).

For internal links on a page referenced using FS_REFERENCE (saved in lt_reference in the following examples), it is advisable to use an image, a heading, and a passage of text from the page reference for the tooltip display.

In addition to FS_REFERENCE, other input component types can of course also be used in links. For information on how they are used in snippets, see the table above and the the FormData data type.

Example

“Thumbnail” field
Displays an image that is saved in the input component with the pt_highlightPicture identifier for the page referenced using lt_reference:

if ( 
           !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty && !lt_reference.pageRef.page.formData.pt_highlightPicture.isEmpty, 
           lt_reference.pageRef.page.formData.pt_highlightPicture 
       )

lt_reference is used to maintain and save the link target (page reference in the same project, selection using FS_REFERENCE). pt_highlightPicture is the variable where an image is saved that is located in the page for the page reference selected in lt_reference (for more information, also see Schema of referenced objects).

“Label” field
Displays text that is saved in the input components with the identifiers pt_headline and / or pt_subheadline for the referenced page, separated by a slash:

if (
           !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty,
           if (
                   !lt_reference.pageRef.page.formData.pt_headline.isEmpty,
                   lt_reference.pageRef.page.formData.pt_headline
               ) +
           if (
                   !lt_reference.pageRef.page.formData.pt_headline.isEmpty && !lt_reference.pageRef.page.formData.pt_subheadline.isEmpty,
                   " / "
               ) + 
           if (
                   !lt_reference.pageRef.page.formData.pt_subheadline.isEmpty,
                   lt_reference.pageRef.page.formData.pt_subheadline
               )           
)

It would also be conceivable to use the display name of the referenced page reference for the label, e.g.,

lt_reference.get.displayName(#language)

In this example, the display name of the page reference saved in the input component with the identifier lt_reference is displayed in the tooltip.

“Extract” field
Displays the text (limited to 65 characters) that is saved in the input component with the identifier pt_intro for the referenced page:

if (
    !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty && !lt_reference.pageRef.page.formData.pt_intro.isEmpty,
    truncate(lt_reference.pageRef.page.formData.pt_intro, 65)
)

lt_reference is used in turn to maintain and save the link target (page reference in the same project, selection using FS_REFERENCE). pt_intro is the variable in which continuous text is saved in the page with the page reference selected in lt_reference.

As the editor generally cannot identify whether the link is an internal or external link based on the information on the preview page (link text, link image, tooltip), the tooltip represents a useful way of displaying this information.