[Summary view] [Print] [Text view]

   1  @title Concepts: Behaviors
   2  @group concepts
   3  
   4  Javelin behaviors help you glue pieces of code together.
   5  
   6  = Overview =
   7  
   8  Javelin behaviors provide a place for you to put glue code. For instance, when
   9  a page loads, you often need to instantiate objects, or set up event listeners,
  10  or alert the user that they've won a hog, or create a dependency between two
  11  objects, or modify the DOM, etc.
  12  
  13  Sometimes there's enough code involved here or a particular setup step happens
  14  often enough that it makes sense to write a class, but sometimes it's just a
  15  few lines of one-off glue. Behaviors give you a structured place to put this
  16  glue so that it's consistently organized and can benefit from Javelin
  17  infrastructure.
  18  
  19  = Behavior Basics =
  20  
  21  Behaviors are defined with @{function:JX.behavior}:
  22  
  23    lang=js
  24    JX.behavior('win-a-hog', function(config, statics) {
  25      alert("YOU WON A HOG NAMED " + config.hogName + "!");
  26    });
  27  
  28  They are called with @{function:JX.initBehaviors}:
  29  
  30    lang=js
  31    JX.initBehaviors({
  32      "win-a-hog" : [{hogName : "Ethel"}]
  33    });
  34  
  35  Normally, you don't construct the @{function:JX.initBehaviors} call yourself,
  36  but instead use a server-side library which manages behavior initialization for
  37  you. For example, using the PHP library:
  38  
  39    lang=php
  40    $config = array('hogName' => 'Ethel');
  41    JavelinHelper::initBehaviors('win-a-hog', $config);
  42  
  43  Regardless, this will alert the user that they've won a hog (named Ethel, which
  44  is a good name for a hog) when they load the page.
  45  
  46  The callback you pass to @{function:JX.behavior} should have this signature:
  47  
  48    lang=js
  49    function(config, statics) {
  50      // ...
  51    }
  52  
  53  The function will be invoked once for each configuration dictionary passed to
  54  @{function:JX.initBehaviors}, and the dictionary will be passed as the
  55  ##config## parameter. For example, to alert the user that they've won two hogs:
  56  
  57    lang=js
  58    JX.initBehaviors({
  59      "win-a-hog" : [{hogName : "Ethel"}, {hogName: "Beatrice"}]
  60    });
  61  
  62  This will invoke the function twice, once for each ##config## dictionary.
  63  Usually, you invoke a behavior multiple times if you have several similar
  64  controls on a page, like multiple @{class:JX.Tokenizer}s.
  65  
  66  An initially empty object will be passed in the ##statics## parameter, but
  67  changes to this object will persist across invocations of the behavior. For
  68  example:
  69  
  70    lang=js
  71    JX.initBehaviors('win-a-hog', function(config, statics) {
  72      statics.hogsWon = (statics.hogsWon || 0) + 1;
  73  
  74      if (statics.hogsWon == 1) {
  75        alert("YOU WON A HOG! YOUR HOG IS NAMED " + config.hogName + "!");
  76      } else {
  77        alert("YOU WON ANOTHER HOG!!! THIS ONE IS NAMED " + config.hogName + "!");
  78      }
  79    }
  80  
  81  One way to think about behaviors are that they take the anonymous function
  82  passed to @{function:JX.behavior} and put it in a private Javelin namespace,
  83  which you access with @{function:JX.initBehavior}.
  84  
  85  Another way to think about them is that you are defining methods which represent
  86  the entirety of the API exposed by the document. The recommended approach to
  87  glue code is that the server interact with Javascript on the client //only// by
  88  invoking behaviors, so the set of available behaviors represent the complete set
  89  of legal interactions available to the server.
  90  
  91  = History and Rationale =
  92  
  93  This section explains why behaviors exist and how they came about. You can
  94  understand and use them without knowing any of this, but it may be useful or
  95  interesting.
  96  
  97  In early 2007, Facebook often solved the "glue code" problem through the use
  98  of global functions and DOM Level 0 event handlers, by manually building HTML
  99  tags in PHP:
 100  
 101    lang=php
 102    echo '<a href="#" '.
 103         'onclick="win_a_hog('.escape_js_string($hog_name).'); return false;">'.
 104         'Click here to win!'.
 105         '</a>';
 106  
 107  (This example produces a link which the user can click to be alerted they have
 108  won a hog, which is slightly different from the automatic alert in the other
 109  examples in this document. Some subtle distinctions are ignored or glossed
 110  over here because they are not important to understanding behaviors.)
 111  
 112  This has a wide array of technical and architectural problems:
 113  
 114    - Correctly escaping parameters is cumbersome and difficult.
 115    - It resists static analysis, and is difficult to even grep for. You can't
 116      easily package, minify, or determine dependencies for the piece of JS in
 117      the result string.
 118    - DOM Level 0 events have a host of issues in a complex application
 119      environment.
 120    - The JS global namespace becomes polluted with application glue functions.
 121    - The server and client are tightly and relatively arbitrarily coupled, since
 122      many of these handlers called multiple functions or had logic in the
 123      strings. There is no structure to the coupling, so many callers relied on
 124      the full power of arbitrary JS execution.
 125    - It's utterly hideous.
 126  
 127  In 2007/2008, we introduced @{function@libphutil:jsprintf} and a function called
 128  onloadRegister() to solve some of the obvious problems:
 129  
 130    lang=php
 131    onloadRegister('win_a_hog(%s);', $hog_name);
 132  
 133  This registers the snippet for invocation after DOMContentReady fires. This API
 134  makes escaping manageable, and was combined with recommendations to structure
 135  code like this in order to address some of the other problems:
 136  
 137    lang=php
 138    $id = uniq_id();
 139    echo '<a href="#" id="'.$id.'">Click here to win!</a>';
 140    onloadRegister('new WinAHogController(%s, %s);', $id, $hog_name);
 141  
 142  By 2010 (particularly with the introduction of XHP) the API had become more
 143  sophisticated, but this is basically how most of Facebook's glue code still
 144  works as of mid-2011. If you view the source of any page, you'll see a bunch
 145  of ##onloadRegister()## calls in the markup which are generated like this.
 146  
 147  This mitigates many of the problems but is still fairly awkward. Escaping is
 148  easier, but still possible to get wrong. Stuff is a bit easier to grep for, but
 149  not much. You can't get very far with static analysis unless you get very
 150  complex. Coupling between the languages has been reduced but not eliminated. And
 151  now you have a bunch of classes which only really have glue code in them.
 152  
 153  Javelin behaviors provide a more structured solution to some of these problems:
 154  
 155    - All your Javascript code is in Javascript files, not embedded in strings in
 156      in some host language on the server side.
 157    - You can use static analysis and minification tools normally.
 158    - Provided you use a reasonable server-side library, you can't get escaping
 159      wrong.
 160    - Coupling is reduced because server only passes data to the client, never
 161      code.
 162    - The server declares client dependencies explicitly, not implicitly inside
 163      a string literal. Behaviors are also relatively easy to grep for.
 164    - Behaviors exist in a private, structured namespace instead of the global
 165      namespace.
 166    - Separation between the document's layout and behavior is a consequence of
 167      the structure of behaviors.
 168    - The entire interface the server may invoke against can be readily inferred.
 169  
 170  Note that Javelin does provide @{function:JX.onload}, which behaves like
 171  ##onloadRegister()##. However, its use is discouraged.
 172  
 173  The two major downsides to the behavior design appear to be:
 174  
 175    - They have a higher setup cost than the ad-hoc methods, but Javelin
 176      philosophically places a very low value on this.
 177    - Because there's a further setup cost to migrate an existing behavior into a
 178      class, behaviors sometimes grow little by little until they are too big,
 179      have more than just glue code, and should have been refactored into a
 180      real class some time ago. This is a pretty high-level drawback and is
 181      manageable through awareness of the risk and code review.