Form

From Resco's Wiki
Jump to navigation Jump to search
User interface components

Forms are one of the main components of mobile apps. The main purpose of a form is to display the details of a particular record and allow editing of the record fields.

A single record can have many fields, and sometimes you want to also displayed additional information. For this reason, you can organize information into multiple blocks that we call cards or tabs. For example, for a contact, the "General" tab may contain the name, surname, and primary phone, and a second tab called "Address" shows the postal address. A third tab can show your appointments related to that contact.

Forms are created and managed in Woodford. They are defined within app projects. Each entity has its own forms.

Types of forms

There are two types of forms:

  • Contact information form - read-only; designed for quick access to information (deprecated)
  • Edit form - allows users to create new records and modify existing field values

Contact information form

Warning This type of form is deprecated and no longer available in the current version of Woodford.

You can find the Contact Info section in Contact Information form. There you can determine which information will be displayed in the special Info tab. In this case, it is a summary of the competitor’s information. It contains predefined categories that cannot be edited, so it should be only used for the entities where it will make sense. It is not really a Read-Only form, it is rather a Contact or Quick Info form. The main function of it is to provide a quick direct phone call option or to send an email without the need to open the edit form. You can also add the available fields to the categories (Address, Call etc.). Information on the Contact Info will be displayed without labels.

Other items in the Tabs section on the toolbar provide a way to add the Iframe, Map and Wall objects. You can also add an available associated list or unrelated list (list of records that will not be filtered).

In the Field Explorer you can add associated views of the fields from the entities bound with the foreign key. Also, when you click on the Contact Info form’s designer part, you can see a list of available fields that can be placed on the Contact Info tab.

Contact Information Form can be adjusted by using Offline HTML with Java Script. For more information please check this section of one of our webinars. Webinar

Note If you use flexible forms (new form UI), the Contact Information Form will be automatically disabled and not displayed to users.

Edit form

This is the form described in this article.

Managing forms

Forms are associated with an entity. To see a list of forms for an entity, edit an app project, select the entity, and click Show UI.

On the Mobile Views, Forms and Charts screen, you can add, clone, or remove forms, edit them and change their properties, as well as export them (to a file in XML format) or import them (for example, to a different app project).

Form designer

form designer overview

When you open a form for editing, the form designer opens. The user interface of the form designer is divided into three panes:

  • Properties pane (left) shows the properties of the items selected on the Designer pane.
  • Designer pane (center) shows a mockup of the form you are designing.
  • Tabs / Fields pane (right) lists items you can add to the form.
    • Tabs pane allows adding components that count as tabs, such as map tab, list of related contacts, tree view, ...
    • Fields & Components pane lists various components that you can place on a detail tab, such as entity fields, buttons, variables, ...
Tip Form designer has been updated in release 16.0. Update your Woodford to 16.0 or later to see the new interface described in this article.

Properties pane

Select any item in the Designer pane to display its properties. For some items you can access additional properties using the Properties button on the toolbar.

The following properties can be configured on the Tab level:

  • Name – Label or title of the tab
  • Side – When using the flexible forms, you can place the tab on the left or right side of the screen when viewing the form in full screen. See example.
  • Header – When using flexible forms, select what to display as the form header.
    • Hidden – The header is hidden. Buttons and functions normally located in the header are no longer available (expand/collapse tab, plus button, ...)
    • Icon & title – The whole header, including the icon and name, will be shown. See Form tab icons for more information.
    • Title – Only the tab name is shown.
  • Icon – Select the tab icon.
  • Width – Full-width tab always uses 100% of the panel width. Half-width tabs can be placed next to each other if the screen is wide enough. Applies to flexible forms only.
  • Height
(on list tab) – Number of rows visible on the list; other records are available with scrolling.
(on other tabs) – The height of the tab in pixels (for example, "400px"). If not defined, the height of the tab automatically changes with the number of fields.
  • Expand Button – Show or hide the button that allows users to expand/collapse form tabs.
  • Initial state – A form tab can start either expanded or collapsed.

Additional settings for Auto Grid (display multiple fields in one row):

  • Max Columns – How many fields should be displayed in one row. This is the maximum value, the row may show fewer fields, depending on available space.
  • Min Width – Define in pixels, what is the minimum width of the form to display multiple fields in one row.

Additional settings for lists:

  • Arrange items – Defines whether records are arranged horizontally or vertically. Scrolling also follows this option.
  • Use Home Icon – Use the images from the Home directory as icons. See Form tab icons for more information.
  • Icon Name – Enter a custom icon name (located in the Tabs directory).
  • Binding – For associated lists, it defines the lookup field.

The following properties can be configured on the Field level:

  • Binding – field ID
  • Style – You can select the style that will be used for the selected element. The designer will also preview the selected style. You can also create your own styles or adjust the existing ones using the Edit Styles button in the toolbar.
  • Grid Behavior – When you display multiple fields in one row using Auto Grid, customize the behavior of each field:
    • Normal – Default behavior, this field can be displayed in a row with other fields.
    • Full Width – This field is always alone in a row.
    • Break After – This field can be displayed in a row with other fields, however, it is the last field in the row.

Additional settings for table items created via Add Table button (display multiple fields in one row):

  • Position in table – Select the table cells that the selected item should occupy.

Additional settings for buttons created via Add Button:

  • Button Text – The text on the button.
  • Label – The text on the label. Note that in default styles, button labels are not displayed in the app.
  • Command – You can associate a command with this button.

Additional settings for image items created via Add Image button – these are the actions that app users can do with the picture in the app.

  • Capture Photo
  • Select Photo
  • Select File
  • Load File From
  • View
  • Clear
  • Open External
  • Copy
  • Paste
  • Print
  • Email
  • Resize Image
  • Edit Image

Creating a form

To create a new simple form, proceed as follows:

  1. Select an entity in the Project menu and click Show UI.
  2. Click New Form and name it, then click OK.
    (Change the Template from the default "Standard Form" only if you're setting up the bulk update command. See below for information about the Cache Mode.)
  3. Use the form designer to customize your form: add more fields, add more tabs, add additional objects.
  4. Click Save & Close to save your changes.

Flexible forms versus tabs

Forms in the mobile app can be displayed in two ways:

Tabbed view or classic view
This is the older, original way of displaying forms. Users can see one tab at a time, and they can switch to a different tab by tapping a button in the menu. It is more suitable for smaller screens.
Flexible form or new UI
This is a newer way to displaying forms. All tabs are displayed simultaneously. Tabs can be placed in multiple columns. Tabs can collapsed to show only their header. On smaller screens, users might need to scroll down to see all content.

See Flexible form for more information about enabling and using flexible forms.

Form layout

If you're using flexible forms, you can click the Form Layout button to configure how the form tabs should be organized on the screen. The layout options are described here.

Caching forms

Form caching is a practice in Resco mobile apps that once a form is drawn, for example, to display the details of a particular account record, switching to a different record is fast, the form is reused. Only the data is replaced; tabs that were collapsed stay collapsed, fields that were hidden remain hidden, etc.

The benefits of caching are clear: working with the app is much faster. Problems may occur if you're using (poorly written) business logic that relies on the form being in the initial default state. You can set up form caching on project level in the project Configuration, or you can override this in form properties. The following options are available:

  • Project Default: Respect the global form caching policy.
  • Disable Caching: Disable caching for a particular type of the form - the app always creates a new instance of this form.
  • Force Caching: Enforce caching for a particular type of the form - the app always keeps this type of form in cache and reuses it when opening another entity record.
Note As a general rule, disabling caching is a good solution when you have many visibility rules and your form doesn’t contain many iframes or other types of tabs requiring complex initialization. Another use case is when you don’t expect users to browse through many records in quick succession, e.g., looking for the right order by checking order details by going through the orders list.

Edit styles

To change existing styles or add new styles, select Edit Styles from the toolbar.

The styles are global for all fields on all forms, so if you change a style that is assigned to multiple fields, even to a form on a different entity, these changes are also applied to these fields. It does not matter from which form you open the style editor. Click Dependencies to see all components where a style is used.

See Style editor for more information.

Add form tabs

Form tabs are the main building blocks of forms. The detail tab is primarily used for record fields. Other tab types have a different purpose, for example, a map tab can display the record location on a map. Drag tabs from the Tabs pane to the Designer pane to add them to your form.

add form tabs to form

Detail tab

From the Tabs pane, drag the Detail tab to the Designer pane. On the Properties pane, you might wish to update its name (default = "General") and icon.

The names of tabs, but also other form components, can only include some characters. Certain special characters are not allowed, for example, /\&*<>?:.;. As a workaround, use localization to change the labels of these UI elements. See Localization examples for inspiration.

Add fields

You have multiple options for adding fields to the form:

  • Select a field in the Designer pane, then click a new field in the Fields & Components pane to add the new field just below the selected field.
  • Click Add Field and select a field from the drop-down menu. The field will be added as the last field of the displayed tab.

Inline field actions

Depending on the Formatting of the field configured in entity properties, the appearance of the field on the form can change. For example, if you set Formatting to "PhoneNumber", the form displays a phone icon next to phone number field that allows users to quickly initiate a call.

field formating:field action showcase single line of text formatting options

Formatting can also be used in barcode scanning scenarios and to define dropdown lists.

A similar feature is available on views.

Lookup item properties

When you select a field that serves as a lookup to another entity, you can click Properties (or double-click the field) to access the Lookup Item Properties window.

Lookup Views tab
Select what view(s) are available for this list. You can also filter the values (see Filter editor). In the app, lookup view is displayed as a simple drop-down menu, user can select from the list of records.
Lookup Dialog Views tab
Select what view(s) are available for this list. You can also filter the values (see Filter editor). In the app, lookup dialog is displayed as a new window, user can filter the records, select from the list, or even create a new record.
Properties tab
You can force the lookup dialog view and disable new record creation.

See Advanced filtering for a more detailed explanation about your options for filtering the records in the lookup.

Table

Click to add a table to your form. Tables allow you to display fields in multiple columns. See displaying multiple fields in a single row.

Button

Drag to create a new button to an existing tab.

  • Modify the Button Text property to change the button text.
  • Optionally, set up also the Label property. Usually, extra labels are unnecessary for buttons, and they are hidden by default styles (the style called "Button"; Label position = Hidden).

You have two options for setting up the button action:

  • Use the Command property to select a form command from a list, or enter a command name directly.
  • Alternatively, use Button Click to set up custom action associated with the button. The following example shows or hides the map tab of your form:
If Condition ChangedItem Equals Button_show_hide_map
Then If Condition Tabs.Map.IsVisible Equals True
Then Step Tabs.Map.IsVisible Assign False
Else Step Tabs.Map.IsVisible Assign True

See also the feature introduction. Webinar

Image

Click Image in the Fields & Components pane to add an image to one of the tabs of your form.

Spacer

Click Spacer in the Fields & Components pane to add a horizontal dividing line or separator. Use dividing lines to organize fields into logical blocks. You can add text labels to your separators; select the separator and edit Binding on the Properties pane. This text can even be localized.

Iframe

Inline frames allow you to add HTML content to your form. They can display online or offline content or execute JavaScript code with business logic. From the Tabs pane, drag the Iframe tab to the Designer pane.

  • Enter a Name of the iframe.
  • Enter a URL. You can use the properties of your entity record in the URL, for example, https://www.google.com/search?q={name}.
  • Check Authenticate if you want to use the credentials of the current mobile CRM user to authenticate on the website. This works for Active Directory CRM authentication only.
  • Check Delay Load to load the website (or offline HTML) when users open the tab. When disabled, the website (or offline HTML) loads as soon as the form opens.
  • Clear Visible to make the tab invisible (useful for scripts).

The buttons Browse and Manage are used for offline HTML. Click Manage to upload files, then click Browse to select one of the uploaded files that will be used as the URL. See Offline HTML for more information.

See this blog post for instructions how to add a LinkedIn search to your contacts. Blog

Rich text

  1. From the Tabs pane, drag the Rich Text tab to the Designer pane.
  2. Enter a name (label) of the tab and select a field that you want to edit in an embedded rich-text editor.
    When you first add a rich-text tab to your app project, Woodford prepares the offline HTML files necessary for the editor; this might take several seconds.
  3. In the app, you can edit the text and apply formatting, such as bold or bulleted lists. The result is saved to the selected entity field in HTML format.
Note In order for the RTF editor to work correctly, the field you wish to use with the editor must be also present on the form. It does not have to be visible (you can hide it using rules). However, the field has to be enabled (it can't be set as disabled) in order for your user to be able to utilize the possibilities of RTF editor.

In release 16.0, we have changed how the rich text editor (and process flow) is integrated with the app. Learn the details.

Map

From the Tabs pane, drag the Map tab to the Designer pane. Select the entity parameters for GPS coordinates, then click OK. This will add a map tab to your form.

Note Displaying records on the map usually requires GPS coordinates: latitude and longitude. However, if you only want to display a single location, you can use the street address. The following address fields are used to search for the location: address1_line1, address1_line2, address1_line3, address1_city, address1_country.

In this case, you can leave the latitude and longitude fields blank. This might result in a warning when publishing the project; you can ignore this warning.

Prerequisites for the map, GPS, and geocoding, as well as Update GPS option on custom entity’s form

You need to go through couple necessary steps to be able to see the Update GPS and Update Address command button and use them to assign the current GPS-enabled device’s GPS coordinates (and address based on the GPS position) to entity fields:

  • The entity must have a floating point number fields with names ending with „latitude“ and „longitude“, for example, GPS_coordinates_latitude and GPS_coordinates_longitude; or, as in case of accounts, contacts, and leads, Address1: Latitude and Address1: Longitude.
  • Precision needs to be set to 5 decimal numbers, the maximum value to 180.00000, the minimum value to -180.00000 for the longitude, and maximum value to 90.00000, minimum value to -90.00000 for latitude.

You need to have a detail tab named exactly “Address” on the edit form. It is possible to change this name to any other by using Localization.

If you want to show more than one location for a single entity record (e.g., invoice address and shipping address), you can add map to the form multiple times, each time with different GPS fields.

Hub

Click to include a hub as a tab to your form. Only hubs that include your form's entity can be selected.

Process flow

Click to add a process to your form. Processes guide users through a series of steps. See Process for more information.

Timeline

Click to add a timeline to your form. Timelines display related records from multiple entities in chronological order. See Timeline for more information.

Chatter (Salesforce only)

Click to add a chatter tab to the entity form. Chatter is a real-time collaboration platform. See Chatter for more information.

Tree view

Click to add a tree view to your form. Tree views display records from multiple entities in a tree-like fashion. See Tree view for more information.

Chat

If you want to be able to use chat to comment on records, place the Chat Wall as a tab on the form. See Chat for Dynamics and Resco Cloud.

Media

From the Tabs pane, drag the Media tab to the Designer pane to link Notes attachments from the form. By default, the media tab is set for capturing signatures, but you can set it up for other actions, like capture photo, record video, and more.

  • As Name, enter the label of the tab.
  • As Required for Status, you can select a status. The action in the media tab must be performed before you can change the status and save the record. For example, capturing a signature might be necessary to allow the status signed.
  • As Entity select an entity that can hold binary files, for example annotation/note or sf_contentversion.
  • As Title enter the subject/title of the record where the file is attached. When the app is trying to display the content of a media tab, the title is used to find the image.
  • As Action, select the actions for the media tab: Clear, Capture Signature, Capture Photo, Select Photo, Select File, Record Audio, Record Video, Load File From, View, Open External, Copy, Paste, Print, Email, Resize Image, Edit Image. (Some actions might be unavailable depending on the OS and the capabilities of the device.)
Tips

Media added to the form from the Tabs pane are treated as a standalone form tab; if you want to add images to an existing tab with other fields, use Image from the Fields & Components pane instead.

You can add as many media tabs as you like, each with different options. You can have a dedicated signature tab, a dedicated photo/picture tab, a record tab, etc.

To allow further validation/logic of the Media tab, you can use form rules with powerful options available for the Media tab items.

  • To see it in action, you can watch this part of one of our webinars. Webinar
  • Newer example that allows automatic cropping and resizing of images can be found here.
  • The full list of variables that you can control on a media tab using rules is listed here.

Tagged image

You can display related records as tags on the image. See Tagged image for more information.

Add lists

From the Tabs pane, drag a list to the Designer pane. This tab shows a list of records from the entity. If a specific associated list is missing, ensure that the lookup that defines the relationship is enabled on the child entity. For example, to add a list of associated Contacts on Account entity via lookup parentcustomerid, the field parentcustomerid needs to be enabled on the Contact entity.

Drag Unrelated Entity List... to add a list of unrelated records. You have to select the entity that should be used.

Associated tab properties

associated tab properties on a form
Properties of an associated list

When you select any list and click Properties (or double-click on the list), you can define additional properties:

Associated Views tab, Lookup Views tab
Select what view(s) will be available for this list. You can also filter the values (see Filter editor).
This additional filter will be combined with the filter defined in the view. This can help narrow down the results, e.g. when you want to assign the primary contact to an account and you don’t want to have all contacts listed, you only want to see the contacts that are associated with the account already. You can create a specific filtered lookup view, or in this case, click Edit Filter and add additional condition that will always apply to the primary lookup field.
Charts tab
Select what charts will be available for the flip to chart functionality.
Calendar tab
Set up how the list should look in calendar view: Define parameters such as date range and day filters.
Map tab
Set up how the list should look like in map view:
  • Set Latitude, Longitude, and Zoom to specify the start map location and zoom level.
  • Set Latitude Field and Longitude Field to specify fields of the associated entity that contain GPS coordinates.
  • You can also configure whether to aggregate and expand map pins.
Properties tab
Define actions and controls available in the app.
  • In Actions you define the available actions or commands. On most associated items, you have the options Create New and Add Existing. This defines whether user can only create a new associated record or associate an already existing record by using the plus button on the associated item’s header.
  • In Controls you manage the available options for displaying the associated item’s data. They can be either displayed as list, a Flip to Map view, or a Chart view.
Actions
Create New Open a new form for adding a new record to the list.
Create New Inline Add a new record inline. Requires editable view. Has no effect if Create New is also enabled.
Add Existing Select a record from the list and associate it.
Add Multiple Existing Select multiple records from the list and associate them. This feature is available as long as the parent entity has a single entity as its target.
Actions (for entities that can contain an attachment, such as Note)
Capture Photo Use device camera to capture a photo.
Select Photo Select an existing photo.
Select File Select an existing file. On Windows 7 and Windows 10 versions of the app, this option also allows uploading multiple files.
Record Audio Use device microphone to record an audio message.
Record Video Use camera and microphone to record a video.
Load File From
Paste Paste content that you have copied from another application.
Controls
Allow Search Check to enable search in tabbed form view
Show Search (Flexi Forms) Check to enable search in flexible forms view
Track Form Editable If the form is read-only (for example completed or canceled), the associated list should not allow creating associated records.
Trigger OnChange event Check this option if you want that changes in the related list trigger the On Change event. See the release information for additional details and animated instructions.

A form tab must be loaded before it can trigger events. All form tabs are loaded when using flexible forms.

Show Records as List Clear to disable list view.
Show Records on Map (If GPS fields are configured) Clear to disable map view.
Show Records as Chart (If chart(s) are configured) Clear to disable charts view.
Show Records as Calendar (If Date fields are configured) Clear to disable calendar view.
Initial Control Select which view should be used initially: calendar, chart, list (default), or map.
Auto Refresh
Auto Refresh the list in online mode each X-seconds Should the content of the view periodically reload in online mode and web app?
Interval Define the auto-refresh interval in seconds.

Add commands

Commands are actions available in the app from the form. App users can start the commands from the hamburger menu of the form.

Woodford designers can configure which predefined commands should be available and when, and even define custom buttons. Click Commands to open the command configuration window. See Form commands for additional information.

Form rules

You can use rules, no-code business logic to finetune the behavior of your forms. Find the full list of available rules and triggers on the rules overview page. Some of the most important rules are listed below:

  • Select Form: you can define multiple forms and use Select Form rule to determine which form should be used for a particular record. For example, the form for creating a new record can be quite brief. Once you save your record, the full form is displayed.
  • On Change: executed when any field on the form is modified.
  • On Save: executed when the form is saved.

See Rules editor and the glossary entry for form rules for more information. Or you can review examples of form rules related to commands.

Form tab icons

Each tab on your form can have an icon. This icon is displayed in Woodford and also in the app. To display an icon, select a form tab and on the Properties pane, set Header to Icon & Title.

custom icon for associated lists on forms

You can then use the image picker on the Properties pane to select the icon for your tab. Alternatively, you can even upload your own custom image: click Remove image (this restores the default icon for the tab; the old icon is not deleted) and then click Add image to upload a new one.

Form tab icons are saved as project images in the Tabs directory.

The app uses the following logic to locate the right icon. The first match wins.

  1. When Use Home Icon is:
    • Disabled: Use the icon selected from the image picker.
    • Enabled: Look into the Home directory for an image with a name that matches the entity name. If you rename the tab, use the updated tab name to find the icon.
  2. Look into the Tabs directory for an image with a name that matches the entity name. If you rename the tab, use the updated tab name to find the icon.
  3. Use the default "General" icon.
  4. If you delete that file, use no icon.

Placeholder text

If you want to advise your users what to enter into the field, you can use this feature. Placeholder text is text that’s displayed in an empty field and provides either a hint to users at what to enter into that field, or some specific instructions. Once user taps on the field to enter data there, the placeholder text is cleared.

There are two options for how to enter such text:

  • Use localization to add static placeholder text.
  • Use form rules to add static or dynamic placeholder text.

Using localization

  1. Navigate to Localization on project level or on organization level.
  2. Click Add to add a new string.
  3. As ID, enter <entity name>.<field name>.empty, for example account.address1_city.empty.
  4. As Label, enter the placeholder text, for example Please enter city.
  5. Click OK to save the string.

Using form rules

You can use rules editor to set placeholder text as a static string or even change it dynamically.

In this example, in OnChange rule, the placeholder text for address1_line1 is static, and when user enters data to the address1_line1, the placeholder text for address1_line2 and address1_line3 shows up.

Step Form.address1_line1.PlaceHolderText Assign Enter street here
If Condition Entity.address1_line1 ContainsData
Then Step Form.address1_line2.PlaceHolderText Assign This is optional
Step Form.address1_line3.PlaceHolderText Assign This is also optional

Displaying multiple fields per row

Traditionally, on a form tab, each row is exactly one field. This makes perfect sense on narrow devices and lower resolution displays. However, if your app users are using larger devices with high-resolution displays, such as tablets or a computer, it can be useful to display two or more fields per row. You have two options how this can be configured:

Warning Both features, Auto Grid and Add Table, are not supported on the Windows desktop edition of Resco Mobile CRM.

Auto Grid (property of a tab)

Auto Grid can be particularly useful when your users have a variety of devices and you value flexibility.

Select a form tab, and on the Properties pane, set the maximum number of columns per row (for example 3), and the minimum width of the form (for example 400 pixels). In the app, if the available space (width) for your form tab exceeds 400, two fields are displayed in a row; when it's over 800, the maximum, three fields are displayed in a single row.

Auto Grid configuration example

Additionally, for each field, you can force it to be always displayed as a single row, or disallow any fields after it in a single row. This behavior is controlled by the Grid Behavior property; you can configure it for each field of your tab. You can also insert a spacer to ensure that the next field starts on the left.

display form fields in multiple flexible columns

For more information about automatic grids, see the feature introduction Webinar and blog. Blog

If you want to enable the automatic grid for all forms of your project, go to Woodford Configuration and modify the parameter Auto Form Grid. The default value is 0 (disabled). The Min Width property of your form overrides the general project settings.

Table

To ensure that your fields are displayed exactly as designed, use the Add Table function. You lose some of the flexibility compared to Auto Grid, but the same table is rendered on all devices (except Windows 7, where the table is ignored: one field is displayed per row).

  1. Select a form tab and drag Table from the Fields & Components pane to the tab.
  2. Select the table, and on the Properties pane, use the + and - buttons to define the number of columns and rows.
    table properties
    • Column width: You can specify the width of each column, either a fixed width (in pixels) or flexible width (using stars notation). To increase the width of a flexible column, add a number before the star; a 2* column is twice as wide as a 1* column.
      The maximum width of the table is equal to the width of the form tab. If the table contains at least one column with a flexible width, the width of the table is set to the page width. To calculate the width of flexible columns, we subtract all fixed-width columns from the form tab width and distribute the remainder evenly.
    • Row height: Use Auto for automatic height calculation or enter an exact pixel size.
      The automatic calculation uses the maximal height of the blocks in the table row. That means either the height of text in a particular font or the height of an image (the image height might be scaled automatically to fit into a particular width).
  3. Add fields to the table (make sure they are actually inside the table element).
  4. Select each field and on the Properties pane, select the table cell(s) to define the Position in table. Note that you can click and drag across multiple cells.
    Item position in table
  5. Sample table in the app:
    Grid item example

See also: Form table designer guide Blog