Functions / Formulas

The Process development kit provides a Framework for implementing new functions used within the documents. This Framework is very similar to both components and plug-in frameworks. It provides a Java-based plug-in model for functions.

To speed time to market and reduce costs for developers, this Framework includes a complete API, libraries and samples that illustrate reference implementation for successful custom functions.

General information

What is a function ?

A function is a small unit of process which transforms data to a particular output. Functions are used in several contexts :

initializing field values
showing or hiding graphical elements through the fragments
defining a test
defining a view filter

Basically, a function is composed of a name, arguments and a method called execute. The return type is a java.lang.Object.

The function Framework gives a standard way for defining :

an XML definition file: an association between the name of the function and its class (full qualified name).
a function class: class to execute while evaluating the functions.
an XML resource file: localized string.

Existing functions

Process implements a number of functions :

The main goal of these functions is to be able to meet the functional needs of our customers without requiring specific development.

This section contains all the information required to use these functions.

Note

Some features may only be available in English and French.

XML definition

The XML function file should be deployed on the custom/functions folder. Its name must be unique on the Process server. To prevent name conflicts it is recommended to use the following template: companyName-functions.xml (e.i. visiativ-functions.xml). This XML definition file provides all the necessary information to describe several functions:

Function name: the name should be unique on the Process server and in upper case

<functions>
  <function class="com.axemble.studio.formulas.functions.DateFunction" name="DATE" category="date">
    <argument index="1" default-value="datetime" />
    <argument index="2" default-value="short" />
    <argument index="3" default-value="default" />
  </function>
</functions>

Function runtime class: the full qualified name of the function class to execute.
Function category: the category is optional. If not declared, the function will appear inside a default category.
argument tags: allows to specify the default values for the optional arguments. Use the zero-based index to target an argument.

Runtime class

A runtime class is a Java class which will be called by the framework. A runtime class must extend the com.axemble.vdoc.sdk.BaseFormulaFunction class.

By creating a function runtime class you need to implement a unique method: execute().

Create the runtime class for the validator

Example:

public class TranslateFunction extends BaseFormulaFunction {
    private static final long serialVersionUID = 1L;

    public String execute(String id, String... args) {
        String language = (String) getContextValue("language"); // retrieve the language
        return LocalizationMap.getString(id, language, args);
    }
}

Note

Considerations about functions with variable parameters (ellipsis, varargs) and Collections Functions with variable parameters receive parameters as an Array. If such a function is passed a java.util.Collection as last parameter, then before the Collection is passed to the execute() method, it will be transformed as an Array of its members. For example, consider the following Collection myElements : CollectionInteger myElements = new ArrayList(); myElements.add(1); myElements.add(2); myElements.add(3); @SUM(4;myElements) is equals to @SUM(4;1;2;3), or 10.

XML resource

In order to localize the name of the function, you should always specify each string as a resource. The XML resource file should be deployed on the custom/internationalization folder. Its name must be unique on the Process server. To prevent name conflicts it is recommended to use the following template: companyName-functions-resources.xml (e.i. visiativ-functions-resources.xml). This file must contain every string used for the treatment.

Use the ids as shown in the following exemple:

<?xml version="1.0" encoding="UTF-8"?>
<res>
	<id value="formula.function.FUNCTION_NAME.label">
		<lang value="en" flag="1">Function label example</lang>
		<lang value="de" flag="1">Funktion Label Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.description">
		<lang value="en" flag="1">Function description example</lang>
		<lang value="de" flag="1">Funktion Beschreibung Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.returnTypeLabel">
		<lang value="en" flag="1">Function return type label example</lang>
		<lang value="de" flag="1">Funktion Return Type Label Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.returnTypeLabel">
		<lang value="en" flag="1">Function return type label example</lang>
		<lang value="de" flag="1">Funktion Return Type Label Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.argument.0.label">
		<lang value="en" flag="1">First argument label example</lang>
		<lang value="de" flag="1">Erstes Argument Label Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.argument.0.description">
		<lang value="en" flag="1">First argument description example</lang>
		<lang value="de" flag="1">Erstes Argument Beschreibung Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.argument.1.label">
		<lang value="en" flag="1">Second argument label example</lang>
		<lang value="de" flag="1">Zweiters Argument Label Beispiel</lang>
	</id>
	<id value="formula.function.FUNCTION_NAME.argument.1.description">
		<lang value="en" flag="1">Second argument description example</lang>
		<lang value="de" flag="1">Zweites Argument Beschreibung Beispiel</lang>
	</id>
</res>

Creation

Fonction

Java classe

La classe Java de la nouvelle fonction doit étendre com.axemble.vdoc.sdk.BaseFormulaFunction et la méthode execute implémentée (public avec le type de retour et le nombre et le type d’arguments libres).

Ci-dessous, un exemple d’une fonction permettant de récupérer le login d’un utilisateur :

public class UserLoginFunction extends BaseFormulaFunction {

	private static final com.axemble.vdoc.sdk.utils.Logger LOG = com.axemble.vdoc.sdk.utils.Logger.getLogger(UserLoginFunction.class);

	public String execute(IUser user, boolean toUperCase) 	{
		if (user != null && user.getLogin() != null) 		{
			if (toUperCase) 			{
				return user.getLogin().toUpperCase();
			} else {
				return user.getLogin();
			}
		} else {
			return null;
		}
	}
}

XML

Le XML utilisé doit être présent dans le dossier custom/functions/ :

<functions>
	<function class="com.vdoctest.formula.UserLoginFunction" name="COPYLOGIN" category="user" >
		<argument index="1" default-value="false" />
	</function>
</functions>

Le nom est obligatoire, et en majuscule. C’est le nom système de la fonction, il est utilisé pour les clés de traductions.
L’attribut class correspond au qualified name de la classe de fonction.
Les balises argument permettent de définir des arguments facultatifs. L’index commence à 0.
Dans l’exemple, si la fonction est appelée sans le deuxième argument, celui-ci sera mis automatiquement à false

Translation keys

Les clés de traductions se mettent dans le dossier custom/internationalization et suivent le schéma suivent (où function_name correspond au nom système de la fonction, en minuscule) :

formula.function.function_name.label : pour le label de la fonction
formula.function.function_name.description : pour la description de la fonction
formula.function.function_name.returnTypeLabel : pour le type de retour
formula.function.function_name.argument.INDEX.label : pour le label de l’argument INDEX
formula.function.function_name.argument.INDEX.description : pour la description de l’argument INDEX

Info

Les index des arguments commencent à 0.

Pour l’exemple ci-dessus, on obtient :

<res>
    <id value="formula.function.copylogin.label">
        <lang flag="1" value="fr">COPIELOGIN</lang>
    </id>
    <id value="formula.function.copylogin.description">
        <lang flag="1" value="fr">Calcule le login d'un utilisateur, en majuscule ou pas</lang>
    </id>
    <id value="formula.function.copylogin.returnTypeLabel">
        <lang flag="1" value="fr">string</lang>
    </id>
    <id value="formula.function.copylogin.argument.0.label">
        <lang flag="1" value="fr">user</lang>
    </id>
    <id value="formula.function.copylogin.argument.0.description">
        <lang flag="1" value="fr">l'utilisateur</lang>
    </id>
    <id value="formula.function.copylogin.argument.1.label">
        <lang flag="1" value="fr">[majuscule]</lang>
    </id>
    <id value="formula.function.copylogin.argument.1.description">
        <lang flag="1" value="fr">copier en majuscule ou pas</lang>
    </id>
</res>