Accessing information from other forms or scripts

Using the

• FormDataValueService
• MetaDataValueService

it is possible to access FirstSpirit elements in a rule execution even if these elements are outside the current context.

This allows information to be retrieved from other forms, e.g.:

• form data from another page,
• from metadata forms, or
• from the project settings.

This information can then be used within the current rule execution.

Using the

• ScriptValueService

form contents can be linked together with a script for further processing. Values from specific fields can be passed to a script, processed there, and then the return value can be written back to a field.

Using the services

The services are accessed in a rule definition via the <SCHEDULE/> tag, e.g.:

<RULE>
     <SCHEDULE delay="0" id="A" service="FormDataValueService">
           (...)
     </SCHEDULE>
</RULE>

<RULE>
     <SCHEDULE delay="0" id="C" service="MetaDataValueService">
         (...)
     </SCHEDULE>
</RULE>

<RULE>
     <SCHEDULE delay="0" id="D" service="ScriptValueService">
          (...)
     </SCHEDULE>
</RULE>

The mandatory “id” attribute is used to assign a freely selectable identifier in the <SCHEDULE/> tag. This must be unique in the rule definition, e.g.: <SCHEDULE id="A" service="FormDataValueService" .../> <SCHEDULE id="B" service="FormDataValueService" .../> If the service is referenced multiple times within the rule definition, “similar” calls can be avoided by assigning different identifiers in the <SCHEDULE/> sections.

Tip: The functionality of the rule definitions can be tested during the development process via the “Form” tab in the integrated preview area.

FormDataValueService

The FormDataValueService enables access to the data of a form.

Access is only possible if the IDProvider is a DataProvider!

MetaDataValueService

The MetaDataValueService enables access to the data of a metadata form
(see also Metadata documentation).

Access is only possible if metadata is set for the IDProvider!

ScriptValueService

The ScriptValueService makes it possible to execute FirstSpirit scripts, which can also receive form values if needed, as well as use the script's return value.

script parameters

Parameter script

script: Reference name of the script to be called

(...)
   <PARAM name="script">
      <TEXT>my_script</TEXT>
   </PARAM>
(...)

The script parameter is a mandatory parameter. All other parameters are available as variables in the script.

Availability and configuration

FormDataValueService and MetaDataValueService

ScriptValueService

All ValueServices are directly available in SiteArchitect and ContentCreator.
It is not necessary to configure or activate the functionality separately.

The functionality is only supported in Isolated mode.

Accessing FirstSpirit elements

The following parameters are used to access a FirstSpirit element (within the <SCHEDULE/> tag):

• ID and Storetype,
• UID and UIDType
• GID and Template (for datasets only) or
• script.

Further parameters are then used to restrict the selection:

• to specific input components (FIELD parameter)
• to content in a specific language (LANGUAGE parameter)

UID and UIDTYPE parameters

UID: Every element in FirstSpirit (apart from a few exceptions, e.g., sections) has a reference name which must be unique for each store. This reference name is also referred to as a UID (unique identifier). To precisely identify an element, the UIDTYPE for the store must also be specified.

UIDTYPE: The UIDTYPE defines the namespace in which the unique identifier (UID) must be unique. Examples of possible values include SITESTORE_LEAF, SITESTORE, PAGESTORE_LEAF, PAGESTORE, TEMPLATESTORE.

(....)
     <PARAM name="UID">
          <PROPERTY name="PAGE_UID" source="#global"/>
     </PARAM>
     <PARAM name="UIDTYPE">
          <TEXT>PAGESTORE</TEXT>
     </PARAM>
(...)

ID and STORETYPE parameters

ID: Every element in FirstSpirit has an ID (numerical value) that is unique across the entire project. To access an element, the STORETYPE parameter is required in addition to the ID.

STORETYPE: Specifies the store via which the element is to be retrieved.
Examples of possible values include SITESTORE, PAGESTORE.

(...)  
     <PARAM name="ID">
          <NUMBER>2979302</NUMBER>
     </PARAM>
     <PARAM name="STORETYPE">
          <TEXT>PAGESTORE</TEXT>
     </PARAM>
(...)

GID and TEMPLATE parameters (datasets only)

GID: Global identifiers (GIDs) are identifiers which are used internally to reference objects. In contrast to UIDs, these are independent of manual changes, such as the renaming of the object.
To access an element, the TEMPLATE parameter is required in addition to the GID.

TEMPLATE: Determining the template of the current FirstSpirit element. The reference name of the template is returned (UID).

(...)
     <PARAM name="GID">
          <TEXT>5cffda3e-19fa-456b-ad7c-028f452ab363</TEXT>
     </PARAM>
     <PARAM name="TEMPLATE">
          <TEXT>database.templatename</TEXT>
     </PARAM> 
(...)

Accessing input components

FIELD parameter

Using the FIELD parameter, a single input component is passed using its variable name (name attribute in the form XML definition of the component). The input component is returned as a FormField type object; using the methods of the object, properties and content of the input component of the current element can then be read out.

Access is only supported for the input component types that are also supported as parameter types for a service (see documentation on the <SCHEDULE/> tag).

(...) 
     <PARAM name="FIELD">
          <TEXT>md_layout</TEXT>
     </PARAM>
(...)

Accessing content in a language

LANGUAGE parameter

The LANGUAGE parameter can either use the abbreviations of the project languages or the global language properties MASTER and LANG. The definitions look different.
Abbreviations:
are passed as TEXT, e.g:

(...)
    <PARAM name="LANGUAGE">
          <TEXT>DE</TEXT>
    </PARAM>
(...)

Global language properties:
For the current language in which the form is opened:

(...)
    <PARAM name="LANGUAGE">
          <PROPERTY name="LANG" source="#global"/>
    </PARAM>
(...)

For the project's master language:

(...)
    <PARAM name="LANGUAGE">
          <PROPERTY name="MASTER" source="#global"/>
    </PARAM>
(...)

Examples

Example A: Access to metadata at page level and transfer of the value to the current section

Access to metadata at page level (<SCHEDULE/> tag):

Example A enables access to metadata (service="MetaDataValueService"). The input component value (“md_layout”) (via the FIELD parameter) of the “PAGE_UID” page (via the UID and UIDTYPE parameters) is retrieved here.

Use in the current context (<DO/> tag):

This value is saved in the input component (“st_layouttext”) of the current section so that the value can then continue to be used in other rules.

<RULE when="ONLOCK">
     <SCHEDULE delay="0" id="A" service="MetaDataValueService">
          <PARAM name="UID">
               <PROPERTY name="PAGE_UID" source="#global"/>
          </PARAM>
          <PARAM name="UIDTYPE">
               <TEXT>PAGESTORE</TEXT>
          </PARAM>
          <PARAM name="FIELD">
               <TEXT>md_layout</TEXT>
          </PARAM>
          <PARAM name="LANGUAGE">
               <PROPERTY source="#global" name="MASTER" />
          </PARAM>
     </SCHEDULE>
     <DO>
          <PROPERTY name="VALUE" source="st_layouttext"/>
     </DO>
 </RULE>

Example B: Access to form data at page level and transfer of the value to the current section

Access to form data at page level (<SCHEDULE/> tag):

Example B enables access to form data (service="FormDataValueService"). The “st_country” input component value (via the FIELD parameter) of the page with ID “2979302” (via the ID and STORETYPE parameters) is retrieved here. The “st_country” input component is a language-dependent combo box with <CMS_INCLUDE_OPTIONS type="database">.

Use in the current context (<DO/> tag):

The language-dependent value of the page is used here to configure the query of an additional input component (“query.countryId”) in the current section:

<RULE>
     <SCHEDULE delay="0" id="B" service="FormDataValueService">
          <PARAM name="ID">
               <NUMBER>2979302</NUMBER>
          </PARAM>
          <PARAM name="STORETYPE">
               <TEXT>PAGESTORE</TEXT>
          </PARAM>
          <PARAM name="FIELD">
               <TEXT>st_country</TEXT>
          </PARAM>
          <PARAM name="LANGUAGE">
               <PROPERTY source="#global" name="LANG"/>
          </PARAM>
     </SCHEDULE>
     <DO>
          <PROPERTY name="query.countryId" source="st_subsidiary"/>
     </DO>
</RULE>

Example C: Access to form data at template level (datasets)

Access to the value of a dataset at template level (<SCHEDULE/> tag):

Example C enables access to data from a database (service="FormDataValueService"). The “cs_title” input component value (via the FIELD parameter) in language “DE” (via the LANGUAGE parameter) of a dataset (via the GID and TEMPLATE parameters) is retrieved here.

<RULE>
     <SCHEDULE delay="0" id="C" service="FormDataValueService">
          <PARAM name="GID">
                <TEXT>5cffda3e-19fa-456b-ad7c-028f452ab363</TEXT>
          </PARAM>
          <PARAM name="TEMPLATE">
               <TEXT>database.templatename</TEXT>
          </PARAM>
          <PARAM name="FIELD">
               <TEXT>cs_title</TEXT>
          </PARAM>	
          <PARAM name="LANGUAGE">
               <TEXT>DE</TEXT>
          </PARAM>
     </SCHEDULE>
</RULE>

Example D: Access to project properties

Access to project properties from the Global Settings for the project (<SCHEDULE/> tag):

Example D enables access to form data (service="FormDataValueService"). The “gs_maxTextSize” input component value (via the FIELD parameter) of the “PROJECT_PROPERTIES_ID” project setting (via the ID and STORETYPE parameters) is retrieved here.

Use in the current context (<DO/> tag):

This value is saved in the input component (“st_maxTextSize”) of the current section so that the value can then continue to be used in other rules.

<RULE>
     <SCHEDULE delay="0" id="D" service="FormDataValueService">
          <PARAM name="ID">
               <PROPERTY name="PROJECT_PROPERTIES_ID" source="#global"/>
          </PARAM>
          <PARAM name="STORETYPE">
               <TEXT>GLOBALSTORE</TEXT>
          </PARAM>
          <PARAM name="FIELD">
               <TEXT>gs_maxTextSize</TEXT>
          </PARAM>
          <PARAM name="LANGUAGE">
               <PROPERTY source="#global" name="LANG"/>
          </PARAM>
     </SCHEDULE>
     <DO>
          <PROPERTY name="VALUE" source="st_maxTextSize"/>
     </DO>
</RULE>

Example E: Access to scripts

Access to scripts (<SCHEDULE/> tag):

The example E allows access to scripts (service="ScriptValueService").

Here, the parameters “title” and “text” are passed to the script “my_script”, which is called with a delay of two seconds. The return value of the script is written to the input component “st_target”.

<RULE>
   <SCHEDULE delay="2000" id="E" service="ScriptValueService">
      <PARAM name="script"> 
         <TEXT>my_script</TEXT>
      </PARAM>
      <PARAM name="title">
         <PROPERTY source="st_title" name="VALUE"/>
      </PARAM>
      <PARAM name="text">
         <PROPERTYsource="st_text" name="VALUE"/>
      </PARAM>
   </SCHEDULE>
   <DO>
      <PROPERTY name="VALUE" source="st_target"/>
   </DO>
</RULE>