Extending the HTML Vocabulary

In my last post I described how to create your own vocabulary and why it is beneficial to do so. However in real life having different word definitions all over the place will make it difficult to track down which words are taken and which event handlers are in place.

That’s why I published vocabulary a couple weeks ago. vocabulary is a little library which helps to create a vocabulary in a structured way, like writing a book.

Getting started

Let’s assume you have a list of entries and each of them has a delete button to remove them from the list. My list example shows my next week’s shopping list :)

• Breaddelete
• Bananasdelete
• Applesdelete
• Cheesedelete
• Beerdelete
• More Beerdelete

1
2
3
4
5
6
7
8

<ul>
  <li id="entry-1"><span>Bread</span><button data-entry-id="entry-1">delete</button></li>
  <li id="entry-2"><span>Bananas</span><button data-entry-id="entry-2">delete</button></li>
  <li id="entry-3"><span>Apples</span><button data-entry-id="entry-3">delete</button></li>
  <li id="entry-4"><span>Cheese</span><button data-entry-id="entry-4">delete</button></li>
  <li id="entry-5"><span>Beer</span><button data-entry-id="entry-5">delete</button></li>    
  <li id="entry-6"><span>More Beer</span><button data-entry-id="entry-6">delete</button></li>
</ul>

Now it would be great if we could make all these delete buttons working in a way that we are able to reuse the functionality without binding event handlers over and over again.

Therefor we start using the vocabulary library. The vocabulary library defines three key terms: Dictionary, Chapter, Word

A Dictionary has to be defined in the vocabulary to organise actions. Imagine a Dictionary as a real book. A book gives the reader an index which is descriptive enough to not force him to look through all the words. In my example I’d call my Dictionary: shopping.

Also like books, the Dictionary may or may not have Chapters. A Chapter helps to improve organisation within a Dictionary. In my shopping example I could have a Chapter for grocery, clothes or furniture. For simplification I won’t use Chapters in my example though.

In our Dictionary we will find plenty of Words with a interpretation of it. The interpretation is basically the function which should be called when the word is requested. A Word is part of a Chapter or directly of a Dictionary.

Creating a first Dictionary

To make our example work we will start by annotating our markup with the proper Word.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<ul>
  <li id="entry-1">
      <span>Bread</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-1">delete</button>
  </li>
  <li id="entry-2">
      <span>Bananas</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-2">delete</button>
  </li>
  <li id="entry-3">
      <span>Apples</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-3">delete</button>
      </li>
  <li id="entry-4">
      <span>Cheese</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-4">delete</button>
      </li>
  <li id="entry-5">
      <span>Beer</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-5">delete</button>
  </li>
  <li id="entry-6">
      <span>More Beer</span>
      <button class="voc-action voc-shopping-deleteEntry" data-entry-id="entry-6">delete</button>
  </li>
</ul>

We added two standard CSS classes to the button. First voc-action which is a helper to make the vocabulary library faster by looking for actions. Second with voc-shopping-deleteEntry we annotated the button to reveal its purpose. For a human reader it is now clear what the button is intended to do. The button is now referenced to the shopping Dictionary where it calls the deleteEntry Word. You may try this example now with the debug build of vocabulary and you will get an “action is not defined for deleteEntry” message in the console.

Let’s continue by defining the action for the Word.

1
2
3
4
5

vocabulary.dict('shopping').add('deleteEntry', function (
    var listEntry = document.getElementById(opt.entryId); // for instance li#entry-1

    listEntry.parentNode.removeChild(listEntry);
});

In this code block three important things happened. First we created a Dictionary called shopping by using the dict() function. Second we added a word deleteEntry to the Dictionary with its function handler by calling add(). Third in the passed function we are accessing the first argument what I called opt here. And opt contains all data attributes which are defined on the element. That means all data-attributes of our button, like data-entry-id, are passed to the function.

• Bread delete
• Bananas delete
• Apples delete
• Cheese delete
• Beer delete
• More Beer delete

Discoverable Dictionary

Now we know how easy it is to understand the purpose of existing markup without the need to look for some hidden event handler and how to create a new word definition. However not all available actions might be used on the same page or may be used in a markup which is loaded later. Though it is still important to know what actions are available. That’s why the vocabulary is self exposable. So just open your browser console and start typing.