velge

    1.0.0-alpha • Public • Published

    Build Status NPM version

    Velge (ch•oose)

    1. verb - Pick out or select as being the most appropriate of two or more alternatives.
    2. noun - Nimble autocompleting tag management in javascript

    Velge Example

    Velge is a nimble tag management widget. It is written in pure javascript, has no dependencies, is fully tested with Mocha, and can be installed via NPM or Bower.

    Some of the features:

    • Event emission for all state and ui events.
    • Fuzzy pattern matching for searching.
    • Customizable sorting, validation, normalization.
    • Keyboard shortcuts for navigation, quick submission, and removal.

    The library is very lightweight and constructed in a way that allows for easy feature additions. We'd love more people to use it, request features, and contribute!

    Installation

    The simplest way is through NPM:

    npm install velge --save

    You'll then want to import the compiled .js and .css:

    <link href="/node_modules/velge/dist/velge.css" rel="stylesheet" type="text/css">
    <script src="/node_modules/velge/dist/velge.min.js"></script>

    If you prefer to import velge directly you can import it directly through CommonJS:

    var velge = require('velge');

    Usage

    Velge can be attached to any container. The structure isn't of any importance:

    <div class='velge'></div>

    Initialize velge with a selector for the container and customization options:

    var container = document.getElementById('container');
     
    var velge = new Velge(container, {
      placeholder: 'Choose'
    });

    Any choices that are provided at initialization will be used to pre-populate the dropdown and chosen lists.

    Loading Tags

    All tag matching is performed locally. As such you must load in all possible choices and an optional set of chosen values:

    velge
      .add({ name: 'orange' })
      .add({ name: 'berry' })
      .add({ name: 'tangy' });
     
    velge
      .choose({ name: 'apple' })
      .choose({ name: 'juicy' });
     
    // Choices: 'orange', 'berry', 'tangy', 'apple', 'juicy'

    Tag objects can be anything that have a "name" property. Whatever object is loaded is what will be passed to any callbacks.

    It isn't always tidy to add choices and chosen separately. For convenience they can also be loaded during construction:

    new Velge(element, {
      choices: [
        { name: 'macintosh' },
        { name: 'cortland' }
      ],
      chosen: [
        { name: 'jonagold' },
        { name: 'snow sweet' }
      ]
    });

    Persisting

    The velge instance emits events for persisting changes after tags have been added, chosen, rejected, or deleted.

    velge
      .on('add',    function(object) { console.log('added', object) })
      .on('choose', function(object) { console.log('chose', object) })
      .on('reject', function(object) { console.log('reject', object) })
      .on('delete', function(object) { console.log('deleted', object) });

    You may prefer to save all changes at the same time, maybe via a more form-like submit action. That can be achieved by using getChosen:

    var chosen = velge.getChosen();
    var names  = chosen.map(function(choice) { return choice.name });

    Other Events

    Sometimes it is helpful to be notified of DOM level events within velge. Currently velge provides focus events which are bubbled up from the input area.

    velge
      .on('focus', function(event) { console.log('has focus'); })
      .on('blur',  function(event) { console.log('lost focus'); })

    Sorting

    By default choices will be displayed in the order they were added. It is possible to specify a sorting behavior during construction, or afterwards:

    var comparitor = function(a, b) {
      if (a.name > b.name)      { return 1;  }
      else if (a.name < b.name) { return -1; }
      else                      { return 0;  }
    };
     
    var velge = new Velge(element, {
      comparitor: comparitor
    })
     
    // Setting options will trigger an immediate re-sort
    velge.setOptions({ comparitor: function(a, b) {
      if (a.createdAt > b.createdAt)      { return 1;  }
      else if (a.createdAt < b.createdAt) { return -1; }
      else                                { return 0;  }
    });

    Limitation Mode

    While velge is designed as an interface for applying multiple "tags" to a resource it can also operate in single, limitation, mode. Under single mode only the most recent tag will be kept, all others will be unchosen.

    var velge = new Velge(element, { limitation: true })

    Error Handling

    Because velge displays all tag additions instantly it can easily fall out of sync with the underlying collection. If, for example, an ajax request fails you can rollback the addition:

    var addCallback = function(choice) {
      $.ajax({
        data: choice,
        type: "POST",
        url:  "/api/resource/1/tags"
      }).fail(function(error) {
        velge.reject(choice);
      })
    };

    Development

    The project is built with modules from NPM. Simply run:

    npm install

    Once all modules are installed you're all set to test, lint, or build.

    npm run test  # scripts/test 
    npm run lint  # scripts/lint 
    npm run build # scripts/build 

    License

    MIT, see LICENSE.txt for details.

    Keywords

    none

    Install

    npm i velge

    DownloadsWeekly Downloads

    1

    Version

    1.0.0-alpha

    License

    MIT

    Last publish

    Collaborators

    • sorentwo