Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
2500_config_apps:0700_add_edit_attributes:0500_ref_attrib [2026/08/13 00:55] – removed - external edit (Unknown date) 127.0.0.12500_config_apps:0700_add_edit_attributes:0500_ref_attrib [2026/08/13 01:10] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +{{tag>configuration attribute reference business_object}}
 +[<10>]
 +====== Setting Properties of Reference Attributes ======
  
 +Reference attributes are explained in detail in the [[2000_concepts:0200_basics:0400_reference_attributes|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 //**AwareIM**// 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:
 +
 +{{  docs:images:reference_grid_with_html_header.png?nolink&600 }}
 +
 +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 [[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_for_References|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 [[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_for_References|Presentation Options for References]]. In the example above the''Edit'' operation represented by the “Edit” button brings up a form of a related business object. 
 +
 +===== Configuring References =====
 +
 +When configuring references the following properties must be specified:
 +
 +===== Multiple allowed =====
 +
 +If this checkbox is ticked the reference represents a “multiple” relationship, otherwise a “single” relationship.
 +
 +===== Matching data =====
 +
 +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. 
 +
 +====Create====
 +
 +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 [[2500_config_apps:0700_add_edit_attributes:0100_common_props|Common Properties]]). If the referred object is a [[2000_concepts:0200_basics:0600_business_object_groups|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.
 +
 +==== Existing ====
 +
 +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. 
 +
 +===== Presentation Options for References =====
 +
 +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. //**AwareIM**// 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 [[.0500_ref_attrib: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:
 +
 +===== Label =====
 +
 +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”).
 +
 +===== Widget =====
 +
 +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.
 +
 +==== Grid widget ====
 +
 +With this widget type referred instances are represented as a standard table (or grid) This is described in the [[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib:0100_table|Displaying References as a Table]] section.
 +
 +==== Drop down widget ====
 +
 +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:
 +
 +==== Fetch records ====
 +
 +Two choices are available – “Fetch all records” or “Fetch records as user types”. You can choose the first option to get //**AwareIM**// 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 //**AwareIM**// 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 //**AwareIM**// 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.
 +
 +==== Empty Text ====
 +
 +If you type any text into this property the drop down will include the specified text when it has no value
 +
 +==== Grouping ====
 +
 +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.
 +
 +==== Mobile style choices ====
 +
 +If this checkbox is ticked the drop down pops up from the bottom of the screen. This is especially useful for mobile applications.
 +
 +==== Save form on selection ====
 +
 +If this checkbox is ticked the form will be saved every time the user selects a value in the drop down 
 +
 +==== Include empty text in choices ====
 +
 +If this checkbox is ticked  //**AwareIM**// 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 
 +
 +==== Page size ====
 +
 +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
 +
 +==== Operations ====
 +
 +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.
 +
 +==== Displayed columns ====
 +
 +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 [[2500_config_apps:1100_add_edit_queries:0200_display_results|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.
 +
 +{{  docs:images:multi_column_dropdown_example.png?nolink&600  }}
 +
 +==== HTML Box widget ====
 +
 +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
 +
 +==== Checkboxes widget ====
 +
 +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.
 +
 +{{  docs:images:checkbox_widget.png?nolink&400  }}
 +
 +The settings of this widget are similar to the “Grid” widget.
 +
 +===== Swap select 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.
 +
 +{{  docs:images:swap_select_widget.png?nolink&400  }}
 +
 +===== Multi-select drop down widget =====
 +
 +This widget is similar to the “multi-selector” widget used for text attributes. See the picture below:
 +
 +{{  docs:images:multi_select_drop_down_widget.png?nolink&400  }}
 +
 +===== Calendar widget=====
 +
 +Choose this widget type if you want references to be displayed in a calendar-like fashion  (see [[2000_concepts:0700_data_presentation:0300_query_results_calendar|Calendar Form of Query Results]]). Note that only references of the [[2500_config_apps:2700_appoint_objects|Appointment]] type can be presented in this manner. The settings you can specify are similar to the ones you specify when configuring a [[2000_concepts:0700_data_presentation:0300_query_results_calendar|Calendar Form of Query Results]].
 +
 +===== Chart widget =====
 +
 +Choose this widget type if you want references to be displayed as a chart (see [[2500_config_apps:1100_add_edit_queries:0200_display_results|Displaying Query Results]]). The settings you can specify are the same as when configuring a chart.
 +
 +===== Custom list widget =====
 +
 +Choose this widget type if you want references to be displayed as a custom presentation of a query (see [[2500_config_apps:1100_add_edit_queries:0200_display_results|Displaying Query Results]]). The settings you can specify are the same as when configuring custom presentation of a query.
 +
 +===== Timeline widget=====
 +
 +Choose this widget type if you want references to be displayed as a timeline of events – see the picture below. See also the [[2500_config_apps:1100_add_edit_queries:0200_display_results:0500_timeline|Displaying Results as Timeline of Events]]
 +
 +{{  docs:images:timeline_widget.png?nolink&600  }} 
 +
 +===== Record sorting/Filtering =====
 +
 +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 
 +
 +<code aim>FIND Account WHERE Account.Status='Open' </code>
 +
 +<callout type="primary" icon="true" title="note"> using different filters you can display different referred instances of the same reference attribute. For example, you could show open accounts of a client on one form section and closed accounts on another form section – see [[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections|Adding/Editing Form Sections]].</callout>
 +
 +====Existing query====
 +
 +If you select the “Existing query” radio button you must select the existing query  (see [[2500_config_apps:1100_add_edit_queries|Adding/Editing Queries]])
 +
 +====Custom query====
 +
 +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 [[2500_config_apps:1100_add_edit_queries|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:
 +
 +{{simplenavi>.:0500_ref_attrib}}