Setting Properties of Reference Attributes

Reference attributes are explained in detail in the Reference Attributes section.

Entering or editing values of reference attributes on a form of a business object in the Operation Mode is somewhat different to other attribute types.

To provide a value of a reference attribute is to indicate that the instance of the business object being created or edited is related through this attribute to one or more instances of another business object. For example, an Account object can be configured to contain a list of its transactions in a reference attribute called MyTransactions. Thus a particular instance of the Account object can be related to a number of instances of the Transaction object.

To display a value of a reference attribute is to display a list of instances of related business objects (or maybe just some members of this list).

When displaying a form containing reference attributes Aware IM generates the appropriate controls required to display, enter or edit values of such attributes. An example of a reference attribute is shown on the picture below:

The instances of the objects related to the instance currently being edited are shown in a table where each row represents an instance of a related object. Table columns show values of certain attributes of the related objects (which attributes will be shown can be defined at the configuration stage – see Presentation Options for References).

The buttons in the rightmost columns of each row allow performing operations with the related instance represented by a particular row. The list of operations is configurable – see Presentation Options for References. In the example above theEdit operation represented by the “Edit” button brings up a form of a related business object.

When configuring references the following properties must be specified:

If this checkbox is ticked the reference represents a “multiple” relationship, otherwise a “single” relationship.

Click on this property to define relationship type (“Peer”, “Owner of” or “Owned by”) and matching attribute in the referenced object. When defining a matching attribute select the “None” radio button if the reference attribute represents a non-matching relationship; if the reference attribute represents a matching relationship select either “Create” or “Existing” radio buttons.

The “Create” option is available if the new reference attribute is being created or the reference attribute represents the non-matching relationship. Selecting this option will create the matching attribute on the referred business object when changes to the current business object are saved. If you select the “Create” option you must also specify the name of the matching attribute on the referred object (the name must meet the requirements imposed on the attribute names – see Common Properties). If the referred object is a business object group the matching attribute is created for all members of the group. You can also specify whether the matching attribute created will be “multiple allowed” or not.

The “Existing” option is available if the new reference is being created or the reference attribute represents the non-matching relationship and there is an attribute on the referred business object or group that refers to the business object being edited through a non-matching relationship. In this case we are “binding” two non-matching relationships in one matching relationship. As there may be several attributes on the referred object having non-matching relationship with the object being edited you may need to select the attribute you want.

Matching relationships are not applicable to attributes owned by notifications.

For reference attributes presentation options define how instances of the referred object are displayed (if at all) on a business object form. There are several ways the referred instances can be displayed on a form – as a table, as a list (either a combo box for single references or a list box for multiple references), as a tree or as a calendar.

When the referred instances are displayed as a table usually only a few instances (the most significant ones) are displayed on the form. Also, usually values of only certain attributes of the referred instances (the most significant ones) are displayed on the form. To display all attributes of a referred instance the user can press the Edit button next to the referred instance entry in the table to bring up a form of the referred object. Aware IM also provides buttons to add and remove instances of the referred object as well as perform operations with the referred instances. An example of such a table is shown in the working_with_reference_in_the_operation_mode section.

When the referred instances are displayed as a combo box (for single references) or a checkbox list (for multiple references) all instances of the referred object are always displayed. Specific instances that are referred to by the object are selected (only one is obviously selected in a combo box). Therefore this option is only recommended when there are not many instances of the referred object in the system so that all of them will fit into the combo box or the list box. In this case this option is preferable because the user will see all instances she can choose from on the form. For example, a Car object may refer to a CarModel object. There are only a fixed number of instances of a CarModel object so a reference to a CarModel on the form of the Car object may be represented as a combo box.

The details of the presentation options that can be specified on the Presentation dialog for references are explained below:

This is the label that will be displayed next to the input control. By default it will be the name of the attribute (if this name has capital letters they will be replaced with spaces – for example, if the attribute name is AccountReference the default label displayed will be “Account Reference”).

This is is the most important presentation property that determines how the reference attribute will be presented to the user. The choice of the widget depends on whether it is a single or multiple reference attribute. For multiple references possible widget types are

• Grid
• Checkboxes
• Swap Select
• Multi-selector
• Chart
• Custom List
• Timeline or
• Tree

For single references possible widget types are

• Grid
• Combo-box
• Checkboxes
• Tree
• Form

Once you select the widget type you need to provide settinsg of the widget in the “Widget settings” property. Widget settings obviously depend on the selected widget.

With this widget type referred instances are represented as a standard table (or grid) This is described in the Displaying References as a Table section.

This option is only applicable for single references. Choose this widget type to display a referred instance as the current selection in a combo box. The choices in the combo-box display possible other instances to choose from and set as a referred instance. The following properties are available for this widget type:

Two choices are available – “Fetch all records” or “Fetch records as user types”. You can choose the first option to get Aware IM to fill up the combo box with all existing instances of the referred object for the user to choose from. Select this option when there are not too many instances of the referred object in the database.

Choose the second option to get Aware IM to fill up the combo box dynamically. The user will be able to type in values in the combo box. As soon as the user finishes typing Aware IM will fill up the combo box with those instances of the referred object that start with or contain values entered by the user. Select this option if there are a large number of instances to choose from.

If you type any text into this property the drop down will include the specified text when it has no value

Apart from references represented as standard grids this property also applies to Combo-boxes and multi-selectors. It allows grouping of items displayed when a combo-box or a multi-selector pop down to reveal choices. The choices are grouped according to the attribute you specify when selecting this property.

If this checkbox is ticked the drop down pops up from the bottom of the screen. This is especially useful for mobile applications.

If this checkbox is ticked the form will be saved every time the user selects a value in the drop down

If this checkbox is ticked Aware IM will add a blank record (if empty text is defined) or the empty text (if it is defined) into the list of choices. This makes it possible for the user to “clear out” the value

If this property is specified the drop down will display one page at a time, so that the user can choose the page he wants to see. This is useful if the drop down shows large amount of data

You can optionally specify the following operations – Add New Reference, Add Reference, Edit Object, Delete Object and Execute Javascript. The icons representing these operations will be displayed next to the dropdown.

By clicking on this property you can specify which attribute(s) of the referred object will be displayed in the drop down (usually just one). If you select more than one, they will be separated by spaces if you select the Standard style of display (the Standard radio button). If you select this radio button you can also optionnaly specify the custom template with which the data will be displayed - defining this template is similar to defining custom data template for custom query presentation – see Displaying Query Results. The picture of a custom drop down that uses an image, a bold subject on the first line and the description on subsequent line is shown below:

If you select the “Multii-Column” style the combobox will be displayed with the header at the top that will show the names of the columns (just like a standard grid). Here you can also specify the widths of the columns, column labels and even the template of the data display. Displayed columns in a multi-column drop-down can include attributes of the Picture type.

This option is only available for single refereces. Use it if you want to represent the reference as read-only HTML. When specifying HTML you can use tag expressions to refer to the attribute values of the reference, for example <<Account.Customer.Name>>. You can also define operations (Add New Reference, Add Reference, Edit Object, Delete Object and Execute Javascript) – the icons representing operations will be displayed next to the HTML box

Use this widget type if you want references to be displayed as a list of checkboxes. This list shows all possible instances of the referred object and the instances referred to by the attribute are ticked. The option should only be used if the list of all instances is not too large.

The settings of this widget are similar to the “Grid” widget.

This option is similar to the checkbox list in that it shows a list of all possible instances and instances referred to by the attribute. The user moves instances from one list to another – see the picture below. Just like checkbox list this widget should be used only if the list of all instances is not too large.

This widget is similar to the “multi-selector” widget used for text attributes. See the picture below:

Choose this widget type if you want references to be displayed in a calendar-like fashion (see Calendar Form of Query Results). Note that only references of the Appointment type can be presented in this manner. The settings you can specify are similar to the ones you specify when configuring a Calendar Form of Query Results.

Choose this widget type if you want references to be displayed as a chart (see Displaying Query Results). The settings you can specify are the same as when configuring a chart.

Choose this widget type if you want references to be displayed as a custom presentation of a query (see Displaying Query Results). The settings you can specify are the same as when configuring custom presentation of a query.

Choose this widget type if you want references to be displayed as a timeline of events – see the picture below. See also the Displaying Results as Timeline of Events

Using this property you can specify whether referred instances will be sorted or filtered in any way. Clicking on this property brings up the “Record Sorting/Filtering” dialog. The “Record Filtering” section of the dialogallows setting up a filter to show only referred instances that match the specified criteria. You can specify these criteria by specifying a query (either choose the existing query or specify the custom one). For example, it is possible to show only open accounts of a client the query will be

FIND Account WHERE Account.Status='Open' 

If you select the “Existing query” radio button you must select the existing query (see Adding/Editing Queries)

If you select the “Custom query” radio button you must specify the query – press the Edit button located next to this option and specify the query details – see Adding/Editing Queries.

Clicking on the attribute in the “Record Sorting” table allows sorting the list of references by the value of the attribute displayed in the column.

See also: