Item Selector in Liferay DXP / 7

Liferay introduced lots of new features in its major release Liferay 7. One of them is Item Selector. Item selector is basically component which lets you select different types of entities.

For example If you want to implement document and media image selection in your application then item selector is there for you.

Item selector provides selection view for any kind of entity like image, video, documents, user, site or your custom entity!!

Why Item Selector ?

There are basic need in any application where you want to provide selection for different items like image, video, custom entity etc. Without item selector, we need to implement different item selection view for different items which not only take extra effort but also becomes inconsistent as per UI perspective.  

Item selector provides easy-to-use, extendable, and most important is consistent item selection view. Means with item selector you can create item selection view for any entity but the view remains consistent where it shows its power.

Basically two things are needed to use item selector.

1. Entity

2. Return Type

1) Entity : Which types of items you want to select with item selector (image, video etc) ? Each entity must implement ItemSelectorCriterion interface to represent in item selector. Liferay provides implementation for common entities like image, video out of the box. You can find list of Liferay’s entities from here. If you want to create custom entity to show in item selector then you need to extend BaseItemSelectorCriterion class which itself implement ItemSelectorCriterion interface.

2) Return Type : What type of information you want to provide when user select item ? Do you want to return URL, UUID, or primary key ? Each return type must implement ItemSelectorReturnType interface. Liferay provides implementation for some of the return types like URL,UUID out of the box. You can find list of Liferay’s return types from here.

So Item selector is a combination of entities and return types.

Here I am going to explain item selector for the image item and URL return type.

Following are the steps.

1. Create URL for the given entities and return types.

2. Use URL of step 1 in Item selector dialog.

1. Create URL for the given entities and return types :

First you need to create URL for the combination of items and return types. Here is an example of image item with URL return type. These steps will remain same for any combination of items and return types.

Dependencies : Add these dependencies to your module’s build.gradle.

dependencies {
   compileOnly group: "com.liferay.portal", name: "com.liferay.portal.kernel", version: "2.0.0"
   compileOnly group: "com.liferay.portal", name: "com.liferay.util.taglib", version: "2.0.0"
   compileOnly group: "javax.portlet", name: "portlet-api", version: "2.0"
   compileOnly group: "javax.servlet", name: "javax.servlet-api", version: "3.0.1"
   compileOnly group: "jstl", name: "jstl", version: "1.2"
   compileOnly group: "org.osgi", name: "org.osgi.compendium", version: "5.0.0"
   compileOnly group: "com.liferay", name: "com.liferay.item.selector.api", version: "2.0.0"
   compileOnly group: "com.liferay", name: "com.liferay.item.selector.criteria.api", version: "2.0.0"
}

Get an Item Selector OSGI Service Component in your portlet class :

private ItemSelector _itemSelector;
   
@Reference(unbind = "-")
public void setItemSelector(ItemSelector itemSelector) {
   _itemSelector = itemSelector;
}

Add return type for URL :

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

Create image item selector instance :

ImageItemSelectorCriterion imageItemSelectorCriterion =
      new ImageItemSelectorCriterion()

Set return type in image item selector :

imageItemSelectorCriterion.setDesiredItemSelectorReturnTypes(
      itemSelectorReturnTypes );

Get RequestBackedPortletURLFactory :

RequestBackedPortletURLFactory requestBackedPortletURLFactory =
    RequestBackedPortletURLFactoryUtil.create(request);

RequestBackedPortletURLFactory is used to generate portlet urls.

Create URL with getItemSelectorURL method :

PortletURL itemSelectorURL = _itemSelector.getItemSelectorURL(
    requestBackedPortletURLFactory, "sampleTestSelectItem",
    imageItemSelectorCriterion);

Parameters :

RequestBackedPortletURLFactory : It is a RequestBackedPortletURLFactory instance and it is used to generate portlet urls.

Event Name : It is a unique event name that is triggered by the Item Selector when the element is selected.

ItemSelectorCriterion : It is an instance of ItemSelectorCriterion object. Here it is for image item.

2. Use URL of step 1 in Item selector dialog :

Declare the AUI tag library :

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

Create button and use the liferay-item-selector-dialog module :

<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>

For more implementation details or support you may contact us at [email protected].

For professional paid support, you may contact us at [email protected] .