View

From Resco's Wiki
Revision as of 15:53, 4 March 2020 by Jzambor (talk | contribs) (View designer)
Jump to: navigation, search
User interface components

Views are one of the main components of mobile apps. The main purpose of a view is to display a list of records of a particular entity.

Views are defined within app projects. Each entity has its own views. A single entity can have multiple views.

  • Administrators can create and manage views in Woodford.
  • App users can their own custom views directly in the app. See Private views.

Types of views

  • Public view displays the list of records of an entity.
Example: A list of your contacts.
  • Associated view displays a list of records from an associated entity, that is relevant for the selected item.
Example: A list of appointments of a particular contact.
  • Lookup view displays the list of records of an entity (same as public view), however, it is used when user should select an entity to be inserted into a form.
  • Dashboard view is a combination of multiple views and charts.
Note If a custom associated view, lookup view, or dashboard view does not exist, the public view is used instead.

Managing views

Views are associated with an entity. To see a list of views 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 views, 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).

You can define multiple views for each entity. While you can select an initial default view in the properties of a view, users can switch to a different view in the app. Users may not switch to hidden views; those are displayed only when explicitly configured.

Creating a view

  1. Select an entity in the Project menu; for example, Competitor.
  2. Click Show UI to display the list of mobile views, forms, and charts.
  3. Click New View and set the properties of the view.
  4. Enter a descriptive Name; for example Competitors.
    The name of a view is used as a logical name. Read also the best practices and instructions for renaming views using localization.
  5. As Type, select one of the four view types:
    • Public List displays the list of records of an entity. Usually what you see after opening an entity in application from Home screen. It can be used everywhere
    • Associated List displays a list of records from an associated entity, that is relevant for the selected item. Example: A list of appointments of a particular contact.
    • Lookup List displays the list of records of an entity (same as public view), however, it is used when the user should select a record.
    • Dashboard List is designed for use in a Dashboard.
  6. As Template, select one of the provided templates or use a blank one to start from scratch.
    Keep in mind the limited screen size of a mobile device. We recommend to use templates; adapting is often less work than creating a template.
  7. Select Hidden if you don't want that your new view is listed as an option in the app to users when they switch views. However, the view can still be used in the app when you explicitly design it that way.
  8. Click OK to start designing your view.

When you edit the properties of an existing view, you can no longer change the template (that's only the starting design of a view), but configure additional parameters:

  • Default – Make this view the default initial view. If the default is not set, the first view in alphabetical order is used.
  • Mode – Make this view dedicated for online or offline view, or for both.
  • Sync Filter – Select if you want to use Sync Filter also in online mode for this view.

View designer

The view designer window is divided into multiple parts:

  • Toolbar with buttons on top: Use it to add or remove elements from your view, or configure additional functions.
  • Properties pane on the left shows properties of the selected component in the Designer pane.
  • Designer pane in the center shows a schema of a single row of the view. You can use the slider to zoom in or out; or you can use the mouse wheel. You can also use it to resize fields and move them around.
  • Fields pane on the right shows fields that you can add to the view.

Fields pane

Click Select Fields to display a list of fields defined for this entity.

  • These fields are available for the mobile device, not only for being displayed in the view, but also for sorting and search.
  • Fields that you select will be available in the Fields pane. You can also disable fields that need to be enabled for synchronization, but they do not need to be added to view to make the designer tidier.
  • If you need additional fields, you must enable them on your entity; see App projects#Managing fields for more information.

Designer pane

If you created your new view as described above, your Designer pane will show three cells: one big cell for Name in the top row and two empty cells below. You have two options how to populate the empty cells with fields (or replace field with another one):

  • Select a cell and click Binding on the Properties pane.
  • Double-click a cell.

In both cases, you must select from a list of fields. Click OK to confirm your selection.

Properties pane

The following properties can be configured on View level:

  • Columns: On wider screens, you can display multiple list items in one line. This can be particularly useful for custom rows; for example when you want to create your view as a gallery of images. The value of Columns is the maximum number of records to display in one line; however, fewer records will be displayed on narrow screens.
  • Auto Grid: Enter a value in pixels, for example 500. When the width of the view in the app exceeds 500 pixels, the design changes to a predefined single-row layout.
  • Auto Header: When enabled, it creates a header row above the data rows. The header row allows simple sorting. This parameter affects your current view, but you can also configure the project-wide setting in Configuration, find Auto List Header under User Experience. To learn more, please check this part of a webinar. Webinar

The following properties can be configured on Row level. First, use the drop-down list to select which row you want to modify.

  • Name – Defines the Row’s name (to distinguish between multiple Row designs).
  • Width – Defines the width of the row in a view.
  • Height – Defines the height of the row in a view.
  • Design Size - Allows you to define width and height for different operating systems.
  • Color – Defines the color of the row’s background.
  • Selected – Defines the color of the row’s background, when the record in view is selected.
  • Next Wide – used for custom responsive layout. Multiple rows of various width must be defined and then chained with this setting. Row design will change with resizing of the application. For more information see this blog. Blog

The following properties can be configured on Cell level. First, use the drop-down list to select which cell you want to modify. Alternatively, you can select the cell in the Designer pane.

  • Left, Top, Width, Height – Coordinates of the selected element (field on the row). You can adjust the element size and position either by entering the coordinates or by drag-and-dropping the element and element’s sides in the designer.
  • Kind – Set how the selected element is displayed in the view.
    • Text: Show text as is.
    • Image: When you select a field for which the Kind is changed to Image, the field’s value is taken as the image name. So for example, if you set the status code field as Image, and add the icons of the different status codes to the customization, the icon on the view will change according to the record’s status code. Also, please see the Form Style Editor’s Folder description for more information.
    • Map Pin: When you select a field for which the Kind is changed to Map Pin, the field’s value is taken as the Map Pin image name. So for example, if you set the status code field as Map Pin, and add the icons of the different status codes to the customization, the Map Pin icon on the map view will change according to the record’s status code. See custom map pins for more information.
    • Text-Edit, Text-DirectEdit, Image-Edit, Image-DirectEdit: The element becomes editable directly from the view. See Editable field.
    • Text-Click, Image-Click: Clicking the element opens details about related entity record. See Clickable field.
  • 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.
  • Binding – Please check the following section for more information.
  • Anchor – Anchors fix the boundary position of the field to the side the anchor is pointing to.

Binding

Binding determines which entity field is displayed in a cell. It is actually a combination of two properties: type and value.

Three binding types exist:

  • Value – this is the default option. This way the field data is shown in standard way, so that you can see the value of the field in Mobile CRM app.
  • Raw Value – this makes sense for example for option sets, if you want to display the numeric representation of an option, rather than its label. This is useful, if you don’t want to display text, but different view images, or map pins based on different value of the option set. It is because images cannot have space in their names
  • Constant – this binding type allows you to enter static text. The exact text is displayed in the app, instead of the entity field data. This way you can add labels to views, for example to describe fields that only show numeric values.

Anchors

Each field has four available anchors. Click an anchor to toggle it on and off. Active anchors fix the boundary position of the field to the side the anchor is pointing to. In the case of the picture below, the City field binds to the left border of the view item and to the bottom border of the Name field. When the anchors are set correctly, the view will not be scrambled when users rotate the screen, e.g., from portrait to landscape.

Anchor.png

For more information about anchors, see Advanced tip: Managing cell anchors in views. Blog

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 views, so if you change a style that is assigned to multiple fields, even to a view on a different entity, these changes are also applied to these fields. It does not matter from which view you open the style editor. Click Dependencies to see all components where a style is used.

See Style editor for more information.

Additional configuration

A view can include additional components, not only entity fields. You can also configure how the data should be displayed.

Buttons

You can add buttons to the view. Depending on your device, buttons are displayed when you select a record in the list, or when you swipe from the right.

Buttons must be enabled:

  • Each user can control the behavior in their mobile app, In the app, go to Setup and enable Appearance > List Buttons.
  • In the configuration of a project (while editing an app project in Woodford, select Configuration from Project menu and search for button).

To add buttons to the view, proceed as follows:

  1. Select Buttons from the toolbar.
  2. The right pane shows your available commands, the left pane shows commands in use. Add buttons from right to left.
  3. For some commands you can specify more details, for example what child entity record to create or which status to set for the record. Select the command and click Properties.

Actions when multiple records are selected

Similar to buttons, you can define actions available when you select multiple records in your view. Click Multi Select to set up the actions.

To trigger multi-selection in the map, you need to tap and hold a record in view where at least one MultiSelect button is enabled. Then you can select multiple records and the selected action will be performed on all selected records.

The operation is similar to Form commands. To see how it works, please check this webinar section. Webinar

Edit filter

Edit Filter is used to restrict the displayed data in the view to only those that meet the specified conditions. Conditions are defined using the generic Filter editor user interface.

The difference between Sync Filter and Edit Filter is that the Sync Filter allows the sync only of those fields that meet the conditions, while the Edit Filter works with all fields and only displays those that meet the conditions. This is the perspective of having more views for one entity.

Edit sort

Edit Sort allows you to select which field will be used for sorting and the direction of sorting (ascending or descending).

You can also sort by multiple fields.

Edit search

Click Edit Search to define where (in which field) will the application search for the character entered into the application’s search field. Also, it can be defined whether to search at the field’s beginning, end or in each full text. You can add multiple fields, the conditions are combined using the logical operation OR.

Because the search uses OR, to enable more advanced search, you can create a filter with a condition over a text field (e.g. Name, Title etc.) and enter @@filter@@ as a filtered text. This will be replaced (in runtime) by the text entered into the search field on the view; see example.

If you have fields for GPS coordinates in the entity, and if you enable this option for the mobile project, users will be able to switch the view from list to map; the records will be displayed on the map.

Images and map pins

Click Add Image and select the type of image to add an image to your view. See Add images to views and forms for more information.

Click Add Map Pin to add a map pin image to your view. You can then select many options for the map pins or use custom pins. See Custom map pins for more information.

You can also watch this WEBINAR for more info on Map Pins. Webinar

Sort fields and filter fields

Since version 9.1 of Mobile CRM app, you can set up additional sorting and filtering on view by using the Search bar. In these two view options, you can specify which fields are available to users for this additional sorting and filtering.

Date fields

Click Date Fields to specify which fields that are used as Start and End date fields. This can be useful if you want to allow Calendar view for this entity.

Advanced view features

Many advanced features involve adding business logic to your view. See Rules editor for more information.

Row scripts

You can define multiple row designs for a view, and then you can define conditions when specific row design should be used. In the following example, we will create a second row with red background, this will be used when the field Name does not contain data.

Note Please check this BLOG POST for an additional example of row script use. Blog

Creating a new style with red background

  1. Click Edit Styles to display the Style editor.
  2. Select primary from the style list, and then click Add. This creates a clone of the primary style.
  3. Change the BackColor (background), ForeColor (text color), and rename the style (for example Red Primary).
  4. Click Save & Close to close the styles editor and return to the view designer.

Creating a second row

You have multiple options for creating rows:

  • Click Clone Row to create a copy of the row selected in the Properties pane. Then rename the row, for example to RedRow.
  • Click Add Row to create an empty row, where you can add fields and design it from scratch.
  • You can also click Copy Design to copy the design of any view from any entity.

In the new row, select a cell and change the style from Primary to Red Primary.

Creating a row script

To define when and how the different the row designs are used, you need to set up a row script. Row script is a combination of steps and conditions (what should happen and when).

  1. Click Row Script to open the script editor.
  2. Add the following conditions and steps.
    If entity.name does not contain data
    Then Step TemplateIndex Assign RedRow
    Else Step TemplateIndex Assign Default
  3. Click Save & Close.

Rows and Rules in the upper menu

View upper menu rows rules.png

Rows section
  • Copy Design – changes current row template design
  • Add Row – adds a new row template
  • Clone Row – adds a new row template, design is copied from the current template
  • Delete Row – deletes the current row
  • Up / Down – changes the order of rows. The order can be seen in a left menu under "Row". The first row template is the default one. It is important for example when using the custom responsive layout.
Rules section

Each of these buttons opens the Rules editor.

  • Row Script – opens the row script editor
  • On Save / On Change – opens the rule editor, applicable when Editable field is set.
  • Button Click – opens the rule editor, applicable when using buttons in a view.
  • Cell Click – opens the rule editor, defines actions after clicking on a cell
  • iFrame – adds JavaScript to a view
Warning Do not use Load reference in Row Script, even when it is possible. It does not work and could cause issues.

Changing style on view dynamically

Since version 10.1, there is also a different option in changing the field style on View dynamically, based on its value or other conditions instead of creating a different row design. It is also possible to change the field’s style by using Row Script directly.

To learn more about this approach, please check this part of WEBINAR and HERE to see the setup and see it in action. Webinar

Best practice in renaming a view

Keep in mind that the view name is used as a logical name, so it's used all over the application. If someone changes the name of a view, it can cause issues with the application. Especially if they change the default view names on pre-defined entities.

Views are used in map, calendar, in entities as public, associated, or lookup views. So when the name is changed, you should reset the views on all these places.

It might be easier to use Localization feature to change the display name of a view, while keeping the logical name untouched. To enable this, you need to keep the view names without spaces or special characters. Underscore is okay to use, but the following characters are not: /\%#&*<>?|“+:{}. Also, some national characters and non-Latin characters are not allowed. See Localization examples for inspiration.

Editable field

Editable field, list, or editable grid is a feature that allows users to edit more records at once, directly from the view, without a need to go to edit form of a record.

To set a field to be editable directly in the view, set the field's Kind to one of the edit options:

  • Edit: All changes to this kind of field must be saved. This requires that there's a Save button (only available in the public view - in the list of records accessed from the home screen).
  • DirectEdit: Changes are changed immediately. This can be used also on lookup or associated views that don't have the Save button.

For more information about editable fields, please check this section of one of our webinars. Webinar

Clickable field

Clickable fields allow you to add a hyperlink of a lookup field to a view. When you tap the field, details of the lookup target record open. This can serve as a kind of a shortcut / quick access; for example to the parent account from an opportunity view.

To enable a clickable field on a view, set the field’s Kind to Text-Click or Image-Click.

iFrames

You can use Offline HTML functionality to add JavaScript and JSBridge to views and perform validation; for example when you use the view to change the data (editable fields, MultiSelect), and to handle view buttons. It is also possible to use JavaScript and JSBridge to load records to the view (FetchXML).

For more information about extending views by using this technology, please check the following part of a webinar. Webinar

There are additional validation options, like the possibility for the app to ask whether a change should be saved or discarded, when users edit records on lists;

OnChange and OnSave actions triggering in JavaScript, validations when records are modified or saved directly on a list, etc. can be seen in this webinar. Webinar

Responsive view / list

In order to use larger screens on tablets (or phones with large screens) to their full potential, it is possible to adjust the view design to be more responsive, i.e., to use the screen more effectively.

To learn how it can be achieved, please check the following blog post. Blog

List / view footer

This feature does not require setup in Woodford project. It allows to see some additional information when using multiselect in Resco Mobile CRM app, like number of selected items vs number of all items in the view or setting up the aggregation (e.g. sum of total amount on Opportunity) for selected vs all items in the view.

To learn more, please check this part of a webinar and this part to see it in action. Webinar

Display multiple records in one row

Traditionally, lists show one record per line. However, you can use the Columns property to display multiple records in one row. See the following webinars for more information: webinar 1 and webinar 2. Webinar

Special views

Woodford offers two special views, one for searching, other for filtering. The following applies to special views.

  • To create them, use the Special View button, not New View.
  • Do not rename them; use the default names (SearchView and FilterView).
  • Only one instance of each special view can exist for an entity.

Search view

It is possible to create a specific view used to display search results. The app automatically switches to this view when you are using the search box.

This needs to be a public view named exactly SearchView; it cannot be hidden. You can set up different looks and functionality of this view. To see it in action, please check this WEBINAR SECTION. Webinar

Filter view

Filter view is used when using an inline filter in a lookup form.

Private views

App users can create and manage their own custom views. See Private view for more information.