Introduce TagField

[glebfox]

Description

Introduce TagField as a replacement for deprecated TokenList.

Reflect functionality of TokenList:

• Lookup action
• ClearAll action

Examples:

• https://docs.sencha.com/extjs/6.5.1/classic/Ext.form.field.Tag.html
• https://www.cssscript.com/demo/multi-select-autocomplete-selectpure/
• https://www.cssscript.com/demo/tagging-system-tags/
• https://www.cssscript.com/demo/customizable-select-box-input-field-enhancement-library-choices-js/
• https://bootstrap-tagsinput.github.io/bootstrap-tagsinput/examples/
• https://yaireo.github.io/tagify/ - investigate features

Progress

• Create base component structure
• implement client-side tags
• Handle enter key press
• Backend search logic
• Work with entity
• Clear all button
• Styling

Changes

TagField is based on SuggestionField, so it supports searching values while typing a text. TagField works both with entities and datatypes. It shows values as separated tags:

and has a popup with suggestions:

Searching values

TagField has all features of SuggestionField, including searching values. For more information, see SuggestionField documentation.

Declarative way:

<tagField id="tagField">
    <query entityClass="io.jmix.samples.ui.entity.SampleUser"
           searchStringFormat="%${searchString}%">
        select e from sample_User e where e.username like :searchString
    </query>
</tagField>

Programming way:

tagField.setSearchExecutor((searchString, searchParams) -> {
    return dataManager.load(SampleUser.class)
            .query("select e from sample_User e where e.username like :name")
            .parameter("name", "%" + searchString + "%")
            .list();
});

Create items

TagField inherits the ability to set ENTER keypress handler. Extending this functionality, TagField provides a predefined class NewTagProvider for converting entered text to tag. For instance, we will convert entered text to entity:

tagFieldDatatype.setEnterPressHandler(new TagField.NewTagProvider<OrderLine>() {
    @Override
    public OrderLine create(String text) {
        OrderLine orderLine = metadata.create(OrderLine.class);
        orderLine.setName(text);
        return orderLine;
    }
});

Tags API

TagField has API for configuring displayed tags.

1. setTagStyleProvider() - generates stylename and adds it to tags.
2. setTagCaptionProvider() - enables to change displayed caption of tags.
3. setTagComparator() - sets comporator for sorting displayed tags.
4. addTagClickListener() - enables to handle clicks on tags.
5. setClearAllVisible() - displays the button for removing tags from the field. It also has an attribute in the XML configuration. The default value is false.

   <tagField id="tagField"
             clearAllVisible="true"/>
   

QA

1. Check that component works with entity: suggestions are shown and can be selected, component value can be changed.
2. Check that clearAllVisible="true"removes all tags from the field;
3. Check Java API:
   • tagStyleProvider();
   • tagCaptionProvider(); // it changes caption only for tags
   • tagComporator(); // sets sorting for tags
   • addTagClickListener();
4. TagField can create new values from entered text by pressing ENTER key. Check that works:

   <tagField id="tagField"
             clearAllVisible="true"/>
   

   @Autowired
   private DatatypeRegistry datatypeRegistry;
   @Autowired
   private Notifications notifications;
   
   tagField.setEnterPressHandler(new TagField.NewTagProvider<Integer>() {
    @Override
    public Integer create(String search) {
        try {
            return datatypeRegistry.get(Integer.class).parse(search);
        } catch (ParseException e) {
            notifications.create(Notifications.NotificationType.TRAY)
                    .withCaption(e.getMessage())
                    .show();
        }
        return null;
    }
   });
   

5. Check that TagField looks pretty under Halo, Hover themes in browsers: Chrome, Safari, Edge, IE11
   Check Helium theme in Chrome, Safari, Edge. Also check predefined sizes: small, large;
6. Try any your cases;

[owlet1997]

Tag <query> is highlighted as a mistake by Idea in XML descriptor: