[Summary view] [Print] [Text view]

   1  @title Concepts: Sigils and Metadata
   2  @group concepts
   3  
   4  Explains Javelin's sigils and metadata.
   5  
   6  = Overview =
   7  
   8  Javelin introduces two major concepts, "sigils" and "metadata", which are core
   9  parts of the library but don't generally exist in other Javascript libraries.
  10  Both sigils and metadata are extra information you add to the DOM which Javelin
  11  can access. This document explains what they are, why they exist, and how you
  12  use them.
  13  
  14  = Sigils =
  15  
  16  Sigils are names attached to nodes in the DOM. They behave almost exactly like
  17  CSS class names: sigils are strings, each node may have zero or more sigils, and
  18  sigils are not unique within a document. Sigils convey semantic information
  19  about the structure of the document.
  20  
  21  It is reasonable to think of sigils as being CSS class names in a different,
  22  semantic namespace.
  23  
  24  If you're emitting raw tags, you specify sigils by adding a ##data-sigil##
  25  attribute to a node:
  26  
  27    lang=html
  28    <div data-sigil="newsfeed">
  29      <div data-sigil="story">
  30        ...
  31      </div>
  32      <div data-sigil="story">
  33        ...
  34      </div>
  35    </div>
  36  
  37  However, this should be considered an implementation detail and you should not
  38  rely on it excessively. In Javelin, use @{method:JX.Stratcom.hasSigil} to test
  39  if a node has a given sigil, and @{method:JX.Stratcom.addSigil} to add a sigil
  40  to a node.
  41  
  42  Javelin uses sigils instead of CSS classes to rigidly enforce the difference
  43  between semantic information and style information in the document. While CSS
  44  classes can theoretically handle both, the conflation between semantic and style
  45  information in a realistic engineering environment caused a number of problems
  46  at Facebook, including a few silly, preventable, and unfortunately severe bugs.
  47  
  48  Javelin separates this information into different namespaces, so developers and
  49  designers can be confident that changing CSS classes and presentation of a
  50  document will never change its semantic meaning. This is also why Javelin does
  51  not have a method to test whether a node has a CSS class, and does not have CSS
  52  selectors. Unless you cheat, Javelin makes it very difficult to use CSS class
  53  names semantically.
  54  
  55  This is an unusual decision for a library, and quite possibly the wrong tradeoff
  56  in many environments. But this was a continual source of problems at Facebook's
  57  scale and in its culture, such that it seemed to justify the measures Javelin
  58  takes to prevent accidents with style information having inadvertent or
  59  unrealized semantic value.
  60  
  61  = Metadata =
  62  
  63  Metadata is arbitrary pieces of data attached to nodes in the DOM. Metadata can
  64  be (and generally is) specified on the server, when the document is constructed.
  65  The value of metadata is that it allows handlers which use event delegation to
  66  distinguish between events which occur on similar nodes. For instance, if you
  67  have newsfeed with several "Like" links in it, your document might look like
  68  this:
  69  
  70    lang=html
  71    <div data-sigil="newsfeed">
  72      <div data-sigil="story">
  73        ...
  74        <a href="..." data-sigil="like">Like</a>
  75      </div>
  76      <div data-sigil="story">
  77        ...
  78        <a href="..." data-sigil="like">Like</a>
  79      </div>
  80    </div>
  81  
  82  You can install a listener using Javelin event delegation (see @{article:
  83  Concepts: Event Delegation} for more information) like this:
  84  
  85    lang=js
  86    JX.Stratcom.listen(
  87      'click',
  88      ['newsfeed', 'story', 'like'],
  89      function(e) {
  90        // ...
  91      });
  92  
  93  This calls the function you provide when the user clicks on a "like" link, but
  94  you need to be able to distinguish between the different links so you can know
  95  which story the user is trying to like. Javelin allows you to do this by
  96  attaching **metadata** to each node. Metadata is attached to a node by adding a
  97  ##data-meta## attribute which has an index into data later provided to
  98  @{method:JX.Stratcom.mergeData}:
  99  
 100    lang=html
 101    <div data-sigil="newsfeed">
 102      <div data-sigil="story" data-meta="0_0">
 103        ...
 104        <a href="..." data-sigil="like">Like</a>
 105      </div>
 106      <div data-sigil="story" data-meta="0_1">
 107        ...
 108        <a href="..." data-sigil="like">Like</a>
 109      </div>
 110    </div>
 111    ...
 112    <script type="text/javascript">
 113      JX.Stratcom.mergeData(0, [{"storyID" : 12345}, {"storyID" : 23456}]);
 114    </script>
 115  
 116  This data can now be accessed with @{method:JX.Stratcom.getData}, or with
 117  @{method:JX.Event.getNodeData} in an event handler:
 118  
 119    lang=js
 120    JX.Stratcom.listen(
 121      'click',
 122      ['newsfeed', 'story', 'like'],
 123      function(e) {
 124        var id = e.getNodeData('story').storyID;
 125        // ...
 126      });
 127  
 128  You can also add data to a node programmatically in Javascript with
 129  @{method:JX.Stratcom.addData}.