Picker Control

When using the Picker control, the ability to search for items is available at runtime. Items can be searched for in one of two ways. Using the Resolve function or using the Search function.
When using the Resolve function, follow the steps below and indicated in the image:

1. Type a character or phrase to search for
2. Click the Resolve icon on the right
3. Left-click the character or phrase
4. Select the item from the list

Multiple items can be added if the control was configured as such. An item can also be removed from this menu and the Search function can be accessed from here as well.

When using the Search function, follow the steps below and indicated in the image:

1. Click the Search icon on the right
2. Type a character or phrase to search for
3. Select the item from the list
4. Click Add

Multiple items can be added if the control was configured as such.

An example would look as follows:

1. Create a View
2. Drag the Picker control onto the canvas. The control can be found in the Input section of the Controls found in the View Designer, see the Properties section below
3. Configure the SmartObject under Data Source of the Properties section
4. Configure the rest of the properties as required
5. Run the View

1. The Picker is a multi-value control
2. A menu will appear when clicking on values that do not resolve (search strings that either do not exist or are ambiguous) that displays suggested values (similar to the search string entered)
3. Clicking on the search button will open the Search Modal screen that can be used to search for required information amongst the selected filter properties
4. When using a Transfer data action a delimited list of known identifiers can be transferred to the Picker control
5. Focus can be set to this control at runtime by using the Focus control method in the Rule Designer
6. The Picker control works best with large non-cached / non offline data

The Picker control is available in the Input section of the Controls found in the View Designer and Form Designer.

When clicking on the ellipsis next to SmartObject, the Configure Data Source screen opens. Configure the data source to be used. See the Input Mappings, Filters and Sorting section for more detail.

The option to cache the SmartObject data is available to allow for client side filtering. This is especially useful when using a SmartForm on a mobile device for example and data is required to be available offline. The control's dataset will be populated on initial load, any other changes to the underlying data source's data will not reflect in the current session until another server call is forced to update the dataset. To enable the caching of data, simply select the Cache the data option on the Configure Data Source screen.

How caching is applied

It is important to note that the user is not required to configure anything except selecting the Cache the data option on the Configure Data Source screen to affect caching. The rules are automatically configured by the server. Designers can however remove these rules and place them somewhere else depending on their need. This is just an explanation of how caching is applied by the system.

Following is a diagram with an explanation of how the caching is applied in the background to enable client side filtering.

When selecting the Cache the data option on the Configure Data Source screen, the following two actions are automatically added to the View Initialize event;

• asynchronously load the list control cache with data

and to the Picker is resolving event:
• asynchronously populate the list control with cached data

Example:

• A user accesses a SmartForm on a mobile device.
• When the View initializes, the action to asynchronously load list control cache with data is executed (1 in diagram)
• When the Picker is clicked the action to asynchronously populate list control with cached data is executed (2 in diagram)
• The user is able to select updated data from the Picker on the SmartForm.
• The device goes offline and the user is still able to access the information in the Picker.

How caching is applied with cascading data

If the option to filter according to another control was selected on the Configure Data Source screen together with the cache the data option, the following action is automatically added to the View Initialize event:

• asynchronously load the list control (child control) cache with data
  

and to the when control (child control) is resolving event:
• asynchronously populate the list control (child control) with cached data
  

Considerations

• If the cached data is filtered, the filter can be removed to bring back all the data.
• Additional records added to the dataset will not reflect until cached data is loaded again.

When clicking on the ellipsis next to Method on the Configure Data Source screen, the Populate Picker List Control with Data screen opens. The Picker control's input properties can be set by using fields or parameters. Filters and sorting can also be applied. This screen is the same as is used in the rule when using the resolving event, see the resolving event and method section below.

This feature now allows for cascading picker controls as the input mappings can be set based on the result of another picker control's values.The data in the Picker Control can be filtered according to another control's (Parent Control) value.

Filters and sorting can be applied to the results that will populate the Picker control. It is advised that a very strict filter is set up to limit the number of items used to populate the Picker control with. The Result Limit property of the Picker control is applied to this resultset as well (default is 100). See the Filters and Sorting section for a detailed description and items that need to be considered when applying these.

When configuring data settings through the Method field of the Configure Data Source screen, a resolving event is automatically created to populate the control using these settings. This ensures that the settings are applied each time the Picker control is requesting data at runtime.

Rules can be created to populate the Picker control at runtime. The following rule definition can be used to execute the resolving event and populate the Picker control each time a data request is performed on the control:
Events: When a control raises an event (When Picker is resolving)
Actions: Populate a list control with data (asynchronously populate Picker list control with data)

The feature to allow a filtered dataset to be used to populate the Picker control can also be used without the resolving event.
To use this feature just add the populate action for the Picker control outside of the context of the resolving event. When this action is used without a Picker context then the Picker will be populated with all the results up the resolve limit. This is useful to pre populate a Picker with a list of items using filters /parameters. The following rule definition can be used for example:
Events: When a control raises an event (When Button is Clicked)
Actions: Populate a list control with data (then populate Picker list control with data)

Considerations

• The Populate a list control with data action will:
  • Set the control to a list of selected values if used outside the when the picker is resolving event
  • When used inside the when the picker is resolving event, it is used with additional dynamic filters to retrieve results for the control when the Picker loads or resolves a value. The action can be modified to include standard input properties, parameters and filters that are common for any search (for example a security label)
• The Load a list controls cache with data action will create a data island (cache) which can later be used with the Populate a list control with cached data action.
• The Populate a list control with cached data action behaves like the Populate a list control with data action except that there are no server calls and the data is retrieved from the cache.

The Picker Control has been enhanced with two methods namely the Load and Resolve methods. This functionality can be used to setup parameters and filtering on top of the standard Picker control behavior. The Resolve method will resolve the values as if they had been typed in and will build a query against all the selected filters instead of just on the identifier column. The Load method feature functions the same as a “data transfer” action however it will always fire a change event regardless if the value was changed or not.
The Load method is used for dependent drop-downs (with Picker controls). A rule is automatically configured for the Load method where dependent Picker controls are used.

Data requests can occur in the following instances: 

• On load - The Resolving Event is fired when the Picker control's value is set via a data transfer action or via output mappings in a SmartObject or View method execution or via the Load control method. The picker will use the value transferred to build a filter against the identifier property (only the identifier) to load data. The filter will be an equals filter unless overridden in the web.config (application setting in the web.config file). When using the data transfer rule action, these filters are applied on the identifier property as configured in the data source of the control and only the values of the identifier property will be transferred 
  
  
• On resolve - The Resolving Event is fired when a value is typed into the Picker control at runtime or when the resolve control method is executed. All the configured filter properties will be searched against to get results using a contains filter.
  
• On search - The Resolving Event is fired when a search is executed in the search popup. All the configured filter properties will be searched against to get results using a contains filter. Paging will be applied based on the Page Size property of the control. The SmartObject.RuntimeListViewRowCount setting in the web.config file will be used to show a row count (setting is set to true) or not (setting is set to false).
  

The web.config files can be found in the following locations:
C:\Program Files (x86)\K2 blackpearl\K2 smartforms Designer (Design time)
C:\Program Files (x86)\K2 blackpearl\K2 SmartForms Runtime (Runtime)

The following entry can be found in the web.config file. This entry is used to enable paging and is set to false by default. When changing the value to true, paging is enabled at runtime:

The following entry should be added to the web.config file if a contains filter should be used instead of an equals filter when loading data

This entry should be added in the appsettings node. If this setting is not added, the equals filter will apply by default

In order to save multiple values, the option Save as XML has to be selected in the Details section of the Properties pane. This is however only possible if the backend SmartObject supports delimiters. In the case of CRM this is not possible and therefore the user needs to be familiar with the structure of the SmartObject with which they are integrating.
When selecting the Save as XML option in the properties of the control, the values selected in runtime will be saved in XML format in the database. This is particularly useful when changing controls where both controls are multiple selection controls. The Check Box List control is also a multiple selection control and the values selected in runtime is saved  in XML format to the database. When changing controls between the Check Box List control and the Picker control, they will both be in XML format and no errors will be experienced. If the Picker control is not in XML format, the user will not be able to change the control to a Check Box List control. In the example below, the Mail_groups__xml_ field is saved as XML and the Sales_Regions field is NOT saved as XML.    

Example of when the data is saved as XML in the database:

Example of when the data is NOT saved as XML in the database:
8;4;1;2;3;5;6;14;9;7

When saving to XML, the data stored in XML format in the database can be used again in a Check Box List control a shown below:

 And will be displayed as shown below:

For-Each looping rule conditions are available for use on List Views and list controls. For more information see the Rule Conditions topic.