Configuration

Generally, all Calyxo configuration files are in XML format.

Each module takes its own set of configuration files. Within a module, each Calyxo component is configured through individual configuration files. However, the Calyxo Base component is somewhat special. Most of its configuration elements may be reused in configurations of other Calyxo components.

Namespaces

Each Calyxo component uses its own separate namespace for configuration elements. The elements described in the following sections are defined within namespace http://calyxo.odysseus.de/xml/ns/base.

Because other components may share Calyxo Base configuration elements, we have to consider two scenarios:

  1. In a standalone Calyxo Base configuration file, we use this namespace as the default namespace.
    <calyxo-base-config version="0.9"
      xmlns="http://calyxo.odysseus.de/xml/ns/base">
      ...
      <set .../> 
      ...
    </calyxo-base-config>
    
  2. In another component, say Foo, this namespace should be bound to prefix base in the root element of the configuration file, as in
    <calyxo-foo-config version="0.9"
      xmlns="http://calyxo.odysseus.de/xml/ns/foo"
      xmlns:base="http://calyxo.odysseus.de/xml/ns/base">
      ...
      <base:set .../> 
      ...
    </calyxo-foo-config>
    
    DTD Limitation
    When using DTD validation, the prefix must be base. Otherwise, an arbitrary prefix is allowed. However, we recommend to use prefix base to keep compatibility.

Throughout this documentation, we'll use the configuration elements without prefix, as they were used in a standalone Calyxo Base configuration file. Keep in mind that the base prefix has to be added, when these elements are reused in configuration files for other Calyxo components.

Schema/DTD Validation

When loading configuration files, Calyxo forces the XML parser to validate documents against an XML Schema definition (XSD) or a Document Type Declaration (DTD). Calyxo prefers XML Schema validation, so, if your parser supports it, it is used. Otherwise, DTD validation is used. In this case, configuration files must declare the Calyxo Base document type:

<!DOCTYPE calyxo-base-config
  PUBLIC "-//Odysseus Software GmbH//DTD Calyxo Base 0.9//EN"
  "calyxo-base-config.dtd">

Copies of the DTD and XSD are located at CALYXO_HOME/calyxo-panels/conf/share/calyxo-base-config.*.

Document structure

In a standalone Calyxo Base configuration file, the root element is <calyxo-base-config>. As common to all of Calyxo's configuration files, the root element specifies the xmlns and version attributes. It may contain <import> elements, followed by <functions>, <set> and <use> elements.

<calyxo-base-config version="0.9"
  xmlns="http://calyxo.odysseus.de/xml/ns/base">

  <!-- import elements can go here -->

  <!-- functions, set and use elements can go here -->

</calyxo-base-config>

Importing another configuration file

A configuration file may import another file containing some other parts of the component's configuration. The imported configuration is merged into the importing configuration.

<import file="../calyxo-control-config-shared.xml"/>

The imported file must be either

  • of the same type as the importing file or
  • a Calyxo Base configuration file.

This feature also gracefully supports sharing of common configuration parts between modules.

Dynamic Attributes

Where it makes sense, attribute values of configuration elements may contain EL expressions. We call these attributes dynamic. Expressions may refer to constant expressions like true, false, 1.23+4.56 and null.

Additionally, dynamic attributes are evaluated in a context, that makes available several implicit objects. These implicit objects are always available under the following names:

  1. moduleContext – resolves to the module context instance
  2. moduleScope – resolves to a map serving module scope attributes
  3. applicationScope – resolves to a map serving application scope attributes

Other identifiers are searched as local variable (see below), then as module scope attribute, then as application scope attribute.

Finally, functions may be declared and used in dynamic attribute expressions. Functions are static methods of a specified class. The element

<functions prefix="foo" class="FooFunctions"/>

registers all public, static methods of class FooFunctions under prefix foo.

Now, expression ${foo:bar(module)} will evaluate to the returned value of the static method FooFunctions.bar(...), passing in the module context as an argument.

Defining Variables

Variables are defined using the <set> element and may be subsequently used in dynamic attribute expressions. The required var attribute is used to specify the variable name.

A variable may have one of the following visibility scopes

  1. local – A local varibale is visible inside following siblings of the <set> element, which defined the variable. Stated another way, a local variable is visible below its declaration down to the end tag of the <set>'s parent element.
  2. module – A variable with module scope is saved as a module context attribute.
  3. application – A variable with application scope is saved as a servlet context attribute.

A variable's scope may be specified using the optional scope attribute. Valid values are local, module and application. The default scope is local.

The dynamic value attribute may be used to specify the variable's value. Here's an example for a (local) variable definition:

<set var="content" value="/WEB-INF/${moduleContext.name}"/>

Assuming module name "foo", the dynamic attribute expression ${content}/bar.jsp will evaluate to /WEB-INF/foo/bar.jsp.

However, specifying the value attribute is the most simple way to define a variable value. Alternatively,

  • a nested <object> element may be used to create and initialize a new object:
    <set var="list">
      <object class="java.util.ArrayList">
        <method name="add">
          <arg value="foo"/>
        </method>
      </object>
    </set>
    
    creates a new java.util.ArrayList and initializes it by calling its add() method with "foo" as argument.
  • a nested <member> element may be used to access an object's method or field:
    <set var="size">
      <member value="${list}">
        <method name="size"/>
      </member>
    </set>
    
    answers the result of invoking method size() on the object given by expression ${list}.

Please refer to the set, use & Co section for further details.

Using Objects

The <use> element can be used to invoke methods and set properties of an object referenced by an expression given in the value attribute:

<use value="${list}">
  <method name="add">
    <arg value="bar"/>
  </method>
</use>

will invoke method add on the oject given by expression ${list}, passing "bar" as an argument.

Please refer to the set, use & Co section for further details.