Creating Custom Item Selector Entities

Does your app require users to select an item that the Item Selector isn’t configured for? No problem. You can create a new entity.

This tutorial explains how to create a new entity for the Item Selector.

Creating Item Selector Criterion

First, you must create a new criterion for your entity. Follow these steps to create an Item Selector criterion:

  1. Create a class that extends the BaseItemSelectorCriterion class.

    The example below creates a class called TaskItemSelectorCriterion:

    public class TasksItemSelectorCriterion extends 
    BaseItemSelectorCriterion {
    
    }
    

    This class specifies what kind of entity the user is selecting and what information the Item Selector should return. The methods inherited from the BaseItemSelectorCriterion class provide the logic for obtaining this information:

    public abstract class BaseItemSelectorCriterion
            implements ItemSelectorCriterion {
    
            @Override
            public List<ItemSelectorReturnType> getDesiredItemSelectorReturnTypes() {
                    return _desiredItemSelectorReturnTypes;
            }
    
            @Override
            public void setDesiredItemSelectorReturnTypes(
                    List<ItemSelectorReturnType> desiredItemSelectorReturnTypes) {
    
                    _desiredItemSelectorReturnTypes = desiredItemSelectorReturnTypes;
            }
    
            private List<ItemSelectorReturnType> _desiredItemSelectorReturnTypes;
    
    }
    

    Note that you can use this class to pass information to the view if needed. For example, the JournalItemSelectorCriterion class passes information about the primary key so the view can use it:

    public class JournalItemSelectorCriterion extends 
    BaseItemSelectorCriterion {
    
            public JournalItemSelectorCriterion() {
            }
    
            public JournalItemSelectorCriterion(long resourcePrimKey) {
                    _resourcePrimKey = resourcePrimKey;
            }
    
            public long getResourcePrimKey() {
                    return _resourcePrimKey;
            }
    
            public void setResourcePrimKey(long resourcePrimKey) {
                    _resourcePrimKey = resourcePrimKey;
            }
    
            private long _resourcePrimKey;
    
    }
    
  2. Create an OSGi component class that implements the BaseItemSelectorCriterionHandler class. Each criterion requires a criterion handler, which is responsible for obtaining the proper selection view.

    The example below creates a criterion handler for the TaskItemSelectorCriterion class:

    @Component(service = ItemSelectorCriterionHandler.class)
    public class TaskItemSelectorCriterionHandler extends 
    BaseItemSelectorCriterionHandler<TaskItemSelectorCriterion> {
    
        public Class <TaskItemSelectorCriterion> 
        getItemSelectorCriterionClass() {
            return TasksItemSelectorCriterionHandler.class;
        }
    
        @Activate
        @Override
        protected void activate(BundleContext bundleContext) {
                super.activate(bundleContext);
        }
    
    }
    

    The @Activate and @Override tokens are required to activate this OSGi component.

Depending on the needs of your app, you may not need to create a return type. If your entity returns information that is already defined by an existing return type, you can use that return type instead.

You can view the default available criteria in the Item Selector Criterion and Return Types reference.

If, however, your entity returns information that is not covered by an existing return type, you’ll need to create a new return type next.

Creating Item Selector Return Types

To create a return type, you must create a class that implements the ItemSelectorReturnType class.

The example below creates a new return type called TaskItemSelectorReturnType:

/**
* This return type should return the task ID and the user who
* created the task as a string.
*
* @author Joe Bloggs
*/
public class TaskItemSelectorReturnType implements ItemSelectorReturnType{

}

The *ItemSelectorReturnType class is used as an identifier by the Item Selector and does not return any information itself. You should determine the information you expect returned (an ID, a URL, a more complex object, etc.), and create a return type to handle that information. The return type class is an API that connects the return type to the Item Selector views. Whenever the return type is used, the view must ensure that the proper information is returned. It’s recommended that you specify the information that the return type returns, as well as the format, as Javadoc (as shown in the TaskItemSelectorReturnType example above).

So far, you’ve created an API that you can use to create a selection view for your new entity. The entity’s criterion and return type classes are used by your application to create the Item Selector URL. You can follow the Selecting Entities using the Item Selector tutorial to learn how to obtain the Item Selector URL.

The selection view is responsible for returning the proper entity information specified by the return type. Currently there isn’t a selection view to select your entity. Follow the Creating Custom Item Selector Views tutorial to learn how to create your new view.

Now you know how to create an entity for the Item Selector!

Related Topics

Selecting Entities using the Item Selector

Creating Custom Item Selector Views

0 (0 Votes)
Selecting Entities Using the Item Selector Previous