Form

From Resco's Wiki
Revision as of 16:48, 3 April 2020 by Jzambor (talk | contribs) (Add rich text)
Jump to: navigation, 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 tabs. For example, for a contact, the general tab may contain the name, surname, and primary phone, and a second tab call 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.

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.

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

Designing forms.png

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

  • Properties pane (left) shows properties of the items selected on the Designer pane.
  • Designer pane (center) shows a mockup of the form that you are designing.
    • The right side shows a list of your tabs.
    • Click any tab to display its content in the left side.
  • Fields pane (right) lists items that you can add to the form.
    • If the tab list is selected in the Designer pane, you can add items as another tab.
    • If tab content is selected, you add items to the tab.
  • Additionally, important functions are available in the toolbar (top).

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 of the tab
  • Side – When using the flexible forms, you can place the tab item to the left or right side of the form when viewing the form in full screen.
  • Header – When using the flexible forms, you can set what to display as the form header.
    • Hidden – Header is hidden and only records are shown (no plus, or flip to button is shown as well).
    • Icon & label – Whole header, including the icon and name will be shown.
    • Label – Only the tab name is shown.
  • Width – Normal represents the ordinary size of one tab, Large means that the tab will take size of two tabs.
  • Height – Number of rows that will be visible in the tab item, other records will be available with scrolling.
  • Expand Button –
  • Expanded –

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 a field.

Additional settings for lists:

  • Orientation – Only available for list items and defines whether records are aligned horizontally or vertically. Scrolling also follows this option
  • 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 image items created via Add Image button – these are the actions that app users can do with the picture in the app.

  • Clear
  • Capture Photo
  • Select Photo
  • Select File
  • Load File From
  • View
  • 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.
  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.

What form is used?

You can define multiple forms for any entity. Click Select Form to configure which forms are used in what cases. The logic is defined using script rules, see Rules editor for more information.

Example of a simple select form rule
If Condition Entity.statecode Equals Active
Then Step FormName Assign MyActiveForm
Else Then Step FormName Assign MyInactiveForm

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 fields

You have multiple options for adding fields to the form:

  • Select a field in the Designer pane, then double-click a new field in the Fields 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.
  • Click Add Spacer 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.

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.

Add tabs

Click Add Detail to add a new tab to the form. It will be placed just below the selected tab in the Designer pane. You can rename it; either click Rename or modify the Name parameter in the Properties pane.

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 lists

Click Add List and select related or associated entity from the drop-down list. The tab shows a list of records from the entity. Alternatively, you can drag a list from the Fields pane to the Designer pane. If a specific associated list is missing, make sure 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.

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

Associated tab properties

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.
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.
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.
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.

Add HTML frames

Inline frame is a visual HTML browser window. You can display online or offline content. Click Add IFrame to add it to your form.

  • 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 user the credentials of the current mobile CRM user to authenticate on the web site. This works for Active Directory CRM authentication only.
  • Check Delay Load to load the web site (or offline HTML) when user opens the tab. When disabled, the web site (or offline HTML) loads as soon as the form opens.
  • Visible

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

Add rich text

Click

Add map

Click Add Map and 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.

Add media

Click Add Media to link Notes attachments from the form. By default, 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 configure the status to which the entity record changes when action in the media tab is performed. For example, capturing signature might change the status to signed.
  • As Entity select Note or Cloud Document.
  • As Title enter the subject or title of the note where the file is attached.
  • 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.
Tips

Media added using the Add Media button are treated as a standalone form tab; if you want to add images to an existing tab with other fields, use Add Image 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.

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 Edit to open the command configuration window. See Form commands for additional information.

Additional form components

Add Button
Click to add a new button to an existing tab. Use Button Click to set up the action or command 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

Add 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.
Add Image
Click to include an image to one of the tabs of your form.
Add Chat
If you want to be able to use chat to comment on records, place the Chat Wall as a tab on the form.
Add Hub
Click to include a hub as a tab to your form. Only hubs that include your form's entity can be selected.

Form rules

Many advanced features involve adding business logic to your view. Add scripts to your form, triggered for example when users click a form tab or change a value. See Rules editor and the glossary entry for form rules for more information. Or you can review examples of form rules related to commands.

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 7 version of the app.

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 a field cell (for example 250). In the app, if the available width for your form tab exceeds 500, two fields are displayed in a row; when it's over 750, the maximum, three fields are displayed in a single row.

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.

Auto Grid example configuration.png

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 click Add Table.
  2. On the Properties pane, use the + and - buttons to define the number of columns and rows.
    Table properties.png
    • 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 explicit 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.png
  5. Sample table in the app:
    Grid item example.png