1 Description

1.1 Contents

xtpxlib-common consists of the following parts (by subdirectory):

1.2 Parameter handling in xtpxlib-common

Parameters, as referred to here, are name/value pairs meant for customizing software's behavior. Things like prompts, URIs, etc. The xtpxlib-common component's parameters have the following characteristics:

• Parameters in this component are handled by the XSLT module parameteres.mod.xsl. This includes:

  • Reading them from an XML document, either a document on its own or embedded into a bigger XML document. The result will be an XPath map(xs:string, xs:string*), which can be inspected and used.

  • Expanding parameter references in strings. Parameter references are constructions like {$parameter-name} (or ${parameter-name}, both will yield the same results).

• Parameters are specified within an XML element called <parameters>, the namespace does not matter. This element can be the root of a document on its own or embedded in a bigger (XML) document. For instance:

  <parameters>
    <parameter name="greeting">
      <value>Hello!</value>
    </parameter>
  </parameters>

  There is a schema available for this.

• A single parameter is specified using a <parameter name="…"> child element.

  The value of the name attribute will be normalized (whitespace collapsed to a single space character, leading/trailing whitespace removed) and space characters are replaced with an underscore (_). So name=" a b " will become parameter a_b.

• Values for a parameter are specified using <value> child element. A parameter can have multiple values. Parameter references inside values (either written as {$parameter-name} or ${parameter-name}) are expanded into their values (for multi-valued parameters only the first value is used).

• It is often useful to specify values for parameters based on different circumstances. For instance based on language (Hello in English or Bonjour in French), or system type (https://www… for production, http://test… for test). This is implemented as follows:

  • When initially reading the parameters you can specify a filter map (map(xs:string, xs:string*)).

  • The <value> elements can have any attributes. These attributes are handled as whitespace separated lists of values.

  • The name of such an attribute is held against the entries in filter map. If a filter entry with this name exists, one of the values of the attribute must be present in the filter map.

  For instance, assume the parameters look like this:

  <parameters>
    <parameter name="greeting">
      <value lang="en">Hello!</value>
      <value lang="nl de">Hallo!</value>
      <value lang="fr">Bonjour!</value>
    </parameter>
    <parameter name="number">
      <value>123</value>
    </parameter>
  </parameters>

  • Reading this with an empty (or absent) filter map, or a filter map that does not have a lang entry, will result in a greeting parameter with multiple values, Hello!, Hallo! and Bonjour!.

  • Reading this with a filter map map{'lang': 'en'} will return the greeting parameter with value Hello!.

  • Reading this with a filter map map{'lang': 'fr'} will return the greeting parameter with value Bonjour!.

  • Reading this with a filter map map{'lang': ('en', 'de')} (not particularly useful) will return the greeting parameter with values Hello! and Hallo!.

  • In all cases the number parameter will get value 123 (since it has no filtering attributes on its <value> element).

  It is possible to combine multiple filter attributes on a <value> element.

• Another thing that is often useful in specifying parameters is to group them. For this you can put a number of <parameter> elements inside a <group name="…"> element. The name of the group is used as a prefix (with a dot (.) separator) for the parameters in the group. For instance:

  <parameters>
    <group name="important">
      <parameter name="greeting">
        <value>Hello!</value>
      </parameter>
    </group>
  </parameters>

  This will result in a parameter called important.greeting.