Skip to content
This repository
Browse code

Added a prereq for doing the code example, added a link to get Flickr…

… API key, and added more information in the implementation notes.
  • Loading branch information...
commit 351e25f4b1400e163859fd9cc35aea364c07bb6b 1 parent f0af949
Joe Catera authored October 19, 2012

Showing 1 changed file with 122 additions and 91 deletions. Show diff stats Hide diff stats

  1. 213  docs/dev_guide/code_exs/binding_events.rst
213  docs/dev_guide/code_exs/binding_events.rst
Source Rendered
@@ -11,7 +11,7 @@ Summary
11 11
 
12 12
 This example shows how to bind events to a mojit, configure code to run on the client, and make AJAX 
13 13
 calls to the YQL Web service. The application listens for events and then makes AJAX calls to 
14  
-YQL to get Flickr photo information.
  14
+YQL to get Flickr photo information. 
15 15
 
16 16
 The following topics will be covered:
17 17
 
@@ -20,6 +20,12 @@ The following topics will be covered:
20 20
 - binding events through the ``mojitProxy`` object
21 21
 - making AJAX calls to YQL from the binder
22 22
 
  23
+Prerequisite
  24
+------------
  25
+
  26
+You will need to `get a Flickr API key <http://www.flickr.com/services/api/keys/apply/>`_
  27
+to run this example.
  28
+
23 29
 Implementation Notes
24 30
 ====================
25 31
 
@@ -70,9 +76,12 @@ get Flickr photo information. To access the utility in your model, specify ``'yq
70 76
 This code example uses the ``flickr.photos.search`` table to get information for photos that have a 
71 77
 title, description, or tags containing a string. For example, the YQL statement below returns Flickr 
72 78
 photo information for those photos that have a title, description, or tags containing the string 
73  
-"Manhattan". Open the query in the YQL Console and click **TEST** to see the returned XML response.
  79
+"Manhattan". 
  80
+
  81
+Using you Flickr API key, run the query in the `YQL Console <http://developer.yahoo.com/yql/console/>`_ 
  82
+and click **TEST** to see the returned XML response.
74 83
 
75  
-`select * from flickr.photos.search where text="Manhattan" <http://developer.yahoo.com/yql/console/#h=select%20*%20from%20flickr.photos.search%20where%20text%3D%22Manhattan%22>`_
  84
+``select * from flickr.photos.search where text="Manhattan" and api_key="{your_flickr_api_key}"
76 85
 
77 86
 The returned response contains photo information in the ``photo`` element. You extract the ``farm``, 
78 87
 ``server``, ``id``, and ``secret`` attributes from each photo element to create the photo URI as 
@@ -104,10 +113,10 @@ the controller through the ``callback`` function.
104 113
        getData: function(query, start, count, callback) {
105 114
           var q = null;
106 115
          // Get Flickr API key: http://www.flickr.com/services/api/keys/apply/
107  
-         var API_KEY = "{your_api_key}";
  116
+         var API_KEY = "{your_flickr_api_key}";
108 117
          start = parseInt(start) || 0;
109 118
          count = parseInt(count) || 10;
110  
-         q = 'select * from flickr.photos.search(' + start + ',' + count + ')  where text="%' + query + '%" and api_key="' + API_KEY+'"';
  119
+         q = 'select * from flickr.photos.search(' + start + ',' + count + ')  where text="%' + query + '%" and api_key="' + API_KEY + '"';
111 120
          Y.YQL(q, function(rawData) {
112 121
            if (!rawData.query.results) {
113 122
              callback([]);
@@ -143,33 +152,33 @@ from a Mojit <calling_yql.html>`_. For more information about YQL, see the
143 152
 Binding Events
144 153
 --------------
145 154
 
146  
-This section will discuss the basics of binding events in Mojito and then look at the binder used in 
147  
-this code example.
  155
+This section will discuss the basics of binding events in Mojito and then look at the 
  156
+binder used in this code example.
148 157
 
149 158
 Binder Basics
150 159
 #############
151 160
 
152  
-A mojit may have zero, one, or many binders within the ``binders`` directory. Each binder will be 
153  
-deployed to the browser along with the rest of the mojit code, where the client-side Mojito runtime 
154  
-will call it appropriately.  On the client, the binder has a proxy object (``mojitProxy``) for 
155  
-interacting with the mojit it represents as well as with other mojits on the page. 
156  
-Methods can be called from the ``mojitProxy`` object that allow binders to listen for and fire 
157  
-events.
  161
+A mojit may have zero, one, or many binders within the ``binders`` directory. Each binder 
  162
+will be deployed to the browser along with the rest of the mojit code, where the client-side 
  163
+Mojito runtime will call it appropriately.  On the client, the binder has a proxy 
  164
+object (``mojitProxy``) for interacting with the mojit it represents as well as with other 
  165
+mojits on the page. Methods can be called from the ``mojitProxy`` object that allow 
  166
+binders to listen for and fire events.
158 167
 
159  
-The binder consists of a constructor, an initializer, and a bind function. The following describes 
160  
-each component and indicates when the ``mojitProxy`` object can be used.
  168
+The binder consists of a constructor, an initializer, and a bind function. The following 
  169
+describes each component and indicates when the ``mojitProxy`` object can be used.
161 170
 
162  
-- **constructor** - creates the namespace for your binder that wraps the initialization code and 
163  
-  binder.
164  
-- **initializer** - is passed the ``mojitProxy`` where it can be stored and used to listen and fire 
165  
-  events with other binders. The ``mojitProxy`` is the only gateway back into the Mojito framework 
166  
-  for your binder.
167  
-- **bind** - is a function that is passed a ``Y.Node`` instance that wraps the DOM node representing 
168  
-  this mojit instance. The DOM event handlers for capturing user interactions should be attached in 
169  
-  this function.
  171
+- **constructor** - creates the namespace for your binder that wraps the initialization 
  172
+  code and binder.
  173
+- **initializer** - is passed the ``mojitProxy`` where it can be stored and used to listen 
  174
+  and fire events with other binders. The ``mojitProxy`` is the only gateway back into the 
  175
+  Mojito framework for your binder.
  176
+- **bind** - is a function that is passed a ``Y.Node`` instance that wraps the DOM node 
  177
+  representing this mojit instance. The DOM event handlers for capturing user interactions 
  178
+  should be attached in this function.
170 179
 
171  
-The skeleton of the ``binders/index.js`` file below illustrates the basic structure of the binder. 
172  
-For more information, see `Mojito Binders <../intro/mojito_binders.html>`_.
  180
+The skeleton of the ``binders/index.js`` file below illustrates the basic structure of the 
  181
+binder. For more information, see `Mojito Binders <../intro/mojito_binders.html>`_.
173 182
 
174 183
 .. code-block:: javascript
175 184
 
@@ -196,9 +205,9 @@ This code example uses the binder ``PageMojitBinder`` to perform the following:
196 205
 - invoke the ``index`` method of the controller through the ``mojitProxy`` object
197 206
 - create an overlay with Flickr photo information received from YQL
198 207
 
199  
-The ``binders/index.js`` for this code example is long and fairly involved, so we will dissect and 
200  
-analyze the code.  Let's begin by looking at the ``bind`` function of ``index.js``, which allows 
201  
-mojits to attach DOM event handlers.
  208
+The ``binders/index.js`` for this code example is long and fairly involved, so we will 
  209
+dissect and analyze the code.  Let's begin by looking at the ``bind`` function of 
  210
+``index.js``, which allows mojits to attach DOM event handlers.
202 211
 
203 212
 In this code snippet of ``binders/index.js``, the ``bind`` function contains the nested 
204 213
 ``updateDOM`` function that updates node content and attaches event handlers. Using the 
@@ -230,9 +239,10 @@ controller. The callback ``updateDOM`` is passed to ``index`` to update the cont
230 239
    ...
231 240
 
232 241
 
233  
-The event handler for mouseovers and mouseouts are handled by the ``showOverlay`` function, which 
234  
-creates the overlay containing photo information. In the code snippet below,  ``showOverlay`` makes 
235  
-an AJAX call to YQL to get photo data that is placed in an unordered list for the overlay.
  242
+The event handler for mouseovers and mouseouts are handled by the ``showOverlay`` function, 
  243
+which creates the overlay containing photo information. In the code snippet below, 
  244
+``showOverlay`` makes an AJAX call to YQL to get photo data that is placed in an unordered 
  245
+list for the overlay.
236 246
 
237 247
 .. code-block:: javascript
238 248
 
@@ -251,7 +261,7 @@ an AJAX call to YQL to get photo data that is placed in an unordered list for th
251 261
            Y.log('IMAGE ID: ' + imageId);
252 262
            target.addClass('overlayed');
253 263
            // Query for the image metadata
254  
-           var query = 'select * from flickr.photos.info where photo_id="' + imageId + '"';
  264
+           var query = 'select * from flickr.photos.info where photo_id="' + imageId + '" and api_key="' + {your_flickr_api_key} + '"';
255 265
            thatNode.one('#display').setContent('Loading ...');
256 266
            Y.YQL(query, function(raw) {
257 267
              if (!raw.query.results.photo) {
@@ -275,9 +285,10 @@ an AJAX call to YQL to get photo data that is placed in an unordered list for th
275 285
      }
276 286
    ...
277 287
 
278  
-Thus far, we've looked at the event handlers, but not the actual binding of the handlers to nodes. 
279  
-At the end of the ``bind`` function, you'll see three important lines (shown below) that 
280  
-bind the ``flipper`` and ``showOutlay`` functions to handle click and mouseover events.
  288
+Thus far, we've looked at the event handlers, but not the actual binding of the handlers 
  289
+to nodes. At the end of the ``bind`` function, you'll see three important lines 
  290
+(shown below) that bind the ``flipper`` and ``showOutlay`` functions to handle click and 
  291
+mouseover events.
281 292
 
282 293
 .. code-block:: javascript
283 294
 
@@ -292,15 +303,43 @@ bind the ``flipper`` and ``showOutlay`` functions to handle click and mouseover
292 303
      }
293 304
    ...
294 305
 
295  
-After a little analysis, the full ``binders/index.js`` below should be easier to understand. The 
296  
-binder attaches event handlers to nodes, invokes a function in the controller, and updates the 
297  
-content in the template. The binder also has a couple of helper functions for parsing and requires 
298  
-the IO and YQL modules, which are specified in the ``requires`` array.
  306
+After a little analysis, the full ``binders/index.js`` below should be easier to 
  307
+understand. The binder attaches event handlers to nodes, invokes a function in the 
  308
+controller, and updates the content in the template. The binder also has a couple of 
  309
+helper functions for parsing and requires the IO and YQL modules, which are specified in 
  310
+the ``requires`` array.
299 311
 
300 312
 .. code-block:: javascript
301 313
 
302 314
    YUI.add('PagerMojitBinder', function(Y, NAME) {
  315
+     var API_KEY = '{your_api_key}';
  316
+     function parseImageId(link) {
  317
+       var matches = link.match(/com\/(\d+)\/(\d+)_([0-9a-z]+)\.jpg$/);
  318
+       return matches[2];
  319
+     }
  320
+     function parsePage(link) {
  321
+       var matches = link.match(/page=(\d+)/);
  322
+       return matches[1];
  323
+     }
  324
+
  325
+     /**
  326
+     * The PagerMojitBinder module.
  327
+     * @module PagerMojitBinder
  328
+     */
  329
+     /**
  330
+     * Constructor for the Binder class.
  331
+     *
  332
+     * @param mojitProxy {Object} The proxy to allow
  333
+     * the binder to interact with its owning mojit.
  334
+     * @class Binder
  335
+     * @constructor
  336
+     */
303 337
      Y.namespace('mojito.binders')[NAME] = {
  338
+       /**
  339
+       * Binder initialization method, invoked
  340
+       * after all binders on the page have
  341
+       * been constructed.
  342
+       */
304 343
        init: function(mojitProxy) {
305 344
          this.mojitProxy = mojitProxy;
306 345
        },
@@ -343,7 +382,7 @@ the IO and YQL modules, which are specified in the ``requires`` array.
343 382
              Y.log('IMAGE ID: ' + imageId);
344 383
              target.addClass('overlayed');
345 384
              // Query for the image metadata
346  
-             var query = 'select * from flickr.photos.info where photo_id="' + imageId + '"';
  385
+             var query = 'select * from flickr.photos.info where photo_id="' + imageId + '" and api_key="' + API_KEY + '"';
347 386
              thatNode.one('#display').setContent('Loading ...');
348 387
              Y.YQL(query, function(raw) {
349 388
                if (!raw.query.results.photo) {
@@ -370,26 +409,18 @@ the IO and YQL modules, which are specified in the ``requires`` array.
370 409
          thatNode.all('#nav a').on('click', flipper, this);
371 410
        }
372 411
      };
373  
-     function parseImageId(link) {
374  
-       var matches = link.match(/com\/(\d+)\/(\d+)_([0-9a-z]+)\.jpg$/);
375  
-       return matches[2];
376  
-     }
377  
-     function parsePage(link) {
378  
-       var matches = link.match(/page=(\d+)/);
379  
-       return matches[1];
380  
-     }
381  
-   }, '0.0.1', {requires: ['mojito', 'yql', 'io', 'dump', 'mojito-client']});
382  
-
  412
+   }, '0.0.1', {requires: ['yql', 'io', 'dump']});
383 413
 Using Paging
384 414
 ------------
385 415
 
386  
-The paging for this code example relies on the application configuration to set route paths and the 
387  
-controller to create links to access previous and next pages.
  416
+The paging for this code example relies on the application configuration to set route 
  417
+paths and the controller to create links to access previous and next pages.
388 418
 
389  
-The ``routes.json`` file below configures two route paths for HTTP GET calls made on the root path. 
390  
-The ``perpage`` configuration, however, requires a query string with the ``page`` parameter, 
391  
-which is used for paging. The ``page`` parameter has the value ``:page``, which is a variable that 
392  
-is assigned a value by the controller that we're going to look shortly.
  419
+The ``routes.json`` file below configures two route paths for HTTP GET calls made on the 
  420
+root path. The ``perpage`` configuration, however, requires a query string with the 
  421
+``page`` parameter, which is used for paging. The ``page`` parameter has the value 
  422
+``:page``, which is a variable that is assigned a value by the controller that we're 
  423
+going to look shortly.
393 424
 
394 425
 .. code-block:: javascript
395 426
 
@@ -416,12 +447,13 @@ The controller for ``PagerMojit`` performs several functions:
416 447
 - calls the ``getData`` function in the model to get photo data
417 448
 - creates URLs for the **next** and **prev** links
418 449
 
419  
-The `Params addon <../../api/classes/Params.common.html>`_ allows you to access variables from the 
420  
-query string parameters, the POST request bodies, or the routing systems URLs. In this code example, 
421  
-you use the ``getFromMerged`` method, which merges the parameters from the query string, POST request 
422  
-body, and the routing system URLs to give you access to all of the parameters. In the code snippet 
423  
-taken from ``controller.server.js`` below, the ``getFromMerged`` method is used to get the value for 
424  
-the ``page`` parameter and then calculate the index of the first photo to display:
  450
+The `Params addon <../../api/classes/Params.common.html>`_ allows you to access variables 
  451
+from the query string parameters, the POST request bodies, or the routing systems URLs. 
  452
+In this code example, you use the ``getFromMerged`` method, which merges the parameters 
  453
+from the query string, POST request body, and the routing system URLs to give you access 
  454
+to all of the parameters. In the code snippet taken from ``controller.server.js`` below, 
  455
+the ``getFromMerged`` method is used to get the value for the ``page`` parameter and then 
  456
+calculate the index of the first photo to display:
425 457
 
426 458
 .. code-block:: javascript
427 459
 
@@ -439,11 +471,11 @@ the ``page`` parameter and then calculate the index of the first photo to displa
439 471
       }
440 472
    ...
441 473
 
442  
-To get the photo data, the controller depends on the model to call YQL to query the Flickr API. 
443  
-Using ``actionContext.models.{model_name}`` lets you get a reference to the model. 
444  
-In this example controller,  the model of the ``PagerMojit`` is accessed through 
445  
-``actionContext.models.PageMojit``, allowing you to call ``getData`` and get the returned data from 
446  
-YQL in the callback function.
  474
+To get the photo data, the controller depends on the model to call YQL to query the 
  475
+Flickr API. Using ``actionContext.models.{model_name}`` lets you get a reference to the 
  476
+model. In this example controller,  the model of the ``PagerMojit`` is accessed through 
  477
+``actionContext.models.PageMojit``, allowing you to call ``getData`` and get the returned 
  478
+data from YQL in the callback function.
447 479
 
448 480
 .. code-block:: javascript
449 481
 
@@ -477,12 +509,12 @@ YQL in the callback function.
477 509
    };
478 510
    ...
479 511
 
480  
-The URLs for the **prev** and **next** links are created by passing the mojit instance, the method, 
481  
-and the query string parameters to the ``make`` method from the ``Url`` addon. The code snippet 
482  
-below creates the query string parameters with the 
483  
-`YUI QueryString module <http://yuilibrary.com/yui/docs/api/modules/querystring.html>`_. If the 
484  
-query string created by ``Y.QueryString.stringify`` is "page=2" , ``actionContext.url.make`` would 
485  
-return the URL ``{domain_name}:8666/?page=2``.
  512
+The URLs for the **prev** and **next** links are created by passing the mojit instance, 
  513
+the method, and the query string parameters to the ``make`` method from the ``Url`` addon. 
  514
+The code snippet below creates the query string parameters with the 
  515
+`YUI QueryString module <http://yuilibrary.com/yui/docs/api/modules/querystring.html>`_. 
  516
+If the query string created by ``Y.QueryString.stringify`` is "page=2" , 
  517
+``actionContext.url.make`` would return the URL ``{domain_name}:8666/?page=2``.
486 518
 
487 519
 .. code-block:: javascript
488 520
 
@@ -496,9 +528,9 @@ return the URL ``{domain_name}:8666/?page=2``.
496 528
      }
497 529
    ...
498 530
 
499  
-Stitching the above code snippets together, we have the ``controller.server.js`` below. The 
500  
-``index`` function relies on the model for data and the ``createLink`` function to create URLs for 
501  
-the **next** and **prev** links.
  531
+Stitching the above code snippets together, we have the ``controller.server.js`` below. 
  532
+The ``index`` function relies on the model for data and the ``createLink`` function to 
  533
+create URLs for the **next** and **prev** links.
502 534
 
503 535
 .. code-block:: javascript
504 536
 
@@ -574,8 +606,8 @@ To set up and run ``binding_events``:
574 606
 #. Create your mojit.
575 607
 
576 608
    ``$ mojito create mojit PagerMojit``
577  
-#. To configure you application to run on the client and use ``HTMLFrameMojit``, replace the code in 
578  
-   ``application.json`` with the following:
  609
+#. To configure you application to run on the client and use ``HTMLFrameMojit``, replace 
  610
+   the code in ``application.json`` with the following:
579 611
 
580 612
    .. code-block:: javascript
581 613
 
@@ -596,8 +628,8 @@ To set up and run ``binding_events``:
596 628
         }
597 629
       ]
598 630
 
599  
-#. To configure routing to call the ``index`` action from the instance of the ``HTMLFrameMojit``, 
600  
-   replace the code in ``routes.json`` with the following:
  631
+#. To configure routing to call the ``index`` action from the instance of the 
  632
+   ``HTMLFrameMojit``, replace the code in ``routes.json`` with the following:
601 633
 
602 634
    .. code-block:: javascript
603 635
 
@@ -618,9 +650,8 @@ To set up and run ``binding_events``:
618 650
       ]
619 651
 
620 652
 #. Change to ``mojits/PageMojit``.
621  
-#. To have the controller get data from the model and create links for paging, replace the code in 
622  
-   ``controller.server.js`` 
623  
-   with the following:
  653
+#. To have the controller get data from the model and create links for paging, replace the 
  654
+   code in ``controller.server.js`` with the following:
624 655
 
625 656
    .. code-block:: javascript
626 657
 
@@ -681,12 +712,13 @@ To set up and run ``binding_events``:
681 712
         }
682 713
       }, '0.0.1', {requires: ['dump']});
683 714
 
684  
-#. To get Flickr photo information using YQL, replace the code in ``model.server.js`` with the 
685  
-   following:
  715
+#. To get Flickr photo information using YQL, replace the code in ``model.server.js`` with 
  716
+   the following:
686 717
 
687 718
    .. code-block:: javascript
688 719
 
689 720
       YUI.add('PagerMojitModel', function(Y, NAME) {
  721
+        var API_KEY = '{your_api_key}';
690 722
         /**
691 723
         * The PagerMojitModel module.
692 724
         * @module PagerMojitModel
@@ -706,7 +738,7 @@ To set up and run ``binding_events``:
706 738
             var API_KEY = "{your_api_key}";
707 739
             start = parseInt(start) || 0;
708 740
             count = parseInt(count) || 10;
709  
-            q = 'select * from flickr.photos.search(' + start + ',' + count + ')  where text="%' + query + '%" and api_key="' + API_KEY+'"';
  741
+            q = 'select * from flickr.photos.search(' + start + ',' + count + ')  where text="%' + query + '%" and api_key="' + API_KEY+ '"';
710 742
             Y.YQL(q, function(rawData) {
711 743
               if (!rawData.query.results) {
712 744
                 callback([]);
@@ -734,9 +766,8 @@ To set up and run ``binding_events``:
734 766
         };
735 767
       }, '0.0.1', {requires: ['yql']});
736 768
 
737  
-#. To create the binder for click events and invoke the ``index`` function of the controller, 
738  
-   replace the code in ``binders/index.js`` 
739  
-   with the following:
  769
+#. To create the binder for click events and invoke the ``index`` function of the 
  770
+   controller, replace the code in ``binders/index.js`` with the following:
740 771
 
741 772
    .. code-block:: javascript
742 773
 
@@ -840,8 +871,8 @@ To set up and run ``binding_events``:
840 871
         };
841 872
       }, '0.0.1', {requires: ['yql', 'io', 'dump']});
842 873
 
843  
-#. To display links to photos and associated photo data in the rendered template, replace the code 
844  
-   in ``views/index.hb.html`` with the following:
  874
+#. To display links to photos and associated photo data in the rendered template, replace 
  875
+   the code in ``views/index.hb.html`` with the following:
845 876
 
846 877
    .. code-block:: html
847 878
 

0 notes on commit 351e25f

Please sign in to comment.
Something went wrong with that request. Please try again.