Controller

The controller is a CGI or Fast-CGI program that is programmed with XML configuration files. It is important to note that no C/C++ code has to be written for the controller part, it is entirely programmed by means of XML.

The controller configuration files (a.k.a. flow files) are located in /opt/DOMAIN/web/flow

The document element must be config. Under this element there are a number of functions, containing statements. Entry point is always the function with the name main. The following statements exist:

call

Calls another function. It has the following attributes:

  • name variable name that contains the function name to call
  • takefrom from where to take the variable
  • default function name to use if the variable does not exist

Example:

<function name="start">
  ...
</function>
<function name="f1">
  ...
</function>
<function name="f2">
  <!-- direct call by name -->
  <call name="f1"/>
</function>
<function name="main">
  <!-- indirect call by form variable: calls f1, f2 or start depending on "action" form variable -->
  <call name="action" takefrom="input" default="start"/>
</function>

header

Outputs the HTTP header. It must have a mandatory attribute type specifying the output media type. The optional attribute charset specifies the charset. Possible pre-defined types are:

  • gif for a GIF file
  • html for a HTML 4.01 page
  • jpg for a JPG file
  • xhtml for an XHTML 1.0 page
  • xml for XML

Types not listed will be output as given.

Example:

<header type="html" charset="utf-8"/>
<process name="page"/>

html

Outputs an HTML tag. It must have a mandatory attribute tag specifying the tag name. An optional tag attributes can contain attributes for the tag. Enclosed in this statement can be other statements such as process, call or invoke whose output will be inside the generated HTML tag. This statemet is typically used to output a part of the html page that is inside an XSL.

Example:

<html tag="html">
  <process name="head"/>
  <html tag="body" attributes='id="cssbody"'>
    <process name="bodypart1"/>
    <invoke class="Test" method="test">
      <success>
        <process name="bodypart2"/>
      </success>
      <failure>
        <call name="error"/>
      </failure>
    </invoke>
  </html>
</html>

function

Defines a new function. The mandatory attribute name contains the function name.

Example:

<function name="main">
  <process name="page"/>
</function>

inputcheck

Starts an input check of values that were entered into a form. This node contains several check subnodes, as well as one success and one failure node.

check

Performs a check of a single field. This node does not have any children but a number of attributes:

  • name mandatory variable name
  • takefrom mandatory variable source
  • type mandatory variable type that selects the type of check to perform
    • email e-mail address check
    • file uploaded file check
    • number decimal number check
    • phone phone number check
    • string text input check
  • allowed allowed characters
  • max maximum number of characters
  • min minimum number of characters
  • precision number of decimal places
  • select true | false : input field is a select box
  • signed true | false : allow signed numbers

success

Actions to take when the input check was successful.

failure

Actions to take when the input check failed.

Example:

<inputcheck>
  <check name="firstname" min="2" max="80"/>
  <check name="lastname" min="2" max="80"/>
  <success>
    <invoke class="Test" method="create">
      <input name="firstname"/>
      <input name="lastname"/>
    </invoke>
  </success>
  <failure>
    <!-- display form again -->
    <process name="form"/>
  </failure>
</inputcheck>

invoke

Calls a method from the application logic via SOAP and places its output in the XML node output. It takes the following attributes:

  • class class name of the method to call
  • method method to call
  • context calling context: user, system or support

It also contains several input, file and one success and failure statement.

input

Defines an input parameter for an application logic call. It has the following attributes:

  • name (mandatory) parameter to set
  • takefrom (mandatory) the parameter source

If the node contains text, this text is used as the parameter value. Otherwise a parameter is looked for in the specified source. When specifying text, variables from the given source can be inserted using $name$.

file

Defines an input file for an application logic call. The attribute name specifies the name of the form field.

success

Actions to take when the application logic call was successful.

failure

Actions to take when the application logic call failed.

Example:

<!-- calls business logic via soap -->
<invoke class="Test" method="create">
  <input name="firstname"/>
  <input name="lastname"/>
  <success>
    <!-- display success message -->
    <process name="success"/>
  </success>
  <failure>
    <!-- display form again -->
    <process name="form"/>
  </failure>
</invoke>

process

Processes an XSLT file. It takes the following attributes:

  • name (mandatory) name of the XSLT file without extension
  • xml (optional) name of the XML file containing localized strings (without extension)
  • extra (optional) name of an XML file containing additional data

If no XML file name is given, an XML file with the same name as the XSLT file is searched.

Example:

<!-- shows a form loading an extra xml document -->
<process name="form" extra="f2vars"/>

redirect

Outputs an HTTP redirect. This ends processing of the flow script. To make the redirect work, it must be the first output, i.e. there must not have been a header, body or process happened before it.

  • target (mandatory) variable name that contains the redirect target
  • takefrom (optional) from where to take this variable
  • ssl (optional) flag: if set to true the redirect will go to https
  • default (optional) a default target in case the variable does not exist

The target can also be a string that uses variables from the specified source in the form of $name$

Example:

<!-- requires ssl and logged in user -->
<redirect target="login"/>

require

Defines requirements that must be fulfilled before processing can go on. There are two possible requirements given as attributes:

  • auth requires an authenticated user. If there is no authenticated user associated with this session, a redirect to the attribute value is performed (this would be a flow script that displays a login form). A user is authenticated if the global session variable userid is set.
  • ssl requires that the HTTP call happened over secured HTTP (HTTPS). If this is not the case, a redirect to the secured version of this URL will be made.

For this statement to work properly, no output must have been generated yet, i.e. there must not have been a header, body or process statement.

Example:

<!-- requires ssl and logged in user -->
<require ssl="true" auth="login"/>

set

Sets a local session variable. The node has no children and the following attributes:

  • name (mandatory) variable to set
  • takefrom (mandatory) the variable source

If the node contains text, this text is used as the variable value. Otherwise a variable is looked for in the specified source. When specifying text, variables from the given source can be inserted using $name$.

Example:

<!-- erases firstname -->
<set name="firstname" takefrom="null"/>
<process name="form"/>

switch

A conditional statement block. Takes several case and one optional otherwise block. The first case that matches is executed, if none matches and an otherwise block is present then this one will be executed. The switch takes the following attributes:

  • var (mandatory) variable name to test
  • takefrom (optional) from where to take this variable

case

Contains a list of statements to execute if the variable named in the switch statement has the value given in the mandatory val attribute of the case statement.

otherwise

Contains a list of statements to execute if none of the case blocks matches.

Example:

<!-- redirects if action is authenticate -->
<switch var="action" takefrom="input">
  <case val="authenticate">
    <redirect target="login"/>
  </case>
  <otherwise>
    <header type="html"/>
    <process name="start"/>
  </otherwise>
</switch>

Valid variable sources

The following valid variable sources exist (value of a takefrom attribute):

  • (empty value or missing takefrom attribute) take from input or local session variable
  • input the HTTP request that caused this call
  • output the result of the last application logic call
  • local a local session variable
  • global a global session variable
  • env the CGI environment
  • cookie the cookie
  • null a null input, producing empty strings