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:0100_common_props [2026/08/13 00:55] – removed - external edit (Unknown date) 127.0.0.12500_config_apps:0700_add_edit_attributes:0100_common_props [2026/08/13 07:20] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +{{tag>configuration business_object attribute properties}}
 +[<10>]
 +====== Common Properties ======
 +
 +Each attribute of a business object or notification must be assigned a particular type (Plain Text, Number, Date etc). Some properties of the attributes are specific to the assigned type whereas others are common to attributes of all types. Both common and specific properties are specified in the Selection Properties window. When you select the specific attribute its properties are displayed in the window. Which properties are displayed depend on the attribute type. The following section describes properties common to all attribute types.
 +
 +===== Name =====
 +
 +Specify the name of the attribute. The following restrictions apply:
 +
 +  - The name must start with a character (not digit) or underscore symbol. All other symbols in the name must be either characters (including underscore symbol) or digits. No spaces or special symbols are allowed.
 +  - The name must be unique among the names of other attributes of the business object or notification owning the attribute.
 +  - The name cannot be one of the names reserved for system use – ''ID'', ''BASVERSION'', ''BASTIMESTAMP'', ''AccessLevel'', ''LoginName'', ''Password'', ''PersonalSettings''.
 +  - The name cannot be the name of an identifier used in ''SQL'' – ''FROM'', ''SELECT'', ''IN'', ''INTEGER'', ''TEXT'', ''BLOB'', ''CHAR'', ''VARCHAR'' etc.
 +
 +===== Description =====
 +
 +Specify any text that describes what the attribute is for, the business concept that it represents, how it is used etc.  Any description if defined is included into the generated documentation for the business space version – see [[2500_config_apps:3100_gen_doc|Generating Documentation]]. 
 +
 +===== Type =====
 +
 +Any attribute must be assigned a type. Choose the required type from the “Type” combo box. The list of types contains //basic types// (''Plain Text'', ''Number'', ''Date'', ''Timestamp'', ''Yes/No'', ''Binary Data'', ''Document'', ''Picture'', ''Shortcut'') and //reference// types. Reference types include the names of all business objects and business object groups defined in the business space version – see [[2000_concepts:0200_basics:0400_reference_attributes|Reference Attributes]].
 +
 +===== Required =====
 +
 +If you tick the “Required” checkbox //**AwareIM**// will check that there is a non-blank value for the attribute when an instance of the business object that owns the attribute is created or edited. The check will be made irrespective of whether the instance of the business object is created or edited by the user or created/changed by rules. If the value of the attribute is blank the appropriate message will be issued to the user and any currently executing processes or rules will be aborted. If the user is creating or editing an instance of the business object the input control displaying the attribute value will have a red star next to it to indicate that the value of this attribute must be provided.
 +
 +===== Calculated =====
 +
 +If you tick the “Calculated” checkbox the user will not be able to change the value of the attribute – the attribute will be read-only. The value of the attribute can only be changed by rules. This option is not applicable for attributes owned by notifications.
 +
 +===== Initial Value =====
 +
 +Most attribute types allow specifying the initial value of the attribute. The initial value is the value that the attribute is initialised with when an instance of the business object or notification is created. This applies both to business objects created by the user or to objects and notifications created by rules. If the user is creating an object she will see the initial value when the form of the object is displayed. She can then change this value if necessary. Be also aware of the following:
 +
 +  - The type and format of the initial value must correspond to the type of the attribute. 
 +  - Rule expressions are not allowed as initial values (with the exception of expressions that set the current date or time, such as ''CURRENT_DATE''). If the attribute value should be initialised to some expression a rule has to be attached to the business object or notification that owns the attribute – see [[2500_config_apps:0800_add_edit_rules|Adding/Editing Rules]].
 +
 +===== Choices =====
 +
 +Most attribute types allow specifying a number of choices for the attribute value. Choices indicate that the attribute may take values from the specified list. Clicking on the “Choices“ property brings up the “Choices” dialog where you can add or delete choices.
 +
 +If the “Other values allowed” checkbox is unchecked on the “Choices” dialog the attribute may not take any other values. In this case if the attribute value is different from the one specified in choices an error message will be issued to the user and the currently executing process or rules will be aborted. When no other values are allowed an attribute with choices is displayed on the form of the business object as a combo box or as radio buttons. 
 +
 +If the “Other values allowed” checkbox is ticked the attribute may take values different from the ones specified in choices. In this case //**AwareIM**// makes no checks of the attribute value and the list of choices exists purely for convenience of the user. When a form is generated the field is displayed as an editable combo box where you can choose values from the list and also specify other values.
 +
 +It is also possible to specify different values for when a choice is displayed to the user and what is stored in the database. For example, if you have a choice of gender you can display "Male" and "Female" as choices but store "M" and "F" in the database. By default display value is equal to the database value. 
 +
 +It is also possible to use tag expressions as choice values – for example <code aim><<SystemSettings.TaxRate>> </code>
 +
 +  - To add a new choice entry click on the cell in the Choices list box and type in the text of the choice entry. Press Enter to finish. To add another entry click on the next cell and type in the text.
 +  - To modify the existing choice entry click on the cell containing the entry in the Choices list box, modify the text of the entry and press Enter. 
 +  - To delete the existing choice entry click on the cell containing the entry in the Choices list box and press the Delete button located next to the Choices list box.
 +  - To change the order of entries click on the cell containing the entry and press the Up or Down buttons next to the Choices list box.
 +  - If you want to add more blank entries to the list box press the “More Rows” button.
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + The type and format of a choice value must correspond to the type of the attribute.</alert>
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + Choices are not applicable for attributes owned by notifications.</alert>
 +
 +==== Dynamic Choices ====
 +
 +A list of choices can be calculated at run-time rather than explicitly specified by the configurator. When the user clicks on the drop down with choices //**AwareIM**// can dynamically run a query to load the choices into the drop down. This will happen if you select the “Choices are determined at runtime” radio button on the “Choices” dialog. You can specify any existing query that will be run to extract choices or define any custom query. As a convenience option you can also select “Use Existing Attribute Values” radio button. In this case //**AwareIM**// will automatically construct a query that will extract all existing values of the current attribute and present them as choices.
 +
 +==== Allow end users to add and edit choices ====
 +
 +Ticking this checkbox will allow end users to manage the list of choices in the Operation Mode. This may be necessary if the configurator does not know up front the list of choices relevant for a particular end user and he does not want end users to work with the Configuration Tool directly. If this option is on end users of particular access levels (usually the system’s administrator) will see an icon on the object form next to the attribute control. If they click on this icon a window will pop-up where they will be able to add, edit or modify a list of choices.
 +
 +The initial list of choices seen by end users will be pre-populated with the choices entered by the configurator in the Configuration Tool (if any).
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + The option for end users to edit list of choices will not be available if the configurator provides her own list and specifies that “other values are not allowed”.</alert>
 +
 +==== Include empty text====
 +
 +Tick this checkbox to include an empty line into the list of choices to allow the user to select a "blank" value
 +
 +===== Indexed =====
 +
 +This is the database specific option for the advanced users. If the “Indexed” checkbox is ticked //**AwareIM**// will instruct the underlying database system to create an index for this attribute. Creating a database index for the attribute can significantly speed up database queries involving the attribute. If your database is likely to have lots of records of instances of the business object that owns the attribute and end users are likely to frequently perform queries on this attribute you may consider making the attribute “indexed”. The “Indexed” option is not available for attributes owned by notifications.
 +
 +===== Validate as =====
 +
 +This dropdown allows you to select an Input mask that will control how validation of Plain Text attributes is performed. For example, an e-mail address attribute needs to conform to the input standards of the e-mail address, some attributes need to be alphanumeric only etc. When you specify the input mask for the attribute //**AwareIM**// will perform validation of the values entered by the user to make sure that they conform to the requirements of the input mask. There are several pre-defined input masks provided by AwareIM and you can also define your own input masks. The input masks provided by AwareIM are:
 +
 +  - E-mail
 +  - URL
 +  - Alpha (characters only)
 +  - Alphanumeric (characters and digits only)
 +  - US Phone (999) 999-9999
 +If you need to provide an input mask different from the above you can enter a regular expression defining the mask. The regular expression must start and end with the "/" symbol, for example:
 +
 +<code>/\\(?\\d{3}\\)? ?\\d{3}[-.]\\d{4}/ </code>
 +
 +The information about format of regular expressions can be found in the [[8000_appendices:0500_regular_expressions|Appendix E]] or on the following site: [[http://www.regular-expressions.info/reference.html|http://www.regular-expressions.info/reference.html]]
 +
 +If you want to re-use the same regular expression in different attributes you can assign a textual name to your expression. To do this you have to modify the UIConfig.props file located in the BIN directory of your //**AwareIM**// installation to add an entry representing your expression. The entry must start with the “TextInputMask” prefix and contain the name of the expression followed by the “#” symbol and then followed by the expression itself, for example:
 +
 +<code>TextInputMask1=US Phone#/\\(?\\d{3}\\)? ?\\d{3}[-.]\\d{4}/ </code>
 +
 +Once you define your expression in the UIConfig.props file you need to re-start the Configuration Tool and the name of your expression will appear in the “Input Mask” combo box.
 +
 +===== SQL type =====
 +
 +AwareIM automatically manages database for all attributes that the configurator defines, so SQL types of each attribute are usually determined by default. It is, however, possible to specifically indicate an SQL type to be used for a particular attribute, for example:
 +
 +<code>DECIMAL (2,10) </code>
 +
 +===== Attribute Presentation =====
 +
 +All attribute types allow specifying presentation options for the attribute. These options control how the input control displaying attribute value will be generated on a business object form. 
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + Presentation options specified for an attribute will be used by default when the attribute is shown on forms unless a particular form section overrides the default options – see [[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections|Adding/Editing Form Sections]].</alert>
 +
 +The following presentation options are common to many attributes:
 +
 +==== Label ====
 +
 +Specify 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 AccountBalance the default label displayed will be “Account Balance”). You can also indicate an empty label.
 +
 +==== Do not add ‘:’ after label ====
 +
 +By default //**AwareIM**// will automatically add the colon symbol after the label, Ticking this checkbox prevents this and the label is displayed as is.
 +
 +==== Icon ====
 +
 +Specify the icon that will be displayed together with the label next to the input control. By default no icon is displayed. Click on the “Edit” button to specify the icon.
 +
 +==== Description ====
 +
 +If you want to provide the description of the attribute click on the "Description" property to bring up the "Attribute Description" dialog. You can type it in in the "Description" text area. If the "Show description underneath the control" radio button is selected the description will appear underneath the input control representing the attribute on the form (see the "Max Borrow Number" attribute on the picture below):
 +
 +{{  :docs:images:0700_add_edit_attributes_image_5.png?nolink&600  |}}
 +
 +
 +If the "Show description as popup window" radio button is selected, a little icon will be displayed next to the control representing the attribute. When a user moves the cursor over this icon a small popup window containing the text of the description will be shown – see the "Max Renewals" attribute.
 +
 +If the "Show description to the right of input control" radio button is selected the description will be shown to the right of the control – see the "Max Loan Period" attribute.
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + You can enclose attribute description in HTML tags to improve its presentation, for example: <code><p style="color:#ff0000">This description will be displayed in red. </p> </code></alert>
 +
 +==== Save form on selection change ====
 +
 +This option is only valid if an attribute has choices. Ticking this checkbox will make the sure that the form of the object will be saved as soon as the user chooses a different choice in the selection.
 +
 +==== Save form on focus loss====
 +
 +This option is only valid if an attribute does not have choices. Ticking this checkbox will make the sure that the form of the object will be saved as soon as the user moves away from the control representing the attribute.
 +
 +====Widget property (Radio buttons)====
 +
 +For many attribute types there is a "Widget" property that allows you to specify which widget will be used to display the attribute. If an attribute has choices and no other values other than choices are allowed it will be possible to select "Radio buttons" as a widget type. In this case you will also be able to set the "Number of columns" property. 
 +
 +==== Widget property (Checkboxes)====
 +
 +This option is only available for an attribute of the Plain Text type and only if it has choices defined. Selecting this option indicates that the user can choose multiple choices and each choice is represented as a checkbox. Setting details of this option is similar to setting options of radio buttons. 
 +
 +<alert type="primary" icon="fa info-circle">
 +**note**
 +
 + //**AwareIM**// represents selected choices as a single delimited string. You must make sure that the length of the attribute is no less than the string formed as a result of concatenation of all possible choices (in case a user selects all checkboxes) plus delimiters.</alert>
 +
 +==== Input control style ====
 +
 +This property allows you to define styling properties of the input control of the widget – colors, fonts, borders etc 
 +
 +==== Label style =====
 +
 +This property allows you to define styling properties of the label – colors, fonts, borders etc 
 +
 +==== Presentation rules ====
 +
 +This property allows you to define conditions when certain presentation elements are displayed. You need to define a condition and select the type of the presentation element that the condition applies to. Then you need to define properties of the element specific to the selected element type. If a condition is not specified the properties of the element will be applied unconditionally.The following element types are supported:
 +
 +^Setting^Description^
 +|''ICON''|this element type controls how attribute will be displayed in different lists, such as in query results or in reference lists. Instead of displaying a value for the attribute you can display an icon representing the value. For example, you can display different icons for the Balance attribute of the Account object – depending on the value of the balance. You can also display icon only or both icon and value – this is specified when you [[2500_config_apps:1100_add_edit_queries|define a
 + query]] or set up [[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_for_References|Presentation Options for References]]. |
 +|''STYLE''|this element type allows you to specify different CSS style options for particular attributes when they are displayed on forms. By default attributes are displayed using predefined colors, fonts and other properties. The “Style” element type  allows you to override the default settings. For example, you can display account balance in red if its value is less than 50 or in green if it is more than 50. To do this define two styles with different color settings and specify a condition for the first style as <code aim>Account.Balance<=50 </code> and for the second one as <code aim>Account.Balance>50 </code>|
 +|''DISPLAY FORMAT''|this element type allows you to display attributes on forms or inside query results using a different format than the format defined in the attribute itself. This can be especially useful when displaying numbers – you may want to display numbers in different formats on different forms. You can even store the format in an attribute of some object – in this case you should specify a tag expression as the format value, for example <code aim><<SystemSettings.NumberFormat>> </code>|
 +|''LABEL''|this element type allows you to specify different labels for attribute on different forms depending on the conditions. This element type can also be used to display a text on a Google Map marker (see GOOGLE MAPS MARKER type below)|
 +|''ACCESS''|this element type allows you to make an attribute visible or read-only based on a condition. This can be especially useful if you define a presentation rule for an attribute on a particular form – this way you can make attribute visible or read-only on a particular form only|
 +|''REQUIRED''|this element type allows you to make an attribute mandatory based on a condition. This can be especially useful if you define a presentation rule for an attribute on a particular form – this way you can make attribute mandatory on a particular form only|
 +|''INPUT MASK''|this element type allows you to specify an unput mask for entering text attributes on forms, which can be different to the mask defined in the attribute itself. You can even store the input mask in an attribute of some object – in this case you should specify a tag expression as the input mask value, for example <code aim><<SystemSettings.InputMask>> </code>|
 +|''CHOICES''|for attributes that have choices it is sometimes necessary to display a subset of all possible choices on a particular form. This element type allows you to specify exactly which choices will be present on the form|
 +|''GOOGLE MAPS MARKER''|this element type should only be used when the attribute holds the address or coordinates of a Google Map marker. This element type allows you to customize the look and feel of the marker and select from a predefined set of available markers or even use a completely customized marker (for this to work you need to define the marker and put it on the server somewhere where it is accessible via a URL. The URL needs to be provided when defing this element type. You can watch a video tutorial about this here: [[5000_videos:770_google_maps_markers]] |
 +==== Script ====
 +
 +For users who are familiar with Javascript this dialog allows specifying additional attribute configuration parameters when attributes are initialized and displayed. See [[:3500|Programmers Reference Guide]] for more details.
 +