Using fragments

Using the Fragment DAP, fragments from one fragment project can be:

• Referenced in another fragment project.
  The fragments can also be edited there and new ones created.
• Referenced in a classic FirstSpirit project, where they can be grouped, structured, and placed in relation to each other. If the settings have been configured accordingly, the referenced fragments can also be edited in FirstSpirit ContentCreator.

Checklist

Following components and configurations are required if you want to use the functionality described on this page:

"FS_INDEX" component

The “FS_INDEX” component is used to reference fragments.
Form “tab”, minimum configuration:

<FS_INDEX name="fragments">
   <LANGINFOS>
     <LANGINFO lang="*" label="Fragment selection"/>
     <LANGINFO lang="DE" label="Fragment auswählen"/>
   </LANGINFOS>
   <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
     <PROJECT remote="fragmentproject"/>
   </SOURCE>
</FS_INDEX>

Activating the DAP function
The SOURCE tag is used to specify the FirstSpirit module and the DataAccessPlugin component via the mandatory parameter name. In this case: “FirstSpiritFragmentAccess/FSFAConnector”.

Defining the remote project
The project from which the fragments are to be selected must be specified via the PROJECT tag. The symbolic project name of the remote project must be specified via the mandatory parameter remote.

Display of selected fragments
The viewMode parameter is used to control the display mode for the fragments in the input component. The display is derived from the configuration in the “Snippet” tab for the template on which the selected fragment is based.

• DETAILS (default): Displays information from the “Thumbnail”, “Label”, and “Extract” fields.
• HEADERS: Displays information from the “Label” field.
• SYMBOLS: Displays information from the “Thumbnail” field.

Syntax example:

<FS_INDEX name="fragments" useLanguages="no" viewMode="headers">...

Restricting to categories

Using the minimum configuration described above, all fragments can be selected from the project that is specified by the remote attribute in the PROJECT tag.
To restrict the selection to specific categories, the configuration can be expanded to include the CATEGORY tag. The name of the relevant content folder or the relevant page template (in the remote project) is specified via the uid parameter (reference name):

<FS_INDEX name="fragments">
   <LANGINFOS>
     <LANGINFO lang="*" label="Fragment selection"/>
     <LANGINFO lang="DE" label="Fragment auswählen"/>
   </LANGINFOS>
   <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
     <PROJECT remote="fragmentproject">
        <CATEGORY uid="teaser"/>
     </PROJECT>
   </SOURCE>
</FS_INDEX>

Multiple categories can also be specified, e.g.:

...
<PROJECT remote="fragmentproject">
     <CATEGORY uid="teaser"/>
     <CATEGORY uid="news"/>
</PROJECT>
...

Specifying the CATEGORY tag simultaneously enables referenced fragments to be edited and new fragments to be created in the remote project. For information on this, see section Editing and creating fragments.

Restricting the number of fragments that can be selected

The number of fragments that can be selected and saved via the component can be restricted by entering an appropriate definition on the “Rule” tab in the template; e.g.:

<RULES>
  <RULE>
    <WITH>
       <NOT>
        <GREATER_THAN>
           <PROPERTY name="size" source="fragments"/>
           <NUMBER>1</NUMBER>
       </GREATER_THAN>
      </NOT>
    </WITH>
    <DO>
      <VALIDATION scope="RELEASE">
          <PROPERTY name="VALID" source="fragments"/>
          <MESSAGE lang="*" text="Only one element allowed"/>
          <MESSAGE lang="DE" text="Darf maximal ein Element enthalten."/>
      </VALIDATION>
    </DO>
  </RULE>
</RULES>

The INDEX component in question is referenced via the source attribute (“Form” tab).

For more information on defining rules, see Checking content ("Rules" tab).

Restricting to variants

By default, all available variants are displayed to the editor for selection. To limit the selection to certain variant dimensions, the configuration can be expanded by the VARIANT tag, e.g.

...
 <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
 <PROJECT remote="fragments">
 <VARIANT name="language" value="EN"/>
 <VARIANT name="language" value="DE"/>
 <VARIANT name="device" value="Mobile"/>
 </PROJECT>
 </SOURCE>
...

VARIANT: A VARIANT definition must exist for each variant dimension that the editor should be able to select.
If the tag is not specified, all variant dimensions are available for selection.
Each VARIANT definition requires the name and value attributes to be specified:

name: This attribute must be used to specify the identifier of the variant dimension that should be available for selection.
This is the value of the name attribute of the desired component in the metadata template of the fragment project from which the selection is made via FragmentDAP.
For each variant dimension that the editor should be able to select, a VARIANT definition with a fitting name attribute must exist.
If more than one variant dimension is defined, only those variants are displayed that fulfill all conditions (AND conjunction).

value: This attribute can be used to restrict the selection to certain types of a variant dimension.
This is the value of the value attribute within ENTRIES / ENTRY of the desired component in the metadata template of the fragment project from which the selection is made via FragmentDAP.
For each type of variant dimension that the editor should be able to select, a VARIANT definition with fitting name and value attribute must exist.
If more than one type of a variant dimension is defined, all variants matching these types are displayed (OR conjunction).

The order of the VARIANT definitions affects the order in which the variants are displayed in the selection dialog. In the example above, variants of the dimension language of type EN are always displayed (i.e. English-language variants).
Variants (and thus the associated fragment) to which the variant restrictions do not apply are not displayed.

This filtering option is only used in an appropriately configured FS_INDEX component, but not in the “Fragment” report. However, the display in the report also takes into account the order of the VARIANT definitions.

Use in FragmentCreator

Selecting fragments

If the correct minimum configuration settings have been made, the editor will be able to select fragments in a variant:

Editing and creating fragments

By using the CATEGORY tag and specifying a valid value for the uid parameter (see section Restricting to categories), it is possible to select fragments from the remote project, edit referenced fragments and create new fragments.

If the correct configuration settings have been made, the editor will be able to edit referenced fragments and create new fragments in a variant.
If only one category was specified (tag CATEGORY), the button creates a fragment of this category:

If more than one category has been specified, the editor will get a dialog to select the desired category

Fragments created using the button are created in the remote project that is specified by the remote attribute in the PROJECT tag, and to be precise, using the template that is selected by the editor. In the example, this would be the template with the reference name “teaser”. The fragments are created in the “Content” area in the folder with the reference name “teaser”.

Use in SiteArchitect

Selecting fragments

In FirstSpirit ContentCreator, fragments can also be selected using the minimum configuration specified above.
Within the FS_INDEX component:

Matching fragments can also be selected from the corresponding report:

Outputting fragments/variants (in FirstSpirit projects)

For information on how to output fragments/variants – which the editor selects from the fragment project – in a FirstSpirit project using an FS_INDEX component that has been configured as described above, see Outputting fragments.

Use in ContentCreator

Selecting fragments

In FirstSpirit ContentCreator, fragments can also be selected using the minimum configuration specified above.
Within the FS_INDEX component:

Matching fragments can also be selected from the corresponding report:

Editing fragments

To enable fragments to be edited in ContentCreator, the “Fragment DAP for ContentCreator” web component must be added to the relevant project in the project properties in the “ContentCreator” area (“FirstSpirit ServerManager / Project properties / Web components”, see page Fragment Data Access Plugin (Fragment DAP)).

A corresponding icon is displayed in the editing dialog with the FS_INDEX component in ContentCreator:

Clicking on the icon opens the FragmentCreator form as a MicroApp in ContentCreator directly, where it can then be edited:

Following this, the editor can close the (FragmentCreator) form (X icon). The changes are saved automatically.

EasyEdit / Inline view

The “Edit” icon can also be shown directly in the preview.
For this purpose, the relevant FS_INDEX component is equipped with an editorId() call in conjunction with the externalReference parameter. This parameter expects the identifier of references that are saved in the FS_INDEX component.

Example:

<div$CMS_VALUE(editorId(editorName:"fragments"))$>
     $CMS_FOR(i, [0..fragments.identifiers.size-1])$
         $CMS_SET(fragment, fragments.values[i])$
         $CMS_SET(objectId, fragments.identifiers[i])$
         <div$CMS_VALUE(editorId(editorName:"fragments", externalReference: objectId))$>
             $CMS_FOR(variant, fragment.variants({"language": #global.language.abbreviation}))$
                 <b>$CMS_VALUE(variant.title)$</b><br>
                 $CMS_VALUE(variant.formData.text)$
              
             $CMS_END_FOR$
         </div>
     $CMS_END_FOR$
</div> 

• fragments: Identifier of the relevant FS_INDEX component
• text: Identifier of an input component in the selected fragment
• objectId: Represents a fragment entry of the FS_INDEX component

For more information about the editorId method, see also Use in projects (→FirstSpirit Online Documentation).

If the template is configured correctly and the user has sufficient permissions, Edit icons are displayed on the selected fragments directly in the preview.

In use

FragmentCreator visualizes if the fragment has a reference to another fragment, specifically with the text “In use”.
Similarly, when a variant is deleted, a dialog box indicates that references to other fragments exist.