create forms to show and edit
object and link properties

In previous lessons we have seen how to define the context of a web application and create the user menu. In this chapter, we will define the basic element for each Oberon application: the form. The forms can be of two types: those viewing / editing data and those for the selection of filters for searches. Moreover, a form can be applied to objects or links and in these cases it can be used to create new instances or to manage existing ones.
The form defined in Oberon are generic: their actual implementation depends on the type of application it is used. For example, in a web application the form should have a render that fits the context of a web page, while in a desktop application, there will be an engine to make rendering for the used graphical format (for example the eclipse SWT).

Users enabled to manage Forms (see user access rights ) can create a new form instance by clicking the "Add new Form" button from the "Context Design" menu and compile the relative information.

A form consists of general properties and of a set of items; in the first tab you can specify the following options (in addition to the usual "Name" and "Description"):

- the format - is a field where you can introduce optional information to describe the form format; the usage of this field depends on the application's rendering engine. For example, you can define here the default dictionary section where search the label translations or the form style or other custom parameters. The wizard pop-up will help you to compile this field setting the more common options.
- the range program - is a program used to compute the list of values for the form-items. For example, when a form item represents a selection control, the combo options are automatically loaded by executing this program. The same program is executed more times, for each item that requires the computation, so you have to write a program code where the result depends on the form-item (or field) name passed as input.
- the filter parameters - the item visibility depends usually on the object current stage or other object's parameters; with these options you can indicate a list of object's parameters (or the Object_GetBasicOption syntax without the brackets), used to determine if a single item will be showed or not. Indicating the dependencies into this field avoids to recompute the object's parameter values for each item inside the "item-visible " trigger.
- the check program - this program checks the form item values before submit the form. Receiving the values from the framework's environment, the program can examine their validity.
- the action program - this program performs some actions after the form is submitted (used for example to create and connect additional objects or to send notifications).

The second tab let you to specify the form's items. It is an ordered list where you can add, remove, insert into a specific position, or move the items. Each item is characterized by a name (unique), a description and some properties that define its behaviour. In particular:

- type - defines the main characteristic and establishes what the item represents inside the form. You can choose from different types of behaviour:

The "basic", "field", "xfield" and "action" item types can be editable and you can choose for them a control type for the user interface by selecting it from the following list:

- width and height/lines - are the horizontal and vertical dimensions; not all the item types and the control types support these properties. Some controls like "select" and "textarea" consider the height as the number of visible lines/options.
- multiple - is supported only for select controls and establish if you can select multiple options.
- format - is a field where you can introduce optional information to describe the item format; the usage of this field depends on the application's rendering engine. You can use the wizard to set the appropriate value for this field.
- item value - its meaning depends on the item type: for "basic", "(x)field" and "action" it represents the Basic Name, the Field Name and the Parameter Name respectively; for the "get", "getlink", "navigate" represents the OOQL expression to compute the value or the object list; for "section", "button" and "label" it is the showed text; for "href", "img" and "embed" it is the (source) URL; for the "hidden" type is the fixed value passed for the hidden parameter.

As said before, the Format wizard help you to define the item format property. The settings depend on the selected item type and the control type:

- the Layout tab allows to set the main properties like the HTML layout or the tag format; in particular everything you write into the tag format will be reported into the html tag, for example you can set here the html tag attributes "style", "class", etc. For the "navigate" type, this option represents the view name applied to present the navigation result. The other options let you to create the form layout adding the <td> </td> </tr> html tags before and after the element.

- the Labels/Translations tab can be used to specify the dictionary key and section (if not specified will use the form default) for the label translation. You can also indicate if this label is or not placed into a different table cell.

- the Controls tab defines both the item output format and the input format in case of editable control. In particular, you can set the limits for integer, float and string values or set the date format for the date type controls. These settings are important during the form's pre-validation.
In this tab you can also define the control change behaviour; if you set:
° Reload page if value change, this means that every time the user acts on the control and changes the value or the selection, the page including the form will be reloaded and all other control values refreshed. This is useful when you need to show or hide some items on the basis of the item value.
° Refresh form fields if value change, this means that when user change the control value, the other sensible controls will be refreshed without reloading the page (using AJAX).
° Reload values on form refresh, this defines the control "sensible": its value or the list of possible values will be reloaded when another control causes the form refresh.

The search operators can be applied to "text" and "date" controls; if you specify the left (L) [and the right (R) operators] the user will be able to define a range for a search filter. The operator should be separated with comma: for example if you set [==,>=,>] for the (L) and [<,<=] for the (R) the user will be able to select blank, ==, >= and > in the first selector (low limit) and blank, <, <= in the second (high limit).

- the Buttons tab is enabled only for the "navigate" type and let you to choose which buttons will be showed and their related click actions.

The last important aspect we have to focus is the item visibility and/or the item access. We don't want to create a form for each condition or for each user role; the same form can be applied for several usages even if you have to introduce little changes to support different users and system conditions. Oberon lets you to control each form-item visibility/access simply defining access rules for it.

First of all you can set if an item is visible (V) to all users and if it is or not editable (E), required (R) or disabled (D) for everybody. The community flags let you to specify these conditions. Moreover, you can set the access (V,E,R,D) for specific users / teams / assignments; the result for the current user is the logical OR of all conditions (community OR user itself OR team membership OR user assignment ).
Finally, if this is not sufficient you can define the "visible / editable / required / disabled " programs to check the visibility, the editability and the other options. These programs receive, as input arguments, the filter parameters declared in the form properties panel and all the form's current values (set by the user and stored inside the framework environment).
They work in negative logic: they can perform all system queries needed for the checks and can raise exceptions to disable a particular condition. For example, if you want disable the editability for a specific field, you may activate the editable flag for the community and define an "editable" trigger: when the program fails depending on a particular situation, the field will not be editable for the current user.


Form wizard [since 2.4]

Creating a new form can be an annoying activity specially when the form is used to create or edit object instances and you have to define items for each object-class field. The form wizard helps you to create faster this kind of forms (they are the majority): from the navigation tree select the class of object to manage, right click on it and select "Create Form..". This action will open the form wizard tool; here you can specify the name and the type of form to generate (create new object for this class, create with autonumber, edit object instances or search for this kind of objects) and also set a description for the new form. In addition, you can define a more complex form where in a single user interface mask you put fields of secondary classes in a way that, at the same time, on the form submit action, you create instances of main and additional classes and connect them togheter with the specified linktypes.

The second panel lists the fields for the main class, the secondary classes and the fields for the specified linktypes. Here you can choose the item to put inside the form.

In the next panel, additional items like the autoname, basic/hidden parameters and buttons can be selected and configurated:

Finally, in the last panel you can specify main properties for each form item: the item-control type, the editable (E) and the required (R) condition, the multivalue option.

The generated form is ready to be used in a web or a desktop application; secondary class fields and link fields are created as "xfield" items. You can move the items up/down to define the correct order or organize the layout (all items are placed by default on a single column).

When a form involves more than one class, a action program is automatically generated, the aim of this program is:
- create / auto-create forms: generate the object instances of secondary classes, set up their fields, add connection of specified linktype between the main class object and them, set the link fields for the new links.
- edit forms: retrieve the object instances of secondary classes connected with the specified linktype, update the object and link fields for them on the base of input values.

Web forms

The actual implementation of a form depends on the type of application where it is used; in a web application you can create your own JSP page or servlet to generate the HTML code based on the Oberon form definition. The oberon_sample application include the forms.jsp; it is a possible implementation of forms render page. Including this file into your jsp pages you have four static methods to perform the main form manipulation actions:

The forms.jsp page requires the javascript part (forms.js) and the style-sheet (forms.css) to be employed. You can see an example of its usage into the edit.jsp code.

First of all you have to retrieve the object ID from the request and establish if you are using the form for edit or create a new instance. When the ID is null you have to create a new java object instance otherwise you can load the object values from the Oberon DB. The JRClient class provides all method to access to Oberon from jsp pages.



Next you can retrieve the form name from the request; this parameter is mandatory in order to create a new object instance. You can avoid to pass it only if you are using the form to edit an existing instance and the object's class has an associated default form (you can use the loadAdminObject method to read this form name).

The previous parts are required for both the createHTMLForm and saveFormData; you can choose to create two jsp pages for the form presentation and the form action or include both methods into the same page. In this case, first you have to place the saveFormData and then the createHTMLForm. Infact, the saveFormData can recognize if you are loading the page for the first time or if you are loading it to perform the form action. If you are creating a new object instance, the saveFormData result can be the forwardPage URL with appended the new object ID in order to jump to the object visualization/edit page (edit.jsp again but with the object ID in the request).

Otherwise, if you are already in the visualization/edit page the code execution can continue showing the form with object values. The createHTMLForm returns the html code representing the form filled with object values; you can directly put this code into the html response. As we have included both methods into the same page, the action page must be the edit.jsp page.