4.5.2.1.19. PickerField

The input field with additional action buttons (PickerField) allows you to display an entity instance in a text field and perform actions by clicking buttons on the right.

XML name of the component: pickerField.

The PickerField component is implemented for Web Client and Desktop Client.

  • As a rule, PickerField is used for reference entity attributes. It is sufficient to specify datasource and property attributes for the component: 

    <dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
</dsContext>
<layout>
    <pickerField datasource="carDs" property="colour"/>

    In the example above, the screen defines carDs data source for a Car entity having the colour attribute. In the pickerField element, you should specify a link to a data source in the datasource attribute, and a name of an entity attribute, the value of which should be displayed in the component – in the property attribute. The entity attribute should refer to another entity, in the example above it is Colour.

  • For PickerField, you can define an arbitrary number of actions, displayed as buttons on the right. It can be done either in the XML descriptor using the actions nested element, or programmatically in the controller using addAction().

    • There are standard actions, defined by the PickerField.ActionType: lookup, clear, open. They perform the selection of a related entity, clearing the field and opening the edit screen of a selected related entity, respectively. For standard actions in XML, you do not have to define any attributes except the identifier. If no actions in the actions element are defined when declaring the component, the XML loader will define lookup and clear actions for it. To add a default action, for example, open, you need to define the actions element as follows: 

      <pickerField datasource="carDs" property="colour">
    <actions>
        <action id="lookup"/>
        <action id="open"/>
        <action id="clear"/>
    </actions>
</pickerField>

      The action element does not extend but overrides a set of standard actions. Identifiers of all required actions have to be defined in order to use them. The component looks like the following:

      Use addLookupAction(), addOpenAction() and addClearAction() to set standard actions programmatically. If the component is defined in the XML descriptor without actions nested element, it is sufficient to add missing actions: 

      @Inject
protected PickerField colourField;

@Override
public void init(Map<String, Object> params) {
    colourField.addOpenAction();
}

      If the component is created in the controller, it will get no default actions and you need to explicitly add all necessary actions: 

      @Inject
protected ComponentsFactory componentsFactory;

@Override
public void init(Map<String, Object> params) {
    PickerField colourField = componentsFactory.createComponent(PickerField.NAME);
    colourField.setDatasource(carDs, "colour");
    colourField.addLookupAction();
    colourField.addOpenAction();
    colourField.addClearAction();
}

      You can parameterize standard actions. The XML descriptor has limited abilities to do this: there is only openType attribute, in which you can specify the mode to open a selection screen (for LookupAction) or edit screen (for OpenAction).

      If you create actions programmatically, you can specify any properties of PickerField.LookupAction, PickerField.OpenAction and PickerField.ClearAction objects returned by methods of adding standard actions. For example, you can set a specific selection screen as follows: 

      PickerField.LookupAction lookupAction = customerField.addLookupAction();
lookupAction.setLookupScreen("customerLookupScreen");

      For more information, see JavaDocs for standard actions classes.

    • Arbitrary actions in the XML descriptor are also defined in the actions nested element, for example: 

      <pickerField datasource="carDs" property="colour">
    <actions>
        <action id="lookup"/>
        <action id="show" icon="icons/show.png"
                invoke="showColour" caption=""/>
    </actions>
</pickerField>

      You can programmatically set an arbitrary action as follows: 

      @Inject
protected PickerField colourField;

@Override
public void init(Map<String, Object> params) {
    colourField.addAction(new AbstractAction("show") {
        @Override
        public void actionPerform(Component component) {
            showColour(colourField.getValue());
        }

        @Override
        public String getCaption() {
            return "";
        }

        @Override
        public String getIcon() {
            return "icons/show.png";
        }
    });
}

      The declarative and programmatic creation of actions is described in Section 4.5.4, “Actions. The Action Interface”.

  • PickerField can be used without any direct reference to data, i.e., without datasource and property specification. In this case metaClass attribute should be used to specify an entity type for PickerField. Entity name in metadata should be defined, for example: 

    <pickerField id="colourField" metaClass="sample$Colour"/>

    You can get an instance of a selected entity by injecting the component into a controller and invoking its getValue() method.

    For proper operation of the PickerField component you need either set a metaClass attribute, or simultaneously set datasource and property attributes.

  • You can use keyboard shortcuts in PickerField, see Section 4.5.11, “Keyboard Shortcuts” for details.

pickerField attributes:

align editable property width
caption enable required  
captionProperty height requiredMessage  
datasource id stylename  
description metaClass visible  

pickerField elements:

actions
validator
Prev  Up  Next
  Home