Configure the Picker

A picker enhances a regular list of values field so that users can quickly find the record they need. Depending on setup, pickers can display either a list of saved searches to pick from, or a list of results most relevant to the user's context. Pickers are already available on certain standard fields and can't be modified, although you can configure new pickers for those fields, if needed. You can also configure pickers for custom list of values fields. Use the cx-picker fragment in Oracle Visual Builder Studio to configure new pickers.

Here's an example of a field without a picker. Without a picker, the field has a button that users can click to view a list of values.

This basic list of values includes the ability to filter on a value that the user enters into the field. For example, if the user enters pi, then a list of accounts whose names include pi display for selection.

This basic filtering functionality is helpful, but the best practice is to add a picker to enable a wider range of search features on a field.

What's a Picker?

A picker is a special kind of search on a dynamic choice list field. With pickers, users can search on more than one attribute of a record, not just on a single attribute. For example, in an Account picker, users can search on account name, address details, and contact name. The screenshot below illustrates a search on city name.

In addition, pickers are more powerful than the standard search on a field because, depending on setup, pickers can display either a list of saved searches or a list of results most relevant to the user's context:

• Saved searches are search filters that are predefined for an object. You (and end users) can define new saved searches, if needed.

  If the picker is configured to display a list of saved searches, then the user can apply a saved search at runtime to filter the records available to search and thus more quickly find the right record to select.

  Here's an example of a picker with a list of saved searches:

  

  At runtime, the picker displays the records based on the default saved search enabled for that object or the last saved search that the user selected.

• If the picker is configured to display a list of results most relevant to the user's context, then when the user opens the list of values, they will see records that are related to their current context in some way.

Picker Example Scenario

This topic illustrates a picker configuration example. In this example, we'll add an Account picker to a Create Payment page so that users can search for and associate an account with a payment record.

In this example, you'll do the following:

1. In Application Composer, create a custom dynamic choice list field.

2. In Visual Builder Studio:

   1. Add the dynamic choice list field to a page layout.

   2. Associate the field with a field template that uses the picker fragment.

   3. Configure the picker layout.

Prerequisites

Before creating the custom Account field, you must:

1. Complete the Adaptive Search setup, if working with a custom object.

   If you're configuring a picker for a field on a custom object, then make sure that you've enabled the custom object for Adaptive Search. The operation of a picker depends on what's already set up in Adaptive Search.

   A picker searches against all Adaptive Search fields that are enabled for keyword search. To enable additional attributes for search, see Make a Field Searchable in the UI in the Adaptive Search and Workspace chapter in the Oracle Fusion Cloud Sales Automation Implementation Reference guide.

2. Create your own workspace in Visual Builder Studio if you don't yet have one.

   If you're configuring a picker for a custom dynamic choice list field that's not yet published, then make sure your workspace is associated with your Cloud Applications sandbox.

3. Add the Common Application Components dependency to your workspace.

   To add a dependency, click the Dependencies side tab in Visual Builder Studio.

   Use the search field to find the Common Application Components dependency and then click Add.

4. This example assumes that you've got a custom Payment object with pages already configured in Visual Builder Studio.

   You can use the CX Extension Generator to set this up quickly. See Create a New Application Using the CX Extension Generator.

1. Create the Custom Dynamic Choice List Field

To get started, create a custom dynamic choice list field on a custom object, Payment, in Application Composer. This dynamic choice list field displays account records.

Note: Creating a custom field is a data model change. Create all data model changes in Application Composer before creating application extensions in Visual Builder Studio. You don't have to publish your sandbox before working in Visual Builder Studio, however, since your workspace is associated with your current sandbox.

To create the custom dynamic choice list field:

1. Ensure you're in an active sandbox.

2. In Application Composer, navigate to the Payment object > Fields node.

3. Create a custom dynamic choice list field with these values:

   Field	Value
   Display Label	Account
   Name	Account
   Related Object	Account
   List Selection Display Value	Organization Name

Tip: In Application Composer, you can optionally add a filter to the dynamic choice list field to constrain the values that users see in the picker. For example, you might want the picker to display only accounts that are based in a specific country or city. Adding a filter means that the picker won't display the list of saved searches to users. Also, if you add a filter to the field in Application Composer, then you must publish your sandbox so that the filter works correctly at runtime.

When you create a dynamic choice list field in Application Composer, two fields are created.

• One field is for use with standard, non-Redwood Oracle applications. The naming convention for this standard field is customfield_c.

  In this example, the Account_c field is automatically created. You can see and modify this field in Application Composer and Visual Builder Studio.

• One field is for use with Redwood Sales. The naming convention for this standard field is customfield_Id_c.

  In this example, the Account_Id_c field is automatically created and displays in Visual Builder Studio only. This is the field that you add to Redwood Sales page layouts.

You can now add the Account_Id_c field to a page layout in Visual Builder Studio. We'll do that in the next section.

2. Add the Field to a Page Layout

Let's add your custom field to a page layout. In this example, we'll add the field to a create page. Typically, you would also add the field to an edit page.

1. In the Redwood user experience of Sales, navigate to the page that displays the area you want to extend. In this example, navigate to the Payments list page.

2. Under the Settings and Actions menu, select Edit Page in Visual Builder Studio.

   

3. Select the project that's already set up for you. If only one project exists, then you will automatically land in that project.

4. Visual Builder Studio automatically opens your workspace. If more than one workspace exists, however, then you must first pick your workspace.

5. When you enter into your workspace in Visual Builder Studio, click the Layouts side tab.

6. On the Layouts side tab, click the Payment_c node.

   

7. On the Payment_c tab, Rule Sets tab, click the Create Layout rule set.

   Note: Optionally repeat these same steps for the Edit Layout rule set.

8. Click the Open icon to edit the default layout.

   

9. Scroll through the list of fields to find your custom dynamic choice list field. Visual Builder Studio shows the internal API name, not the display name.

   Tip: To find your field more quickly, use the Filter field. For example, enter account into the Filter field.

   

10. Select the field, Account_Id_c, from the field list.

    When you select a field, it displays in the list of fields to the right, at the bottom of the list. You can optionally use the field's handle to drag the field to the desired location.

    

    If you were to preview the create page at this point, then the Account field that displays is a simple list with only basic search filtering.

    

    To add a picker to the field, you must associate the field with a field template that uses the picker fragment. Let's do that next.

3. Associate the Field with a Field Template

Let's add a picker to your custom dynamic choice list field to give users enhanced searching functionality. To do this, you associate the field with a field template that uses the picker fragment.

Note: The following steps illustrate the required picker parameters, but you can set other parameters, as well. See Parameters for the cx-picker Fragment.

1. Make sure that you're still on the Rule Sets tab, viewing the default layout.

2. Click the Account_Id_c field.

   

3. On the Properties pane, above the Template field, click Create.

   Note: If you're doing these steps a second time for the Edit Layout rule set's layout, then in the Template field, you don't need to create a field template. Instead, you can select the template that you're about to create in the next step.

4. In the Create Template dialog, in the Label field, enter a label for the template.

   In this example, enter AccountPickerTemplate.

   

5. Click Create.

   Visual Builder Studio creates a placeholder template with a basic structure, including an Input Text node which you can see on the Structure pane.

   

6. Delete the default Input Text node from the Structure pane by right clicking the node and clicking Delete.

7. Click the Code button.

   

8. In the template editor, select the accountPickerTemplate template tags.

   

9. On the Components palette, in the Filter field, enter cx-picker.

10. Drag and drop the cx-picker fragment to the template editor, between the template tags.

    

11. Make sure the fragment code is selected, as illustrated in this screenshot.

    

    Tip: On the Structure pane, selecting the Fragment Container node for the picker template accomplishes the same thing.

    

12. On the Properties pane for the cx-picker fragment, in the Input Parameters section, set values for the required picker parameters.

    Required Parameters for the cx-picker Fragment

    Parameter	Sample Value	Description
    dynamicLayoutContext	[[ $dynamicLayoutContext ]]	This parameter is set by default and you don't have to change it, provided the field displays on a create or edit page. If this field doesn't display on a create or edit page, then refer to the dynamicLayoutContext description in Parameters for the cx-picker Fragment for more details.
    pickerLayoutId	PickerLayout	This parameter points to the rule set whose layout controls how the picker looks at runtime. The default value, which you don't have to change, is PickerLayout, the ID of the Picker Layout rule set that's predefined for each object including custom objects. If you need to create a custom rule set, then create the rule set as a dynamic table and ensure that the values for the Label and ID fields are identical. Then add the ID to this parameter.
    resource	[[ {"name": "accounts","displayField":"OrganizationName","endpoint":"cx-custom","primaryKey":"PartyId" } ]]	Use this parameter to pass the target object name and end point: name - target object name endpoint - target object end point Optionally pass these additional attributes: displayField - the field value that's displayed in the picker field after the user makes a selection. If not provided here, then the picker displays the first field in the picker layout, by default. primaryKey - the field to derive the primaryKey from. If not provided, then the object's primaryKey field will be used. Be sure to update the resource parameter with the appropriate values for your use case. For example, replace accounts with the REST API name of the object that the dynamic choice list field is based on.

    For additional parameters that you can set for the cx-picker fragment, see Parameters for the cx-picker Fragment.

4. Configure the Picker Layout

Finally, select which fields display in the picker by modifying the Picker Layout rule set. This rule set's layouts control how the picker looks at runtime.

The Picker Layout rule set and default layout are predefined for each object, including custom objects.

In this example, we're adding an Account picker which means we must modify the Picker Layout rule set for the Account object.

1. On the Layouts side tab, click the CX Sales > Accounts node.

   

2. On the Accounts tab, Rule Sets tab, click the Picker Layout rule set.

3. Duplicate the default layout and then click the Open icon to edit the default_copy layout.

   

4. Scroll through the list of fields to add any desired fields to the picker layout.

   Tip: To find your field more quickly, use the Filter field. For example, enter city into the Filter field.

5. Select the field, City, from the field list.

   When you select a field, it displays in the list of fields to the right, at the bottom of the list. You can optionally use the field's handle to drag the field to the desired location.

   

Test the Picker Flow

You can now test the picker that you added to the list of values field.

1. From the payment_c-list page, click the Preview button to see your changes in your runtime test environment.

   

2. The resulting preview link will be:

   https://<servername>/fscmUI/redwood/cx-custom/payment_c/payment_c-list

3. Change the preview link as follows:

   https://<servername>/fscmUI/redwood/cx-custom/application/container/payment_c/payment_c-list

   Note: You must add /application/container to the preview link.

   The screenshot below illustrates what the list page looks like with data.

   

4. In the Action Bar, enter Create Payment.

5. Click Create Payment.

   The Create Payment drawer displays.

6. In the Create Payment drawer, click the three dots next to the Account field to view the list of saved searches.

   

7. If you enter some text into the field, the picker leverages Adaptive Search to return matched results. In the example below, we've entered pinnacle tech.

   

   In the picker, try searching on a city, for example, austin, so you can see how you can search on other record attributes.

   

   To understand how the search works, see Search Within Fields in the Search and Lists chapter in the Oracle Fusion Cloud Sales Automation Using Digital Sales (Redwood Sales) guide.

8. Once you're happy with how the picker looks, repeat these same steps for the edit layout.

   When configuring a second layout, you don't have to create a new field template and configure the picker fragment again; you can select the field template that you created in this procedure.

   You also don't need to configure the picker layout a second time.

9. Save your work by using the Push Git command.

   Navigate to the Git tab, review your changes, and do a Git push (which does both a commit and a push to the Git repository).