Forms And User Interfaces AwareIM Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Forms And User Interfaces ======

===== How to ... =====

<accordion autoclose>

<anchor id="design_a_form">
<accordion-item title="design a form">
There are three types of forms used in //**AwareIM**//:

==== Object Form ====

This form is used to enter or change values of attributes of a business object. //**AwareIM**// generates the default layout of a form automatically for every business object. You can control how this is done - see the “[[2500_config_apps:0500_add_edit_objects:0200_defining_forms|Business Object Forms]]” section for details.


==== Visual Perspective =====

This form represents a top-level screen that users see when they log into the application. The screen usually contains the system menu, status information, company logo etc. //**AwareIM**// generates the default visual perspective, but you can customize the default perspective and/or supply your own. It is also possible to define several visual perspectives and switch between them. See the “[[2500_config_apps:1500_add_edit_vp|Adding/Editing Visual Perspectives]]” section for details.
</accordion-item>

<anchor id="attach_actions_to_buttons">
<accordion-item title="attach actions to buttons">
===== Object Form =====

Most of the time you do not need to define buttons for object forms. //**AwareIM**// automatically generates the Save and Cancel buttons, that allow submitting or cancelling the changes to the business object, for these forms. //**AwareIM**// also automatically generates the button in the form caption that allow invoking operations with a business object being edited – see the “[[:2500_config_apps:0500_add_edit_objects:0200_defining_forms:0200_form_properties#panel_operations|Panel Operations]]” section for details. You can, however, add your own custom buttons that perform other operations (such as start a process) from a form. To do this you need to define an HTML cell in the form and add an HTML button element that starts a process – see [[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0100_adding_editing_forms|Adding/Editing Business Object Forms]] section (editing of HTML cells).

===== Visual Perspective =====

Usually a visual perspective contains the system menu, which is automatically generated by //**AwareIM**//. You can configure the names of the menu items and the types of operations they invoke as part of the visual perspective configuration. See the “[[2500_config_apps:1500_add_edit_vp:0100_working_with_vp_editor:0500_defining_layout_of_content_panels:1100_setting_menu_item_props|Setting Menu Item Properties]]” section for details.

You can also supply your custom menu instead of getting //**AwareIM**// to generate its own. See [[3400_how_to:0200_forms_and_user_interface]].
</accordion-item>

<anchor id="control_the_order_of_attributes_on_automatically_generated_forms">
<accordion-item title="control the order of attributes on automatically generated forms">
When //**AwareIM**// generates an automatic form for a business object by default it generates controls for all attributes in the order that the attributes have been added to the business object. You can get //**AwareIM**// to generate the controls only for some attributes and specify the desired order of the controls by specifying the attributes and their order and layout in the Form Section Dialog. See the “[[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections|Adding/Editing Form Sections]]” section for details.
</accordion-item>

<anchor id="initialize_form_controls">
<accordion-item title="initialize form controls">
When the user is entering attribute values of a new business object using an object form you can get //**AwareIM**// to initialize controls in the form with some values. In order to do this you need to configure the initial value for the attribute represented by the control you want to initialize. See the “[[2500_config_apps:0700_add_edit_attributes:0100_common_props|Common Properties]]” section for details on how to do this.

If initialization of an attribute depends on some complex conditions you can define a business rule that sets the value of the attribute based on these conditions and declare that this rule should be used during form initialization. See the “[[2000_concepts:0800_data_processing:0100_rule_evaluation:0900_initialization_rules|Initialization Rules]]” section.
</accordion-item>

<anchor id="validate_user_input">
<accordion-item title="validate user input">
Certain validation rules can be specified when you define attributes of an object. For example, you can specify that the attribute may take only certain values (Choice list) or that the attribute value may only be within the given range (Value Range). See the “[[2500_config_apps:0700_add_edit_attributes:0100_common_props|Common Properties]]” for details on how to do this.

If you want more complex validation of the attribute values then you can attach a rule to the object that checks the value of the attribute. Use ''[[ref:a_f:a:report_error|REPORT ERROR]]'' action to indicate the error action. When this action is executed //**AwareIM**// will abort any changes done to the object and display the specified error message to the user suggesting to re-enter the invalid value. For example:

<code aim>IF Client.Spouse IS DEFINED AND Client.MaritalStatus='Single' THEN 
   REPORT ERROR 'Marital status cannot be single when spouse is defined' </code>
</accordion-item>

<anchor id="set_up_custom_form_layout">
<accordion-item title="set up custom form layout">
If you want references of the object to be displayed not on tabs inside the form of the object but as separate panels altogether you can use the ''[[ref:a_f:a:display_layout|DISPLAY LAYOUT]]'' action. 

To use the ''[[ref:a_f:a:display_layout|DISPLAY LAYOUT]]'' action to provide custom layout of attributes and references do the following:

  - Define a process that would show the form of the object (the object should be passed as process input), for example,<code aim>VIEW MyObject</code>
  - Define queries that would show references of the object (the queries should assume that the object is in the context, for example:<code aim>FIND MyReference WHERE MyReference IN MyObject.References</code>
  - Define a visual perspective with a single tab inside the main frame
  - Define content panels of this tab to show a form of the object in one content panel and references of the object in the other content panels. The panel showing the form should use the process defined in 1.; and panels for references should use queries defined in 2.
  - Define a process that would display the layout:<code aim>FIND MyObject WHERE …
DISPLAY LAYOUT MyTab FROM_VP MyPerspective</code>
</accordion-item>

<anchor id="set_up_forms_with_tabs">
<accordion-item title="set up forms with tabs">
If you want to design an object form that has tabs you need to define two or more form sections for the form – every form section will be represented by a tab. The name of the form section will be the name of the tab. You should also set the navigation style of the form to be “Random”. See the “[[2000_concepts:0400_data_entry_and_editing:0200_sections|Form Sections]]”, “[[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections|Adding/Editing Form Sections]]”, “[[:2500_config_apps:0500_add_edit_objects:0200_defining_forms:0200_form_properties#navigation_type|Choosing Form Section Navigation Style]]” sections.
</accordion-item>

<anchor id="use_different_forms_for_different_users">
<accordion-item title="use different forms for different users">
You may want to display the information differently for different users – for example, some information should be visible to some users, but not others. You may also want to display the information using different colors and fonts. //**AwareIM**// allows displaying different forms for different categories of users based on their access level. There are three types of forms used in //**AwareIM**// – object forms, presentations and visual perspectives (see [[3400_how_to:0200_forms_and_user_interface]]). 

===== Object Form =====

When configuring a business object form you can specify the access level(s) that the form will be used for. Therefore if you want //**AwareIM**// to display different forms for users of different access levels you can configure several forms for the business object and specify the access level(s) that each form will be used for. See the “[[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0100_adding_editing_forms|Adding/Editing Forms]]” section for details.

==== Visual Perspective ====

You can specify the access level that the visual perspective will be used for as part of the configuration of the visual perspective. Therefore you can configure different visual perspectives for different access levels. See the “[[2500_config_apps:1500_add_edit_vp|Adding/Editing Visual Perspectives]]” section.
</accordion-item>

<anchor id="show_related_records">
<accordion-item title="show related records">
You can show the values of attributes of the business objects related to a particular business object on the forms or presentations of this object. For example, if a PurchaseOrder object is related to an OrderLineItem object via the multiple relationship you can show which order line items are related to a particular purchase order on the form or presentation of this order.

===== Object Form =====

 //**AwareIM**// will automatically show the related objects on the object form if you include the reference attribute that represents the relationship in the list of attributes to be displayed on the form. You can control how the related objects will be shown – which attributes of the related objects will be displayed, whether they will be sorted etc. See the “[[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_For_References|Presentation Options for References]]” section for details.

Also if an object is related to another object via a single relationship you can display the value of just one attribute of the related object on a form. In order to do this you have to define an attribute of the Shortcut type that will point to a particular attribute of the related object. See the “[[2500_config_apps:0700_add_edit_attributes:0800_shortcut_attrib|Setting Properties of Shortcut Attributes]]” section.

===== Query Results ===== 

To display attributes of related objects on the query results form you have to define an attribute of the Shortcut type that will point to a particular attribute of the related object (see the “[[2500_config_apps:0700_add_edit_attributes:0800_shortcut_attrib|Setting Properties of Shortcut Attributes]]” section) and include this attribute in the list of attributes to be displayed by a query (see the “[[2500_config_apps:1100_add_edit_queries|Adding/Editing Queries]]” section).

===== Presentation =====

To display the values of attributes of the related object on a presentation you have to define a sub-presentation element in your presentation. The sub-presentation element must refer to the presentation of the related object and the query of the sub-presentation element must find the related objects, for example:

<code aim>FIND OrderLineItem WHERE OrderLineItem IN PurchaseOrder.MyLineItems </code>


See also the “[[2500_config_apps:4200_report_designer:0300_edit_elements:1000_edit_subreports|Editing Sub-report/Sub-presentation Element]]” section.
</accordion-item>

<anchor id="choose_values_from_a_list">
<accordion-item title="choose values from a list">
If you want a user to pick attribute values from a list instead of (or in addition to) entering them manually while entering or editing a form of a business object you have to do the following:

  - If the contents of the list are static, i.e. the list always contains the same values, then you have to configure the attribute to have “static” choices and define the values of these choices. While defining choices you can also specify whether other values are allowed or not. See the “[[2500_config_apps:0700_add_edit_attributes:0100_common_props|Common Properties]]” section for details.
  - If the contents of the list are dynamic, i.e. you cannot define the values of the list up-front at the configuration stage, then select the “dynamic choices” radio button and define a query to run to determine choices. Alternatively, the list can represent a related business object and the attribute can be a reference to this business object. For example, if you want a user to choose the type of the car from the list on a form of the ''Car'' object (and you do not know all possible car types at the configuration stage), then you need to configure the ''CarType'' object and get the ''Car'' object to refer to the ''CarType'' object through the reference attribute called ''MyCarType''. Also when defining presentation properties of the ''MyCarType'' attribute you have to specify that the attribute should be represented by the drop down list rather than by the relationship table (see the “[[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_For_References|Presentation Options for References]]” section).
</accordion-item>

<anchor id="set_up_system_menu">
<accordion-item title="set up system menu">
//**AwareIM**// automatically generates the menu for the configured application. The default menu includes very generic operations that allow you to create any business object, run any query or start any process. In most cases you would probably like to customize the generic menu and include the menu items that create specific objects, run specific queries or start specific processes. For details on how to do this see the “[[2500_config_apps:1500_add_edit_vp:0100_working_with_vp_editor:0500_defining_layout_of_content_panels:1100_setting_menu_item_props|Setting Menu Item Properties]]” section. 

You can also provide your custom menu in addition to or instead of the menu generated by //**AwareIM**//. See [[3400_how_to:0200_forms_and_user_interface]].
</accordion-item>

<anchor id="set_up_custom_menu">
<accordion-item title="set up custom menu">
If you do not want //**AwareIM**// to generate the menu for the configured system you can provide your own custom menu (or you can combine both menus). To do this:

  - Prepare your own HTML page with your own menu. The menu should include links invoking //**AwareIM**// operations. The full list of the URL’s corresponding to the //**AwareIM**// operations is provided in the [[8000_appendices:0400_links_to_operations|Appendix D]].
  - Import this page as the Main Page of the visual perspective – see the “[[2500_config_apps:1500_add_edit_vp:0100_working_with_vp_editor:0200_defining_frame_props|Setting Main Page Properties]]” section.
  - If you do not want //**AwareIM**// to generate its own menu, specify that the menu frame should not be present – see the “[[2500_config_apps:1500_add_edit_vp:0100_working_with_vp_editor|Working With Visual Perspective Editor]]” section.
</accordion-item>

<anchor id="customize_colors_and_fonts">
<accordion-item title="customize colors and fonts">
Colors and fonts of your application can be specified when defining visual perspectives. A particular set of colors and fonts is called a “theme”. You can choose different pre-defined themes for your visual perspective. You can also customize a theme by overriding its CSS style settings in your own .CSS file as described here:
[[3400_how_to:0200_forms_and_user_interface]]
</accordion-item>

<anchor id="display_a_hierarchy_of_related_records">
<accordion-item title="display a hierarchy of related records">
You can display related records in a tree-like hierarchical fashion. For example, a design component (DesignComponent object) may consist of sub-components; each sub-component may consist of other sub-components etc. To display a hierarchy of such components in a tree you need to define a reference attribute (called for example, SubComponents) in the DesignComponent object that refers to multiple other components (also DesignComponent object) – see [[3400_how_to:0100_awareim_basics]].

Then open the SubComponents attribute for editing, go to the Presentation dialog and choose “Tree” from the “Display as” drop down. For more details see also the “[[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_For_References|Presentation Options for References]]”.

Another way of displaying a hierarchy is to display a standard grid of parent records first (Query using the Standard form) and then define a query that would show children records for a selected parent. Then set up the parent query to display the children query when a row is expanded (see [[2500_config_apps:1100_add_edit_queries|Adding/Editing Queries]] section). For each children query you can also display an operation to show its children when a row is expanded.
</accordion-item>

<anchor id="display_microsoft_outlook_like_calendar">
<accordion-item title="display Microsoft Outlook-like calendar">
To display your appointments, activities, meeting request in a calendar fashion similar to Microsoft Outlook do the following:

  - Use the "Edit/Add Appointment Object" command in the application menu of the Configuration Tool to add the skeleton of the Appointment object to your configuration. Add your own attributes to the Appointment object if necessary.
  - Define a query that will query on the Appointment object. In the "Display Results" section of the query choose "Calendar" option. The calendar will be shown when the query is run.
  - You can also define a reference attribute that will point to the Appointment object. For example, you can define the Appointments attribute in the Doctor object. Go to the Presentation dialog of this attribute and choose "Calendar" from the "Display As" drop down. The calendar will be shown on the form of the Doctor object.
For more details see "[[2000_concepts:0700_data_presentation:0300_query_results_calendar|Calendar Presentation of Query Results]]" and "[[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_For_References|Presentation Options for References]]".
</accordion-item>

<anchor id="synchronize_with_google_outlook_exchange_and_other_third_party_calendars">
<accordion-item title="synchronize with Google, Outlook, Exchange and other third party calendars">
You can synchronize the appointment records stored in your AwareIM system with third party calendars, for example Google Calendar, Outlook, iCloud and so on. Synchronization with third party calendars in AwareIM is performed using Cronofy API, so before you can use synchronization you need to create an account with Cronofy ([[https://www.cronofy.com/|https://www.cronofy.com/]] ) and create an application for your Cronofy account.  Once you create an application with Cronofy you will be given “Client ID” and “Client Secret”. Write them down as you will need them in AwareIM. You can also see a full list of calendars that are supported at the Cronofy web site.

To support calendar synchronization in AwareIM you will need to do the following:

  - Create a query that will display “Appointment” objects as a calendar (see the previous section
  - Define a Panel Operation for your query. Select the type of the operation to be “Synchronize with Calendar”.
  - Click on the Settings button to define some properties of this operation. You will then need to enter the Client ID and Client Secret that you have obtained from Cronofy.
  - If your “Appointment” object supports “appointment owners” (for example, a list of attendees of an event or a list of people responsible for the task) you can get AwareIM to read the information about event attendees and automatically associate them with objects in your application. To do this:
    - Define an object representing an “event attendee”. 
    - Provide a relationship between an “Appointment” object and the “Attendee” object – it has to be a multiple reference inside the Appointment object
    - When specifying settings of the synchronization operation tick the checkbox that your appointments (events) support attendees.
    - Select the reference attribute defined at b) 
    - Define how AwareIM should map attendees read from a third party calendar to the “attendee” object defined in your application – it can map them by their email address or display name or both.
At runtime the operation will be represented by a button displayed above or below the calendar. When the users press this button AwareIM will ask the user to select the calendar to synchronize with and whether perform a one-way or two-way synchronization. You can perform synchronization multiple times – in this case AwareIM will only deal with changes that happened to occur in both calendars since the time of last synchronization.

Note that there is also a type of Panel Operation that synchronizes with a Google Calendar only. This operation type has now been superseded with a more generic operation and will be eventually phased out. However it can still be used now to synchronize with a Google Calendar.
</accordion-item>

<anchor id="show_records_in_different_colors">
<accordion-item title="show records in different colors">
You can display records in different colors depending on some condition. For example, you might want to show overdue loans of a library member in red while showing non-overdue loans in black. To do this:

  - Open the required reference attribute for editing (for example, “Loans” attribute of the “Member” object) 
  - Go to the Presentation dialog and click on the “Item Rules” button
  - Specify presentation rules using rule table, for example:
<code aim>IF Loan.DueDate < CURRENT_DATE THEN
   Display in red </code>

For more details see the “[[2500_config_apps:0700_add_edit_attributes:0500_ref_attrib#Presentation_Options_For_References|Presentation Options for References]]” section.
</accordion-item>

<anchor id="display_different_icons_for_different_types_of_records">
<accordion-item title="display different icons for different types of records">
You may want to show an icon next to a particular record when a record is displayed in different lists such as results of a query or a list of children on a form of the parent object. You may want to show different icons depending on the value of some attribute in the record – for example, show different icons depending on whether an e-mail is read or un-read. To do this you need to specify “presentation rules” in the presentation of the attribute. The rules specify which icons will be displayed under which conditions – for example if the value of the “State” attribute is “READ” display “read” icon, if the value is “UNREAD” display “unread” icon. Read more about presentation rules in the “[[2500_config_apps:0700_add_edit_attributes:0100_common_props|Common Properties]]” section.
</accordion-item>

<anchor id="display_a_form_of_a_child_object_inside_the_form_of_the_parent_object">
<accordion-item title="display a form of a child object inside the form of the parent object">
Define a reference attribute to the child in the parent object. Go to the Presentation dialog of this attribute, tick “Allow Inline Editing” checkbox, select the “Show Form for Each Row” radio button and then click on the “Details” button to select the form of the child object to be shown.
</accordion-item>

<anchor id="display_attributes_in_different_colors">
<accordion-item title="display attributes in different colors">
If you want to display certain attributes of an object on a form in different colors you can use HTML cells in a form layout and reference an attribute inside the cell. For example, if you want to display attribute “MyAttribute” of the object “MyObject” in red define the following HTML cell in your form layout:

<code html><font color=’#ff0000’><<MyObject.MyAttribute>></font></code>

Note that with the above method you can only show attributes as read-only.

You can also set attribute styles when defining presentation properties of an attribute – see the “Common Properties” section under the “[[2500_config_apps:0700_add_edit_attributes|Adding/Editing Attributes]]” section. With this method the attribute does not need to be read-only. You can set styles for input controls or labels or both. The advantage of this method is that you can define conditions for displaying values and labels in different colors.

If you want to show specific attribute values in different colors in queries you can define styles for the attribute as described above and then indicate that you want to use these styles in a particular query. To do this click on the “Details” button in the Display Results section and then click on the “More” button located next to the attribute entry and tick the “Use Attribute Styles” checkbox.
</accordion-item>

<anchor id="display_attributes_as_read_only">
<accordion-item title="display attributes as read-only">
//**AwareIM**// will automatically display “calculated” attributes and attributes protected by the ''[[ref:a_f:a:protect]]'' rules as read-only, but it will display them in a read-only text box. If you want to get rid of the text box you can use HTML cells in a form layout and reference an attribute inside the cell. For example, if you want to display the attribute “MyAttribute” of the object “MyObject” define the following HTML cell in your form layout:

<code aim><<MyObject.MyAttribute>> </code>

Note that you can also use expressions inside tags and use the HTML tags to display attributes as bold, colored, italicised etc.
</accordion-item>

<anchor id="make_an_attribute_visible_read_only_mandatory_or_display_a_different_set_of_choices_on_a_particular_form_only">
<accordion-item title="make an attribute visible, read-only, mandatory or display a different set of choices on a particular form only">
Normally you define whether an attribute is visible or read-only using dynamic business rules and you define whether an attribute is mandatory by ticking the “Required” property of the attribute. This makes the attribute visible, read-only or mandatory on all forms. There are scenarios, though where you want to make the attribute visible, read-only, mandatory or display a particular set of choices on a particular form only. To do this:

  - Open the form section that has the attribute using the Form Designer
  - Select the required attribute
  - Click on the “Presentation rules” property. 
  - Define the appropriate presentation rule (conditional or unconditional) – select ACCESS as element type to make the attribute visible or read-only (specify this in the Element dialog) or select REQUIRED as element type to make the attribute mandatory or select Choices to display a different set of choices (for an attribute that has choices)
</accordion-item>

<anchor id="implement_wizard_forms">
<accordion-item title="implement “wizard” forms">
For simple “wizard” forms set the Type property in the Navigation section of the property window of the form to “Wizard”. When you do this sections of the form will be traversed in a “wizard-like” fashion. For more complex wizards use “[[2500_config_apps:1600_multistep|multi-step processes]]” – see more details about using wizards in //**AwareIM**// in this video tutorial.

{{page>:5000_videos:590_multistep_processes&inline}}
</accordion-item>

<anchor id="make_your_application_responsive_to_different_screen_sizes">
<accordion-item title="make your application “responsive” to different screen sizes">
 

{{page>:5000_videos:490_responsiveness&noheader&inline}}
</accordion-item>

<anchor id="recalculate_values_in_controls_dynamically_after_a_user_changes_some_values">
<accordion-item title="recalculate values in controls dynamically after a user changes some values">
Sometimes it may be necessary to dynamically recalculate values in controls of a form after a user has changed values in other controls. For example, let’s say we have a form of the object “MyObject” showing 3 attributes – “Value1”, “Value2” and “Sum”. We want to dynamically show the value of the attribute Sum as Value1 + Value2. We want the system to show the sum immediately after the user changes the values of Value1 or Value2. To do this we need to define a business rule:

<code aim>MyObject.Sum = MyObject.Value1 + MyObject.Value2 </code>

This is not different from any other business rule. The trick here is when defining the rule to go to the “Advanced” tab and tick the “Use rule in dynamic recalculation on forms” checkbox. If this is ticked //**AwareIM**// will automatically fire the rule when any field that the rule depends on loses focus, and display the result.
</accordion-item>

<anchor id="show_hide_disable_enable_controls_dynamically_after_a_user_changes_some_values">
<accordion-item title="show/hide/disable/enable controls dynamically after a user changes some values">
This is a variation of the previous item. Sometimes it may be necessary to dynamically show/hide controls on a form after a user has changed values in other controls. For example, let’s say we have a form of the object “MyObject” showing 2 attributes – “Value1” and “Value2””.  Value1 is of the Yes/No type and is shown as a checkbox. We want to dynamically show or hide the value of the attribute Value2 depending on whether the checkbox is ticked. To do this we need to define a business rule:

<code aim>IF MyObject.Value1 = 'No' THEN READ PROTECT MyObject.Value2 FROM ALL </code>

This is not different from any other business rule. The trick here is when defining the rule to go to the “Advanced” tab and tick the “Use rule in dynamic recalculation on forms” checkbox. If this is ticked //**AwareIM**// will automatically fire the rule when any field that the rule depends on loses focus, and show/hide the appropriate controls.
</accordion-item>

<anchor id="start_processes_from_forms">
<accordion-item title="start processes from forms">
It is sometimes necessary to have a button or a hyperlink on a form of the object that starts a process using the current instance of the object as a parameter. To implement such functionality you need to define an HTML cell and place a button or a hyperlink inside this cell (this is explained in detail in the [[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections:0100_defining_form_section|Editing Form Section Layout]] section.
</accordion-item>

<anchor id="show_google_maps">
<accordion-item title="show Google Maps">
You can display Google Maps in the following places in the system:

  - In static HTML of a content panel of a visual perspective
  - In object forms
A Google map shown on a form can only show one address and this address must be stored in some attribute of the object. A Google map shown in a visual perspective can show multiple. Again an object that the query queries on must have the attribute that stores the address to be shown on a Google map.

To define a Google map on a form define a form layout cell of the “Google Map” type – see the “[[2500_config_apps:0500_add_edit_objects:0200_defining_forms:0300_form_add_sections|Editing Form Sections]]” section. 

Defining a Google Map in a content panel of a visual perspective is explained in detail in the “[[2500_config_apps:1500_add_edit_vp:0100_working_with_vp_editor:0400_content_panel_html|Defining Content Panel with Static HTML content]]” section. The look and feel of markers can be customized using presentation rules of the corresponding attribute. This is explained here [[2500_config_apps:0700_add_edit_attributes:0100_common_props]]

You can show colored areas on Google Maps using the so-called “polygon” feature. Each area must be represented as a collection of map points in the KML format. An example of the polygon specified in the KML format is provided here:

[[https://developers.google.com/kml/documentation/kml_tut#polygons|https://developers.google.com/kml/documentation/kml_tut#polygons]]

To display polygon areas on a Google Map you need to do the following:

  - Define a business object representing the area. This object can have any attributes you like, but it must have an attribute that will store the KML representation of the polygon as described in the example above.
  - Define a query that will retrieve instances of this object. Note that:
    - You can define item rules on  this query to specify the background color of the area
    - You can define “Mouse Over” options to specify what happens when the user moves the mouse over the area
    - You can define operations to specify what happens when the user clicks on the area
  - When specifying Google Map options provide the query above and identify the attribute of the “Polygon” object that stores the KML data of the polygon.
Note: Some usages of Google Maps require you to create an account and specify a special key. If you need to provide a key for your Google Maps account you can do this in the predefined ''GoogleMapsKey'' attribute of the ''SystemSettings'' object.
</accordion-item>

<anchor id="show_thumbnails">
<accordion-item title="show thumbnails">
To show pictures as thumbnails you need to have an attribute of the Picture type defined in some business object. Then you can define a query that would show this attribute in the query results. The presentation properties of the Picture attribute allow you to specify scaling options for pictures displayed by queries.

Perhaps a better way to display thumbnails is to use the custom presentation for queries and select the “Thumbnails” data template. This is described in the “[[2500_config_apps:1100_add_edit_queries:0200_display_results|Displaying Query Results]]” section. Using this option you can also display descriptions of the picture underneath or above the picture (or both).
</accordion-item>

<anchor id="create_dashboards_and_allow_end_users_to_customize_them">
<accordion-item title="create dashboards and allow end users to customize them">
To create a dashboard you need to define a visual perspective with at least one tab containing content panels. This is explained in the “[[2500_config_apps:1500_add_edit_vp|Adding/Editing Visual Perspectives]]” section. You can define content panels containing results of queries, processes or HTML. Content panels can be laid out according to one of the available layouts. You can also allow end users to edit the initial layout – switch visibility of individual panels as well as move or resize them. 

{{page>:5000_videos:580_user_defined_dashboards&inline}}
</accordion-item>

<anchor id="implement_item_reordering_within_a_grid_or_custom_query">
<accordion-item title="implement item reordering within a grid or custom query">
//**AwareIM**// supports reordering of items using drag and drop within grids (standard query results) and custom query views (custom query results). 

If you want to support item reordering within grids or custom views you need to define a process that would handle the reordering of the items. When the user performs a “drop” she always does it on some node in the grid or custom view. This node always represents some instance of a business object. We will call it the “drop instance”. The node being dragged also represents some instance of the business object. We will call this instance the “drag instance”.

The process implementing the drop must have the object representing drag and drop instances as its input. Both drag and drop instances will be in the Context of the process. The “drop” instance will always be the first in the Context and can be referred to with the “This” prefix. The drag instance will be the second in the Context and can be referred to with the “That” prefix. The rest is up to the process – it can do whatever it wants with the drag and drop instances. For example, if we are reordering a list of tasks and the Task object has the SequenceOrder attribute defining the order of the task in the list we could write our process to do the following:

<code aim>ThatTask.SequenceOrder = ThisTask.SequenceOrder + 1 </code>

Once you have defined processes to handle item reordering you can start configuring it for those components that need to support it. Go to the “Drag-and-drop/Reordering” property of standard or custom queries, select the “Allow Reordering” radio button and specify the process that handles item reordering.
</accordion-item>

<anchor id="implement_drag_and_drop_between_grids">
<accordion-item title="implement drag-and-drop between grids">
A record can be dragged from one grid represented by a standard query to another grid represented by some other standard query. Note that this will only work if both queries query on the same business object.

In order to support this, you need to define a process that will be run when a record is dropped. For example, if you have a query showing open issues and a query showing closed issues and you drag an issue from the “open issues: grid to the “closed issues” grid a process will need to change the status of the issue to Closed. A record being dragged is automatically given as input to the process, so the process has to declare the Issue object as input and change its status ''Issue.State = 'Closed' ''

You then need to open the “Drag-and-drop/Reordering property of the query, whose records are being dragged and tick the “Allow dragging records of this query” checkbox. Then you need to go to the same property of the target query and tick the “Allow dropping records of the same type” checkbox and then specify the process to be run.
</accordion-item>

<anchor id="use_the_screen_tour_feature">
<accordion-item title="use the “Screen Tour” feature">
The “Screen Tour” feature allows configurators to add explanation to the elements of a form, query or visual perspective, so that the user can understand the screen better. The explanation of the element is displayed to the user at the bottom of the screen with the marker pointing to the element of the screen being displayed. The user can jump between the elements of the screen and //**AwareIM**// automatically scrolls to the element being explained and displays the marker for the element. This section explains how a configurator can add tours to forms, queries and visual perspectives. 

Adding tours to forms and queries is reasonably straightforward. Before you add a tour you need to assign unique “id’s” to the elements that you want to mark on a form or a query. You will then refer to these id’s when you define a tour. You can assign id’s to the form cells, query columns, operations on a form or query, form sections. Just make sure that these id’s are unique within a form or a query. 

Once id’s are assigned you can click on the Tour button on the form or query and define “tour sections”. When you define a tour section you need to provide the id of the element that the section applies to and the explanation of the section. At runtime AwareIM will mark the element identified with the provided id and display an explanation of the element at the bottom of the screen. If an element is a form cell AwareIM will show a marker next to the cell, if it’s a form section //**AwareIM**// will show the marker next to the tab of the section, if it’s an operation it will put the marker next to the button of the operation and so on.

Note that tour sections are ordered – //**AwareIM**// will show the tour by marking the first section and then the user can jump to the next section in the order.

Adding tours to visual perspectives can be slightly more complicated. Just like with forms and queries you can assign unique id’s to the elements of a visual perspectives – tabs and content panels (the latter is done in the Other dialog of the content panel). //**AwareIM**// will then mark the corresponding tabs and panels on the screen. However, visual perspectives can also include forms and queries for which you have already defined their own tours. When defining a tour for a visual perspective you have an option of including these tours in the tour of the visual perspective. In this case refer to the id of the enclosing content panel, tick the “Include tour of the element shown in the content panel” 

Note also that visual perspectives, forms and even queries can include HTML sections. If you want to mark an element inside such an HTML section you can add id to the corresponding HTML element, for example:

<code aim><div id='some unique id'> </code>

You can then refer to this id just like you refer to the id of other elements of the visual perspective. The only difference is that you need to specify this id explicitly rather than choose it in the drop down of the defined id’s.

For an example of using the Tour feature see the Photo Album sample application (visual perspectives for Author and Guest access levels)
</accordion-item>

<anchor id="add_support_for_electronic_signature_to_your_application">
<accordion-item title="add support for electronic signature to your application">
If you want end users to sign electronically using the mouse (or fingers or stylus pens on mobile devices) you can add support for the electronic signature to your applications. To do this you need to add an attribute of the Picture type to one of your objects. An electronic signature will be stored in this attribute as a PNG file. When defining properties of this attribute, tick the “Represents signature” checkbox. When you add such attribute to your form //**AwareIM**// will automatically show a signature component that will allow users to sign electronically.
</accordion-item>

<anchor id="add_right_to_left_support">
<accordion-item title="add right-to-left support">
To enable RTL-support for a user make sure that the value of the RTL attribute in the user is set to Yes. The RTL attribute is a predefined attribute that is added by //**AwareIM**// automatically to all members of the ''SystemUser'' group. You can set the value of the RTL attribute by rules or explicitly from the user interface when the user record is created.
</accordion-item>

<anchor id="embed_video_in_a_form">
<accordion-item title="embed video in a form">
You will need to define an attribute of the Document type in some object and then add an HTML cell to your form with the following contents:

<code aim><div style='width:400px;height:400px'><<MyObject.DocumentAttribute>></div> </code>

The div element is just to give width and height to the video. The actual video is embedded by a reference to the document attribute (''MyObject.DocumentAttribute'')
</accordion-item>

<anchor id="use_css">
<accordion-item title="use CSS">
If you are familiar with the CSS technology then you can customize and enhance the look and feel of your //**AwareIM**// application. You can also improve “responsiveness” of your application by providing media-specific definitions for your screen elements.

//**AwareIM**// lets you assign CSS classes and styles to most of the widgets it uses – grids, calendars/schedulers, forms, visual perspectives, tabs and so on. You can, therefore, use custom fonts, colors, visual effects for specific queries, visual perspectives or forms. In addition you can refer to your specific CSS classes when defining your custom HTML fragments – in forms, in content panels of your visual perspectives, in custom panel headers, etc. See the Sales Portal and CRM sample application for the examples of using CSS classes in an application. Many queries and forms in these applications use custom CSS classes.

You can create one or more CSS files and put your class definitions there. You can then put your file(s) into the ''AwareIM/Tomcat/webapps/AwareIM/Custom/CSS'' folder. Or you can create a sub-folder within this folder and put your CSS file(s) there. The difference is that CSS files placed into the root CSS folder are available to ALL your applications, whereas if you put the file(s) in the sub-folder they become available to a particular application only. In this case you have to make sure that the name of the sub-folder is exactly the same as the name of the corresponding business space.

Placing the files in these folders is all you have to do – at runtime //**AwareIM**// will automatically upload and use the files from these folders.
</accordion-item>

<anchor id="use_icon_fonts_to_display_an_icon_for_a_button">
<accordion-item title="use icon fonts to display an icon for a button">
There are many places in the Configuration Tool that you may need to use icons - when defining "panel" operations or "operations on records", when defining menu commands, tabs and so on. Every time you add an icon you need to specify its properties on the "Icon Settings" dialog. There are two methods of specifying an icon - you can just specify where in the file system the file representing the icon is - the file must be of the image type (png, jpg, gif and so on). The icon stored in the file should be 16 pixels wide and 16 pixels high. If you use this method, you should select the "Icon is represented by a file" radio button and select the icon file in the file system.

More often, though, you will use the second method where you define a CSS class (or classes) that represents the icon. The CSS class you specify in most cases uses a special web font where symbols of the font are represented by icons in a vector format. Because of this, icons are easily scalable, it is easy to change their size or color. AwareIM includes support for two well-known web fonts - "Font Awesome" and "LineIcons". If you want to use these fonts you don't need to do anything else, but if you want to integrate a different font, then you have to modify some of the AwareIM files to achieve this.

If you want to use Font Awesome or LineIcons you should select the "Icon is represented by a CSS class" radio button. If you know the name of the classes, you can just enter them into the text box next to the radio button. Alternatively, you can select the font and click on the "Pick Symbol" link. //**AwareIM**// will display all symbols available in the font, and you can click on the symbol you want. The corresponding classes will be added to the text box. You will see the preview of the symbol. You can change the color and size of the icon and if you are using Font Awesome then you will also be able to specify some icon animation effects and rotate the icon.

By default, //**AwareIM**// comes with the free versions of both Font Awesome and LineIcons. If you want to use the Professional version of both fonts you need to purchase them and install somewhere on the same machine where //**AwareIM**//. Then you need to install them into AwareIM. To do this go to the AwareIM Control Panel and select the "Settings/General" menu item. The "General Settings" dialog will be displayed. Click on the "Install Font Awesome Pro" button or "Install LineIcons Pro" button and then specify the location of the font(s) on your machine. When the installation finishes the Professional fonts will appear in the list of fonts of the "Icon Settings" dialog.

What if you want to use icons from some other font? In this case you need to provide the definition of this font in your own CSS file (see [[3400_how_to:0200_forms_and_user_interface]]). Or you can just add the CSS file provided by the font maker to the ''AwareIM/Tomcat/webapps/AwareIM/Custom/CSS'' folder
</accordion-item>

<anchor id="display_colour_editor">
<accordion-item title="display colour editor">
Sometimes you need to store a colour, which you can edit using a colour editor. To do this define an attribute of the Plain Text type in an object – this attribute will store a textual value of the colour (need about 10 characters). Change the ''Content'' property of the attribute to specify ''Colour''. When you do this the attribute will be displayed using a Colour Picker widget on forms. If this attribute is used in queries it will be displayed as a box with the background colour stored in the attribute. If you want to display textual values go to the ''Display Format'' property of the query column and select ''Text''.
</accordion-item>

<anchor id="let_users_edit_images_stored_in_attributes_of_the_picture_type">
<accordion-item title="let users edit images stored in attributes of the Picture type">
Select the Picture attribute in the list of attributes of the object or on a particular form. Go to the ''Display Settings'' property. Then tick the ''Allow cropping and resizing'' checkbox. After you do this end users will be able to crop and/or resize images stored in this attribute.
</accordion-item>

</accordion>