Tags - globules-io/OGX.JS GitHub Wiki

Tags is a component to display and manage tags. It includes an auto complete mechanism. This component can be used in multiple scenarios, either using strings or objects.

Tags requires List and might also require Form if you wish to restrict the user input (see restrict).

Stack

Extends

 Uxi, Touch

Requires

 List

OML

 "selector:Tags":{CONFIG}

Config

 let config = {
      el:_SELECTOR_,
      add:true|false, //Allow user to type to search for tag or add tags
      remove:true|false, //Allow user to remove previously added tags
      name:_STRING_, //optional, if set, generates an hidden field with updated value
      required:_BOOLEAN_, //Optional, if name is set, the required property of the hidden field
      lowercase:_BOOLEAN_, //Optional, force the input tag to be saved as lowercase
      max:_INT_, //If set, the maximum number of tags that the user can add
      display_max:_INT_, //If set, the maximum number of suggestions to display
      display_more:_BOOL_, //If set, adds a `+[int] other` at the end of the tag list,
      click_more:_BOOL_, //If set with `display_more`, will show all tags on click,
      hide_input_on_disable:_BOOL_, //Hide the input field when the component is disabled
      tags:_ARRAY_, //Array of available tags
      current_tags:_ARRAY_,  //Array of selected tags, defaults to []
      tags_ascii:_OBJECT_, //Optional, an key store object holding the ascii value of all tags for speed
      image:_URL, //image of the 'remove' icon embeddded in the tag
      mode:'string' |'object' |'ascii', //Work with strings, objects or ascii
      placeholder:_STRING_ //The default text to display in the input field,
      restrict:_BOOLEAN_ | _OBJECT_ //Optional, input restriction, see restrict,
      strict:_BOOLEAN_ //Optional, defaults to false, see strict          
 };

Modes

Tags offers different modes of operation when it comes to searching and proposing tags (autocomplete).

If the operating mode is set to string, the component expects the array to be a simple array of strings. If the add flag is set to true, meaning that the end user can add tags, the added tags will be stored as string as well.

  ['Tornado', 'Hurricane', ...]

If the operating mode is set to object, the component expect the array to be a array of object, each object owning at least the property 'label'.

  [{label:'Tornado', date:'2017-05-12'}, {label:'Hurricane', date:'2017-05-15'} ...]

Every tag added by the end user in this mode will result in the following object added to the list

  {label:_USER_INPUT_STRING_}

Restrict

If you wish to restrict the input to certain characters or length, you can either pass true (and use the default restrictions) or pass a restriction configuration object. For more information, see Form.restrictField.

Strict

In strict mode, when setting strict:true in config, the end user can only select a proposed tag and cannot create his own

Display

You can limit the number of suggestions by setting the display_max flag to true. In this case, the last tag will be the number of remaining tags expressed as +32 other if the number of remaining tags was 32. You can also make this +other tag clickable by setting the click_more flag to true. In, this case, when the end user clicks/taps this tags, the component will then render all tags.

Get/Set

To set the current user tag(s)

 tags.val(_ARRAY_);

To set the current user tag using lookup

 tags.val(_PROP_, _VAL);

To get the current user tag(s)

 tags.val();

Note that if you are using Tags within a HTML Form, then you should set the field type to json in the config of the field.

Methods

 tags.tags(_ARRAY_); //Get/Set auto complete tags
 tags.val(_ARRAY_); //Get/Set user tags
 tags.clear(); //Removes all user tags
 tags.add(_STRING_);  //Add a user tag
 tags.remove(_STRING_);  //Add a user tag

Events

 OGX.Tags.TAG_ADDED //User tag added, broadcast added tag
 OGX.Tags.TAG_REMOVED //User tag removed, broadcast removed tag
 OGX.Tags.CHANGE //User tag added or removed, broadcast current tags
 OGX.Tags.SELECT //User has touched a current tag

Destroy

tags.destroy();