Skip to main content

Context

The context is used within Word document templates and is available through the keyword context.

It is a supporting layer between Aspose and Flowable to use Flowable expressions and variables during the template generation. Below there is a list of methods which can be used.

tip

The name of the context object can be changed by the Context object property in Flowable Design. The default value is context.

To get started with the template generation, checkout the how-to generate documents.

Methods​

Value retrieval​

value(String expressionText): Gets a value from an expression. In case an expression is unable to resolve it will throw an error, and it won't generate the document. This can be useful if the document should not be rendered in case of errors in the expression. However, an alternative approach is to use the valueOrDefault(String, Object) method as described below, which is resolving the error case to a default value.

For example, to display the value of a variable location: 

[context.value("${location}")]

valueOrDefault(String expressionText, Object defaultValue) : Gets a value from an expression or returns a default value in case the value resolves to null or the expression throws an exception. For example, when the value could not be found it will render the default value.

hasValue(Object obj, String key): Checks if a (nested) value from a map, JSON node, or variable container exists and returns a boolean value.

For example, to check if a person variables has an address field"

<<[context.hasValue(context.value("${person}"), "address")]>>

And to check if that address has again a nested field, for example street:

<<[<<[context.hasValue(context.value("${person}"), "address.street")]>>

booleanValue(String expressionText): Gets a boolean value from an expression.

mapValue(Object obj, String key): Retrieves a (nested) value from a map (or JSON node, or variable container). If the value does not exist, null is returned.

Examples: 

<<[context.mapValue(context.value("${person}"), "address")]>>
<<[context.mapValue(context.value("${person}"), "address.street")]>>
<<[context.mapValue(context.value("${person}"), "unknown")]>>

In this example, if this would lead to null, doing 

<<[context.mapValue(context.value("${person}"), "unknown.street")]>>

Would throw an error.

General expression evaluation​

evaluate(String expression, Object item): Evaluates a given expression using a specified input parameter. It takes exactly one item which is either a Map, a VariableContainer or a JsonNode. The item is then used as a base for an expression. The expression directly uses the field out of the object which is provided and does not require an additional prefix. The expression has access to all variables present in the document's context.

evaluate(String expression, Object item, String itemName): This method accepts any type of item, which is identified by an itemName. This itemName provides a way to reference the input item within the expression.

Looping​

foreach(String expressionText): Ability to iterate over a list based on an expression which evaluates to an iterable item. This could for exmaple be a list coming from a form or created with an Init Variable task or something else.

For example, to use the mapValue in a forEach block for writing out a nested collection, given the following JSON:

{
    "tasks": [
        {
            "candidateUserIds": [
                {
                    "id": "abc",
                    ...
                },
                ...
            ]
        },
        ...
    ]
}

would need to be

<<foreach [task in context.foreach("${tasks}")]>>
    <<foreach [candidateUserId in context.foreach(context.mapValue(task,candidateUserIds))]>>
        User ID:<<[context.mapValue(candidateUserId,"userId")]>>
    <</foreach>>
<</foreach>>

Images​

image(String expressionText): Displays an image within a document. The expression needs to resolve to a content item, a list of content items or bytes.

HTML and Markdown​

asHtml(String expressionText): The 'rich text' form component stores its value either as markdown or html. When stored as html, the html won't be 100% perfect for using in Aspose within a Word template. Calling this method will change the html that is incompatible to make it compatible.

markdownAsHtml(String expressionText): Converts text as a markdown to a HTML text which can be used for rendering within a Word template.