Online Dokumentation FirstSpirit - Auf Informationen aus anderen Formularen und Scripten zugreifen

können Formularinhalte und mit einem Skript zur Weiterverarbeitung miteinander verbunden werden. Es können Werte aus bestimmten Feldern an ein Skript übergeben, dort verarbeitet und dann die Rückgabe in ein Feld zurückgeschrieben werden.

Die Dienste verwenden

Der Zugriff auf die Dienste erfolgt innerhalb einer Regeldefinition über das Tag <SCHEDULE/>, z. B.:

<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>

Über das Pflicht-Attribut „id“ wird im <SCHEDULE/>-Tag ein freiwählbarer Identifier vergeben. Dieser muss innerhalb der Regeldefinition eindeutig sein, z. B.:
<SCHEDULE id="A" service="FormDataValueService" .../>
<SCHEDULE id="B" service="FormDataValueService" .../>
Wird der Service innerhalb der Regeldefinition mehrfach referenziert, können über die Vergabe unterschiedlicher Identifier in den <SCHEDULE/>-Abschnitten „gleichartige“ Calls vermieden werden.

Tipp: Die Funktionalität der Regeldefinitionen kann während des Entwicklungsprozesses über das Register „Formular“ im Bereich Integrierte Vorschau getestet werden.

FormDataValueService

Der FormDataValueService ermöglicht den Zugriff auf die Daten eines Formulars.

Der Zugriff ist nur möglich, wenn der IDProvider vom Typ DataProvider ist!

MetaDataValueService

Der MetaDataValueService ermöglicht den Zugriff auf die Daten eines Metadatenformulars
(siehe auch Dokumentation zu Metadaten).

Der Zugriff ist nur möglich, wenn für den IDProvider Metadaten gesetzt sind!

ScriptValueService

Der ScriptValueService ermöglicht die Ausführung von FirstSpirit-Skripten, die bei Bedarf auch Formularwerte entgegennehmen können, sowie die Nutzung der Skriptrückgabe.

Parameter script

script: Referenzname des aufzurufenden Skriptes

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

Der script-Parameter ist ein Pflichtparameter. Alle anderen Parameter stehen als Variablen im Skript zur Verfügung.

Bereitstellung und Konfiguration

Verfügbar ab FirstSpirit-Version 2020-12 FormDataValueService und MetaDataValueService

Verfügbar ab FirstSpirit-Version 2024-10 ScriptValueService

Alle ValueServices sind im SiteArchitect und im ContentCreator direkt verfügbar.
Eine gesonderte Konfiguration oder Aktivierung der Funktionalität ist nicht notwendig.

Die Funktionalität wird nur im Isolated-Modus unterstützt.

Auf FirstSpirit-Elemente zugreifen

Der Zugriff auf ein FirstSpirit-Element (innerhalb des <SCHEDULE/>-Tags) erfolgt über die Parameter:

ID und Storetype,
UID und UIDType,
GID und Template (nur für Datensätze) oder
script.

Anschließend wird die Auswahl über weitere Parameter eingegrenzt:

auf bestimmte Eingabekomponenten (Parameter FIELD)
auf Inhalte in einer bestimmten Sprache (Parameter LANGUAGE)

Parameter UID und UIDTYPE

UID: Jedes Element in FirstSpirit hat (bis auf wenige Ausnahmen, z. B. Absätze) einen Referenznamen, der pro Verwaltungsbereich eindeutig sein muss. Dieser Referenzname wird auch als UID bezeichnet (Unique Identifier). Zur genauen Identifikation eines Elements muss zusätzlich der UIDTYPE für den Verwaltungsbereich angegeben werden.

UIDTYPE: Der UIDTYPE definiert den Namensraum, in dem der eindeutige Bezeichner (UID) eindeutig sein muss. Mögliche Werte sind z. B. SITESTORE_LEAF, SITESTORE, PAGESTORE_LEAF, PAGESTORE, TEMPLATESTORE.

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

Parameter ID und STORETYPE

ID: Jedes Element in FirstSpirit hat eine projektweit eindeutige ID (numerischer Wert). Für den Zugriff auf ein Element wird zusätzlich zur ID der Parameter STORETYPE benötigt.

STORETYPE: Angabe des Verwaltungsbereichs, über den das Element geholt werden soll.
Mögliche Werte sind z. B. SITESTORE, PAGESTORE.

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

Parameter GID und TEMPLATE (nur Datensätze)

GID: Bei Globalen Identifiern (GIDs) handelt es sich um Identifier, die intern zur Referenzierung von Objekten eingesetzt werden. Diese sind (anders als UIDs) unabhängig von manuellen Änderungen, wie dem Umbenennen des Objekts.
Für den Zugriff auf ein Element wird zusätzlich zu GID der Parameter TEMPLATE benötigt.

TEMPLATE: Ermittlung der Vorlage des aktuellen FirstSpirit-Elements. Es wird der Referenzname der Vorlage zurückgegeben (UID).

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

Zugriff auf Eingabekomponenten

Parameter FIELD

Über den Parameter FIELD wird eine einzelne Eingabekomponente anhand ihres Variablennamens (name-Attribut in der Formular-XML-Definition der Komponente) übergeben. Die Eingabekomponente wird als Objekt vom Typ FormField zurückgeliefert; über die Methoden des Objekts können dann Eigenschaften und Inhalte der Eingabekomponente des aktuellen Elements ausgelesen werden.

Es werden lediglich Zugriffe auf bestimmte Eingabekomponententypen unterstützt, wie sie auch als Parametertypen für einen Service unterstützt werden (siehe Dokumentation zum <SCHEDULE/>-Tag).

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

Zugriff auf Inhalte einer Sprache

Parameter LANGUAGE

Für den Parameter LANGUAGE (<PARAM name="LANGUAGE">) können entweder die Abkürzungen (abbreviation) der Projektsprachen oder die globalen Spracheigenschaften „MASTER“ und „LANG“ verwendet werden. Die Definitionen sehen dabei unterschiedlich aus.

Abkürzungen:
werden als TEXT übergeben, z. B.:

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

Globalen Spracheigenschaften:
Für die aktuelle Sprache, in der das Formular geöffnet ist:

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

Für die Mastersprache des Projektes:

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

Beispiele

Beispiel A: Zugriff auf Metadaten auf Seitenebene und Übernahme des Wertes in den aktuellen Absatz

Zugriff auf Metadaten auf Seitenebene (<SCHEDULE/>-Tag):

Das Beispiel A ermöglicht den Zugriff auf Metadaten (service="MetaDataValueService"). Hier wird der Wert der Eingabekomponente („md_layout“) (über den Parameter FIELD) der Seite „PAGE_UID“ (über die Parameter UID und UIDTYPE) geholt.

Verwendung im aktuellen Kontext (<DO/>-Tag):

Dieser Wert wird in der Eingabekomponente („st_layouttext“) des aktuellen Absatzes gespeichert, um den Wert bspw. anschließend in anderen Regeln weiter zu verwenden.

<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>

Beispiel B: Zugriff auf Formulardaten auf Seitenebene und Übernahme des Wertes in den aktuellen Absatz

Zugriff auf Formulardaten auf Seitenebene (<SCHEDULE/>-Tag):

Das Beispiel B ermöglicht den Zugriff auf Formulardaten (service="FormDataValueService"). Hier wird der Wert einer Eingabekomponente „st_country“ (über den Parameter FIELD) der Seite mit der ID „2979302“ (über die Parameter ID und STORETYPE) geholt. Die Eingabekomponente „st_country“ ist eine sprachabhängige Combobox mit <CMS_INCLUDE_OPTIONS type="database">.

Verwendung im aktuellen Kontext (<DO/>-Tag):

Der sprachabhängige Wert der Seite wird hier verwendet, um im aktuellen Absatz die Abfrage einer weiteren Eingabekomponente zu konfigurieren („query.countryId“):

<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>

Beispiel C: Zugriff auf Formulardaten auf Vorlagenebene (Datensätze)

Zugriff auf den Wert eines Datensatzes auf Vorlagenebene (<SCHEDULE/>-Tag):

Das Beispiel C ermöglicht den Zugriff auf Daten aus einer Datenbank (service="FormDataValueService"). Hier wird der Wert einer Eingabekomponente „cs_title“ (über den Parameter FIELD) in der Sprache „DE“ (über den Parameter LANGUAGE) eines Datensatzes (über die Parameter GID und TEMPLATE) geholt.

<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>

Beispiel D: Zugriff auf Projekteigenschaften

Zugriff auf Projekteigenschaften aus den Globale Einstellungen für das Projekt (<SCHEDULE/>-Tag):

Das Beispiel D ermöglicht den Zugriff auf Formulardaten (service="FormDataValueService"). Hier wird der Wert einer Eingabekomponente „gs_maxTextSize“ (über den Parameter FIELD) der Projekteinstellung „PROJECT_PROPERTIES_ID“ (über die Parameter ID und STORETYPE) geholt.

Verwendung im aktuellen Kontext (<DO/>-Tag):

Dieser Wert wird in der Eingabekomponente („st_maxTextSize“) des aktuellen Absatzes gespeichert, um den Wert anschließend in anderen Regeln weiter zu verwenden.

<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>

Beispiel E: Zugriff auf Skripte

Zugriff auf Skripte (<SCHEDULE/>-Tag):

Das Beispiel E ermöglicht den Zugriff auf Skripte (service="ScriptValueService").

Hier werden Parameter „title“ und „text“ an das Skript „my_script“ übergeben, das mit einer Verzögerung von zwei Sekunden aufgerufen wird. Der Rückgabewert des Skripts wird in die Eingabekomponente „st_target“ geschrieben.

<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>

Druckversion | Seitenanfang