bevacqua/insignia

🔖 Customizable tag input. Progressive. No non-sense!

Insignia

Customizable tag input. Progressive. No non-sense!

Browser support includes every sane browser and IE7+.

Demo!

You can see a live demo here.

Inspiration

I needed a tag input that was progressively enhanced, fast, easy to use, and reliable. Tag inputs I stumbled upon were too bloated, too dependant on JavaScript, or provided an unfriendly human experience.

The goal is to produce a framework-agnostic tag input editor that is easily integrated into your favorite MVC framework, that doesn't translate into a significant addition to your codebase, and that's enjoyable to work with. Insignia shares the modular design philosophy of Rome, the datetime picker.

Features

• Small and focused
• Natural keyboard navigation
• Progressively enhanced
• Extensive browser support

Install

You can get it on npm.

npm install insignia --save

Or bower, too.

bower install insignia --save

Usage

Insignia demands one thing of you: the input must have no siblings.

<div>
  <input id='insigificant' />
</div>

If client-side JavaScript never executes, because its disabled or too slow (on intermittent mobile network connections, for example), you should treat user input as a delimited list of tags. When JavaScript does execute, you should consider sending tags as a single string and splitting them on the server-side, for consistency.

insignia.find(input)

Retrieves a previously created instance of Insignia associated with the provided input. Returns null if none can be found.

insignia(input, options={})

Insignia exposes a function to turn an input into a tag list input. Empty spans will be added on both sides of your input element.

A few options may be provided. They are detailed below.

free

Defaults to true. When this flag is turned off, tags can't be edited by hand but they can still be deleted entirely using backspace. Tags would have to be added programmatically.

deletion

When true, humans will be able to delete individual tags by clicking on an icon.

delimiter

The separator between tags. Defaults to ' '. Must be a single character.

preventInvalid

This option will prevent tags identified as invalid from being added. By default this is turned off and they just get a nsg-invalid CSS class.

validate(value)

A method that validates whether the user input value constitutes a valid tag. Useful to filter out duplicates. Defaults to the method below, that does exactly that. Note that in the code below, toy is the API returned by calling insignia(el).

function validate (value) {
  return toy.findItem(value) === null;
}

Note that tags is only a copy and modifying it won't affect the list of tags.

render(container, item)

A method that's called whenever a tag should be rendered. Defaults to setting getText(item) as the container's text.

getText

When you have complex data items from autocomplete, you need to set getText to read the value that should be used as a display value.

getValue

When you have complex data items from autocomplete, you need to set getValue to read the value that should be used as each tag's value.

convertOnBlur

By default, tags are converted whenever the blur event fires on elements other than input. Set to false to disable.

Instance API

When you call insignia(input, options), you'll get back a tiny API to interact with the instance. Calling insignia repeatedly on the same DOM element will have no effect, and it will return the same API object.

.addItem(data)

Adds an item to the input. The data parameter could be a string or a complex object, depending on your instance configuration.

.findItem(data)

Finds an item by its data string or object.

.findItemIndex(data)

Return the index of the first item found by its data string or object.

.findItemByElement(el)

Finds an item by its .nsg-tag DOM element.

.removeItem(data)

Removes an item from the input. The item is found using the data string or object.

.removeItemByElement(el)

Removes an item from the input. The item is found using a .nsg-tag DOM element.

.value()

Returns the list of valid tags as an array.

.allValues()

Returns the list of tags as an array including invalid tags.

.refresh()

When changing the value of the el input by hand, call .refresh() to convert tags again.

.destroy()

Removes all event listeners, CSS classes, and DOM elements created by insignia. The input's value is set to the output of .value(). Once the instance is destroyed it becomes useless, and you'll have to call insignia(input, options) once again if you want to restore the behavior.

Instance Events

The instance API comes with a few events.

Event	Arguments	Description
add	data, el	Emitted whenever a new item is added to the list
remove	data	Emitted whenever an item is removed from the list
invalid	data, el	Emitted whenever an invalid item is added to the list

You can listen to these events using the following API.

const toy = insignia(el);
toy.on('add', data => console.log(data)); // listen to an event
toy.once('invalid', data => throw new Error('invalid data')); // listener discarded after one execution

toy.on('add', added);
toy.off('add', added); // removes `added` listener

function added (data) {
  console.log(data);
}

License

MIT

insignia's Issues

deleting tags in between other tags leaves a space

1. 
2. 

It looks like the intention here is to leave room while someone types in a new tag, but if you're just deleting tags, that's not the desired behavior and the extra space looks a bit weird.

IE11 error when initializing

Got this error in IE11, also on the demo page.

"Object doesn't support property or method 'from'"

Looks like IE11 does not support Array.From

Demo breaks focussing on Safari OS X

Unable to focus other inputs on the demo page: http://bevacqua.github.io/insignia/

Clicking on another field, or using the tab key has no effect. There are no errors in the console.

See: http://quick.as/pdveca62

Safari 7.1, OS X 10.9.5 (Mavericks)

HTML span Injection on parse()

Currently I grab the value on parse() and make it toLowerCase. Works pretty nice.

Now I wanted to wrap some special cases in span. I came up with this:

parse: function (value) {
  //console.log("parse");
  value = value.trim().toLowerCase();
  var find = ["mm", "in"];
  var replace = ["<span class='unit-mm'>mm</span>)", "<span class='unit-in'>in</span>"];
  var modValue = value.replaceArray(find, replace);
  return modValue;
},

The problem is that the Tag "22mm" will be displayed as text and not as a DOM injected span:
22mm

Is there a way to further inject DOM Elements to a found tag in the fashion of the deletion: true statement, that is able to append the close-label?
Or is it easier to listen to the insignia-evaluated event and then manipulate the DOM afterwards? How could a listener for that looks like?

EDIT:
In a broader question: How can I not only inject HTML but also set the class of the .nsg-tag as I would like to render/validate my tags with different designs for specific content. How can I do that? This basicly comes down to how one can use multiple instances in a single DOM with multiple .nsg-tag-styles.

Cheers
Mortimer

Only allow tags from horsey

What would be the sanest way to restrict the creation of tags that don't match horsey's autocomplete? I.e the user can't free form new tags, only choose from a list of existing.

In Internet Explorer, it is impossible to focus other inputs. Insignia constantly remains in focus.

I've tested this in IE9, IE10, and IE11. It does not occur in IE11.

.from() method in es5 file

Announced that IE7+ supported, but es5.js version contains .from() method that not supported in ie<=11

Keeping .nsg-tag attributes while updating

Hi,

I need to achieve something tricky with your plugin.
I am using the event 'add' to add an attribute to the tag (an id). It works like a charm for creating tags and results are stored in the database perfectly.

BUT I need to be able to update tags and keeping the same id.
Do you have any idea on how I can achieve this ?

My current code

function initInsignia(id) {
	// get the input
	var input = document.querySelector('#select-rows input.input-answer[data-id="' + id + '"]');
	// check if not already initialized
	if ($(input).hasClass('nsg-input')) {
		return;
	}
	// init
	var tagInput = insignia(input, {
		deletion: true,
		preventInvalid: true,
		delimiter: '\t'
	});

	// add event
	tagInput.on('add', (data, el) => {
		// create an id 
		$(el).attr('data-id', makeid());
		// if it is the first tag, add the 'correct' class, else 'incorrect'
		$(el).addClass($(input).parent().find('.nsg-tag').length === 1 ? 'correct' : 'incorrect').prepend(
			// add a button similar to the one for deletion to toggle 'correct'|'incorrect' status
			$('<span/>', { class: 'nsg-tag-toggle' }).click(function () {
				$(this).parent().toggleClass('incorrect').toggleClass('correct');
			})
		);
	});

	// nothing there
	tagInput.on('remove', (data) => {
		
	});

	// use TAB and ENTER to add tags
	input.addEventListener('keypress', function (e) {
		if (e.keyCode === 13 || e.keyCode === 9) {
			tagInput.refresh();
			e.preventDefault(); // prevent form submission
		}
	});

	return tagInput;
}

Delimiter option

Feature request
An option for selecting a delimiter that isn't space would be nice.

Also, without looking at the code more, not sure if an option to allow a custom key to tag-ify the test (e.g. pressing enter to turn the text into a tag) would be a good idea, or if it's more suited to external code using the API.

Make tag unchangeable

I am looking for a solution that, if the user clicks on the tag, it should not be editable. Anyone can provide the solution?

I tried to use free: false, but this is not working.

same as this issue: #20

Make tag unchangeable

Great plugin!

How can I stop users from changing a tag. For example when coupling with horsey, so I'm providing tags for selection and I want them to stay exactly as I provide them.

first thought was

readTag: function(e) {
    return false;
}

now I got the purpose of this option better :D
but maybe it's still capable of preventing it?

Ah to maybe better illustrate what I mean. Right now, when clicking on a rendered tag it's changing back to plain text (input mode) so I could rewrite it, how to block that?

Maybe setting up a click event on rendered tags which just returns false, would that work?
Actually just tried it, could be my lack of js, but couldn't catch clicks on tags..

`deletion: true` "crosses"?

I imagine that you intended a typical [x] icon to pop up when moused over (or normally) as a short cut to delete by clicking. But I don't see any "crosses" in the GUI in Fx & Chrome Win7.

Problem resetting an insignia field without destroying it

Hi Nicolas, I am using horsey & insignia on a field and am having trouble 'resetting' the it. It was my understanding that all I need to do is: set the value of the input to an empty string, then call .convert() on the element, but this is not the case..

I made, what feels like, a hacky solution to this:

// Setup insignia on the element
var tagInput = insignia(el);

// then when I want to reset, I run:
tagInput.destroy();
el.value = '';
tagInput = insignia(el);

What is the recommended way to achieve this?

`insignia.find()` does not exist

The method is documented but does not exist.

insignia dragula mode?

Looking at insignia, I wish it had dragula's drag-n-drop. Click / tap puts tags into edit mode. Could we hold-and-drag-and-drop to reorder?

Feature requests

I'm looking for an advanced tag input control. Insignia is almost what I need, except for a few features. I wonder, if Insignia can be adjusted to provide means to implement them.

• Store objects as tags. E.g. { kind: 'fruit', value: 'orange' } --> [fruit icon] orange. Or else provide render() method for me to render tags in a custom way: fruit:orange --> [fruit icon] orange. User would input metainformation for a tag (i.e.kind), for example, via a typeahead menu. I would like to keep tags editable as they are, and let user change the kind as well as value. Initially it would be OK if a such object tag would simply devolve to fruit:orange text upon edit.
• Auto-sortable tags. I need to be able to sort tags automatically, using complicated sort criteria. Ideally, I need to be able to provide sorting (not comparison) function to the Insignia.
• Line breaks. I need to be able to clear the line before certain tags. E.g. tag newline should always be placed on a beginning of a new line in the tag field (equivalent of always injecting <br/> before it). Probably could be done via render() method discussed above.
• Custom HTML. Optional. I'd like to be able to inject custom HTML before / after certain tags to provide extra UI elements (for example "insert another specific tag here" button).
• Typeahead. We discussed it in #4.

Placeholder option

Responsiveness improvements

If there is no JS support the user will get a classic input box where he/she can enter a string. If there is JS support, there will be additional features but the input field that is submitted will always be empty and you need to use javascript to collect the values. I think this requires unnecessary extra-work. Why not create a new hidden field that is populated/updated whenever the tags change? Or at least create an event that can be used to do that when the module is instanciated.

Or maybe the functionality is already there but the documentation is not clear for this scenario. Or I wasn't paying attention :)

Autocomplete option

Would be great if tags can be autocompleted from a given list.

Case insensitivity option

Would be great if an option could be added that recognizes e.g. JavaScript, Javascript and javascript as dupes.

Browser autocomplete email duplication

Version

Insignia: 5.0.0
Browser: Chrome 83.0.4103.116

How to reproduce

Add autocomplete HTML attribute

<input id='del' autocomplete="email">

In browser, select any browser's suggested emails.
The email will be duplicated.

Screenshot

Ajax values

awesome work,
how can we use twitter type ahead or any other auto complete to get values from server ?

thanks in advanced.