The Entity Selector is one of the most powerful and commonly used components on a page. It allows users to select different entities from a hierarchy, and have the page data update accordingly.
In some ways, the Entity Selector is similar to the Hierarchy control. You should use the Entity Selector when:
- You want to limit the number of selections a user can make. For example, you may want the user to only be able to select 3 entities.
- You want to filter the hierarchy to only show entities of a specific type (primary template).
- You want the hierarchy to start from a specific child node.
The Entity Selector component consists of a list of entities, along with a set of filters. Here is what an Entity Selector looks like (version 4.4):
And here is what a user can do with an Entity Selector:
What a User Can Do
With the Entity Selector, users can:
- Select one or more entities from the list, depending on how the control was configured.
- Find an entity they know exists in the hierarchy. To do this, just start typing the name of an entity into the text box at the top. The list of entities will refresh as you type. When you find the entity you are looking for, click the check box in the list to select it.
- Filter the list of entities by selecting a hierarchy from the drop-down list. The entities in that hierarchy will be displayed in the list. You can click the arrow to scroll through the list until you find the entity you are looking for.
- You can also further filter by a node in the hierarchy. Start typing the name of the node in the text box next to the drop-down list. As you type, you will be presented with a list of matching nodes - select one of these to display the available entities.
Note that configuration can affect the results, if the control was configured to only show entities of a certain type (primary template).
What a Page Designer Can Do
When configuring the entity selector, a page designer can:
- Restrict the user to selecting a single entity (Select Mode = Single).
- Allow the user to select a specific number of entities. (Select Mode = Multiple, Number of Selections is specified)
- Allow the user to select as many entities as they want. (Select Mode = Multiple, Number of Selections is unspecified)
- Restrict the entities shown in the list to be of a certain type (Template Filter is specified).
- When the page is first loaded, have the list of entities start from a specific node in a hierarchy (Start Node is specified).
Configuration Tips & Best Practices
Do not use the Hierarchy control and Entity Selector on the same page. Doing so may result in unexpected behaviours.
You should add the following page defaults to guide the user in selecting the relevant assets:
- selectedEntity (type Entity) or selectedEntities (type EntityList)
- selectedHierarchy (type Text)
Do you have any other tips to share? Let us know in the comments below!