User Interface

User Dialogs

A User Dialog is one of the two possibilities to interact with the user in a process. The other possibility are simple web pages as already used in pre Xpert.ivy 4.x releases. User Dialogs are provided in Axon.ivy 5.x using Java Server Faces (JSF) technology from Oracle .

In Axon.ivy we use Html Dialog - or HD for short - as the name for a User Dialog Component built with JSF.

User Dialog Concept

The concept of a User Dialog follows the famous Model-View-Controller pattern. It consist of the following parts:

  • Data - The internal data of the User Dialog (the model)

  • View / Panel - The visual representation of the User Dialog (the view)

  • Logic - The implementation of the functionality (the behavior) of the User Dialog (the controller)

  • Interface - A description of the capabilities of the User Dialog

  • (Data Binding) - A mapping of widget properties with data members

  • (Event Mapping) - A mapping of an UI event with a process in the User Dialog Logic

The logic (i.e. controller) of User Dialogs is implemented in a process based manner. This means that all the GUI events (which are generated by the user who interacts with the dialog) are handled by means of a corresponding UI process in the logic of the User Dialog component. So the behaviour of the User Dialog is not implemented by writing source code in a programming language (such as Java, Visual Basic or C#) but rather by graphically modelling a process logic in Axon.ivy.

The multi-part structure of a User Dialog becomes also evident when looking at its representation in the Axon.ivy project tree:

Interface

The interface of a User Dialog defines its behavior in an abstract way and independent of its implementation. In other words it defines what a User Dialog is capable to do. In more detail, the interface defines Start Methods and Methods of a User Dialog.

The interface is edited and defined using the Interface Editor.

Logic

The logic of a User Dialog defines how a User Dialog performs its work by means of a process model. For each UI Event (triggered by the actual user, e.g. by clicking on a button) and for each Start Method and Method defined on the interface you may implement a process to handle these events.

The logic of a User Dialog is edited and defined using the Process Editor.

To build the logic of a User Dialog the Process Editor offers a set of process elements that is somewhat different from the standard set. The extra User Dialog drawer of the Process Editor palette contains elements, which can only be used within User Dialog logic:

IconTitleShort Description
User DialogOpens another User Dialog
Init StartInvoked when the User Dialog is started. This element is executed at most once and initializes the User Dialog and its data.
Method startInvoked when one of the methods declared in the User Dialog Interface is called.
Event StartInvoked when a mapped widget event is received from the view of the User Dialog.
ScriptEncapsulates IvyScript code or changes in the User Dialog data.
Process EndEnds a User Dialog UI process.
Exit EndExits and closes this User Dialog and continues with the calling process (if opened synchronously).

Table 6.1. Process elements only available in User Dialog Logic

On the other hand, some elements of the Dialog & Control drawer are missing, because they are forbidden:

IconTitleShort Explanation
Request StartThe normal Request element is replaced with the User Dialog start element.
Web PageThe Page element is HTML-specific and thus not available in the User Dialog logic.
TasksThe Tasks element is not available because role change and task data persistence can only happen between User Dialogs.
TaskThe Task element is not available because role change and task data persistence can only happen between User Dialogs.
Event StartStart Event Beans are currently not supported inside User Dialogs.
IntermediateIntermediate Events are currently not supported inside User Dialogs.
Call & WaitCall & Wait are currently not supported inside User Dialogs.
Process EndThe regular Process End element is replaced with the User Dialog End element.
End PageThe End Page element is HTML-specific and thus not available in the User Dialog logic.

Table 6.2. Process elements that are forbidden in User Dialog Logic

Warning

When invoking callables from inside a User Dialog you have to bear in mind, that the callable process will be executed within the scope of the User Dialog that executes it, i.e. the same restrictions apply as if the callable was defined right inside the User Dialog's logic. This ultimately means that you have to ensure that the called (business) process does not contain any of the forbidden elements mentioned above. Otherwise you will experience failures or unpredictable results during execution of the callable process.

Data

The data of a User Dialog define its internal state (if you are familiar with the MVC pattern, you should consider the data as the Model of a User Dialog). The data of a User Dialog has private scope (i.e. is not visible from outside). Access can be granted by defining and implementing methods that return or manipulate internal data.

The data of a User Dialog is edited with the Data Class Editor.

User Dialog Interface Editor

Overview

The User Dialog Interface editor is used to define the API (Application Programming Interface) of a User Dialog. Since User Dialogs are components which are intended for reuse, they must define a stable interface on which other clients (i.e. processes or User Dialogs) can rely upon. An interface is defined independently from the implementation of the User Dialog and therefore separates the way of how a User Dialog performs its work from the declaration of what it is capable to do.

Accessibility

Axon.ivy Project Tree -> double click on the Interface node below a User Dialog in the tree:

Interface tab

The User Dialog Interface editor consists of the sections for the declaration of Start methods and Methods. Each section can have multiple entries, which can be added, edited and removed with the respective buttons. You can also edit an entry by simply double clicking on it (with the exception of the initially present default start() method).

Tip

It is strongly recommended to write a short description for each declared interface part in the Description area of the details pane. This will help clients of the User Dialog to understand the characteristics of the respective part.

Start Methods

Start methods define different entry points into a User Dialog. A User Dialog can be started with different parameters and return different values, depending on which entry point is chosen at call time.

When a new Start method is added (or edited) you must provide a name as well as input and output parameters. The name of the method is entered on the first page of the opened wizard.

The second page of the wizard is used to define the input and output parameters of the method. Both lists may be left empty. By clicking on the add button a new entry can be generated. Each method parameter consists of a name, a type, an optional description and the definition of whether null should be accepted at this position or not.

Tip

If the name/parameter combination (the so called signature) of the Start method as defined so far is identical to the signature of another Start method, then a warning will be displayed. The warning disappears when either arguments are added or argument types are changed or if the name of the method is altered accordingly, i.e. the signatures are no more identical.

Tip

You may already specify the type of the parameter here by adding a colon ':' to the parameter name, followed by desired type (e.g. myDateParameter:Date). When only adding a colon to the name without a type, the data type selection dialog will appear.

Note

Start methods defined in the User Dialog Interface can be selected inside a User Dialog Process element when the respective User Dialog is chosen to be started.

Methods

In the Methods section of the User Dialog Interface Editor the regular interaction methods of a User Dialog are defined. Those methods become available when a User Dialog is accessed with scripting, e.g. when used as an embedded User Dialog.

The declaration of Methods is absolutely similar to the declaration of Start methods, with the sole difference that a Method can only have a single return parameter (or none).

Metadata tab

You can define a textual description, a set of tags (keywords) for each User Dialog. These can be searched by the Ivy search page.

Description

A description of the User Dialog

Tags

The tags are a space separated list of keywords used to categorize User Dialogs. We suggest to define a vocabulary of tags within your team/company to always use the same terms.

New User Dialog Wizard

Overview

The New User Dialog wizard lets you create a new User Dialog. This can be a Html Dialog or an Offline Dialog.

The wizard creates several resources for the new User Dialog:

View

The visual component of the User Dialog (different technologies are possible).

Process

The Process that contains the logic of the User Dialog.

Data Class

The Data Class that holds the data of the User Dialog.

Interface

The Interface defines the ways of interaction with other User Dialogs or business processes.

Accessibility

File -> New -> Html Dialog

Page 1: Dialog Definitions
The New User Dialog Wizard Page 1

Figure 6.1. The New User Dialog Wizard Page 1

Project name

Choose the project that your User Dialog belongs to.

Namespace

Enter a namespace for your User Dialog. Use namespaces to group your User Dialogs. The grouping hierarchy is separated by the dot character. This is a similar concept as packages in the Java programming language.

Name

Enter the name of the User Dialog that you want to create.

Dialog Type

Select the type of the User Dialog that you want to create.

Tip

Since Html Dialog as well as Offline Dialog both base on JSF technology, it's possible to switch between those two dialog types after creation.

View Type

A view type defines the base layout of a User Dialog. Depending on the dialog type the view layouts vary and have the following attributes:

For the dialog types Html Dialog (JSF) and Offline Dialog (JSF) the view type could be selected from a predefined list of layouts. The list contains page and component layouts. Use a page layout for a standalone Html page, select a component layout to create a reusable Html component. See the corresponding chapter layouts and templates for more information.

Page 2: Dialog Data
The New User Dialog Wizard Page 2

Figure 6.2. The New User Dialog Wizard Page 2

This page provides the functionality to create necessary configuration of a User Dialog simple and quickly. The starting point is a data class. e.g. the data class of the process that calls the User dialog. Based on this data class the following configuration could be created:

Start-Method

A start method is created based on the selected In and Out attributes. The necessary parameter mapping will be automatically generated.

Data Class fields

For each selected In/Out attribute a field will be created in the Data Class of the User Dialog. The name of the created field could be defined in the column 'Field Name'.

Form (for Html/Offline Dialogs)

For each selected UI attribute a form field is created in the view. E.g. for a field birthday, of type Date, a label and a datepicker will be generated.

Tip

Create a User Dialog in the context of a User Dialog Process Element: If the New User Dialog Wizard is opened on a User Dialog Process Element, the initial Caller Class will be the class of the calling process and the in/out parameter mapping from the process to the User Dialog and back will be generated automatically.

Tip

Create a User Dialog in the context of a Data Class: If the New User Dialog Wizard is started via the context menu on a Data Class, the initial Caller Class will be the selected Data Class.

Html Dialogs

An Html Dialog (in the following abbreviated as HD) is one of two possibilities to implement a User Dialog Component. HDs are implemented using the Java Server Faces technology from Oracle

This means, that the view of an HD is defined with the means of an XHTML document and that it is displayed in a web browser.

PrimeFaces JSF Component Library

Axon.ivy is bundled with the JSF component library PrimeFaces, an open source JSF component library developed by Prime Teknoloji. It provides a collection of mostly visual components (widgets). These can be used by JSF programmers in addition to the small set of basic components that are shipped with the core JSF platform. A very good starting point to learn more about PrimeFaces can be found in the PrimeFaces Showcase. Detailed PrimeFaces widget API documentation can be found in the PrimeFaces VDL doc.

Tip

The Html Dialog Editor supports PrimeFaces during design time. This means that you can profit from code completion support, tag validation, structured properties in the property view and a graphical representation in the preview part for all PrimeFaces widgets.

The elements of the PrimeFaces library are introduced with the <p:> namespace on your XHTML page. In addition also the primefaces-extension<pe: and primefaces-mobile <pm: widget libraries are included in the Axon.ivy installation.

Note

It is also possible to install and use additional JSF libraries. To do so you copy the concerning .jar file into the folder /webapps/ivy/WEB-INF/lib of Axon.ivy Designer and Axon.ivy Engine respectively. Then you have to add a namespace attribute xmlns:xx on your html pages to use the widgets.

Themes

With themes the visual appearance of the application such as the color scheme and the decoration of components can be changed. PrimeFaces comes with a number of predefined themes where you can choose from. Or you can create your own theme using the theme generator tool jQuery ThemeRoller. To learn more about PrimeFaces themes, the web site PrimeFaces Themes is the right starting point:

The theme called modena-ivy is configured as default. However, you can easily configure another default theme with the following steps:

  • The PrimeFaces Community Themes are already included in the product. To use a own theme copy your themeXY.jar file into the folder /webapps/ivy/WEB-INF/lib of Designer and Engine respectively

  • Edit the theme setting parameter primefaces.THEME in the file /webapps/ivy/WEB-INF/web.xml

  • Restart Axon.ivy

Tip

By using the ch.ivyteam.ivy.jsf.primefaces.IvyPrimefacesThemeResolver the theme can be configured by application and session. See Engine Guide > Miscellaneous > Html Dialogs > Primefaces Theme

Html Dialog Data Binding and Event Mapping

An Html Dialog follows the model-view-controller pattern of the Axon.ivy User Dialog concept. So part of an implemented HD is a data class (the model) whose data fields can be bound to widget properties of the view. To define such a binding, Axon.ivy provides the special object data.

On the other hand, the controller part of an Html Dialog is implemented by a series of UI processes that can be mapped to events on the view such as mouse clicks. To define such an event mapping, Axon.ivy provides the keyword logic to call an event process or a method process in the logic.

Look at the following small code sample of a form with a mapped data attribute on an input text field and a button with a bound event process:

  <h:body>
    <h3>My JSF Form</h>
    <h:form id="myForm">
        <p:outputLabel value="#{ivy.cms.co('/labels/street')}" for="street" />
        <p:inputText value="#{data.address.street}" id="street" />
        <p:commandButton value="#{ivy.cms.co('/labels/submit')}" actionListener="#{logic.submit}"/>
    </h:form>
  </h:body>
    
Data Class Auto Initialization

Data Classes are automatically initialized if an Html Dialog sets a property on it.

E.g. If data.address is null and a form is submitted with a value for data.address.street then a data.address object is automatically created.

See also Public API ch.ivyteam.ivy.scripting.objects.jsf.el.AutoInitializable.

Html Dialog Editor

Overview

The Html Dialog editor allows to implement the view of an Html Dialog (i.e. the JSF view). The Html Dialog editor consists of two views, the source view and the graphical view. In the source view you can read and edit the JSF (or xhtml) source in a text-based editor. In the graphical view you can preview and edit the visual representation of the JSF page. Both views are linked to each other and every change is synchronized to the other view. So a change in one view is automatically reflected in the other one, e.g. if I change the text of a h1 HTML element in the source view then the design view is immediately updated and shows the new text. There are options to arrange the two views in horizontal or vertical panes or to show only one of them.

The third element is a palette with drawers for the most important Primefaces and JSF components and widgets that can be used in views. Such components/widgets can be dragged from the various palette drawers and then be dropped onto both the design view or onto the source view As well the rearrangement of already positioned widgets is possible in both views.

Accessibility

Axon.ivy Project Tree -> double click on the View node of a Html Dialog:

Graphical View

The graphical view of the Html Dialog editor allows to compose an Html Dialog view in a graphical mode by selecting a UI element from the palette and positioning it on the view. Similarly, already positioned elements can be dragged to another position on the view, simply by selecting and dragging them with the mouse. In the same way, just select an element and press the delete key to remove an element from the JSF page. As the graphical and the source views are linked together, all these actions are synchronized to the source view.

Tip

The graphical view displays the JSF page as realistic as possible. It also shows all the content from the template or from includes. But you cannot select or edit these elements.

Default Actions

If you double click on one of the most important elements (the ones that you find in the palette) then the default action of this element is triggered. It depends on the element what happens. For example for a Primefaces OutputLabel you can edit the text of the label or choose a CMS content object for it. On the other hand, for the Primefaces DataTable you can select which list from the data class will be used as data source for the table.

Visual Markers

The graphical view displays overlay markers for some elements:

  • CMS markers are displayed if you use the CMS for displaying text or an image. This helps you to verify very fast whether your JSF page is properly translated/internationalized.

  • Data binding markers are visible when the value of an input element is bound to a data element with an EL expression. You can use these markers to verify whether all your inputs are bound to data or a backing bean.

  • You see logic mapping markers if you call a Html Dialog logic element in a button or link. Use these to verify if all your actions are properly mapped to logic elements.

Source View (Code)

For each element that has been dropped on the view the corresponding code is generated in the source. Alternatively you can use the auto completion support in the source editor. Just enter the first letter(s) of a valid code fragment and a selection list of matching elements pops up.

Content Assist (Ctrl+Space)

In addition to the auto completion support you get further assistance for writing expressions if you press Ctrl+Space on an expression to get a pop-up with context aware list of proposed code fragments to select from.

Quick Fix (Ctrl+1)

There are Quick Fixes available to create missing events, methods and data attributes on the current Html Dialog. Simply press Ctrl+1 on a logic or data expression respectively.

CMS Quick Assist (Ctrl+1)

There are Quick Assists available to create or use content objects in the current Html Dialog. Simply press Ctrl+1 on a text attribute or on text between xml tags.

Tip

If a new content object is created with the Quick Assist you can directly rename the created content object in the Html Dialog Editor. Just type a new name and confirm with Enter, to abort the renaming press Esc.

CMS Drag & Drop support

CMS contents can directly be dragged from the CMS View into the Html Dialog Editor. The dropped content will be automatically converted into a valid JSF tag or EL-expression. Currently the content types String and Text as well as all Images-types support drag & drop operations.

Linking to CMS content (F3 or Ctrl)

There is a shortcut to navigate to CMS content. Simply press F3 on a ivy.cms.co(...) expression to jump to the corresponding object in the CMS. Alternatively press Ctrl and click on the link.

Linking to Data Class (F3 or Ctrl)

There is a shortcut to navigate to a data class definition. Simply press F3 on a data.xyz expression to jump to the corresponding Data Class. Alternatively press Ctrl and click on the link.

Linking to Logic (F3 or Ctrl)

There is a shortcut to navigate to a logic element definition. Simply press F3 on a logic.xyz expression to jump to the corresponding logic element. Alternatively press Ctrl and click on the link.

Properties View

Together with the Html Dialog Editor you will want to use the Eclipse properties view to define attributes for the UI elements of your dialog. Simply switch to the Process Development Perspective that will display the properties view at the bottom left area of the workbench window.

Html Dialog View Types

An Html Dialog is either a page or a component. Both are complete Html Dialogs and have therefore their own view, model (data class) and controller (logic). This concept allows to build up component oriented UI design.

Note

The templates for page and component are configured in the Html Preferences.

Html Dialog Page

An Html Dialog page represents a full page that is finally displayed in the web browser. Therefore a page can be opened by a User Dialog Process Step.

Html Dialog Layouts

An Html Dialog Page uses an Html Dialog Layout. An Html Dialog Layout is the concept of a master page that defines a common layout for a number of similar dialogs. An Html Dialog Page references a layout and implements defined parts of it. For example the layout provides the header- and footer-area whereas the content-area is individually implemented on each dialog.

Axon.ivy brings a set of predefined layouts. The layout (together with the view type) is chosen in the New User Dialog wizard.

For more information about templating have a look at the official JSF documentation.

Custom Html Dialog Layouts

Axon.ivy is not limited to the usage of the built-in Html Dialog Layouts. Custom layouts can be added with small effort.

In order to add a custom layout - which is a normal .xhtml file - it needs to be stored into the folder webContent of the project. In doing so, the custom layout can now be referenced as a layout inside an Html Dialog.

To make the custom layout show up in the New User Dialog wizard (for selection of the view type), it must be stored in the folder webContent/layouts of the project.

The folder structure of webContent/layouts should follow the following contract:

  • webContent/layouts/[MyTemplateName].xhtml

  • webContent/layouts/[A sub folder]/[for additional template content]

Html Dialog Component

A component can be embedded into other Html dialog or again in another component.

View Definition

The view consists of two parts, an interface and the implementation. The interface is constituted by a <cc:interface componentType="IvyComponent"> tag and is followed by an optional list of component attributes. The implementation part starts with a <cc:implementation> tag and the component attributes can be accessed with the expression cc.attrs.attributeName

The following code fragment defines an example Html Dialog component:

        <cc:interface componentType="IvyComponent">
            <cc:attribute name="caption" />
        </cc:interface>
        <cc:implementation>
            <p:fieldset legend="Address Component">
                <h:outputLabel value="#{cc.attrs.caption}" />
                <h:panelGrid columns="2">
                    <p:outputLabel value="Street" for="street" />
                    <p:outputLabel value="Country" for="country" />
                    <p:inputText value="#{data.address.street}" id="street" />
                    <p:inputText value="#{data.address.country}" id="country" />
                </h:panelGrid>
            </p:fieldset>
        </cc:implementation>
        
Usage

A component could be inserted with the <ic:-tag. E.g. <ic:my.namespace.ComponentName ... />.

Tip

In the Html Dialog Editoryou have pretty nice tool support for inserting components. You can drag and drop an available component from the palette. You can select one from the auto completion popup list and you can define required attributes in the properties view.

Start Method

Optionally you can define the start method that should be used to start the embedded component with the attribute startMethod. If you do not define the start method, then a default start method will be used. Parameters of the start method can be defined by adding them as named attributes. Parameters are mapped by name, i.e. an attribute of the tag will be mapped to the start method parameter with the same name. Furthermore you can set the component attributes that you defined in the interface of the component by simply adding them as attributes of the tag too.

Note

You can not override start methods. So do not use multiple start methods with the same name but different parameter lists.

See the following code fragment that inserts a Html Dialog component. The start method start(data.person.BillingAddress:address) will be used, the current value of the data class property billingAddress will be used as parameter for the start method and the component attribute caption will be set to the value "Billing Address"

    <h:panelGrid columns="2">
        <ic:ch.ivyteam.htmldialog.demo.component.AddressComponent
            startMethod="start" address="#{data.person.billingAddress}"
            caption="Billing Address">
        </ic:ch.ivyteam.htmldialog.demo.component.AddressComponent>
    </h:panelGrid>
    

Html Dialog Preferences

In the Axon.ivy Designer preferences you can configure the templates used for the creation of Html Dialogs and Offline Dialogs.

Note

There are different templates for Html Dialogs and Offline Dialogs. Whereas Html Dialog templates are targeted to make use of the full JSF stack, Offline Dialog templates are designed to work without enduring connection to the Engine and are optimized for use on rather small mobile devices with touch input.

Accessibility

Axon.ivy Designer Menu -> Windows -> Preferences -> Web -> HTML Files -> Editor -> Templates

Html Dialog View Type Templates

View Type Page and View Type Component are the predefined view types for Html Dialogs. Furthermore every template with a name that starts with 'View Type' is considered as an Html Dialog View Type and therefore listed in the New User Dialog Wizard.

Offline Dialogs have only one predefined view type called Offline View Type Page. Custom templates for Offline Dialogs have to start with 'Offline View Type'

Tip

When the template for a View Type contains <ui:composition template="${layout}">, it will be a template for an Html Page. Otherwise it will be a template for an Html Component.

Form Field Templates

Every template with a name pattern 'form field [Type]' (for Html Dialogs) respectively 'offline form field [Type]' (for Offline Dialogs) is considered as a form field template of the specified type. The form field templates are used during the creation of a Html Dialog by the New User Dialog Wizard.

Tip

Each template can be inserted into an Html Dialog view via the auto complete function (CTRL+Space).

Html Dialog with Multiple Views

To implement a user interaction that consists of several pages (for example a wizard), one Html Dialog can have multiple views (.xhtml files). This allows to enclose a complex user interaction in one Html Dialog and to abstract it from the business process.

How to add a view

In the New menu in the Axon.ivy project tree you find the New Html Dialog View wizard to add a view to a Html Dialog. Just enter the name of the view and the xhtml file for the view is created and added to the Html Dialog. In the ivy project tree all view files of a Html Dialog are displayed below the main node of that Html Dialog.

How to switch views during runtime

If you have created a Html Dialog with several views you have to implement the navigation between the views for the user on your own. The basic solution is a commandButton with an update attribute to load the next view.

You find an example of a multi view Html Dialog in the HtmlDialogDemos project that is provided with the Axon.ivy Designer.

<h:form id="myForm">
    <p:panel header="Multi View Demo" id="panel">
    <h3>Payment - Credit Card</h3>
    <p:messages id="msgs"/>
    <h:panelGrid columns="2">
        <p:outputLabel value="Credit Card Number"/>
        <p:inputMask required="true" value="#{data.creditCardNumber}" 
            id="CreditCardNumber" mask="9999-9999-9999-9999"></p:inputMask>
    </h:panelGrid>           
    <p:commandButton value="Next" update="myForm" action="#{logic.nextView('CreditCard')}"/>
    </p:panel>
</h:form>      

Converters

Converters are used to convert number or date/time values for string representation and vice versa. If you want to display a Number or Date/DateTime process data attribute well formated in an input widget then use the basic converters provided by the JSF core framework: convertNumber and convertDateTime.

See this code fragment from an input form:

<p:calendar id="Birthday" value="#{data.birthday}" navigator="true" 
        required="true" pattern="dd.MM.yyyy">
    <f:convertDateTime pattern="dd.MM.yyyy" />
</p:calendar>            
    
Custom Faces Converters

Custom Faces Converters can be implemented as a Java class with a specific FacesConverter annotation and then be used in your Axon.ivy project.

Example:

    @FacesConverter("MyCustomFacesConverter")
    public class MyCustomFacesConverter implements Converter            
        

Validators

The JSF core framework provides a number of basic validators that can be used to validate the entered values in an input form.

  • validateDoubleRange

  • validateLength

  • validateLongRange

  • validateRegex

  • validateRequired

Example code fragment from an input form:

            <p:inputText value="#{data.zipCode}" id="ZipCode" required="true">
                <f:convertNumber integerOnly="true" groupingUsed="false"/>
                <f:validateLength minimum="4" maximum="5"/>
            </p:inputText>     
    
Client Side Validation

In some cases it makes sense to perform the validation of the entered values before they are sent to the server (e.g. in an Offline Dialog). For this reason, Primefaces provides a client side validation framework. Client side validation is added as addition to the JSF validators. Thus, it can give instant feedback - even while typing - to the user. Since the JSF validators (see above) remain still active, the data is also validated on server side after the form has passed client side validation and is submitted.

Example code fragment from an input form:

            <p:inputText value="#{data.zipCode}" id="ZipCode" required="true">
                <f:convertNumber integerOnly="true" groupingUsed="false"/>
                <f:validateLength minimum="4" maximum="5"/>
                <p:clientValidator event="keyup" />
				<p:clientValidator event="blur" />
            </p:inputText>     
            <p:message for="ZipCode" display="text" showDetail="true" />
            
            <p:commandButton actionListener="#{logic.close}" value="Proceed" validateClient="true" icon="ui-icon-check"  />
        

Tip

It's useful to add the client validators to the desired input field and also to trigger client side validation on the submit button. This way you make sure, that client side validation is performed during field modification, but also if the user tries to submit the from without any modification.

In order to provide a good instant feedback, a message element dedicated to the input field might be quite helpful.

Managed Beans

In Html Dialogs it is possible to communicate with normal Java objects by using ManagedBeans. Use the following annotations to define the lifecycle scope of the managed bean:

  • @ApplicationScoped - the bean instance is created at creation of the application or at the engine startup and destroyed when the application is either deleted or the engine shuts down.

  • @SessionScoped - the bean lives for the whole duration of the session

  • @RequestScoped - an instance of the bean is created for each new request and thrown away after the response has been sent. This is the default scope that will be used when no scope is set specifically.

Note

JSF 2.0 introduced an additional scope @ViewScoped and offers the possibility to define custom scopes. This is basically also supported in Axon.ivy, but it is recommended to use it with care since it might not behave as expected.

In the HtmlDialogDemo Project that is included in the Axon.ivy Designer you find an example.

Bean Validation (JSR 303)

The JSR 303 is a specification that defines a metadata model for bean validation. The fields of the JavaBean classes, that are used for storing the data, are annotated to describe the constraints and their validation. Experienced programmers can use JSR 303 annotations in Axon.ivy projects. The validation information will then be considered by Html Dialogs when the field of the class is bound to a widget. There is no validation information given in the *.xhtml file of the Html Dialog itself. However, the Html Dialog uses the annotations of the fields to validate the user input.

All annotations defined in the package javax.validation.constraints are supported. For the validation messages you can use Ivy macros to get the message content from the CMS. For example:

  • @NotNull "means that a value is required"

  • @Size "restricts the length of a string or array or the size of a collection or map"

  • @Max "restricts the maximum allowed value"

  • @Min "restricts the minimum allowed value"

  • @Pattern "restricts a string to a given regular expression"

  • @Digits "restricts the maximum number of digits of the integer and faction part"

  • @Future "restricts a date to the dates in the future"

  • @Past "restricts a date to the dates in the past"

@SessionScoped 
public class Person 
{
	@Size(min=3, max=10, message="<%=ivy.cms.co(\"/ch.ivyteam.htmldialog.demo/BeanValidationDemo/between3And10Characters\")%>")
	@NotNull(message="<%=ivy.cms.co(\"/ch.ivyteam.htmldialog.demo/BeanValidationDemo/notnull\")%>")
	private String name;
	
	@Pattern(regexp="[1-9][0-9]{2}\\.[0-9]{2}\\.[1-8]([0-8][0-9]|9[012])\\.[0-9]{3}", message="<%=ivy.cms.co(\"/ch.ivyteam.htmldialog.demo/BeanValidationDemo/socialSecurityNumber\")%>")
	@NotNull(message="<%=ivy.cms.co(\"/ch.ivyteam.htmldialog.demo/BeanValidationDemo/notnull\")%>")
	private String socialSecurityNumber;

There will always be validation requirements for which these standard annotation will not suffice. For these cases it is possible to create your own annotation. You find an example in the HtmlDialogDemo project that is included in the Axon.ivy Designer.

public class Person 
{
	@LicensePlate(message="<%=ivy.cms.co(\"/ch.ivyteam.htmldialog.demo/BeanValidationDemo/licensePlate\")%>")
	private String vehicleLicense;

// re-use other existing constraints:
@NotNull
@Size(min=4, max=20)
@UpperCase // custom constraint in same package
@StartsWith(prefix="ZG") // custom constraint in same package

//only show the validation message from this annotation and not from it's re-used types:
@ReportAsSingleViolation 

@Target( { METHOD, FIELD, ANNOTATION_TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = {})
@Documented
public @interface LicensePlate {
    String message() default "Field does not contain a valid license plate";
    Class<?>[] groups() default {};
    public abstract Class<? extends Payload>[] payload() default {};
}

Ajax Method Call API

Methods of a Html Dialog can be called with JavaScript through a REST like interface. This Ajax method call API of Axon.ivy can be used to integrate JavaScript libraries like D3, jQuery or your own JavaScript scripts. See the Ajax Method Call Demo in the Html Dialog Demo Project:

		<script type="text/javascript">
				// jQuery is used to intercept the click on the Button with id #hello
				$("#hello").click(function(){

						// The ivyajaxapi.js script provides the logic object, 
						// which contains a function for each method available on the dialogs interface.
						// If you would like to use the REST API in a more advanced way or without jQuery, 
						// have a look at the generated ivyajaxapi.js script to see how the REST API is used.
						logic.helloWorld( 
							
							// The first parameter is a data structure, which represents the list of parameters
							{"name": "World"},
							
							// The second parameter is a function, which is called on a successful response.
							function(returnData)
							{
								// returnData is a JavaScript Object containing one field for each Method return value.
								// returnData.result accesses the return value named result.
								$("#result").html(returnData.result);
							});
				});
		</script>

Error Handling

The exception handling in HTML Dialogs can be customized. Depending on the request type the customization differs.

HTTP Request

If an exception occurs in a non-ajax HTTP request, the user will be redirected to the specified error page. The customization of these error pages is described in the chapter Configuration / Error Handling of the engine guide.

AJAX Request

If an exception occurs in an ajax-based HTTP request, the configured Primefaces ajax exception handlers comes into play. The handler must be defined as part of the *.xhtml file. In the provided standard layouts, handlers are already configured. See webContent/layouts/includes/exception.xhtml for details.

<p:ajaxExceptionHandler update="ajaxExceptionDialog" onexception="PF('ajaxExceptionDialog').show();"/>

The above ajax exception handler will catch every exception of every type. If an exception occurs the action in onexception will be executed. In this example, a Primeface dialog will be shown.

<p:p:dialog id="ajaxExceptionDialog" header="Error" widgetVar="ajaxExceptionDialog" height="400px">				
	<p:h:outputText value="Error Id: #{errorPage.exceptionId}"/>
	<p:br/>
    ...
<p:/p:dialog> 

The errorPage bean is available within the ajax exception handling. Properties like exceptionId or message can be used to provide specific error information to the user.

View Expired Exception

If the view or the session of a user expires then there is a possibility to catch that exception with a specialized ajax exception handler. Instead of catching all exceptions you can specify the type of the exception to catch.

<p:ajaxExceptionHandler
    type="javax.faces.application.ViewExpiredException" 
    update="viewExpiredExceptionDialog" 
    onexception="PF('viewExpiredExceptionDialog').show();"/>

This handler will only catch exceptions of type javax.faces.application.ViewExpiredException. The exception handler with the most specific type of exception will be used.

<p:dialog id="viewExpiredExceptionDialog" header="View or Session Expired" widgetVar="viewExpiredExceptionDialog" height="50px">
	<h:outputText value="The view or session has expired."/>
	<br/>
	<h:outputLink value="#{ivy.html.loginRef()}">Please login again.</h:outputLink> 
</p:dialog>

Web Page

This chapter shows how Web Pages and -content are used within Axon.ivy.

Using Web Pages (web content) in a Business Process

As an alternative to User Dialogs, you can display Web Pages or other web resources to the user of an Axon.ivy process application in a browser to let him or her interact with the executed process.

Such content is embedded within a business process by using the Web Page element or by using end pages for various elements in a process (End Page element, a Simple Task Switch element or a Task Switch element). Whenever the process reaches such an element, then the defined content is presented to the user.

You are free to use HTML-based content (plain HTML, JSP) or other resources (such as images, text files, RTF and many more) as long as they can be displayed in a web browser. In addition, you are free to use resources from the CMS or from the web content folder of the project.

Warning

When you re-use resources like JSP pages in different process elements, you need to carefully consider how to integrate the content with the process. When you access members of the data class (e.g. in the JSP) you must ensure that this member is accessible in all processes that use the resource. Furthermore, in Web Page elements you need to ensure that a) there is a way to continue with the process, e.g. an out-link and that b) that way can be used in all usages of the resource.

Warning

Please bear in mind that web pages can only be used if a single HTTP request is available from the client. This means that you cannot use web pages if at least one of the following conditions apply:

  • The current request was not triggered by HTTP (e.g. started by an Event Bean).

  • The current task is executed by SYSTEM.

  • The process is running in a parallel execution section, e.g. after a Split element.

Creating and Editing Web Pages from within the Process

A web page can be created or accessed directly from the process. Open the inscription mask of any page-capable process element. Depending on whether the page is already defined or not, you will be presented with either of the two scenarios described in the sections below.

No page has been specified yet

You can define the Web Page that should be displayed by using one of the following three methods:

  1. Enter the path to an existing page by hand. Specify either a CMS path (e.g. /HtmlPages/myPage) that points to a content object or give a path to a web content file (e.g. commonPages/infoPage.html) instead.

    Note that content object paths do not have a file extension, but web content paths do. Web content paths are always specified relative to the webContent folder of the current project.

    If you enter a path to a non-existing web content resource, then pressing the Create button will create an empty file at the specified location in the webContent folder and open Eclipse's default editor on it.

    If you enter the name of a non-existing content page, then pressing the Create button will have the same effect as described under (3).

  2. Select an existing content object by using the content smart button or an existing web content file by using the file smart button.

    You can select any content object and any file, but a "wrong type" error will be displayed if the selected content object is not suitable as a page. Likewise a "invalid web content path" error will be shown, if you select a file outside the project's web content folder.

  3. Click Create to generate an entirely new page in the content management system.

    A dialog will appear that allows you to enter the name and type (normal or JSP) of the new page. The created page will be associated with the current element and it will be placed appropriately inside the CMS ProcessPages/<ProcessName> folder (see below).

A page is already specified

Click on Edit to open the specified page either in the content editor (if it is a content object) or the system's default editor (if it is a web content file) so that you can edit its contents. You can change the default editor for any file type by opening Window/Preferences and navigating there to /General/Editors/File Associations.

Alternatively you can use the content smart button or the file smart button to select an entirely different page to be displayed.

You can also edit the specified path by hand if you like.

Where Web Pages are stored

The page that is displayed is either stored in the CMS or in the web content folder of the project.

By default, CMS pages are stored in the ProcessPages hierarchy in a further sub folder named after the containing process (e.g. ProcessPages/Main/MyPage). Although it is not required to store the pages within this scheme, it is recommended to keep your pages separated. All content objects that can be downloaded can be used, especially the Page and JSP types, but also some Document (e.g. RTF, HTML, PDF or Plain Text) and other types are working.

Pages in the web content folder can be stored in any hierarchy below the project's web content folder (it is not allowed to use or reference content that is stored outside the project's web content folder). You can use any type as long as it is possible to render it in the browser of the user.

Note

Some browsers delegate the displaying of certain file types to third party plugins and/or applications depending on the configuration of the client. Thus this behaviour cannot be controlled by Ivy.

HTML content in the CMS

There are a number of specific content object types that are uniquely used inside HTML Dialog pages. All of them have their own editors, the usage of which is described in the following sections.

Note

Web Pages can be accessed without starting a process. This allows you to create for example a translated start page with some process start links. See also chapter Access CMS Content with a Browser.

Web Page Editor

The Page Editor is used to specify the Style Sheet and Layout of a page. They can either be inherited from their parent objects in the CMS hierarchy or can be set explicitly. Use the combo boxes to set one of the style sheets, i.e. page layouts which are contained in the corresponding CMS top level folders. The Search... buttons on the other hand opens a dialog which does show all CSS and Layout content objects in the whole CMS to select one. So the children content objects of the page represent the selected Layout (see Layout Editor). The missing or obsolete parts (i.e. children in the CMS hierarchy) of a page (e.g. after changing layout) may be created or deleted with the corresponding buttons at the bottom of the editor.

HTML Panel Editor

Overview

This is the most important editor to edit your HTML content. Each Web Page (see Page Editor) has sections that are called Panels and which are defined by the page's layout. Generally, a page has as many panels as are specified by its associated layout (see Layout Editor).

In the panels of a page, the actual content of the page is defined. Each content part of a panel is stored as an own content object below that panel's content object inside the content management:

The contents of a panel are arranged in a table from left to right and from top-to bottom in a structured manner. Each table cell contains a single content object or some custom HTML or JSP code.

A panel can be rendered as plain HTML or as a HTML table. If it is rendered with plain HTML cells are simply rendered one after another. Rows are separated with a <br> tag. On the other hand, if it is rendered as a HTML table, each cell will be rendered as a cell of the table. You can switch the rendering kind using the checkbox As HTML Table. Switching the rendering influences the available context menu items of a cell and the buttons Table, Row and Cell.

You can switch between the Edit and the Source View of a panel. The Edit View as explained above shows the table of the panel with its cells. The Source View on the other hand shows the JSP Code that is generated from the Edit View.

Menus
Insert Process Link/Form ...

Use this menu to insert a link or form that triggers the continuation of the process after the page element.

Insert Content ...

Use this menu to create sub content objects (Texts, Strings, Sources, Process Links, Tables, Result Tables, Smart Tables, Images) and insert them or already existing content objects into the panel.

Insert Attribute

Use this menu to insert process attribute values into the panel. The menu will open an Attribute Browser where you can choose the process attribute to insert. You can specify a condition that gets evaluated during the rendering of the panel to control whether the content of the cell is rendered into the panel or not. Moreover you can specify how the process data value should be formatted.

Insert JSP

Use this menu to insert JSP code into the panel.

Context Menus

Edit

Opens the type specific editor (Attribute, Content, JSP, ...) of the selected cell.

Edit Condition

Opens an IvyScript editor to edit the condition that controls whether the content of the cell is rendered or not.

Move

Use this menu to move the current cell to another location.

Remove

Removes the selected cell.

HTML Attributes <...> Table

Opens an HTML attribute editor to edit the HTML attributes of the table.

HTML Attributes <...> Row

Opens an HTML attribute editor to edit the HTML attribute of the currently selected table row.

HTML Attributes <...> Cell

Opens an HTML attribute editor to edit the HTML attributes of the currently selected table cell.

Insert Row

Inserts a row above the selected cell.

Delete Row

Deletes the row of the selected cell.

Merge Cell Left

Merges the selected cell with the cell at the left side.

Merge Cell Right

Merges the selected cell with the cell at the right side.

Merge Cell Up

Merges the selected cell with the cell at the top.

Merge Cell Down

Merges the selected cell with the cell at the bottom.

Split Cell into Rows

Splits the selected cell into multiple cells one cell for each row.

Split Cell into Columns

Splits the selected cell into multiple cells one cell for each column.

Buttons and Check boxes

As HTML Table

Use this checkbox to switch the rendering kind of the panel from raw HTML to HTML table and vice versa.

Table

Use this button to open an HTML attribute editor to edit the HTML attributes of the table.

Row

Use this button to open an HTML attribute editor to edit the HTML attribute of the currently selected row.

Cell

Use this button to open an HTML attribute editor to edit the HTML attribute of the currently selected cell.

HTML Table Editor

The HTML Table editor can be used to configure a HTML table. In contrary to the Result Table the numbers of rows and columns is defined here statically. And for each cell the content must be chosen specifically although the content itself may be generated dynamically at run-time. Using the menu Insert... it is possible to use Text, Source or CMS elements and using the menu Insert Attribute it is possible to use attributes from the process data in the cell content.

Tip

A Text element can be inserted in a cell by just selecting the cell and starting to type the text. The Text Editor opens automatically then.

With the buttons Table, Row and Cell or the corresponding entries in the popup menu the HTML attributes for the corresponding table part can be manipulated. Furthermore you can add/delete table rows and merge or split table cells to influence the layout of the table. The source tab allows to view and edit the generated HTML code directly.

Typically a table object is not created as an independent content object in the CMS tree, but rather inserted below a Page content object. The cell contents are no first-class CMS elements but are stored within the HTML table content object itself.

Result Table Editor

The Result Table editor is used to configure the dynamic generation of (HTML) data tables on either DB page or Page process elements. Typically a result table object is not created as an independent content object in the CMS tree, but rather inserted below a Page content object when a table gets inserted onto one of the pages panels (using the Panel Editor).

Data Source

Specify here the source of the result table's data. You can select a recordset or a list as data source from the process data attributes.

Visible Columns

Select the columns that should be rendered by the result table. You can either use the column numbers (1,5,8,2,3) or column names (name, first_name, customer_id) in a comma-separated list to specify subset and order.

Selection Links

Hers it is possible to select which column entries that should be turned into a link for the one of the page's output links. The select entry specifies what value that should be assigned to which result value (a process attribute). This is used to identify the selected record on the next process element.

Table Caption

A caption text for the rendered result table. Macros may be used.

Column Headers

Specify the names of the columns as they should appear in the header row as a comma-separated list. Macros may be used, the order must be the same as specified in the Visible Columns field.

Automatic Headers

If selected, then the column headers will be selected from the specification in the database.

Empty Table Text

The text to display if the source data is empty. May contain macros.

HTML Attributes

Specify the HTML attribute values for table, even rows, odd rows, header cells and column cells.

For almost all of the above described features, the attributes of the corresponding HTML tags can be edited explicitly by clicking on the HTML tag button.

Link editor is used to render process and static links. Whereas the execution of a process link will lead to the continuation of the process (i.e. activate a specific arc in the process model) and the activation of a static link leads to some other HTML page independent of the process.

Links can be rendered in many different forms, e.g. both the "classical" hyperlink as well as the display of a form with a submit button are considered to be special forms of links.

All of those different link types are configured with the HTML Link Editor. The link editor can be opened in two different ways: either by selecting a link content object below a page in the CMS editor tree or by double clicking on a link field in the HTML Panel Editor.

The following options can be configured for all links:

Link Target (Href)

Specify the target of the link that will be jumped when the link is activated. If this is the configuration of a process link, then a macro that specifies the link that should be executed will already be specified (see example image above). However, any valid HTTP-link is accepted as value for this field, e.g. http://www.acme.com.

Link Type

Specifies the visual appearance (type) of link that should be configured. Depending on the type that is selected, the configuration fields below this attribute will change.

Depending on the selected Link Type, additional options are available for configuration.

For Text, Button, Image and Timed Auto-Redirect, the Link Editor allows for configuration of rather simple additional options. The smart buttons at the right side of the macro fields can be used to either configure the HTML attributes of the rendered link source or to insert and expand process attributes and content objects.

The following options can be configured for those link types (configuration of a Form Link is described in the next section):

Displayed Text

Specifies the text that will be shown to the user and presented as link. This option is available for the link types Text, Button and Image + Text.

Alternate Text

Specifies the alternate text that will be set on the displayed image (is shown by most browsers as tool-tip when the mouse hovers over the image). This option is only available for the link type Image.

Time to go in Seconds

Specifies number of seconds to wait before the link is activated automatically. This option is only available for the link type Auto-Redirect (timed).

When selecting Form as Link Type the link editor will show a sub-editor that allows you to specify a form and all form fields, that are initialized and/or set from/to process data. Furthermore, you can configure whether a Submit and/or a Reset button should be displayed (including the text of the buttons). At the bottom you even have the choice to change the editor's view for either designing the tabular layout of the form in a graphical editor or directly editing the HTML code.

At run-time the form defined in the Form Field Editor will be rendered in a HTML page. Clicking the submit button results in the continuation of the process of this element. Therefore, if you disable the submit button you have to ensure that a process link for process continuation is part of the HTML page (e.g. by adding such a link in the HTML view of the editor).

If the Details button of a form field is clicked (when configuring a Form Link) a specialized sub-editor is presented to the user. This editor allows to configure in detail how a specific form field is to be rendered in HTML.

Several types of input kinds for the form fields are available such as text fields, lists or date pickers. For each type, the configuration and therefore the layout of this editor may differ slightly and some parts (irrelevant to the chosen) may be invisible. For most form fields you can define the layout, the default value and the validation.

Input Kind

Input KindImageDescriptionHTML Tag
Text Field
A single line input field for text of all kind. <input type="text">
Password Field
The same as the text field but each inserted character is displayed as black bullet.<input type="password">
Text Area
This is a multi line input field for text of all kind. <textarea>
Check Box
A simple box to selecting zero, one or more of two or more options (ideally for yes/no or true/false information). The data that is associated with the chosen option is saved.<input type="checkbox">
Radio Button
It is sort of a button for selecting one and only one of two or more options which are mutually exclusive. The data that is associated with the chosen option is saved. <input type="radio">
Combo Box
A text field with an attached drop-down list to select from several predefined values. <select size="0">
List
A list to choose from several predefined values.<select size="nbOfOptions">
File Upload
With this input kind, the user can choose a file to upload to the Axon.ivy Engine file area. <input type="file">
Hidden Field
Hidden fields can be used to transfer additional data invisible for the user (for use in e.g. JavaScript or e-mail transfer of forms)<input type="hidden">
Date Picker
To choose a date. Note that the date is displayed according to the language set in the browser of the user (while simulating in the Designer you can set the language with a toolbar button). Note too, that if dates are entered in a 2-digit format, then Axon.ivy will interpret numbers within the next 20 years as years in the future. All other numbers are interpreted as years from the past (e.g. in 2010 entering 30 leads to 2030 whereas entering 35 leads to 1935). The Javascripts used for the Date Picker are copied into the webContent folder of the project to scripts/datepicker and scripts/jquery.Implemented in Java Script

Table 6.3. All the different input kinds

Displayed Name

Axon.ivy adds a text label to the form field for reference. The text of this label can be set here using process data or CMS entries.

Orientation

It is possible to choose how the label and the form field are positioned to each other, either side by side or super-imposed.

Initialize with...

You can use process data, function return values (both value from attribute) or plain text (initial value) to set a default value for the form field. For check boxes it is additionally possible to select whether it is checked or not.

Warning

Make sure that the data types of the default value matches to the chosen form field otherwise an error will be thrown at runtime.

Maximum Characters

The maximum number of characters which are allowed to enter. The user will not be able to enter more characters.

Size (Columns)

You can set the width of the form field to layout your forms nicely.

Options

Here the content of the list based form fields (Combo Box, List, Check Box, Radio Button) can be defined. You can either choose an Ivy Script recordset or list (select options form attribute) or you can define the content in a table with values and display texts. For recordset based content, the first column is used as values and the second column as display texts (all other columns are omitted). For list based content all the list entries are used as value and as display names.

Values per Row

For check boxes and radio buttons it is possible to define how many options are rendered in the same line (or row)

Rows

Only used for the list form field. It represents the number of visible rows in the list. If more items than rows are defined, the list will have scroll bars.

Mime Type

Is only used for the file upload form field. The mime type corresponding to the type of file which can be uploaded.

Input Validation

By selecting an input validation script you may validate the values that an user enters in a specific field on the client, e.g. before the form is submitted. If the user tries to submit a form but input validation fails on some of the form fields, then a message will be displayed to the user and the form will not be sent.

Axon.ivy offers you a number of built in validation functions that can be selected from the Input Validation combo box. The scripts that are available depend on the input kind of the currently edited form field (e.g. different scripts are available for checkbox and text input fields).

If the built-in scripts do not satisfy your needs, you may provide your own validation scripts written in JavaScript. Read the section How to provide own Validation Scripts to learn more about this topic.

Warning

Please note, that JavaScript must be enabled in your client's browsers in order for the validation scripts to work!

Alert message if invalid

For any selected Input Validation a predefined warning message exists. If you don't like the default message, you may specify a custom message that will be displayed if the entered value is invalid.

You may use the content smart button to select and insert a textual content object that should be displayed as message or as part of your message. This allows you to specify messages in multiple languages.

If you leave the field empty, the default message of the selected validation script will be displayed.

Smart Table Content Editor

Overview

On the Smart Table Content editor you configure what content to show in the smart table. You can configure the data source for the table. Furthermore, you can influence the visual look and feel and set options such as header, body or footer label texts, for each entry in the table.

The Smart Table Content Editor

Figure 6.3. The Smart Table Content Editor

Accessibility

Content Management -> Smart Table Content Object

Features
Configuration

Select the Renderer Configuration which is used when the Smart Table is rendered and then displayed on the client browser. See the Smart Table Configuration for more details.

Source

Select the type of the source for your table. Either List, Recordset or Record. Define in the IvyScript text field the path to your source.

Table Caption

Enter a text to display as caption of the table. Use IvyScript macros if needed. example: <%=ivy.cms.co("/labels/header")%>

Columns Configuration:
Columns (a column configuration is shown as row in the editor)

Field: Define the name of the field of your data source to map to the current column. If your data source is a list, then the list elements must contain a field or method with the configured name (e.g. userName or getUserName()). If your data source is a recordset, then the records must have a field with the configured name. The value of the field is mapped to the variable value which you can use in the IvyScript text field of the Value field.

Header: Enter a text to display as header of the column. Use IvyScript macros if needed, e.g. <%=ivy.cms.co("/labels/header")%>. Note hat this has only an effect if the Show Header check box is selected too.

Visible: Enter a IvyScript expression which results in a Boolean value, to configure the visibility of the column. If no condition is set, then the column is visible.

Value: Enter a IvyScript expression to configure what label that should be displayed in the table cell. This IvyScript is executed for every cell in this column (once per row in the table).

Link: Choose the link where the process goes if we click on a cell on this column. It is also possible to define the process attributes where to store the row index, the column index or the column name.

Sortable: Activate this check box if you want your table to be sortable. Clicking on the header of a column triggers then a sorting of the whole table according to the selected column. The variable value is used for sorting which is defined in the column Field.

Footer: Enter a IvyScript expression to configure what label that should be displayed in the table footer.

<>: Allowed to edit the HTML attributes for the table header, body or footer cells. E.g. choose colors or borders. Note that this specific settings of HTML attributes will override any settings from the configuration.

Actions

Add: Adds a new column configuration to your table definition. The column configuration will be shown as row in the Columns Configuration table.

Remove: Removes the selected Column Configuration(s) from your Columns Configuration table.

Up: Moves the selected Columns Configuration(s) up in the table. This means that the column(s) moves one position to the left in the resulting table.

Down: Moves the selected Columns Configuration(s) down in the table. This means that the column(s) moves one position to the right in the resulting table.

Show Header: Activate this check box if you want your table to have a header row.

Autom. Header: Activate this check box if you want the system to label your headers.

Show Footer: Activate this check box if you want your table to have a footer row.

Variables

in: The process data at the point of time when this CMS element is executed.

index: Table index of the currently selected table entry.

originalIndex: Index of the currently selected entry in the data source (without respect to the visual order, e.g. after a sorting).

value: The value of the currently selected field (as defined in the field column) in the data source element (i.e. record).

it: The currently rendered element of this widget's list data source (only available, if the source is of type List).

list: The list defined as data source (only available, if the source is of type List).

record: The currently selected record (only available, if the source is of type Recordset).

recordset: The recordset defined as data source (only available, if the source is of type Recordset).

Max. rows per Page

Enter a IvyScript expression to configure the maximum number of rows are shown per page.

Empty Table Text

Enter a plain text that will be displayed if the table source is empty.

JSP Editor

The JSP editor is used to edit a JSP content object which can be used in the Web Page, End Page, Task Switch or Simple Task Switch process elements.

Inside JSP content objects you can make use of the Environment Variable ivy. It is imported and declared as follows:

    <%@ page import="ch.ivyteam.ivy.page.engine.jsp.IvyJSP"%>
    <jsp:useBean id="ivy" class="ch.ivyteam.ivy.page.engine.jsp.IvyJSP" scope="session"/>

You can also use the in object (i.e. process data) of the process where the associated process element is located. You can access the process data by using the ivy.html.get() method, e.g.:

    <%=ivy.cms.co("myUri")"%>
    <%=ivy.html.get("in.myString")%>

Furthermore you can insert references to content from the web content directory into your JSP content objects, e.g.:

    <jsp:include page="/jspToInclude/include.jsp" />
    <img src="images/myImage.jpg" >

Layout Editor

The Layout editor is used to edit a JSP Layout content object which defines the Layout of an HTML dialog page (see Page Editor).

Inside the Layout JSP content objects you can make use of the Environment Variable ivy or you can insert references to content from the web content directory (see JSP Editor).

For the layout creator there are some useful functions on the ivy variable:

Layout functionsDescription
ivy.style()Returns the URL to the CSS style, which is set on the current HTML dialog page (see Page Editor).
ivy.content("coName","coType")The layout creator can define a placeholder for content, that the page designer should fill in. When a page with this layout is created the specified placeholder is created as a content object with the given name and type under the HTML dialog page whose value is set by the page designer. At execution time the value of the content object is set as a String into the layout.
ivy.panel("panelName")This creates a Panel content object with the specified name under the HTML dialog page when a page with this layout is created.

A very simple JSP Layout example which includes the style of the page, creates a content object named Caption with the type String and a Panel content object with the name Panel1 looks as follows:

<%@ page import="ch.ivyteam.ivy.page.engine.jsp.IvyJSP"%>
<jsp:useBean id="ivy" class="ch.ivyteam.ivy.page.engine.jsp.IvyJSP" scope="session"/>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
       "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <link rel="stylesheet" type="text/css" href="<%=ivy.style()%>"/>
  <title><%=ivy.content("Caption","String")%></title>
</head>
<body>
<jsp:include page='<%=ivy.panel("Panel1")%>' flush="true"/>
</body>
</html>

Link Browser

The link browser can be used to insert a HTML <a href="..."> link tag. The appearing dialog shows the available link types to choose from. If you select a link type and then press Ok (or double-click the link type), then another dialog appears to configure the link.

Link Browser

Figure 6.4. Link Browser

Visible Text

The visible text of the HTML link that will be inserted. Or, in HTML language, the text between the <a> and the </a> tags.

Link Type

The type of link to insert.

Link TypeDescriptionHTML href link target
Process A link to continue the process with the corresponding sequence flow out of the Web Page element that shows this page. The link target is addressed relatively, i.e. uses the same protocol like the request to the page. See the section for the inscription mask of the web page element for further information about process links.<%=ivy.html.ref("MyLink.ivp")%>
Process (SSL on)Same as the process link, but addresses the process link absolutely using HTTPS.<%=ivy.html.ref("MyLink.ivp", true)%>
Process (SSL off)Same as the process link, but addresses the process link absolutely using HTTP.<%=ivy.html.ref("MyLink.ivp", false)%>
Content Object This is a link to a content object in the CMS. Note that not all content object types may be used but only the ones that represent file-based resources. This holds true especially for file-based content objects such as images or documents.<%=ivy.html.coref("/uri/to/my/jpeg")%>">
Process StartA link that starts a new process. Note that the process is started in a new case.<%=ivy.html.startref("myPID/start.ivp")%>
Web ContentFor linking to a resource in the web content folder<%=ivy.html.wr("myResource")%>
HTTP AddressInserts a link to an arbitrary web resource such as a web page or a video on the web.http://www.example.com

Table 6.4. Link Types

Other content editors

Content editors that are not described in this chapter are described in the Content Object Value Editor chapter.

HTML content in the Web Content Folder

Although it is recommended that you store all (or most of) your content in the project's CMS, as an alternative you can place web resources into a folder within the root folder of your project with the name webContent.

These web content files can be referred from CMS pages either by addressing them relatively (to the web content directory) or by using the method ivy.html.wr(fileNameRelative). Of course, you can also reference directly from one web content file to another (e.g. a web content HTML file that displays a web content image with a img tag.). It is even possible to mix references between CMS and web content files (e.g. a JSP in the web content includes a JSP in the CMS which imports a JavaScript file in the web content and so on).

Warning

Web content files can always be referenced relative to the web content folder. But in contrast to content objects in the CMS, resources in the web content folder are only visible in the same project. If the resource is not found then there is no lookup in the required projects.

Tip

To gain access to Axon.ivy functionality please insert the following code to your hand-made JSP page in the web content folder:

    <%@ page import="ch.ivyteam.ivy.page.engine.jsp.IvyJSP"%>
    <jsp:useBean id="ivy" class="ch.ivyteam.ivy.page.engine.jsp.IvyJSP" scope="session"/>

HTML Best Practice

How to provide own HTML Validation Scripts

Inside the Form Field Details Editor you may specify client side validation scripts to validate user input before submitting a form. If the validation fails (i.e. some user input is invalid) then the form will not be submitted.

Out of the box, Axon.ivy allows you to select from a number of predefined scripts, e.g. Integer > 0 as shown below:

Testing for Integer > 0 may be fine for some cases, but what if you need to test whether an integer value is greater than 10 and smaller than 20? In this case you need to provide your own validation script to test your specific input requirements.

HTML validation scripts are written in JavaScript and are stored in a *.js file. The script file contains a header line and a check function. For example:

<!--ivy.input_validate name_de="Ganzzahl: 10 < x < 20" name_en="Integer: 10 < x < 20"--> 
function integerBetween10And20(field,msg,loc) 
{ 
  msg_en=field.name+" must be a Number between 10 and 20";      // default message en
  msg_de=field.name+" muss eine Zahl zwischen 10 und 20 sein";  // default message de  

  if(field.value.length==0 
     || isNaN(new Number(field.value)) 
     || !(field.value > 10 && field.value < 20)) // check function
  {
    if(msg!=null && msg.length>0)     
      alert(msg);     // alert with custom message, if defined
    else if(loc=="de")       
      alert(msg_de);  // alert with default german message
    else       
      alert(msg_en);  // alert with default english message  
    return false;   
  }   
  else 
  {
    return true; 
  }
}            

The header of the script file defines the name of the script as it is displayed in the validation combo box of the Form Field Details Editor.

The JavaScript validation function must always define the same 3 parameters: field is the field that is being validated, msg is the custom validation alert message that may optionally be defined when selecting a validation script and loc is the language code that will be provided by the Axon.ivy runtime system.

The above defined checks if the given input field contains a number between 10 and 20 and if so, true is returned. If the value is not a number or not between 0 and 20, then an alert message is shown to the user and false will be returned (which will prevent the sending of the form, as long as the field value is not correct).

In order for the script to be able to selected from the Form Field Details Editor, it must be located in the webContent/scripts/validation folder of the Axon.ivy project where it will be used:

Once you have copied your script to this location, it will become available in the validation selection combo box of the Form Field Detail Editor:

Tip

If you don't like the behavior of any built-in scripts then you may change them as well. Simply edit the associated validation script file.

You may generally edit the available validation scripts at any time. The changes will become effective immediately on save (unless browsers or other internet entities use a previously cached copy of an old script).

Warning

Please note, that JavaScript must be enabled in your client's browsers in order for any validation scripts to work!

Also make sure that the name of your script function and the name of your script file are exactly identical (including capitalization). The script will be referred by name of the file. If it does not match the actual function name, then the script will not be executed, and validation will not take place without any obvious error.