Forms and form pages will be used in many situations in Fabasoft Folio.
Note: The Fabasoft app.ducx user interface language distinguishes two types of forms. The default are forms that consist of one or multiple form pages (form and formpage). This forms can be used for all situations described above. Alternatively there are so called desk forms (deskform) which only define a dataset and can only be used for restricting the lists displayed in explore mode and in the tree view. It is not recommended to use this desk forms anymore.
Syntax |
form reference { |
A form consists of form pages holding the properties that should be displayed. Form pages can either be defined inline or existing form pages can be reused.
The form keyword is used to define a form. It must be followed by a reference and curly braces.
The audience keyword is used to define the target audience of a form. The next table shows the possible values that can be assigned to audience. When audience is not specified implicitly enduser is the target audience.
Audience | Description |
enduser | The form is usable by all users. The ACL COOSYSTEM@1.1:DefaultAdministratorACL is assigned to the form. |
administrator | The form is usable by administrators only. The ACL COOSYSTEM@1.1:DefaultDeveloperACL is assigned to the form. |
Table 11: Audience of a form or form page
When a form is used in a dialog or in the attribute editor (which uses dialogs for reading and changing properties, too) you may define a title for the form, a page headline and a page description. In a confirm dialog only a title and a description will be displayed.
For more information about title, heading and descriptions in dialogs please refer to chapter “Defining the title, a heading and a description of a dialog”.
The property formcaption stores the multilingual text that may be displayed as title. It stores one string for each supported language. An entry in the multilingual files is only generated if explicitly used.
The property formpagelabel stores the multilingual text that may be displayed as name of a tab in multi-tab dialogs or as headline in a single tab dialog. It stores one string for each supported language. An entry in the multilingual files is generated automatically.
The property formpagedescription stores the multilingual text that explains the data shown on the form page in more detail. It stores one string for each supported language. An entry in the multilingual files is only generated if explicitly used.
Example |
userinterface APPDUCXSAMPLE@200.200 form FormInvoice { |
Each form can consist of multiple form pages that can either be reused or defined inside the form block.
The formpage keyword is used to define a new form page inside the form block. For reusing an existing form page, you just need to provide the reference of the form page followed by a semicolon.
The order of the form pages in the form block also determines their order on the form when it is displayed in the user interface.
When enabling the generic view, properties that are not explicitly assigned to a form page are displayed on a system-generated form page. The name of the system-generated form page corresponds to the name of the object class the properties belong to.
To enable the generic view for a form, COOATTREDIT@1.1:formgeneric can be set to true. In this case, it is not necessary to define any form pages as all properties of the object class of the current object are displayed in a generic manner. In the generic view, the order of the properties on the system-generated form page is determined by the object class definition.
When setting inherit to true, the form pages inherited from the base classes are displayed after the form pages defined in the current form.
When setting inheritfrom to a class, the form pages inherited from this class and its base classes are displayed. This setting is evaluated after the property inherit.
Example |
userinterface APPDUCXSAMPLE@200.200 form FormInvoice { formpage PageInvoiceGeneral { formpage PageInvoiceDates { |
A form page is defined in a formpage block that must be nested within a form block. The formpage keyword must be followed by the reference of the form page and curly braces.
A form page consists of a dataset block holding the properties and classes which can be used in the layout definitionto be displayed, an optional layout definition, and some general settings concerning the symbol displayed on the tab and the target audience.
If an existing form page should be reused open the Software Component References folder and select Copy Layout from the context menu of a form page. If the selected form page has no XML layout an error message is shown.
To insert the layout of the selected form page, switch to the form designer and select Paste Layout in the context menu of the destination form page.
The symbol keyword is used to assign a symbol to a form page. The symbol referenced by the symbol assignment is displayed on the tab of the form page.
Note:
As is the case for a form, the audience keyword is used to define the target audience of a form page. For the possible values that can be assigned to audience see chapter “Defining the audience for a form”.
Please note that when a form is presented to an end-user that contains a form page with audience set to administrator, the form page in question is not displayed.
The dataset keyword is used to assign properties or fields to a form page.
All properties displayed on a form page must be listed in the dataset block nested within the formpage block. Semicolons must be used to separate multiple entries.
If a class has been added to the dataset block, all defined properties of only this class can be used in the layout. Inherited properties have to be added explicitly.
Fabasoft app.ducx also allows you to reference fields in the dataset block nested within the formpage block. You may only use fields that have been defined in a fields block using the Fabasoft app.ducx object model language, and each field referenced in the dataset block must be preceded by the keyword field.
Fields may be utilized to temporarily compute values that should not be stored persistently.
The optional get and set keywords allow you to define get and set expressions for calculating the field value. The get expression is evaluated before a field is displayed. The set expression is calculated when leaving the form page displaying a field or when clicking a branch (e.g. Apply).
When a get or set expression of a field is evaluated, the local scope this contains the vApp state dictionary. The global scope ::this contains a dictionary holding the keys listed in the next table.
Key | Description |
root | The root key stores the current object. |
attribute | The attribute key stores the object representing the field. |
parent | The parent key stores the parent object of the current object. |
value | The value key stores the current value of the field. Note: This key is only available for set expressions. |
isedit | The isedit key is true if the field is evaluated on an editable form page. |
isvalue | The isvalue key is true if the field is evaluated on a standard form page, not a form page for a search. |
isdashboard | The isdashboard key is true if the field is evaluated in a dashboard view. |
Table 12: Global scope for get and set expressions of fields
A formpage block can contain an optional layout block that allows you to define a specific layout of controls on the form page.
The layout block contains a list of controls. If controls must be displayed side by side, these controls are grouped together within a row block. You can use the keywords listed in the next table to influence the way the property is displayed and behaves.
Keyword | Description |
rowspan | The rowspan keyword is used to define how many rows the control spans. |
colspan | The colspan keyword is used to define how many columns the control spans (default is four; one column for the label and three columns for the data). |
valign | The valign keyword is used to define the vertical alignment of text within the control (top, middle or bottom). |
halign | The halign keyword is used to define the horizontal alignment of text within the control (left, center or right). |
fontfamily | The fontfamily keyword is used to specify the name of a font family used within a control with a CSS conformant string, i.e.: fontfamily = "verdana, sans-serif". Note: Some controls override the used font, so that this element is ignored. This element is available in Version 2013 Spring Release or later. |
fontcolor | The fontcolor keyword is used to define the color of text within the control (hexadecimal value). |
fontsize | The fontsize keyword is used to define the size of text within the control (pt, px, em). |
labeltext | The labeltext keyword is used to reference a string object that will provide the text of the label. |
labelvisible | The labelvisible keyword is used to define whether the label is visible (true or false). |
labelrowspan | The labelrowspan keyword is used to define how many rows the label spans. |
labelcolspan | The labelcolspan keyword is used to define how many columns the label spans. |
labelposition | The labelposition keyword is used to define the position of the label (top, bottom, left or right). |
labelvalign | The labelvalign keyword is used to define the vertical alignment of a label (top, middle or bottom). |
labelhalign | The labelhalign keyword is used to define the horizontal alignment of a label (left, center or right). |
labelfontfamily | The labelfontfamily keyword is used to specify the name of a font family used for the label text of a control with a CSS conformant string, i.e.: labelfontfamily = "verdana, sans-serif". Note: This element is available in Version 2013 Spring Release or later |
labelfontcolor | The labelfontcolor keyword is used to define the color of the label text (hexadecimal value). |
labelfontsize | The labelfontsize keyword is used to define the size of the label text (pt, px, em). |
detail | The detail keyword is used to define the columns of an aggregate or object pointer list. This can be either a layout block: detail = layout {...} or a reference to form page: detail = PageDetails; Note: Using a form page is available in Version 2017 Summer Release or later. |
simple | The simple keyword is used to define the columns of an aggregate that should be displayed in the simple view for in-place editing. With object pointer lists the columns in the overview are specified. This can be either a layout block: simple = layout {...} This block can specify a filter to be used in the simple view. or a reference to form page: simple = PageSimple; Note: Using a form page is available in Version 2017 Summer Release or later. |
empty | The empty keyword is used to define a cell in the grid layout without content. |
filter | The filter property is used to apply a filter function to an object list property. A filter is an instance of COOSYSTEM@1.1:FilterExpression. |
aggregation | The aggregation property is used to apply a function on a column. Predefined values in Fabasoft Folio are MenuSum, MenuAverage or MenuCount. |
sort | The sort property sorts values in a column of a list. Available modes are up and down. When specifying such a value, a unique index should be set, too. |
group | The group property allows to group values in a column of a list. Available modes are unique, alpha, year, quarter, month, week, day and hour. When specifying such a value, a unique index should be set, too. |
index | The order of grouped and sorted columns is defined by index. This value should always be set when sort or group are specified. |
fixed | The fixed property allows to make a column not horizontal scrollable. There are at least three columns necessary and it will not work on the last two columns. The column index starts with 1. |
width | The width property is used to define the width of a column. There is no measure used. app.ducx removes added measures automatically. |
height | The height property is used to define the height of a column. There is no measure used. app.ducx removes added measures automatically. The height of a row in a detail layout cannot be changed. |
Table 13: Elements allowed within a layout block
A behavior influences the appearance of a property when displayed in a form page. Behaviors defined in the layout overwrite behaviors defined at the property level (see 5.1.3 Defining miscellaneous object class aspects).
Behavior always are expressions which are evaluated to get the desired value. If there are only constants used in the expression, the syntax allows to omit the expression block, resulting in a simple assignment.
Keyword | Description |
visible | The property is only visible in the user interface, if the expression returns true. If the expression returns null or throws an error, the default visibility applies (i.e. invisible defined for the attribute). If a row in the layout does not contain any visible property, the whole row is removed. |
changeable | The property is changeable in the user interface, if the expression returns true. If the expression returns null or throws an error, the default behavior applies (i.e. readonly or readonly(ui) defined for the attribute). |
mustbedef | The property must contain a value, if the expression returns true. If the expression returns null or throws an error, the default behavior applies (i.e. not null defined for the attribute). |
validate | The expression is used to check whether the value entered in the property is valid. If an error occurs when evaluating the expression, this error is shown. If the expression returns false, a standard error is displayed. |
change | If the value of the property gets changed, the expression is executed. If an error occurs when evaluating the expression, this error is shown. The result of the expression is not relevant. |
searchchange | If the value of the property gets changed in context of a search form, the expression is executed. If an error occurs when evaluating the expression, this error is shown. The result of the expression is not relevant. |
accset | The accset property is an expression which returns a list of access types (COOSYSTEM@1.1:AccessType). The current user must have access to the current object via at least one of these access types (based on the ACL evaluation of the Fabasoft Folio Kernel) in order to change the value of this property. |
accsetline | The accsetline property is an expression which returns a list of access types (COOSYSTEM@1.1:AccessType). This expression is evaluated for each line in an aggregate list, so that special access rights can be applied for each line in the list. The current user must have access to the current object via at least one of these access types (based on the ACL evaluation of the Fabasoft Folio Kernel) in order to change the value of the line. |
weight | The value of the weight property is an expression which has to return one of the enumeration values defined in COOATTREDIT@1.1:HighlightType. The weight of a form page element is used to draw the user’s attention to this particular element. |
controlstyle | The value of the controlstyle property is an expression which returns either a list of control styles (enumeration type COOATTREDIT@1.1:ControlStyle) or a control style definition (object of object class COOATTREDIT@1.1:ControlStyleDefinition). If the expression returns null or throws an error, the default behavior applies. A control style definition references specific control styles. The following control styles are supported:
Usage: controlstyle = expression {...} |
controloptions | The value of the controloptions property is an expression, which returns additional options for a control as a dictionary. Please refer to the white paper “Fabasoft Folio Controls” for a description of possible options for specific controls. If the expression returns null or throws an error, the default behavior applies (i.e control arguments specified as parameters to the control or the control arguments specified at the attribute using COOATTREDIT@1.1:attrrepresentation). |
Table 14: Behaviors allowed within a layout block
When one of the abov behavior expressions is evaluated, the local scope this contains the vApp state dictionary. The global scope ::this contains a dictionary holding the keys listed in the next table.
Key | Description |
root | The root key stores the current object. |
attribute | The attribute key stores the object representing the property or field. |
value | The value key stores the current value of the property or field. |
isedit | The isedit key is true if the property or field is evaluated on an editable form page. |
isvalue | The isvalue key is true if the property or field is evaluated on a standard form page, not a form page for a search. |
isdashboard | The isdashboard key is true if the property or field is evaluated in a dashboard view. |
Table 15: Global scope for behavoir expressions
In a row block, the reference of a property or field can be preceded by the reference of a control. The control determines the behavior as well as the look and feel of this property or field.
Table 16 provides a list of available controls. For detailed information on controls and the associated parameters, please refer to the white paper “Fabasoft Folio Controls”.
Control | Description |
COOATTREDIT@1.1:CTRLAcl | This control is used to display and edit access control lists. |
COOATTREDIT@1.1:CTRLAttrpath | This control is used to display a property path. |
COOATTREDIT@1.1:CTRLBase | This control is used for simple data types like integer, float, string and object pointers. |
COOATTREDIT@1.1:CTRLCont | This control is used to upload content. |
COOATTREDIT@1.1:CTRLCurr | This control is used to display and edit currency properties. |
COOATTREDIT@1.1:CTRLDateTime | This control is used to display date and datetime properties. |
COOATTREDIT@1.1:CTRLMLName | This control is used to display and edit multilingual strings (using the compound type COOSYSTEM@1.1:LanguageStringList). |
COOATTREDIT@1.1:CTRLObjNav | This control is used to display and edit an object pointer describing a hierarchical relationship. |
COOATTREDIT@1.1:CTRLPassword | This control is used for entering passwords. |
COOATTREDIT@1.1:CTRLPhone | This control is used to display and edit telephone numbers. |
COOATTREDIT@1.1:CTRLPick | This control is used to display a list of enumeration entries or a list of objects as a group of radio buttons or checkboxes. |
FSCVENV@1.1001:CTRLRating | This control is used to display a star rating. |
COOATTREDIT@1.1:CTRLResearch | This control is used to display the input field for a research term. |
COOATTREDIT@1.1:CTRLStrList | This control is used to display a list of strings in a combo box. |
COOATTREDIT@1.1:CTRLText | This control is used to enable multiline text input for string lists. |
COOATTREDIT@1.1:CTRLTimespan | This control is used to display and edit a time span in days, hours, minutes and seconds. |
COOATTREDIT@1.1:CTRLTimestamp | This control is used to display and edit a time stamp in hours, minutes and seconds. |
COOATTREDIT@1.1:CTRLTree | This control is used to display the tree. |
COOATTREDIT@1.1:CTRLViewCont | This control is used to display content. |
COOATTREDIT@1.1:CTRLXMLAttr | This control is used to display attributes of an XML document. |
FSCDOX@1.1001:CTRLHtmlEditor | This control is used to attach an HTML editor to a string, string list, content or content aggregate. |
FSCSIMLIST@1.1001:CTRLSimList | This control is used to display a simple object list, comparable to the Microsoft Outlook mail-add field. |
FSCVENV@1.1001:CTRLDictionary | This control is used to display dictionaries. |
FSCVENV@1.1001:CTRLInstantiate | This control is used to display the creatable objects and templates in the dialog box displayed when creating a new object. |
FSCVENV@1.1001:CTRLPict | This control is used to display and upload pictures. |
FSCVENV@1.1001:CTRLProgress | This control is used to display a progress bar. |
FSCVENV@1.1001:CTRLRawText | This control is used to transfer the contents of script component objects to the web browser and can be used for injecting HTML code into the current page. |
FSCVENV@1.1001:CTRLURLNav | This control is used to display and edit a URL and can be attached to a string property. |
Table 16: Predefined controls in Fabasoft Folio
The following example demonstrates how to use the form page layout elements discussed in this chapter.
Example |
userinterface APPDUCXSAMPLE@200.200 form OrderForm { formpage OrderGeneralPage { APPDUCXSAMPLE@200.200:ordertotal { |
The following example demonstrates how to define a form page and apply the COOATTREDIT@1.1:CTRLObjNav control to the FSCFOLIO@1.1001:orgindustry property of an organization to allow the user to select an industry from a hierarchical list of industries.
Note: In Fabasoft Folio, industries are represented as instances of object class FSCFOLIO@1.1001:FunctionTerm. The root object for the available industries is FSCFOLIO@1.1001:TermIndustry, where the top-level industries must be referenced in the FSCTERM@1.1001:narrowercompterms property. Subordinated industries must be referenced in the FSCTERM@1.1001:narrowercompterms property of the FSCFOLIO@1.1001:FunctionTerm object describing an industry.
The control parameters Root and Lists of the COOATTREDIT@1.1:CTRLObjNav control must be initialized with the addresses of the corresponding expression objects responsible for determining the root object of the hierarchy and the lists describing the hierarchy. To find out the address of the expression objects, refer to the “Address Assignment” list in the Eclipse Project Explorer.
For detailed information on the control parameters of the COOATTREDIT@1.1:CTRLObjNav control refer to the white paper “Fabasoft Folio Controls”.
Example |
app.ducx Object Model Language objmodel APPDUCXSAMPLE@200.200 // Assuming that APPDUCXSAMPLE@200.200:ExprTermRoot is assigned the address // Assuming that APPDUCXSAMPLE@200.200:ExprTermList is assigned the address return dictionary @treelist = { app.ducx User Interface Language userinterface APPDUCXSAMPLE@200.200 form FormOrgIndustry { formpage PageOrgIndustry { |
Besides properties there are other elements available as row elements:
Example |
app.ducx User Interface Language userinterface APPDUCXSAMPLE@200.200 form FormOrgIndustry { formpage PageOrgIndustry { empty; hrule { colspan = 2; static StrTxt; } row { |
The layout can be defined using the provided graphical form designer. You can switch from the Code pane to the Form Pages pane. The Palette contains all properties that are defined in the dataset.
The form designer provides following features:
Note: Starting with version 18 the form designer generates a quite simple default layout to support the responsive design.
Figure 15: Example of a form page
Syntax |
deskform reference { |
Desk forms are special types of forms, used for displaying object list properties of compound objects in the so called explore view.
For instance, a desk form is used for displaying the object list properties shown in the list view on the right-hand side when you select an instance of object class Person in the tree view of the desk.
The deskform keyword is used to define a desk form. It must be followed by a reference and curly braces.
Inside a deskform block, the audience keyword can be used for defining the audience for a desk form. For further information concerning the audience keyword please refer to chapter “Defining the audience for a form page”.
All object list properties displayed on a desk form must be listed in a dataset block nested within the deskform block. Semicolons must be used to separate multiple entries.
The order of the properties in the dataset block also determines their order on the desk form.
Example |
userinterface APPDUCXSAMPLE@200.200 deskform CustomerDeskForm { dataset { |