User Interface

The interface of a User Dialog defines its behavior in an abstract way and independent of it's 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.

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:

Icon	Title	Short Description
	User Dialog	Opens another User Dialog
	Init Start	Invoked when the User Dialog is started. This element is executed at most once and initializes the User Dialog and its data.
	Method start	Invoked when one of the methods declared in the User Dialog Interface is called.
	Event Start	Invoked when a mapped widget event is received from the view of the User Dialog.
	Script	Encapsulates IvyScript code or changes in the User Dialog data.
	Process End	Ends a User Dialog UI process.
	Exit End	Exits 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:

Icon	Title	Short Explanation
	Request Start	The normal Request element is replaced with the User Dialog start element.
	Web Page	The Page element is HTML-specific and thus not available in the User Dialog logic.
	Tasks	The Tasks element is not available because role change and task data persistence can only happen between User Dialogs.
	Task	The Task element is not available because role change and task data persistence can only happen between User Dialogs.
	Event Start	Start Event Beans are currently not supported inside User Dialogs.
	Intermediate	Intermediate Events are currently not supported inside User Dialogs.
	Call & Wait	Call & Wait are currently not supported inside User Dialogs.
	Process End	The regular Process End element is replaced with the User Dialog End element.
	End Page	The 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

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.

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.

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.

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:

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>
    

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.

        <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>
        

    <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>
    

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

To implement a user interaction that consists of several pages (for example a wizard), one Html Dialog can be 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.

<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 are used to convert number or date/time values for string represnetation 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>            
    

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

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

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>     
    

            <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"  />
        

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:

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

@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;

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 {};
}

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>

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

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

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

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

<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>

Process based Rich Dialogs are components that follow the MVC based User Dialogs of Axon.ivy. But Rich Dialogs differ in some portions to normal User Dialogs.

The 4-part structure of a process based Rich Dialog becomes also evident when looking at it's representation in the project tree:

Logic

Like for all other User Dialogs, the logic of a Rich Dialog defines how a Rich Dialog performs its work by means of a process model. But in addition to UI Events, Start Methods and Methods also the Fired Event and Accepted Broadcast that are defined on the interface are implemented as a process.

For Rich Dialogs, the Process Editor offers a few additional elements. The User Dialog drawer of the Process Editor palette contains elements, which can only be used within the Rich Dialog logic:

Icon	Title	Short Description
	Broadcast Start	Invoked when the Rich Dialog receives an accepted broadcast event as declared on it's interface
	Script	Encapsulates IvyScript code or changes in the Rich Dialog data (replaces the normal Script element).
	Fire Event	Fires one of the events declared on this Rich Dialog's Interface.

Table 6.3. Process elements only available in Rich Dialog Logic

The Rich Dialog User Context is a concept to store data for a Rich Dialog for the user currently logged in. E.g. it is possible to store the last search string of a search dialog inside the context to show this string next time the user opens the panel again. Therefore the Rich Dialog User Context only works when a user is logged-in. When no user is logged-in, the context is empty and each interaction with the context has no effect.

Axon.ivy itself uses the Rich Dialog User Context to store the UI-State of certain widgets.

This section describes how to configure the context for a small application, like a News Reader.

Standalone Configuration

Each time the Rich Dialog NewsReader is called, the same context should be used. So the user will get the same context each time when he opens the Rich Dialog NewsReader.

Technically one Rich Dialog, but functional multiple different usages

The Rich Dialog NewsReader is used e.g. for financial and local news. The context should be different. The user likes to have one context for financial news and one for local news.

Configuration for Financial News:

Each time the Rich Dialog NewsReader is opened with the context-name FINANCE, this specific Rich Dialog User Context will be used. There is no difference from which location (Rich Dialog Call element) the Rich Dialog is opened.

Configuration for local News:

Each time the Rich Dialog NewsReader is opened with the context-name LOCAL, this specific Rich Dialog User Context will be used. There is no difference from which location (Rich Dialog Call element) the Rich Dialog is opened.

Embedded Rich Dialog

The Rich Dialog NewsReader contains two embedded Rich Dialogs, the NewsList and the NewsConfiguration. The embedded Rich Dialog NewsList has configured the context mode Embedded, because the context is depending on it parent Rich Dialog Context, the NewsReader context. Therefore separate contexts will be used for financial and local news, as defined in the NewsReader Rich Dialog. The embedded Rich Dialog NewsConfiguration contains the global configuration of all news readers in the application. Therefore the context mode is Standalone. It should always use the same context without dependency to the context of the NewsReader.

Configuration of NewsList

The context of the Rich Dialog NewsList is linked to the parent Rich Dialog NewsReader. Therefore, related to the configuration of the parent Rich Dialog two contexts will be created. One for finance news and one for local news.

Configuration of NewsConfiguration

The context configuration of the Rich Dialog NewsConfiguration does not depend on the parent Rich Dialog. Therefore only one context will be created. It will always use the same context regardless which context configuration NewsReader does use.

The Rich Dialog UI State stores and restores a part of the UI state. The state is stored automatically when a windows closes. At startup of a window, the last known state is restored automatically too.

The data is stored on the Rich Dialog User Context. Therefore, when no user is logged-in, this functionality is disabled.

Currently the following widgets are supported:

Button groups are used to logically group exclusively selectable widgets (e.g. radio buttons or toggle buttons). In order for a button group to effectively control the select state of it's guarded components it must be associated specifically with each widget that it contains.

Button groups do not have a visual representation and must therefore be placed next to the panel rather than on the panel itself:

To associate a button group with a widget, you first select the widget(s) inside the Visual Editor or inside the Beans View and then set the button group object to be associated on the group attribute in the Properties View, as demonstrated above.

Symbol on Palette
Category	Non Visual Widgets
Purpose	Logically group a number of selectable items and ensure that at most one is selected at a time.
Events	-
Important Properties	-

Table 6.13. ButtonGroup Summary

The chart widgets can be used to display numeric data in a graphical way. Two types of charts are supported, pie charts for small one-dimensional data sets and and bar charts for two-dimensional data. The charts widgets must be primarly used with a Java API, there is only limited tool support in Axon.ivy, e.g. there is no Drag and Drop of events for the event mapping or there is no widget configuration view.

To add a chart widget to a Rich Dialog use the Choose Bean entry from the palette in the Visual Editor. Then choose either the ULCVPieChart or the ULCVBarChart and place it on the Rich dialog. Alternatively you can use the widgets by adding the corresponding code in the Java source of the Rich Dialog yourself. You can set most of the properties in the properties view of the Rich Dialog perspective. But full support for the widgets is only given in code, either in Java by enhancing the Rich Dialog source file manually or by accessing the widget with IvyScript.

Both charts can be used in 2D or 3D, for 3D charts use the appropriate constructors ULCVPieChart(boolean is3DChart) and ULCVBarChart(boolean is3DChart) respectively. Both charts can optionally display a legend, can use titles and sub titles and both offer adding a listener to be notified when the user clicks on the pie or bar. Use addMouseListener(IChartMouseListener<EV extends ChartMouseEvent>) then you get either a BarMouseEvent or a PieMouseEvent that you can query for more information about the click.

Pie charts are ideal to display small one-dimensional data sets with only some values. Use addPieSlice(PieSlice slice) or setPieSlices(List<PieSlice> slices) to add data to the pie chart. In addition to the value it is possible to set a solid color or a gradient and a title (only by constructor) for each slice.

For two-dimensional data, bar charts are better suited. You can add data by using addDataSeries(DataSeries series) or setDataSeries(List<DataSeries> series). A data series is a list of values that belong together and each value is represented as a bar in the same color/gradient. The other axis is defined by categories that group together the values with the same index from different data series. In other words, the values of the data series represent the y-values where as the categories are the x-values. For data series with lots of values, the bar chart widget supports paging. Switch it on with setPagingEnabled(true). It's even possible to configure the number of values per page and whether the coordinate system should be the same for all pages or whether it should be scaled.

Both widgets support the most important visual settings for charts such as background colors/gradients and transparency, shadows, tool tips and setting the fonts and font sizes of the texts used in the charts (values, axis labels, titles).

The RBooleanCellWidget is like a check box for table editing. Check boxes are used to let the user select an option.

The mapped table cell value shout be a boolean value, like true or false.

The check box will generate both an Action Event and a Value Changed event if it is selected or deselected.

You can provide your own selected and unselected icons (if you want to replace the standard check mark).

Symbol on Palette
Category	Action / Selection widget
Purpose	A check box to display and change a boolean cell value.
Events	Action, Focus, Key
Important Properties	text, icon, pressedIcon, rolloverIcon, selectedIcon, toolTip

Table 6.14. RButtonCellWidget Summary

A border layout pane is a container which arranges its components using a Border Layout. Essentially, a border layout consists of 5 areas: North, East, South and West which are arranged around the Center. The component in the center always consumes as much of the available space as possible. The surrounding components are stretched accordingly.

You can specify the amount of vertical and horizontal spacing in between the 5 areas by setting the vGap and hGap properties, respectively.

Symbol on Palette
Category	Container widget
Purpose	A container which uses a Border Layout to arrange its components.
Events	Focus, Key
Important Properties	hGap, vGap

Table 6.15. RBorderLayoutPane Summary

A box pane is a container which arranges its components using a Box Layout. Essentially, working with a Box Layout is similar to layouting with HTML tables. A box layout consists of n rows and mcolumns, where the height of each row and the width of each column are determined by the tallest or widest component, respectively. If a widget does not fill the available cell space, then it may be stretched and/or positioned inside the cell by defining its widget style properties accordingly.

You can specify the amount of vertical and horizontal spacing that is used between the rows and columns by setting the verticalGap and horizontalGap properties, respectively.

Symbol on Palette
Category	Container widget
Purpose	A container which uses a Box Layout to arrange its components.
Events	Focus, Key
Important Properties	horizontalGap, verticalGap

Table 6.16. RBoxPane Summary

The browser widget can be used to show an embedded web browser.

The browser widget will generate Web Browser - COMPLETED event, every time a new web page is loaded.

Symbol on Palette
Category	Information / Input widget
Purpose	An embedded native browser which can be used to display web pages.
Events	Web Browser, Focus, Key
Important Properties	Url, Content

Table 6.17. RBrowser Summary

Buttons are typically used to start an action or to generate an event. The button generates an Action Event if it is clicked.

Symbol on Palette
Category	Action widget
Purpose	A button with text and/or icon.
Events	Action, Focus, Key
Important Properties	text, icon, pressedIcon, rolloverIcon, selectedIcon, toolTip

Table 6.18. RButton Summary

Badge mode for RButton

The RButton can be rendered like a smart phone like badge, a clickable icon paired with an overlay that displays a number. Such badges are typically used to start dialogs, tools or processes that work on a list of entities, e.g. a badge could be used to start a mail inbox dialog using the overlay to display the number of new unread messages.

Set the setShowBadge() method to change between normal button and badge mode and use the setBadgeValue() method to set the overlay content.

Buttons are typically used to start an action or to generate an event. The button generates an Action Event if it is clicked. The Button text, icon and tooltip are taken from the cell value.

To process the action event of the button, map the event to a Rich Dialog Process start in the Rich Dialogs panel logic. In the code tab of the Event Start Process step enter the following code:

import ch.ivyteam.ivy.richdialog.widgets.components.customrenderers.RButtonCellWidget;
RButtonCellWidget button = event.getSource() as RButtonCellWidget; 
int row = button.getRow(); 
int column = button.getColumn();

Symbol on Palette
Category	Action widget
Purpose	A Button with a text to start an action. The cell value are displayed as text.
Events	Action, Focus, Key
Important Properties	text, icon, pressedIcon, rolloverIcon, selectedIcon, toolTip

Table 6.19. RButtonCellWidget Summary

Displays are placeholder widgets onto which Rich Dialogs can be loaded dynamically at runtime. A Card Display works like a "stack of cards": only the last loaded Rich Dialog on top is visible. The previously loaded Rich Dialogs will become visible again if the top component is unloaded (i.e. removed).

A card display generates a Selection Changed Event if a new Rich Dialog is loaded onto it.

Symbol on Palette
Category	Display widget
Purpose	Placeholder for Rich Dialogs that are loaded dynamically at runtime. Shows only last loaded component.
Events	Selection Changed, Focus, Key
Important Properties	displayId, toolTip

Table 6.20. RCardDisplay Summary

A card pane is a container which arranges its components using a Card Layout. The components or containers that are managed with a Card Layout are handled like a "stack of cards" where only the top component is visible. In order to identify the contained elements (i.e. cards) must be provided with an unique name. By setting a name to the selectedName property of a card pane the currently shown (i.e. top) component can be changed.

Any kind of widget or container can be a "card" on a card pane. Typically cards are containers, i.e. sub-panels, with an individual layout.

List<String> names = panel.CardPane.getNames();
panel.myCardPane.selectedName = names.get(in.cardIndex);
in.cardIndex = (in.cardIndex + 1) % names.size();
        

Symbol on Palette
Category	Container widget
Purpose	A container which uses a Card Layout to arrange its components (only component is visible).
Events	Focus, Key
Important Properties	selectedName

Table 6.21. RCardPane Summary

Check boxes are used to let the user select an option. The check box will generate both an Action Event and a Value Changed event if it is selected or deselected.

You can provide your own selected and unselected icons (if you want to replace the standard check mark).

Symbol on Palette
Category	Action / Selection widget
Purpose	A check box with text that allows to select/deselect an option.
Events	Action, Focus, Key, Value Changed
Important Properties	text, toolTip, selected

Table 6.22. RCheckBox Summary

Check box menu items are menu entries that represent on/off options. They can be used both inside RMenu and RPopupMenu widgets. The standard check-box icon of a check box menu item can be replaced by setting a different Icon Uri and Selected Icon Uri in the Widget Configuration Text/Icon Tab. Generally, check box menu items behave exactly the same as a RCheckBox widgets.

Check box menu items generate both an Action event and a Value Changed event if they are selected or deselected.

Since check box menu items do not have a direct visual representation they should be placed directly on or below a menu widget inside the Java Beans View. This view allows you to comfortably set up menu hierarchies using sub menus and menu items:

Symbol on Palette
Category	Action widget
Purpose	A selectable (on/off) option item in a menu.
Events	Action, Value Changed, Key, Focus
Important Properties	text, selected, toolTip

Table 6.23. RCheckBoxMenuItem Summary

The RCloseableTabbedDisplay is an extension of the RTabbedDisplay but with closable tabs. Please consult the documentation of RTabbedDisplay for general information about tabbed displays.

In addition to the RTabbedDisplay the RCloseableTabbedDisplay displays a close icon for each tab.

A Tab Closing Request event is generated, when a user clicks the close icon of a tab. Processes that are mapped to this event can cancel the closing of the tab by calling the cancel method on the event. If none of the mapped event processes call the cancel method on the event, then the tab will be closed automatically at the end of the event process.

The following process and ivyScript snippets show how to cancel the closing somewhere in the event process of the Tab Closing Request event:

The close icon of the tab can be changed. For that the properties tabCloseIconUri and tabInactiveCloseIconUri are provided. Set a path to a CMS icon (for example /myIcons/closeIcon) to change the icons. If only the tabCloseIconUri is specified, a gray version of it is used as the inactive close icon.

Symbol on Palette
Category	Display widget
Purpose	Extension of RTabbedDisplay to handle closing of tabs.
Events	TabClosingRequest, SelectionChanged, Focus, Key
Important Properties	displayId, tabPlacement, toolTip, tabCloseIconUri, tabInactiveCloseIconUri

Table 6.24. RCloseableTabbedDisplay Summary

A collapsible pane is a container for exactly one sub component (e.g. another container) which can be collapsed and expanded programmatically by setting the property collapsed to true or false respectively. By default a collapsible pane collapses vertically.

You can switch off the animated collapse by setting the animated property to false. In this case the embedded component will simply disappear or appear at once.

When working with a collapsible pane, a few things have to be taken into consideration. If a collapsible pane collapses with all it's content (i.e. effectively reduces it's size to 0), then extra space becomes available for all the other components on the panel.

This means that a collapsible pane can only be used within a container with a layout that in principle can handle the extra space, e.g. RGridBagLayoutPane or RBorderLayoutPane.

Furthermore the contents of the collapsible pane (including the collapsible pane itself) should never have any layout property set to request any extra space in the direction of the collapse (it's okay though to request any extra horizontal space, if the collapsible pane is oriented vertically).

To achieve those requirements, the following two layout structures are recommended:

1. Use a surrounding container with a GridBag Layout.

Assuming a vertical collapsing pane place a component that is configured to consume any extra space above or below the collapsible pane. This component will take up the extra space that becomes available when the panel collapses and will grow into that direction. Therefore the collapsible panel will shrink either from bottom to top or from top to bottom, depending on whether the "space consumer" is placed below or above, respectively. The example above simply employs a "vertical glue" RFiller component to consume the extra space.

2. Use a surrounding container with a Border Layout.

Assuming a vertical collapsing pane place the collapsible pane either into the north or south area of the surrounding container. If the panel collapses, the center area will receive and consume all extra space automatically and give it to the component which is placed there (if any). Therefore the collapsible panel will shrink either from bottom to top or from top to bottom, depending on whether is placed in the north or south area, respectively. Typically all other areas of the surrounding border layout pane stay empty.

Symbol on Palette
Category	Container widget
Purpose	A container which has the ability to collapse (i.e. hide) and expand (i.e. show) a single embedded component.
Events	Focus, Key
Important Properties	collapsed, animated

Table 6.25. RCollapsiblePane Summary

A combo box allows the user to select one from a pull-down list of multiple options.

A combo box generates an Action Event if an option is selected.

You can configure both the appearance and the source of the data that a combo box should show on the Combo Box data tab of the Widget Configuration View. You can specify text and/or icon as well as a tool tip for each entry depending on the entry's value itself.

The data source can either be a List, a Record Set or an Enumeration. Depending on what is used, the properties selectedListEntry, selectedRecord or selectedEnumValue will return the currently selected value.

Symbol on Palette
Category	Data widget
Purpose	A combo box allows to select exactly one from a list of options.
Events	Action, Focus, Key
Important Properties	listData, recordsetData, enumClassName, selectedIndex, selectedListEntry, selectedRecord, selectedEnumValue, maximumRowCount, prototypeDisplayValue, font, toolTip

Table 6.26. RComboBox Summary

A combo box cell widget is similar to a normal combo box like the RComboBox.

A combo box allows the user to select one item from a pull-down list of multiple items.

A combo box generates an Action Event if a item is selected.

You can configure both the appearance and the source of the data that a combo box should show on the Combo Box data tab of the Widget Configuration View. You can specify text and/or icon as well as a tool tip for each entry depending on the entry's value itself.

The data source can either be a List, a Record Set or a Enumeration. Depending on what is used, the properties selectedListEntry, selectedRecord or selectedEnumValue will return the currently selected value.

Symbol on Palette
Category	Data widget
Purpose	A combo box allows to select exactly one from a list of options.
Events	Action, Focus, Key
Important Properties	listData, recordsetData, enumClassName, selectedIndex, selectedListEntry, selectedRecord, selectedEnumValue, maximumRowCount, prototypeDisplayValue, font, toolTip

Table 6.27. RComboBoxCellWidget Summary

Date Pickers are used to query a date from an user. The date can either be entered directly into the Date Picker's date field or be comfortably selected with the integrated pop-up calendar (will start at the currently set date). The date picker widget is by default not initialized (empty) , use the valueAsDate property to set another date. Use the setDate() method with the parameter null to reset the RDatePicker

The date picker widget generates an Action event if a new date has been selected.

Attributes

The date field returns the selected/entered date value or null if the input was invalid (be careful with Axon.ivy's Null Handling feature).

The attribute valueAsDate delivers the selected date or a Date.UNINITIALIZED_DATE value if the user input does not represent a valid value.

The attribute firstDayOfWeek sets the day that starts the week. So that setting e.g. the value "3" (which means Wednesdays, the default would be 1=Monday) then weeks under each other will be displayed starting with Wednesdays. (see screenshot below)

The attribute flaggedDates enables you to highlight some dates. You should provide an array of dates that should be highlighted (just like on the screenshot the 20 and 21.June).

The attribute daysOfTheWeek let you provide own titles for the days (see screenshot: "Mi"=Wednesday, "do"=Thursday, etc.)

The attribute linkDate enables you to customise the label and the destination date of the link at bottom of the picker (on the screenshot it is "3.Juni 2009", the default is today in the current language).

The attribute timeZone let you change the time zone the date picker should work with.

Summary

Symbol on Palette
Category	Input widget
Purpose	Allows the user to specify a date with the help of a calendar.
Events	Key, Focus, Action, ValueChanged
Important Properties	valueAsDate, toolTip

Table 6.28. RDatePicker Summary

Fillers are invisible glue components that consume space in a specific layout. The can either have a rigid fixed size (in which case they simply keep a fixed distance between two components) or they can have a glue behaviour, in which case they consume additional space, e.g. if a window gets resized. The latter is typically the intended behaviour if fillers are used inside a GridBagLayout.

Style Configuration

The style configuration of a filler define whether it is used as glue or as a rigid size block.

If the preferredIsExactSize style property of a filler is set to true, then the filler will never change it's preferred size, no matter whether the layout changes due to resizing. In other words: the minimum and maximum size will be set to the preferred size and all other properties will be ignored.

If the property is set to false, then the filler will behave as configured by the rest of the style properties, i.e. it will request to be displayed with it's preferred size, but may change size to the specified minimum and maximum size, if the managing layout manager (typically GridBagLayout) requests so, due to size changes of the surrounding container. In this way, the described glue behaviour can be achieved. By default, the styles verticalGlue and horizontalGlue are already available for all fillers.

Symbol on Palette
Category	Layout Helper widget
Purpose	Fillers consume space between widgets in a configured way.
Events	No events
Important Properties	Do not set properties of a filler directly, use pre-configured Styles instead.

Table 6.29. RFiller Summary

A flow layout pane is the simplest container layout available. It uses a Flow Layout where all added components are arranged in a single row. The row's contents are aligned either left, right or centered if extra space is available.

The desired alignment of components can be set with the alignment property. The amount of horizontal spacing that is used between the components can be specified by setting the hGap attribute. The amount of space that is added above and below the components can be set with the vGap attribute.

Symbol on Palette
Category	Container Widget
Purpose	A container which aligns it's added component left, centered or right in a single row.
Events	Focus, Key
Important Properties	alignment, hGap, vGap

Table 6.30. RFlowLayout Summary

A grid bag layout pane is the most powerful container in terms of layouting, it uses a GridBag Layout to arrange it's components. In a grid bag layout components are arranged and aligned in a grid, but each component may span several grid cells both horizontally and vertically. The sizes of grid cells are generally determined by the tallest and widest components in their row or column, respectively. If a component has more space available than it's preferred size measures, then it may be instructed to consume the additional horizontal or vertical space or to align itself inside the cell, either at north, northwest, west, southwest, south, southeast, east, northeast or northwest position. By using nested containers that provide an own layout but for the area they occupy the design of forms is very flexible.

Because components can be configured to consume extra available space, grid bag layout containers are largely insensitive with respect to size changes of a window, for example. Components maintain their relative positions and may grow or shrink according to the configuration. By using RFiller components, placeholders can be used that have the sole purpose of consuming as much space as possible either horizontally or vertically or both.

The following layout style properties are available for all components that are contained inside a grid bag layout pane:

Symbol on Palette
Category	Container widget
Purpose	A container with a very flexible and powerful row/column based layout manager.
Events	Focus, Key
Important Properties	-
Component Layout Properties	fill, weightX, weightY, anchor (see above)

Table 6.32. GridBagLayoutPane Summary

A grid layout pane arranges it's components in n rows and m columns in cells of equal size according by using a Grid Layout. The size of the grid cells is determined by the tallest and the widest contained component. All components are stretched to this size. Components can not span across multiple columns or rows.

The horizontal and vertical space between rows and columns can be configured by setting the hGap and vGap properties, respectively. The number of desired columns and rows can be configured by setting the columns and rows properties, respectively. The number of columns will increase automatically by one, if more than n x m components are added, but the number of rows stays constant at the configured value.

Because all contained components are forced to have the same size, this pane is usually only employed in special situations, e.g. for button panels, where it is desired for aesthetic reasons that all buttons have the same size, independent of the length's of their texts.

Symbol on Palette
Category	Container widget
Purpose	A container which arranges it's components in n x m grid cells of equal size.
Events	Focus, Key
Important Properties	rows, columns, hGap, vGap

Table 6.33. RGridLayout Summary

The html pane widget can be used to render a (small) HTML document on a label. Actually it is between RBrowser and RLabel. RBrowser is capable to render more complicated HTML pages, and it allows navigation for a user just like RHtmlPane per default. RLabel can also render HTML content if you surround content with the <HTML> tag. Meanwhile working with RHtmlPane we recommend starting the text that the widget should display with an <HTML> tag.

Symbol on Palette
Category	Label widget
Purpose	A multi-line label which can display HTML texts with links.
Events	Focus, Key, Hyperlink
Important Properties	text, toolTip, veto

Table 6.34. RHtmlPane Summary

A hyperlink can be used in place of a button. It takes less room and may look better in some places. An optional icon can also be provided, the configuration possibilities are equal to those of a button.

Hyperlinks are rendered in a different color, once they have been activated. The hyperlink generates both an Actionevent and a Clicked event if it is clicked.

Symbol on Palette
Category	Action widget
Purpose	A hyperlink that can be activated with a mouse click.
Events	Action, Clicked, Focus, Key
Important Properties	text, icon, focus, key, toolTip

Table 6.35. RHyperlink Summary

Hyperlinks are typically used to start an action or to generate an event. The hyperlink generates an Action Event if it is clicked. The hyperlink text, icon and tooltip are taken from the cell value.

You will usually use RHyperlinkCellWidget if you need a clickable icon and / or text cell.

To process the action event of the hyperlink, map the event to a Rich Dialog Process start in the Rich Dialogs panel logic. In the code tab of the Event Start Process step enter the following code:

import ch.ivyteam.ivy.richdialog.widgets.components.customrenderers.RHyperlinkCellWidget;
Object source = event.getSource();
if(source instanceof RHyperlinkCellWidget) {
	RHyperlinkCellWidget hyperlink = source as RHyperlinkCellWidget;
	ivy.log.debug("" + hyperlink.getRow() + " : " + hyperlink.getColumn());
}

Symbol on Palette
Category	Action widget
Purpose	A hyperlink with a text and / or icon to start an action. The cell value is displayed as text.
Events	Action, Focus, Key
Important Properties	text, icon

Table 6.36. RHyperlinkCellWidget Summary

Labels are used to write short texts on the UI, e.g. for labelling text fields or for writing status or title messages. A label can have an optional icon to display, the relative position of text and icon can be configured, as well as the gap between them.

Labels are also capable of displaying simple HTML. Start the text that the label should display with an <html> tag. This way you can for example use the <font> tag to show parts of a text in a different color, or use <b> to render text or in bold type. Use <br> to render multiple lines.

Labels can be assigned to another widget by using the labelFor property. If this property is set, the focus will be forwarded to the assigned widget, if the label receives it.

Symbol on Palette
Category	Label widget
Purpose	A label which can display plain or simple HTML texts.
Events	Focus, Key
Important Properties	text, icon, toolTip, labelFor, font

Table 6.37. RLabel Summary

The list widget shows an arbitrary number of entries which are also available for (multi-) selection.

A list generates a List Selected Event if an entry is selected and an Action event if a list entry is double clicked.

You can configure both the appearance and the source of the data that a list should show on the List Data tab of the Widget Configuration view. You can specify text and/or icon as well as a tool tip for each entry depending on the entry's value itself.

The data source can either be a List or a Record Set. Depending on what is used, the properties selectedListEntry; selectedListEntries or selectedRecord; selectedRecords will return the currently selected value(s). The selection mode (single selection, single interval selection or multiple selection) can be set with the selectionMode property.

With the property autoSelectFirstEntry you can have the widget select the first data entry automatically (if data is present). This has also the effect, that a call to clearSelection() will reset the selection to the first data entry (instead of clearing). The property is set to false by default.

Symbol on Palette
Category	Data widget
Purpose	A list shows an arbitrary number of items and allows the user to select one or multiple entries from that list.
Events	List Selected, Action, Focus, Key
Important Properties	listData, recordsetData, selectedIndices, selectedListEntry, selectedListEntries, selectedRecord, selectedRecords, autoSelectFirstEntry

Table 6.38. RList Summary

Displays are placeholder widgets onto which Rich Dialogs can be loaded dynamically at runtime. A List Display shows the loaded Rich Dialog panels as entries of a list.

A list display automatically shows a scroll bar if the number of loaded Rich Dialogs exceeds the available space. You can configure and override this behavior by setting the properties horizontalScrollBarPolicy and verticalScrollBarPolicy to the respective values NEVER, AS_NEEDED or ALWAYS in the properties view (the default is AS_NEEDED).

The RListDisplay does not support selection or offer selection events, but a Rich Dialog can be scrolled into the visible area by either selecting it on the display with it's name (i.e. the name that is provided by a call to IRichDialogPanel.getName()).

Symbol on Palette
Category	Display widget
Purpose	Placeholder for Rich Dialogs that are loaded dynamically at runtime. Shows loaded components in a scrollable list.
Events	Focus, Key
Important Properties	displayId, horizontalScrollBarPolicy, verticalScrollBarPolicy, toolTip

Table 6.39. RListDisplay Summary

The RLookupTextField is a mixture between RTextField and RComboBox. The text field shows a list of suggestions while typing, the suggestions are filtered according to the entered text, as the user continues typing. At any point of typing, the user may choose to select one of the suggestions or stay with his input.

The selection of a suggested entry is performed if the user hits either Enter or Tab during typing. The user may use the up and down Arrow Keys or the mouse to select a specific entry from the suggestion list.

Events

As well as RTextField, RLookupTextField also offers events like Value Changed Event, Key Event and Selection Changed events.

Key Event is sent when ever a key is typed, the Value Changed Event is only sent when the user leaves the text field and the value has changed.

The Value Changed Event is transmitted synchronously and the Key Event is transmitted asynchronously.

Data

Data for an RLookupTextField is configured very similar to a RComboBox.You can configure both the appearance and the source of the suggestions that the text field shows on the Data tab of the Widget Configuration view. You can specify the display strings of the suggestions for each entry depending on the entry's value itself.

The data source can either be a List or a Record Set. Depending on what is used, the properties getSelectedListEntry() or getSelectedRecord() will return the currently selected value. If no value from the suggestion list has been chosen, then null will be returned by those methods.

Use getText() to get the text that is actually shown in the text field, which may be different from the associated selection's model entry (e.g. if the user has entered a text that does not match an entry, or if the entry's display string is different from the entries value).

Special Properties

With the property lazyLookupIdleTime you can set an idle time in milliseconds. The text field will wait for a pause in typing that is longer than this idle time, before the entered text is sent to the server (thus filtering the displayed suggestions). Setting an higher idle time is recommended, if your users type very fast and feel annoyed by the fact, that the outgoing requests to filter large suggestion lists block their input.

If the property forceSelection is set to true then only selections from the suggestion list are accepted. The text field is then used merely to filter the proposals. If the entered text does not match any of the suggestions it will be marked as invalid. When leaving the text field, then invalid text will be discarded and the text will be reset to the last selected valid value (which is possibly empty).

If the property forceSelection is set to false, then user input which is not among the proposed entries will also be accepted. In this case, it may occur that querying the selected value with getSelectedRecord() or getSelectedEntry() results to null, because the user input does not match any of the proposals. In this case you should use getText() to access the text that was entered by the user.

If autoSelectFirstEntry is set to true, then the text of the RLookupTextField will be initialized with the first entry of the data list.

Symbol on Palette
Category	Input widget
Purpose	An RTextField that offers a lookup function to help text selection from a list. As you begin to type your text a selection list will appear. This list shows prefix matches with the text you typed in.
Events	Key, Focus, Value Changed
Important Properties	listData, recordsetData, selectedListEntry, selectedRecord, valueAsString, lazyLookupIdleTime autoSelectFirstEntry, forceSelection, autoSelectFirstEntry

Table 6.40. RLookupTextField Summary

A menu is a container for RMenuItem (and similar) widgets. It can be nested within other menus, including RPopupMenu. Menus can also be added to a RMenuBar.

Menu widgets do not provide any events and they don't have any special properties worth mentioning, use the Widget Configuration Text/Icon Tab to set text and optional icon of a menu.

Since menu widgets do not have a visual representation on the panel they should be placed directly inside the widget tree of the Java Beans view. This view allows you to comfortably set up menu hierarchies using sub menus and menu items:

Symbol on Palette
Category	Container widget
Purpose	Provide a container for menu items and thereby define contents of a menu.
Events	-
Important Properties	-

Table 6.41. RMenu Summary

Menu bars are containers for RMenu widgets. A menu bar is constantly visible (as opposed to a RPopupMenu which only appears on demand) and shows the available top level menus with their name. If a menu is clicked, then it unfolds and displays it's entries which are then available for selection. Menu bars are typically placed at the top of a screen, but they don't have to.

Menu bars do not support any events and they don't have any special properties worth mentioning.

Note

Although menu bars do have a visual representation on the edited panel, the added menus should not be dropped onto the menu bar component inside the visual editor area. Instead they should be inserted below the menu's representation in the Java Beans view, where the hierarchical structure of the menu components becomes apparent.

Symbol on Palette
Category	Container widget
Purpose	A container for menu objects.
Events	-
Important Properties	-

Table 6.42. RMenuBar Summary

Menu items are the standard entries for RMenu and RPopupMenu widgets. They can have a text and/or icon. In fact, a menu item behaves exactly the same as a RButton in all aspects of its use.

Menu items generate an Action event if they are selected.

Since menu items do not have a direct visual representation they should be placed directly on or below a menu widget inside the Java Beans view. This view allows you to comfortably set up menu hierarchies using sub menus and menu items:

Symbol on Palette
Category	Action widget
Purpose	A clickable item of a menu.
Events	Action, Key, Focus
Important Properties	text, icon

Table 6.43. RMenuItem Summary

Menu separators are used to visually separate menu items into groups. Simply place them between any menu items of a menu container in the Java Beans view.

Menu separators do not generate any events.

Since menu separators do not have a direct visual representation they should be placed directly on or below a menu widget inside the Java Beans view. This view allows you to comfortably set up menu hierarchies using sub menus and menu items:

Symbol on Palette
Category	Layout Helper widget
Purpose	Visually separate menu items into groups.
Events	-
Important Properties	-

Table 6.44. RMenuSeparator Summary

Password fields are used to query passwords from the user. The entered input is not rendered in clear text but as * characters. The text field generates a Value Changed event and a Key event every time a key is typed and an Action event if the return/enter key is pressed.

The Value Changed event is transmitted synchronously and the Key event is transmitted asynchronously. Since the synchronous event handling may lead to a blocking of the UI if the user types too fast, it is generally recommended to map the asynchronous Key event instead (will keep the UI responsive).

Symbol on Palette
Category	Input widget
Purpose	A field where the user can enter a password.
Events	Key, Focus, Action, Value Changed
Important Properties	text, echoChar, toolTip, font

Table 6.45. RPasswordField Summary

A popup menu is a container for RMenuItem (and similar) widgets. It can be associated with a component or a container and will normally appear when the user clicks the right mouse button on that component.

RPopupMenu widgets do not provide any events and they don't have any special properties worth mentioning.

Since popup menus do not have a visual representation on the panel they must be placed next to the panel rather than on the panel itself:

To associate a popup menu with a component, you first select the component inside the Visual Editor or inside the Java Beans view and then set the menu object to be associated on the componentPopupMenu attribute in the Properties view, as demonstrated above.

Note

The popup menu can also be inherited from a parent component, i.e. you can associate a popup menu with a top level container (e.g. the panel itself) and can then reuse it on the inner components. If you consult the Java Beans view, you can easily identify the components that are able to inherit the popup-menu of a container.

By inheriting the popup menu of a parent component you don't have associate a popup menu with each sub component again, if you should decide to use another menu on the parent. Inheritance is supported over multiple levels, as long as the direct parent component also inherits the menu.

Symbol on Palette
Category	Container widget
Purpose	Define the contents of a context / popup menu on a component.
Events	-
Important Properties	-

Table 6.46. RPopupMenu Summary

A progress bar can be used to inform the user about the amount of completed work or to show a percentage graphically. Progress bars can either have a horizontal or vertical orientation, which can be specified with the orientation property. Progress bars are pure information widgets, i.e. the displayed information can not be altered directly by the user in any way. .

The appearance and behavior of a progress bar can be configured: The minimum and maximum value can be set and an optional label string can be defined which can be rendered over the progress bar.

Symbol on Palette
Category	Information widget
Purpose	Show a percentage value graphically.
Events	Focus, Key
Important Properties	value, maximum, minimum, orientation, string, stringPainted, toolTip

Table 6.47. RProgressBar Summary

Radio buttons are used give the user the possibility to select exactly one from a number of options. The radio button will generate both an Action event and a Value Changed event if it is selected or deselected.

You can provide your own selected and unselected icons (if you want to replace the standard radio mark).

Symbol on Palette
Category	Action / Selection widget
Purpose	A radio button that allows to select exactly one from multiple options.
Events	Action, Focus, Key, Value Changed
Important Properties	text, toolTip, selected, group

Table 6.48. RRadioButton Summary

Radio button menu items are typically used in groups of at least two and represent a number of exclusively selectable options. They can be used both inside RMenu and RPopupMenu widgets. The standard radio button icon of a RRadioButtonMenuItem can be replaced by setting a different Icon Uri and Selected Icon Uri in the Widget Configuration Text/Icon Tab. Generally, radio button menu items behave exactly the same as a RRadioButton widgets.

Radio button menu items generate both an Action event and a Value Changed event if they are selected or deselected.

Since radio button menu items do not have a direct visual representation they should be placed directly on or below a menu widget inside the Java Beans view. This view allows you to comfortably set up menu hierarchies using sub menus and menu items:

Symbol on Palette
Category	Action widget
Purpose	One of a number of exclusively selectable items in a menu.
Events	Action, Value Changed, Key, Focus
Important Properties	text, selected, toolTip, group

Table 6.49. RRadioButtonMenuItem Summary

A standalone scroll bar can be used to let the user adjust a property in a continuous way; e.g. as an alternative to a RSlider widget which only offers to select a range value in discrete steps. Scroll bars can either have a horizontal or vertical orientation, which can be specified with the orientation property.

A scrollbar produces continuously Adjustment events if the knob is dragged with the mouse.

The scrollbar's position value is a value between 0 and 1, indicating the percentage at which the bar's knob is positioned.

Symbol on Palette
Category	Input widget
Purpose	Select a value between 0 and 1 in a continuous way, by positioning the scrollbar knob with the mouse.
Events	Adjustment, Focus, Key
Important Properties	position, orientation, unitIncrement, blockIncrement, toolTip

Table 6.50. RScrollBar Summary

A scroll pane provides a "viewport" (i.e. a window) that can be moved about a single sub component which is typically larger than the area taken up by the scroll pane container. Different scroll bar policies both for vertical and horizontal scrolling can be configured by setting the properties verticalScrollBarPolicy and/or horizontalScrollBarPolicy to AS_NEEDED, ALWAYS or NEVER respectively. Scrolling with the mouse wheel can be enabled or disabled by setting the property wheelScrollingEnabled.

Symbol on Palette
Category	Container widget
Purpose	A for a single sub-component providing horizontal and vertical scrollbars to move the viewport about the contents of the subcomponent.
Events	Focus, Key
Important Properties	verticalScrollBarPolicy, horizontalScrollBarPolicy, wheelScrollingEnabled

Table 6.51. RScrollPane Summary

A slider widget can be used to let the user adjust a property in a discrete or continuous way. Sliders can either have a horizontal or vertical orientation, which can be specified with the orientation property. With the inverted property the orientation of the range of values can be selected.

The appearance and behavior of a slider can be further configured: The maximum and minimum range value can be set, as well as the minor and major tick spacing. You can define whether the ticks should be painted, whether the track should be painted and whether the knob should snap to the tick marks or not.

A slider produces Value Changed events if the knob is dragged with the mouse.

Symbol on Palette
Category	Input widget
Purpose	Select an numerical value between a defined minimum and maximum, by positioning the slider knob with the mouse.
Events	Value Changed, Focus, Key
Important Properties	value, minimum, maximum, orientation, inverted, minorTickSpacing, majorTickSpacing paintTicks, snapToTicks, toolTip

Table 6.52. RSlider Summary

A split pane divides the available space into two areas, either left and right or top and bottom, into each of which exactly one component or sub-container may be placed.

In between the two areas, a divider component allows to distribute the available space with the mouse. Use the orientation property to set the split pane's orientation to either horizontal split or vertical split. The dividerLocation attribute may be used to initially place the divider.

The divider can either be continuously dragged with the mouse or any of it's two arrow icons can be clicked, in which case it will move completely to the indicated side, hence closing the component on this side entirely (see examples above). If you set the oneTouchExpandable property to true then the divider may be moved to the opposite side with a single mouse click (this behaviour is off by default).

Normally the two components are only re-layouted when the user let's the divider go. If you want a continuous re-layouting during the drag then you must set the continuousLayout property to true.

Symbol on Palette
Category	Container widget
Purpose	A two-area container with a movable divider to redistribute space.
Events	Focus, Key
Important Properties	orientation, dividerLocation, resizeWeight, oneTouchExpandable, continuousLayout, dividerSize

Table 6.53. RSplitPane Summary

Displays are placeholder widgets onto which Rich Dialogs can be loaded dynamically at runtime. A RTabbedDisplay shows the loaded Rich Dialog panels as tabs.

A tabbed display generates a Selection Changed event if one of its tabs (i.e. loaded Rich Dialogs panels) is selected. This also happens if a new Rich Dialog is loaded onto the display, because it will become the selected tab.

Symbol on Palette
Category	Display widget
Purpose	Placeholder for Rich Dialogs that are loaded dynamically at runtime. Shows loaded components as tabs.
Events	Selection Changed, Focus, Key
Important Properties	displayId, tabPlacement, toolTip

Table 6.54. RTabbedDisplay Summary

A tabbed pane is a container which arranges its components behind each other (similar to RCardPane) but making each one directly accessible by providing tabs. By clicking on a tab the associated component is brought to front. The location of the tabs can be configured as top, bottom, left and right with the property tabPlacement. The currently selected tab can be set with the selectedIndex attribute. The added components are associated with an index starting at 0.

Any kind of widget or container can be a "tab" on a tab pane. Typically tabs are containers, i.e. sub-panels, with an individual layout.

Each tabbed component can have it's tab labelled be given a tool tip by setting the properties title and toolTipText inside the containment attribute, respectively.

Symbol on Palette
Category	Container widget
Purpose	A container which arranges it's components behind each other, making them accessible with a tab.
Events	Focus, Key
Important Properties	selectedIndex, tabPlacement

Table 6.55. RTabbedPane Summary

Table widgets are used to show tabular data.

A table generates a List Selected Event if a row is selected, an Action Event if a row is double clicked and a Value Changed Event if one of the RTable cell values has changed.

You can configure both the appearance and source of the data that a table should show on the Table Data tab of the Widget Configuration view. There you can specify a style configuration for each column cell as well as icon, text and tool tip for each column, based on the value of the cell or the whole row data. The widget config also allows you to specify the table columns as editable and/or sortable. The column entries are sorted according to the value they represent if you double click on the header of a column.

The Widget Configuration lets you define each column to be editable or not, by ivyScript. The edited values are stored in the data model directly (List or Recordset). There is no event at the moment, that signals a change in the RTable data.

The appearance of the table widget itself can be further configured by setting the properties showGrid, showHorizontalLines and showVerticalLines.

The data source for a table can either be a List of Lists with equal length or a Recordset. Depending on what is used, the properties selectedListEntry; selectedListEntries or selectedRecord; selectedRecords will return the currently selected list or record. The selection mode (single selection, single interval selection or multiple selection) can be set with the selectionMode property.

With the property autoSelectFirstEntry you can have the widget select the first data entry automatically (if data is present). This has also the effect, that a call to clearSelection() will reset the selection to the first data entry (instead of clearing). The property is set to false by default.

import ch.ivyteam.ivy.richdialog.widgets.components.RTableValueChangedEvent;
RTableValueChangedEvent changedEvent = event as RTableValueChangedEvent;
int row = changedEvent.getFirstRow();
int column = changedEvent.getColumn();

Symbol on Palette
Category	Data widget
Purpose	A table can show a (large) amount of tabular data and allows the user to select one or multiple rows from the spread sheet.
Events	List Selected, Action, Focus, Key, Value Changed
Important Properties	listData, recordsetData, selectedListEntry, selectedListEntries, selectedRecord, selectedRecords, selectionMode, autoSelectFirstEntry

Table 6.56. RTable Summary

The RTableTree widget is a combination of the RTable and RTree widgets. It therefore offers the combined amount of events and configuration possibilities. Please consult the documentation of the mentioned widgets for a detailed explanation of the respective aspects.

Use the Widget Configuration TableTree data tab to configure the table tree widget style and data settings.

With the property autoSelectFirstEntry you can have the widget select the first data entry automatically (if data is present). This has also the effect, that a call to clearSelection() will reset the selection to the first data entry (instead of clearing). The property is set to false by default.

Symbol on Palette
Category	Data widget
Purpose	A table displays hierarchical tree data in a tabular fashion. Nodes/rows can be selected, expanded and collapsed.
Events	Tree Selection, Tree Load (configurable), Tree Expansion, List Selected, Action, Focus, Key
Important Properties	treeData, listData, recordsetData, selectedTreeNode, selectedTreeNodes, selectedListEntry, selectedListEntries, selectedRecord, selectedRecords, selectionMode, autoSelectFirstEntry, rootVisible

Table 6.57. RTableTree Summary

A RTaskPane is essentially the same as a RCollapsiblePane, with the difference that it provides a title bar which consists of a title text, an optional icon and a collapse/expand button. Any kind of widget or container can be the content of a task pane on a task pane container.

Task panes are best used inside a RTaskPaneContainer, which is a parent container designed specifically to show task panes in a side bar below each other. The task pane container takes care of taking up the extra space if a pane is collapsed and shifts the other panes accordingly. Task pane container can also be configured to ensure that at most a single task pane is open at one time.

If you want to use a task pane outside a task pane container then you have to take care of correct re-layouting yourself (i.e. provide other components that take up extra available space in case of collapsing). Consult the documentation of RCollapsiblePane for more information on this matter.

Use the Widget Configuration text/icon tab to set title and icon of a task pane. The state of a task pane (i.e. collapsed or expanded) can be defined by setting the expanded attribute.

Symbol on Palette
Category	Container widget
Purpose	A collapsible container with a title bar intended to be used inside a RTaskPaneContainer.
Events	Focus, Key
Important Properties	text, icon, expanded

Table 6.58. RTaskPane Summary

A task pane container is a container for RTaskPane components only. The added task panes are arranged vertically below each other. The task pane container itself has only limited configuration possibilities: if you set singleTaskPaneOpen to true, then only one task pane can be opened at a time (i.e. the previously opened task pane will be closed before opening a new one).

Any kind of widget or container can be the content of a task pane on a task pane container. See RTaskPane to learn how to configure a single task pane.

The task pane container will show the contained task panes in exactly the state as they were configured in the Rich Dialog editor. I.e. all closed panes will be initially shown in collapsed state and all open panes will be initially shown in expanded state.

Symbol on Palette
Category	Container widget
Purpose	A container for RTaskPane widgets.
Events	Focus, Key
Important Properties	singleTaskPaneOpen

Table 6.59. RTaskPaneContainer Summary

Displays are placeholder widgets onto which Rich Dialogs can be loaded dynamically at runtime. A Task Pane Display shows the loaded Rich Dialogs as individual Task Panes on a Task Pane Container. By setting the property singleTaskPaneOpen to true you can configure that at most one task pane should be open (i.e. the previously open task pane will be closed if another task pane is selected or opened).

A task pane display does not generate any non-standard events.

Symbol on Palette
Category	Display widget
Purpose	Placeholder for Rich Dialogs that are loaded dynamically at runtime. Shows loaded components as task panes.
Events	Focus, Key
Important Properties	displayId, singleTaskPaneOpen, toolTip

Table 6.60. RTaskPaneDisplay Summary

Text areas are used to allow the user to enter multi-line texts. The text area generates a Value Changed event and a Key event every time a key is typed.

The Value Changed event is transmitted synchronously and the Key event is transmitted asynchronously. Since the synchronous event handling may lead to a blocking of the UI if the user types too fast, it is generally recommended to map the asynchronous Key event instead (will keep the UI responsive).

Use the attributes lineWrap and wrapStyleWord to enable/disable line wrapping and to enable/disable whole word wrapping, respectively. Obviously the setting second attribute has only an effect, if line wrapping is enabled.

Validation

The Widget Configuration view shows an additional Validation Tab if a text area is selected.

By selecting a specific validation configuration you can define the format of the input.

You can edit existing configurations or add new ones in the Widget Input Validation subtree of the Configuration Editor. You can specify Number, Date, Percent, String/Regular Expression based validations.

Tip

Most of the existing validation configurations do not support multiple lines input. Thus they will not suite ideally for a text area. Therefore, it is recommended to create regular expression based validation configurations specific to the text area. In order to support multiple lines, the existence of newline characters (\r\n) must be considered.

Symbol on Palette
Category	Input widget
Purpose	An area where the user can enter a multi-line text.
Events	Key, Focus, Value Changed
Important Properties	text, lineWrap, wrapStyleWord, caretPosition, toolTip, font

Table 6.61. RTextArea Summary

Text fields are used to get (single line) input from the user. The text field generates a Value Changed event and a Key event every time a key is typed.

The Value Changed event is transmitted synchronously and the Key event is transmitted asynchronously. Since the synchronous event handling may lead to a blocking of the UI if the user types too fast, it is generally recommended to map the asynchronous Key event instead (will keep the UI responsive).

Validation

The Widget Configuration view shows an additional Validation Tab if a text field is selected.

By selecting a specific validation configuration you can define the format of the input.

You can edit existing configurations or add new ones in the Widget Input Validation subtree of the Configuration Editor. You can specify Number, Date, Percent, String/Regular Expression based validations.

Given that a valid format is ensured, you can access the value of a text field from the specialized attributes valueAsNumber, valueAsDate and valueAsString.

Note that the return value is a e.g. Date.INVALID if the user input does not represent a valid value.

Warning

Be aware that the accessing of a text field's value as number or as date will fail with an exception at runtime if the input entered by the user does not match the requested format. Therefore you should always enforce valid input with a proper Validation Configuration if you intend to access an entered date and number directly with the respective attribute.

Symbol on Palette
Category	Input widget
Purpose	A text field where the user can enter a string.
Events	Key, Focus, Value Changed
Important Properties	text, valueAsDate, valueAsString, caretPosition, toolTip, font

Table 6.62. RTextField Summary

Text fields are used to get (single line) input from the user in a RTable.

For more informations about this widget see the documentation of RTextField. The possibilities and functionalities are quite the same.

Toggle buttons are used to let the user visually enable an option in an on/off style. If a toggle button is clicked, it will stay in pushed state if it was previously unselected or vice versa. A toggle button will generate both an Action event and a Value Changed event if it is selected or deselected.

Symbol on Palette
Category	Action / Selection widget
Purpose	A toggle button with text and/or icon that allows to select/deselect an option.
Events	Action, Focus, Key, Value Changed
Important Properties	text, toolTip, selected

Table 6.63. RToggleButton Summary

A tool bar lines up widgets in a dock. Although any kind of widget or container can be a component of a tool bar, typically buttons are used. The look and feel of a tool-bar is determined by the kind of components it contains, but generally it will remove any borders of the added contents to make them look smoothly integrated. When rolling the mouse over the contents of a tool bar then the currently pointed at component appears enhanced.

A tool bar can have a horizontal or vertical orientation which can be set with the orientation attribute.

Symbol on Palette
Category	Container widget
Purpose	A tool bar contains other widgets (typically buttons) and aligns them in a dock style either horizontally or vertically.
Events	Focus, Key
Important Properties	orientation

Table 6.64. RToolBar Summary

Tree widgets are used to display hierarchically organized data.

A tree generates a Tree Selection event if a node is selected and an Action event if a node is double clicked. To support the lazy loading of data, the generation of a Tree Load event can be configured in the Tree Data tab of the Widget Configuration view. Additionally the tree widget supports Tree Expansion Events that occur whenever a node is expanded or collapsed.

The data source of a tree is always a Tree object. The Widget Configuration Tree Data tab allows you to define the appearance and rendering of each tree node, which can be based on the tree's value object and/or on a separate info string. It possible to define style, text, icon and tool tip for each rendered tree label.

The appearance of the rendered tree can be further configured by setting the properties rootVisible (i.e. whether the root node should be displayed or not) and showsRootHandles (i.e. whether the root node should be displayed with an expand/collapse handle in front).

The tree widget supports multi-selection of nodes by default. The properties selectedTreeNode; selectedTreeNodes will return the currently selected node(s).

With the property autoSelectFirstEntry you can have the widget select the first data entry automatically (if data is present). This has also the effect, that a call to clearSelection() will reset the selection to the first data entry (instead of clearing). The property is set to false by default.

Symbol on Palette
Category	Data widget
Purpose	A tree displays hierarchical data. Nodes can be selected, expanded and collapsed.
Events	Tree Selection, Tree Load (configurable), Tree Expansion, Action, Focus, Key
Important Properties	treeData, selectedTreeNode, selectedTreeNodes, autoSelectFirstEntry, rootVisible

Table 6.65. RTree Summary

There are two ways to display PDF documents in a Rich Dialog based process. First you can open the PDF in the RBrowser widget. Internally the RBrwoser widget then opens a real browser in a separate operating system process and in there the embedded PDF plugin (usually Acrobat Reader) will be used to display the PDF. This has the disadvantage that you have no real control about the PDF viewing, e.g. if the browser decides to open the PDF document in its own window there is nothing you can do about it. To avoid such problems, you can use the ULCVPdfViewer widget which is purely Java based and does not use any external operating system processes. So, you can fully control where the PDF is displayed.

To add a PDF viewer widget to a Rich Dialog use the Choose Bean entry from the palette in the Visual Editor. Then choose the ULCVPdfViewer and place it on the Rich Dialog. The widget must be used primarily with a Java API as there is only limited tool support in Axon.ivy, e.g. there is no Drag and Drop of events for the event mapping or there is no widget configuration view.

To open a PDF document, you simply use the method openDocument(java.net.URL). The PDF viewer does support most of the actions that users expect from a PDF viewer like printing, zooming, searching or navigating the document trough the built-in tool bar and status bar. If not required then you can switch off the tool bar and status bar with setToolBarVisible(false) and setStatusBarVisible(false) .

Developers can use the setXyzToolBarVisible() or setXyzButtonVisible() methods to define whether they want that their users can use the corresponding command groups or commands respectively. And end users can customize the tool bar groups and buttons themselves with a popup menu. All these settings are stored when a Rich Dialog is closed and restored at the next start. If you don't want to allow this to your users, then use the method setToolbarPopupMenuVisible().

With the portal display you can create your own portal with Rich Dialogs (from now on called Portlets) . Use the User Dialog Call element to load your Portlets asynchronously into the display exactly like you do with other displays. The display then arranges them in a column layout where the number of columns and the column width ratio can be configured.

The display adds to every Portlet a title bar that offers some generic features. Each Portlet supports off-the-shelf closing, minimizing, maximizing and title renaming. All without adding a single line of code. Furthermore you can Drag and Drop each Portlet in the portal and move it to a new position. The portal supports even two more operations, refresh and handling a configuration dialog for a Portlet. Let's see how these features can be used:

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 it's 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.

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.

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.

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.

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.

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).

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:

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

Configuring Text, Button, Image and Timed Auto-Redirect Links

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).

Configuring a Form Link

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).

Configuring Form Field Details

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 Kind	Image	Description	HTML 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.66. 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.