Naming scripts

Skript-Namen sollten aber auch möglichst simpel und allgemein vergeben werden. So ist "Author" sinnvoller als "ReportAuthor".

• Names of scripts must be set thoughtfully, as they serve as a unique identifier. Once a script is in a template, changing the name causes the script to having to be reinserted.

• At best, script names describe the output. For example, "LocationDate" makes more sense than "LetterStart."

• Script names should also be as simple and general as possible. For example, "Author" makes more sense than "ReportAuthor".

  Often, however, the output cannot be described because it may be completely changed by specific conditions. In this case, the location of the script in the document may be set as the name (e.g. "Footer1stPage").

• Skript-Namen werden mittels Script names are formatted using "Pascal Casing" formatiert. Das bedeutet, dass der Anfangsbuchstabe und jeder Wort-Anfangsbuchstabe immer gross sind.Beispiele. This means that the initial letter and each word-initial letter are always capitalized.

  Examples:

  • ContactInformation

  • LocationDate

• Skript-Namen dürfen keine Umlaute Script names must not contain umlauts (äöü) und keine Sonderzeichen ausser and special characters except "_" (Underlineunderline) enthalten. Punkte dienen zur Einteilung in die Ordnerstruktur.

• Skript-Namen sind auf 100 Zeichen begrenzt.

• Die Entwicklungssprache in primedocs ist grundsätzlich Englisch, sowohl im Source Code als auch in den Skripten. Kommentare bilden eine Ausnahme: dort darf auch auf Deutsch geschrieben werden. Kommentare beginnen mit den Zeichen <!-- und enden mit -->.

Globale Konfigurationen

Möglichst global

In den meisten Fällen gilt: je globaler desto besser. Das bedeutet: lieber ein Skript zu viel auslagern als eines zu wenig. Sobald ein Skript mehr als einmal vorkommt, wird es ausgelagert (in die Globalen Konfigurationen eingefügt und verknüpft), damit das Skript nur an einem Ort gepflegt werden muss.

Wenn man ein neues Skript benötigt, das leicht unterschiedlich zu einem existierenden Skript sein soll, erreicht man das auf drei Arten:

1. Bestehendes Skript erweitern

• . Dots are used for classification in the folder structure.

• Script names are limited to 100 characters.

• The development language in OneOffixx is basically English, both in the source code and in the scripts. Comments are an exception: there you may also write in German. Comments start with the characters <!-- and end with -->.

Global Configurations

As global as possible

In most cases, the more global the better. This means: it is better to outsource a script too much than one too little. As soon as a script occurs more than once, it is swapped out (added to Global configurations and linked) so that the script only needs to be maintained in one place.

If you need a new script to be slightly different from an existing script, you accomplish this in three ways:

1. Extend existing script

The existing script can be modified to create the desired difference on a condition. The condition could, for example, query the state of a non-visible document parameter checkbox (e.g. DocParam.EnableDateOfInHeader) or rely on the contents of a specific script name (e.g. CustomElements.EnableDateOfInHeader = 'true'). BeispielExample:

<CustomDataNode id="HeaderAdditionalText">
  <Line>
    <Element id="Org.Unit" />
  </Line>
  <Line>
    <Text when="DocParam.EnableDateOfInHeader">{D[Texts.DateOf]} </Text>
    <Element id="DocParam.Date" fFormatingDate="{D[Configuration.DateFormat.WrittenOut]}" />
  </Line>
</CustomDataNode>

Hier wird (neben der Abteilung auf der 1. Zeile) entweder "vom 1. Januar 2017" oder "1. Januar 2017" ausgegeben, je nach dem, ob DocParam.EnableDateOfInHeader in einer Vorlage aktiviert ist oder nicht.

✔ Wartbarkeit – Da kein zusätzliches Skript erstellt wurde, ist es später einfacher, den Überblick über die Skripte und deren Funktionalitäten zu haben.

❌ Komplexität – Skripte mit Conditions sind anspruchsvoller zu lesen und zu bearbeiten.

2. Vererbung nutzen

Falls ein Skript in der Layoutvorlage entweder geschrieben oder mit den Globalen Konfigurationen verknüpft ist, besteht auch die Möglichkeit, dieses Skript in die Inhaltsvorlage zu kopieren und dort den Inhalt zu ändern. Dann wird der Skriptinhalt folglich durch die Hauptvorlage gesteuert. Dabei muss der Name zwingend gleich bleiben. Die Dokument-Pipeline geht dann bei der Generierung durch alle Skripte durch und wird dann die in der Kette unterste Version des Skriptes nehmen (in diesem Fall in der Inhaltsvorlage). Das geht natürlich auch von Layoutvorlage zu Funktionsvorlage oder von Inhaltsvorlage zu Funktionsvorlage.

✔ Einfachheit – Das Skript wird lediglich kopiert und in die auf der Layoutvorlage basierende Vorlage in der Vorlagenhierarchie eingefügt und angepasst. Der Vorgang ist sehr simpel und unkompliziert.

✔ Wartbarkeit – Soll wieder das globale Skript benutzt werden, wird das überschreibende Skript einfach gelöscht oder auskommentiert.

❌ Komplexität – Für andere Vorlagenbearbeiter kann es schwierig sein, das richtige Skript zu finden, das sie in der Word-Vorlage sehen. Grund dafür ist, dass die Id gleich lautet (was wir mit der Vererbung auch ausnutzen). Sie müssen wissen, dass bei der Generierung effektiv nicht auf das globale Skript sondern auf eine überschreibende Version in der Inhalts- bzw. Funktionsvorlage zugegriffen wird.

3. Kopie erstellen

Im Notfall kann man das Skript kopieren, den Namen des Skripts anpassen und die Änderungen an der Kopie vornehmen. Dieses neue Skript muss dementsprechend in der Vorlage neu eingefügt werden. Der Unterschied zum anderen Skript sollte gut ersichtlich sein (zum Beispiel kann ein Kommentar erfasst werden. Bestenfalls sieht man den Unterschied im Namen).

✔ Schneller – Kopien von Skripten zu erstellen, ist einfacher und geht schneller.

❌ Wartbarkeit – bei vielen ähnlichen Skripte kann leicht die Übersicht verloren gehen. Das insbesondere dann, wenn die Unterschiede der ähnlichen Skripte nicht ersichtlich sind.

Gruppen ("Group")

Neue Skripte werden bei praktisch allen Kundenlösungen in den Globalen Konfigurationen in der Gruppe "Scripts" abgelegt. Neben Skripten können in den Globalen Konfigurationen auch andere Konfigurationen, die häufig verwendet werden, abgelegt werden, wie z. B. Regex-Validierungen, HTML-Bausteine oder Formatierung-Dokumentfunktion-Konfigurationen. Letzteres sollte jedoch wenn möglich immer direkt an die Layout- bzw. Inhaltsvorlage angehängt werden. Solche Skripte gehören dann nicht in die Gruppe "Scripts", sondern in dafür neu angelegte Gruppen. Formatierung-Dokumentfunktion-Konfigurationen gehören beispielsweise in die Gruppe "Formatting".

Namen von Konfigurationsteilen und Skripten

Grundsätzlich haben einzelne Einträge in den Globalen Konfigurationen beim Auslagern genau denselben Namen wie die darin enthaltenen CustomDataNodes. Im folgenden Beispiel, ist die Gruppe "Scripts" und der Eintrag "Salutation" angewählt. Das CustomDataNode hat ebenfalls den Namen Here (next to the department on the 1st line) either "from January 1, 2017" or "January 1, 2017" is output, depending on whether DocParam.EnableDateOfInHeader is enabled in a template or not.

✔ Maintainability – Since no additional script was created, it is easier to keep track of scripts and their functionalities later.

❌ Complexity – Scripts with conditions are more demanding to read and edit.

2. Use inheritance

If a script is either written in the layout template or linked to the Global Configurations, it is also possible to copy this script to the content template and change the content there. Then the script content is consequently controlled by the main template. In this case, the name must remain the same. The document pipeline then goes through all scripts during generation and will then take the lowest version of the script in the chain (in this case in the content template). Of course, this also works from layout template to function template or from content template to function template.

✔ Simplicity – The script is simply copied and pasted into the layout template based template in the template hierarchy and adjusted. The process is very simple and straightforward.

✔ Maintainability – If the global script is to be used again, the overwriting script is simply deleted or commented out.

❌ Complexity – For other template editors it can be difficult to find the right script they see in the Word template. The reason for this is that the Id is the same (which we also take advantage of with inheritance). They need to know that the generation is effectively not accessing the global script but an overriding version in the content or function template.

3. Create a copy

In case of emergency, you can copy the script, adjust the name of the script and make the changes to the copy. Accordingly, this new script must be reinserted in the template. The difference from the other script should be clearly visible (for example, a comment can be entered. At best, one sees the difference in the name).

✔ Faster – Creating copies of scripts is easier and goes faster.

❌ Maintainability – with many similar scripts, it is easy to lose track of them. This especially if the differences of the similar scripts are not apparent.

Structure in the Global Configurations

Groups

New scripts are stored in the Global Configurations in the "Scripts" group for practically all customer solutions. In addition to scripts, other configurations that are frequently used can also be stored in the Global Configurations, such as regex validations, HTML modules or Formatting document function configurations. However, the latter should always be attached directly to the layout or content template if possible. Such scripts then do not belong in the "Scripts" group, but in groups newly created for this purpose. For example, Formatting document function configurations belong in the "Formatting" group.

Names of configuration parts and scripts

In principle, individual entries in the Global Configurations have exactly the same name as the CustomDataNodes they contain when swapped out. In the following example, the group "Scripts" and the entry "Salutation" is selected. The CustomDataNode is also named "Salutation":

Oft werden jedoch verschiedene Skripte für eine Vorlagengruppe oder für einen Dokumenttyp (Verträge, Briefe, ArbeitszeugnisseHowever, often different scripts are needed for a template group or for a document type (contracts, letters, certificates of employment, etc.) benötigt. In dem Fall werden diese Skripte alle in einen Eintrag abgespeichert. Die Namen der einzelnen CustomDataNodes sind dann gemäss dem Schema: Eintrag.Name. Im folgenden Fall ist das this case, these scripts are all stored in one entry. The names of the individual CustomDataNodes are then according to the scheme: http://Entry.Name . In the following case it is Signers.Signer_0.

Diese Konfiguration wird folglich in den Vorlagen durch This configuration is consequently integrated in the templates by {[Scripts.Signers]} integriert. Unter At "Inhalt verknüpfen" kann man somit den Ordner "Signers" aufrufen, der vier Skripte enthält. Die Skripte von den Globalen Konfigurationen werden, wenn möglich, in den Layoutvorlagen verknüpft, damit alle anhängenden Inhaltsvorlagen diese Skripte auch zur Verfügung haben. Der Fall, dass nur eine Vorlage eine grosse Anzahl Skripte benötigt, ist relativ selten.

Es gibt einen Fall, in dem es sinnvoll ist, Skripte mit Nummern zu versehen, nämlich wenn je nach Bedingung, verschiedene Inhalte in einer Tabelle stehen und verschieden formatiert werden. Wenn ein Skript also auf mehrere Teil-Skripte aufgeteilt werden muss, ist dieses Skript meistens ausschliesslich für diese Verwendung vorgesehen. Unter dieser Ausnahme macht es keinen Sinn, für jedes Teil-Skript einen beschreibenden Namen zu vergeben.

Ein Beispiel: Nehmen wir an, es wird eine Tabelle erstellt, die fett oder normal formatiert wird. Die Skripte können dann nach Row (=Zeile) und Column (=Spalte) und danach nach fett und nicht fett eingeteilt werden. So weiss man genau, welches Skript in welche Zelle kommtLink Content" you can thus access the folder "Signers" which contains four scripts. The scripts from the Global Configurations are linked in the layout templates, if possible, so that all attached content templates also have these scripts available. The case where only one template requires a large number of scripts is relatively rare.

There is one case where it makes sense to number scripts, namely when, depending on the condition, different content is in a table and formatted differently. Thus, if a script must be divided into several partial scripts, this script is usually intended exclusively for this use. With this exception, it makes no sense to assign a descriptive name for each partial script.

Example: Suppose a table is created that is formatted bold or normal. The scripts can then be divided by Row and Column and then by bold and non-bold. This way you know exactly which script goes into which cell:

• Protocol.Row1.Col1.bold

• Protocol.Row1.Col2.normal

• Protocol.Row2.Col1.bold

• Protocol.Row2.Col2.normal

• Protocol.Row3.Col1.bold

• Protocol.Row3.Col2.normal

    <!-- Table Tabellenzeilerow 1 --> 
    <CustomDataNode id="Protocol.Row1.Col1.bold">
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'"> 
        <Condition when="DocParam.SitzungDateMeetingDate">
          <Line>
            <Text>Sitzung</Text>
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>
    
    <CustomDataNode id="Protocol.Row1.Col2.normal">
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'"> 
        <Condition when="DocParam.SitzungDateMeetingDate">
          <Line>
            <Element id="DocParam.SitzungDateMeetingDate" separator=", " />
            <Element id="DocParam.SitzungUhrMeetingTime" textafter=" Uhr" />
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>

    <!-- Table Tabellenzeilerow 2 -->
    <CustomDataNode id="Protocol.Row2.Col1.bold">
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'">
        <Condition when="DocParam.SitzungOrtMeetingPlace">
          <Line>
            <Text>Ort</Text>
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>
    
    <CustomDataNode id="Protocol.Row2.Col2.normal">
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'"> 
        <Condition when="DocParam.SitzungOrtMeetingPlace">
          <Line>
            <Element id="DocParam.SitzungOrtMeetingPlace"  />
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>
    
    <!-- TabellenzeileTable row 3 -->
    <CustomDataNode id="Protocol.Row3.Col1.bold">
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'">
        <Condition when="DocParam.VorsitzChair">
          <Line>
            <Text>Vorsitz<<Text>Chair</Text>
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>
    
    <CustomDataNode id="Protocol.Row3.Col2.normal">
      <!-- ProtokollProtocol -->
      <Condition when="DocParam.RBEinladungProtokollRBInvitationProtocol='2'"> 
        <Condition when="DocParam.VorsitzChair">
          <Line>
            <Element id="DocParam.VorsitzChair" />
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>

Das wäre in Word zum Beispiel so:

Image Removed

Grundsätzlich sollte der Name gemäss dem Kapitel Namensgebung bei Skripten möglichst beschreibend sein oder in wenigen Fällen die Position beschreiben.

Rekursion in Skripten

Einfache Rekursion

Manchmal macht es Sinn, in einem Skript auf das Resultat eines anderen Skripts zuzugreifen. Wenn z. B. in fünf verschiedenen Skripten der Lösung ermittelt werden muss, ob sich Profil und Signer_1 entsprechen und ob die aktuelle Organisationseinheit nicht das Finanzdepartement ist, kann das über ein Skript ermittelt werden, auf dessen Resultat wir im Anschluss zugreifenFor example, in Word, it would be like this:

Image Added

Basically the name should be as descriptive as possible according to the chapter Naming scripts or in a few cases describe the position.

Recursion in scripts

Simple recursion

Sometimes it makes sense to access the result of another script in one script. If, for example, in five different scripts of the solution it has to be determined whether Profile and Signer_1 correspond to each other and whether the current organizational unit is not the Finance Department, this can be determined via a script whose result we access afterwards:

<Configuration>
  <Script engine="XSL" version="2" depth="3">
    <!-- ↓ istis dann 'true', wennif sichprofile Profiland und Signersigner_1 entsprechen are the same
       and undthe dieOU OEis gleichzeitignot nichtthe dasfinance Finanzdepartementdepartment istat the same time -->
    <CustomDataNode id="Logic.Signer1EqualsProfileAndOuIsNotFinance">
      <Condition when="Profile.Id = Signer_1.Id">
        <!-- d7427a29-dda3-4a22-b6ec-e97dba9a8c22 istis diethe IDid derof OEunit "Finanzdepartementfinance department" ↓ -->
        <Condition notwhen="Profile.OrganizationUnitId = 'd7427a29-dda3-4a22-b6ec-e97dba9a8c22'">
          <Text>true</Text>
        </Condition>
      </Condition>
    </CustomDataNode>
  </Script>
</Configuration>

Beim Verknüpfen von globalen Skripten, die auf andere Logik-Skripte zugreifen, muss darauf geachtet werden, dass das Logik-Skript ebenfalls verknüpft wird. Beispiel, wobei "CompanyAddress" das Resultat des Logik-Skripts benötigtWhen linking global scripts that access other logic scripts, care must be taken to ensure that the logic script is also linked. Example, where "CompanyAddress" needs the result of the logic script: {[Scripts.Logic.Signer1EqualsProfileAndOuIsNotFinance]}
{[Scripts.CompanyAddress]}

Multiple recursion (Depth)

Der Zugriff auf ein Resultat eines simplen Skripts funktioniert immer. Der Zugriff auf ein Resultat eines Skripts, das wiederum auf das Resultat eines weiteren Skripts zugreift, wird mit Depth ermöglicht. Das passiert in der Skripte-Dokumentfunktion. Hier ist die Depth auf 5 gesetztAccessing a result of a simple script always works. Accessing a result of a script which in turn accesses the result of another script is enabled with Depth. This happens in the Scripts document function. Here the Depth is set to 5:

<Configuration>
  <Script engine="XSL" version="2" depth="5">

Das bewirkt nun, dass die Skript-Resultate 3-mal berechnet werden und folglich, dass der Zugriff eines Skriptes A auf das Resultat eines Skriptes B, das auf das Resultat eines Skripte C zugreift, funktioniert. Die Depth ist in jeder Kundendatenbank folgendermassen in den Globalen Konfigurationen ausgelagert:

Image Removed

In jeder Skripte-Dokumentfunktion sieht die Verknüpfung dann so ausThis causes now that the script results are calculated 3 times and consequently that the access of a script A to the result of a script B, which accesses the result of a script C, works. The Depth is stored in each customer database in the Global Configurations as follows:

Image Added

In each [Scripts document function](~/docfunc/docfunc-all/scripts.md) the link then looks like this:

<Configuration>
  <Script engine="XSL" version="2" depth="{[Config.Depth]}">

Wenn ein Resultat eines Skripts, das auf andere Skripte zugreift, nicht wie erwartet ist, muss überprüft werden,

• ob das Skript, auf das zugegriffen wird, überhaupt verfügbar / verknüpft ist.

• ob die Depth mindestens so hoch ist, wie die Anzahl verschachtelter Zugriffe.

Code-Darstellung

Eine Einzugsebene besteht aus 2 Leerzeichen oder einem Tab. Beim Druck der Tab-Taste im primedocs-XML-Editor werden 2 Leerzeichen eingefügt. Wenn mehrere Zeilen markiert sind, kann durch Druck "Tab" und "Shift+Tab" der Einzug der markierten Zeilen vergrössert und verkleinert werden. Folgend ein Beispiel mit korrekten EinzügenIf a result of a script accessing other scripts is not as expected, it is necessary to check,

• whether the script being accessed is available / linked at all.

• whether the Depth is at least as high as the number of nested accesses.

Code representation

An indent level consists of 2 spaces or a tab. When pressing the Tab key in the OneOffixx XML editor, 2 spaces are inserted. If multiple lines are selected, pressing "Tab" and "Shift+Tab" can increase and decrease the indent of the selected lines. The following is an example with correct indents:

<Configuration>
  <Script engine="XSL" version="2" depth="{[Config.Depth]}">

    <CustomDataNode id="EnclosuresBox">
      <Line>
        <Text>{D[Texts.Enclosures]}:</Text>
      </Line>
      <Line>
        <Element id="DocParam.Enclosures" linePrefix="&amp;#8211;&amp;#009;" />
      </Line>
    </CustomDataNode>

  </Script>
</Configuration>

Globale Konfigurationen

Global Configurations

Nice code in the Global Configurations includes having an empty paragraph follow each "CustomDataNode" element in an entry. Here is an example:

    <CustomDataNode id="CompanyAddress.IncludingUnit">
      [...]
    </CustomDataNode>

    <CustomDataNode id="CompanyAddress.WithoutUnit">
      [...]
    </CustomDataNode>

    <CustomDataNode id="CompanyPhone">
      [...]
    </CustomDataNode>

Skripte

Scripts

CustomDataNodes are also visibly separated from each other by blank lines. Complicated scripts as well as conditions in the scripts should be explained in an introductory comment. For conditions, the value of the when/notwhen attribute can contain line breaks. These improve readability:

<Configuration>
  <Script engine="XSL" version="2" depth="{[Config.Depth]}">

    {[Scripts.CompanyAddress]} 

    {[Scripts.EnclosuresBox]}

    <CustomDataNode id="InfoBox.Top">
      <!-- At the Obentop anof derthe orangenorange InfoBox appears erscheintthe diedescription Beschreibungfrom austhe demdocument Dokument-Parameterparameter
           (DocParam.Description), if sofernit dieseis ausgefülltfilled istin. AnsonstenOtherwise erscheinta einegeneral information 
         allgemeine Information (Texts.ContractInformation ausfrom GlobalenGlobal ÜbersetzungenTranslations) appears,  
          sofern esif sichit umis einena Vorschlagproposal, einena Vertragcontract oderor einan Angebot handeltoffer. -->     
      <Element id="DocParam.Description" />
      <Condition notwhen="DocParam.Description">
        <Condition when="DocParam.DocType = '{U[DocParam.DocType.Proposal]}' |
                         DocParam.DocType = '{U[DocParam.DocType.Contract]}' |
                         DocParam.DocType = '{U[DocParam.DocType.Offer]}'">
        <!-- DerThe Texttext untenbelow erscheinwill nur,only wennappear esif sichit umis
einen             a Vorschlagproposal, einencontract Vertragor oder ein Angebot handelt offer -->
          <Line>
            <Text>{D[Texts.ContractInformation]}</Text>
          </Line>
        </Condition>
      </Condition>
    </CustomDataNode>

    <CustomDataNode id="InfoBox.Bottom">
 
    <!-- Unten an der orangenAt the bottom of the orange InfoBox erscheintthe dieversion Versionfrom austhe demdocument   parameter
        Dokument-Parameter (DocParam.Version) sowie eine Copyright-Information.  appears as well as a copyright information.-->
      <Line>
        <Text>{D[Texts.Version]} </Text>
        <Element id="DocParam.Version" />
      </Line>
      <Line fixoutput="true" />
      <Line>
        <Text>&amp;#169; </Text>
        <Element id="DocParam.Date" fFormatingDate="yyyy" separator=" " />
        <Element id="Profile.Org.Title" />
      </Line>
    </CustomDataNode>

    <!-- ÜbersetzungenTranslations -->
    <CustomDataNode id="Texts.Page">
      <Text>{D[Texts.Page]}</Text>
    </CustomDataNode>

    <CustomDataNode id="Texts.PageOf">
      <Text>{D[Texts.PageOf]}</Text>
    </CustomDataNode>

  </Script>
</Configuration>

Dokument-Parameter

Document parameters

By bringing attributes to the same height with tabs, clarity can be increased:

  <Text       Id="DocParam.Subject" />
  <DateTime   Id="DocParam.Date" />
  <CheckBox   Id="DocParam.Option01" />
  <CheckBox   Id="DocParam.Option02" />
  <CheckBox   Id="DocParam.Option03" />
  <CheckBox   Id="DocParam.Option04" />
  <CheckBox   Id="DocParam.Option05" />
  <CheckBox   Id="DocParam.Option06" />
  <CheckBox   Id="DocParam.Option07" />
  <CheckBox   Id="DocParam.Option08" />
  <CheckBox   Id="DocParam.Option09" />
  <CheckBox   Id="DocParam.Option10" />
  <CheckBox   Id="DocParam.Option11" />
  <CheckBox   Id="DocParam.Option12" />
  <ComboBox   Id="DocParam.Options" SelectedValue="2">
    <Item Value="1" DisplayText="Option A" />
    <Item Value="2" DisplayText="Option B" />
  </ComboBox>
  <Text       Id="DocParam.Option12Text" />
  <Text       Id="DocParam.Enclosures" />
  <Text       Id="DocParam.CopyTo" />