Selecting Entities with an Item Selector

The steps here show you how to get and use an Item Selector to select entities in your app. For an explanation of the Item Selector API and more information on these steps, see the Item Selector introduction.

Get an Item Selector

First, you must get an Item Selector for your use case. Follow these steps:

Determine the criterion and return types for the Item Selector. The criterion corresponds to the selected entity type, and the return types correspond to the data you expect to receive from those selections. For a list of the criterion and return types that Liferay DXP provides, see Item Selector Criterion and Return Types. For example, if you need an Item Selector that selects images and returns their URLs, use ImageItemSelectorCriterion and URLItemSelectorReturnType. You can create criterion and/or return types if there aren’t existing ones for your use case.
Use Declarative Services to get an ItemSelector OSGi Service Component:
```
import com.liferay.item.selector.ItemSelector;
import org.osgi.service.component.annotations.Reference;

...

@Reference
private ItemSelector _itemSelector
```
The component annotations are available in the module org.osgi.service.component.annotations.
Create the factory you’ll use to create the Item Selector’s URL. To do this, invoke the RequestBackedPortletURLFactoryUtil.create method with the current request object. The request can be an HttpServletRequest or PortletRequest:
```
RequestBackedPortletURLFactory requestBackedPortletURLFactory =
    RequestBackedPortletURLFactoryUtil.create(request);
```

Create a list of return types expected for the entity. For example, the return types list here consists of URLItemSelectorReturnType:

List<ItemSelectorReturnType> desiredItemSelectorReturnTypes =
    new ArrayList<>();
desiredItemSelectorReturnTypes.add(new URLItemSelectorReturnType());

Create an object for the criterion. This example creates a new ImageItemSelectorCriterion:

ImageItemSelectorCriterion imageItemSelectorCriterion =
    new ImageItemSelectorCriterion();

Use the criterion’s setDesiredItemSelectorReturnTypes method to set the return types list to the criterion:
```
imageItemSelectorCriterion.setDesiredItemSelectorReturnTypes(
    desiredItemSelectorReturnTypes);
```
Call the Item Selector’s getItemSelectorURL method to get an Item Selector URL for the criterion. The method requires the URL factory, an arbitrary event name, and a series of criterion instances (one, in this case):
```
PortletURL itemSelectorURL = _itemSelector.getItemSelectorURL(
    requestBackedPortletURLFactory, "sampleTestSelectItem",
    imageItemSelectorCriterion);
```
Add the itemSelectorURL to the request to be able to retrieve it from the JSP: <code/>request.setAttribute("itemSelectorURL", itemSelectorURL.toString())</code>"

Using the Item Selector Dialog

To open the Item Selector in your UI, you must use the JavaScript component LiferayItemSelectorDialog from AlloyUI’s liferay-item-selector-dialog module. The component listens for the item selected event that you specified for the Item Selector URL. The event returns the selected element’s information according to its return type.

Follow these steps to use the Item Selector’s dialog in a JSP:

Declare the AUI tag library:

<%@ taglib prefix="aui" uri="http://liferay.com/tld/aui" %>

Define the UI element you’ll use to open the Item Selector dialog. For example, this creates a Choose button with the ID chooseImage:
```
<aui:button name="chooseImage" value="Choose" />
```

Get the Item Selector’s URL:

<%
String itemSelectorURL = GetterUtil.getString(request.getAttribute("itemSelectorURL"));
%>

Add the <aui:script> tag and set it to use the liferay-item-selector-dialog module:
```
<aui:script use="liferay-item-selector-dialog">

</aui:script>
```
Inside the <aui:script> tag, attach an event handler to the UI element you created in step two. For example, this attaches a click event and a function to the Choose button:
```
<aui:script use="liferay-item-selector-dialog">

    $('#<portlet:namespace />chooseImage').on(
    'click',
      function(event) {
        
      }
    );

</aui:script>
```
Inside the function, you must create a new instance of the LiferayItemSelectorDialog AlloyUI component and configure it to use the Item Selector. The next steps walk you through this.
Create the function’s logic. First, create a new instance of the Liferay Item Selector dialog:
```
var itemSelectorDialog = new A.LiferayItemSelectorDialog(
    {
        ...
    }
);
```
Inside the braces of the LiferayItemSelectorDialog constructor, first set set the eventName attribute. This makes the dialog listen for the item selected event. The event name is the Item Selector’s event name that you specified in your Java code (the code that gets the Item Selector URL):
```
eventName: 'ItemSelectedEventName',
```
Immediately after the eventName setting, set the on attribute to implement a function that operates on the selected item change. For example, this function sets its variables for the newly selected item. The information available to parse depends on the return type(s). As the comment below indicates, you must add the logic for using the selected element:
```
on: {
        selectedItemChange: function(event) {
            var selectedItem = event.newVal;

            if (selectedItem) {
                var itemValue = JSON.parse(
                selectedItem.value
                );
                itemSrc = itemValue.url;

                
            }
        }
},
```
Immediately after the on setting, set the title attribute to the dialog’s title:
```
title: '<liferay-ui:message key="select-image" />',
```
Immediately after the title setting, set the url attribute to the previously retrieved Item Selector URL. This concludes the attribute settings inside the LiferayItemSelectorDialog constructor:
```
url: '<%= itemSelectorURL.toString() %>'
```
To conclude the logic of the function from step four, open the Item Selector dialog by calling its open method:
```
itemSelectorDialog.open();
```

When the user clicks the Choose button, a new dialog opens, rendering the Item Selector with the views that support the criterion and return type(s).

Here’s the complete example code for these steps:

<%@ taglib prefix="aui" uri="http://liferay.com/tld/aui" %>

<aui:button name="chooseImage" value="Choose" />

<%
String itemSelectorURL = GetterUtil.getString(request.getAttribute("itemSelectorURL"));
%>

<aui:script use="liferay-item-selector-dialog">

    $('#<portlet:namespace />chooseImage').on(
        'click',
        function(event) {
            var itemSelectorDialog = new A.LiferayItemSelectorDialog(
                {
                    eventName: 'ItemSelectedEventName',
                    on: {
                            selectedItemChange: function(event) {
                                var selectedItem = event.newVal;

                                if (selectedItem) {
                                    var itemValue = JSON.parse(
                                    selectedItem.value
                                    );
                                    itemSrc = itemValue.url;

                                    <!-- use item as needed -->
                                }
                            }
                    },
                    title: '<liferay-ui:message key="select-image" />',
                    url: '<%= itemSelectorURL.toString() %>'
                }
            );
            itemSelectorDialog.open();
        }
    );
</aui:script>

Item Selector

Creating Custom Criterion and Return Types

Creating Custom Item Selector Views

« Item SelectorCreating Custom Criterion and Return Types »