Vocabulary

Vocabulary connects semantic Markup with corresponding Javascript functionality.

Short Story

Let's assume you have a button which should execute some Javascript code

<button id="myButton">Click me</button>

Rather then writing a piece of code which binds an event handler and executes the logic as you used to do it ...

var btn = document.getElementById('myButton');

btn.addEventListener('click', function () {
  alert('you deleted an entry');
});

... you would annotate your markup properly ...

<button id="myButton" class="voc-action voc-todo-deleteEntry">Click me</button>

and allow people to understand the purpose of the markup without searching through your source code.

You will find the long story on my blog.

Concept

Think of your desirable actions as a unique word in a vocabulary. deleteEntry would be one of these words. Obviously deleteEntry is not a really unique expression in a global scope. To make the creation of unique expressions easier we will have multiple dictionaries in our vocabulary. In the previous example we created a dictionary called todo. Within this dictionary deleteEntry was unique. However dictionaries can be huge and hard to find a word in it. Therefor a dictionary may have chapters. So that a word does not need to be unique in a dictionary anymore but in one of its chapters.

Technically vocabulary provides 3 broad terms: Dictionary, Chapter, Word

Vocabulary -> has dictionaries -> [has chapters ->] has words

Basic Usage

To define a new word we will access the global object called vocabulary.

window.vocabulary;

We will create a new dictionary or access an existing one by using the dict() method.

vocabulary.dict('todo');

Now we are able to add new words to the dictionary.

vocabulary.dict('todo').add('deleteEntry', function (opt) {
	console.log('entry deleted');
});

Or to one of its chapters.

vocabulary.dict('todo').chap('foo').add('deleteEntry', function (opt) {
	console.log('entry deleted');
});

Since we have our code in place, we could simple trigger it.

vocabulary.dict('todo').execute('deleteEntry');

Or properly annotate our button (or any other HTML markup) to trigger the action

<button id="myButton" class="voc-action voc-todo-deleteEntry">Click me</button>

Additional Things

.voc-action

The voc-action css class has to be added to the element which is annotated with the action. This is necessary for performance reasons, because the actions will be detected through event delegation. Setting this will avoid having performance issues when huge dictionaries are in place.

Handler arguments

The handler function which was defined through add() will have the this object set to the Chapter or Dictionary if directly attached to it. Additionally an object is passed as the first argument. It will contain these default properties.

{
	target: HTMLElement, // element which contained the defined action
	originalEvent: Event // browser event
}

passing options

As described the first argument of the handler function will contain an object. This object contains a key/value list of values passed through data- attributes.

<button id="myButton" class="voc-action voc-todo-deleteEntry" data-entry-name="foo">Click me</button>

vocabulary.dict('todo').add('deleteEntry', function (opt) {
  console.log('entry '+ opt.entryName +' deleted');
});

The deleteEntry will be able to access the value through its first argument opt.entryName

Events

Word definitions are independent of the event type and usually reacts on click events. Though through annotation of the css class it is possible to bind the function to another event.

<select class="voc-action voc-todo-updateEntry--change">
  <option>Chinese</option>
  <option selected>English</option>
  <option>French</option>
  <option>German</option>
  <option>Italian</option>
  <option>Japanese</option>
  <option>Korean</option>
  <option>Portuguese</option>
  <option>Spanish</option>
</select>

The added double dash will limit the execution of the handler to change events. Most of the default browser events are observed by the vocabulary. Adding new events which can be used is done through a build configuration or by calling vocabulary.addEvent('customEvent').

API Documentation

The JSdoc is build under /docs or viewable through rawgit. Sorry for the ugly default template.

How to add Plugins/Helpers

coming soon

Example

I adapted the todo-mvc example from jQuery to vocabulary quickly. Available under /example

How to Customize your Build

You may customize several build options before running grunt to change the prefix or the global namespace. config.json should be self-explainable.

Dependencies

none

Browser Support

IE10+, evergreens Chrome, Firefox, Android 3.0+, iOS 5.0+

classList polyfill for IE 9.0 addEventListener polyfill for IE 8.0 and older