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 theadd
flag is set totrue
, 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 was32
. You can also make this +other tag clickable by setting theclick_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 aHTML Form
, then you should set the fieldtype
tojson
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();