{"id":1415,"date":"2018-03-01T21:02:18","date_gmt":"2018-03-01T13:02:18","guid":{"rendered":"http:\/\/localhost\/help\/?page_id=1415"},"modified":"2024-10-23T14:20:46","modified_gmt":"2024-10-23T06:20:46","slug":"entity-selector","status":"publish","type":"page","link":"https:\/\/oihelp.corporate.ifs.com\/help\/p2-explorer\/explorer-studio\/controls\/entity-selector\/","title":{"rendered":"Entity Selector"},"content":{"rendered":"

<\/p>\n

This article applies to versions 4.5.4 and later of IFS OI Explorer. For more, see Release History<\/a>.<\/p>\n

Overview<\/h2>\n

The Entity Selector allows a user to select one or more entities from a list. The user can either use a search bar to search for entities by name, or use a filter to find the entities in a hierarchy.<\/p>\n

The Entity Selector can be used as an alternative to the Hierarchy<\/a> control when you want to flatten the hierarchy to show a simple list of entities, or you want to use a multi-select list of entities.<\/p>\n

\n

Configuring an Entity Selector<\/h2>\n

Basic Mode<\/h3>\n
\"\"<\/a><\/div>\n\n\n\n\n\n\n\n
Select Mode<\/strong>:<\/td>\nSingle or Multiple. Defines whether the user will be allowed to select a single entity, or multiple entities. In Single mode, users can select only 1 entity. In Multiple mode, users can select up to 10 entities.<\/td>\n<\/tr>\n
Selected Entities<\/strong>:<\/td>\nThe variable that is generated when a user selects an entity or entities from the list. If the Select Mode is Single<\/em>, this variable becomes selectedEntity<\/em>.<\/td>\n<\/tr>\n
Hierarchy Name<\/strong>:<\/td>\nChoose the name of the hierarchy that is the starting point for the list of entities that is initially displayed in the component. The entities are displayed in a flat list.<\/td>\n<\/tr>\n
Template Filter<\/b>:<\/td>\nThis can be a variable or text field. It contains the name of the primary template by which entities are filtered in the component. This requires some knowledge of the asset model in IFS OI Server. Only entities of this type will be displayed, even during searches.<\/td>\n<\/tr>\n
Style<\/b>:<\/td>\nThe style you want to apply to the Entity Selector component. If you are a Style Administrator, you can add a new Entity Selector style<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Advanced Mode<\/h3>\n

Advanced mode has 2 additional fields and additional options for the Hierarchy Name.<\/p>\n

\"\"<\/a><\/p>\n\n\n\n\n\n
Hierarchy Name<\/b>:<\/td>\nYou can choose the supply the name of the hierarchy from a variable.<\/td>\n<\/tr>\n
Start Node<\/b>:<\/td>\nThe name of the node in the hierarchy that is the starting point for the list of entities that is initially displayed in the component. Only the descendants of this node will be displayed.<\/td>\n<\/tr>\n
Number of Selections<\/b>:<\/td>\nThe maximum number of entities that a user is able to select from the available list of entities. This is only available in Multiple mode.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u00a0<\/p>\n

Related: Using the Entity Selector<\/a> in display mode, Adding a new Entity Selector style<\/a><\/p>\n

\n

Tutorial: Adding an Entity Selector that Drives a Pie Chart<\/h2>\n

If you're unfamiliar with the process of building pages, read the article Building an Explorer Page<\/a>.<\/p>\n

In this tutorial, we'll look at adding an Entity Selector to a page, which will allow the user to only select a single entity. We'll also add a Pie Chart to show how using the Entity Selector can affect another component on the page.<\/p>\n

\"\"<\/a><\/p>\n

Now, let's look at how we're actually going to do this, step-by-step.<\/p>\n

Note<\/strong>: This configuration uses the Sample Data<\/em> table and dataset queries that can be optionally made available during initial installation and setup. If you don't have access to this data, you will need to adjust the configuration to suit your data at your site.<\/p>\n

\u00a0<\/p>\n

Step 1. Add the Entity Selector to the Page<\/strong><\/p>\n

\"\"<\/a><\/p>\n

Drag and drop the Entity Selector component onto a grid cell. The Entity Selector is in the Hierarchy \"hierarchy\" group.<\/p>\n

\u00a0<\/p>\n

Step 2. Configure the Entity Selector<\/strong><\/p>\n

\"\"<\/a><\/p>\n

In this step, we want to create an Entity Selector that will allow the user to select a well from a specific point in the hierarchy. We need to use the Advanced configuration for this.<\/p>\n

Click the Advanced<\/strong> button, and configure the fields as follows:<\/p>\n\n\n\n\n\n\n\n
Select Mode<\/strong><\/td>\nSingle<\/td>\nAllow the user to select only one entity at a time.<\/em><\/td>\n<\/tr>\n
Selected Entity<\/strong><\/td>\nselectedEntity<\/td>\nThis will automatically be populated, and is the variable that the Entity Selector uses to store the name of the entity that the user selects. You can change this variable name if you need to store more than one selected entity, but we generally recommend using the supplied default variable.<\/em><\/td>\n<\/tr>\n
Hierarchy Name<\/strong><\/td>\n(Variable) selected Hierarchy<\/td>\nThis is the variable that the Entity Selector uses to determine the hierarchy that will initially be displayed.<\/em><\/td>\n<\/tr>\n
Template Filter<\/strong><\/td>\n(Text) Oil Producing Well<\/td>\nOnly entities that have this template will be displayed in the component, even when using the Entity Selector's search capability.<\/em><\/td>\n<\/tr>\n
Start Node<\/strong><\/td>\n(Entity) Far North Coast<\/td>\nOnly entities that are children of this node, as well as having the Oil Producing Template, will be initially displayed. <\/em><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Step 3. Set the Default Values<\/strong><\/p>\n

\"\"<\/a><\/p>\n

If you don't set any default values, the Entity Selector will not have an entity selected when the page is first loaded. We can set the initial selected entity here. This means the page will show relevant data when it is loaded, rather than displaying a 'No data<\/a>' message.<\/p>\n

<\/i>BEST PRACTICE<\/span><\/p>\n

You should specify default values for any variables used, to guide the user in selecting the relevant assets.<\/p>\n<\/div>\n

\u00a0<\/p>\n

Let\u2019s change the default data that is displayed. We are interested in the selectedEntity<\/strong> variable.<\/p>\n