src/js/jquery.mobile.tizen.loadprototype.js

   1 //>>excludeStart("jqmBuildExclude", pragmas.jqmBuildExclude);
   2 //>>description: Loads widget's prototype
   3 //>>label: Widget prototype loader
   4 //>>group: Tizen:Core
   5
   6 define( [ ], function ( ) {
   7 //>>excludeEnd("jqmBuildExclude");
   8
   9 ( function ( $, undefined ) {
  10
  11         ensureNS( "jQuery.mobile.tizen" );
  12
  13         jQuery.extend( jQuery.mobile.tizen, {
  14                 _widgetPrototypes: {},
  15
  16                 /*
  17                  * load the prototype for a widget.
  18                  *
  19                  * If @widget is a string, the function looks for @widget.prototype.html in the proto-html/ subdirectory of the
  20                  * framework's current theme and loads the file via AJAX into a string. Note that the file will only be loaded via
  21                  * AJAX once. If two widget instances based on the same @widget value are to be constructed, the second will be
  22                  * constructed from the cached copy of the prototype of the first instance.
  23                  *
  24                  * If @widget is not a string, it is assumed to be a hash containing at least one key, "proto", the value of which is
  25                  * the string to be used for the widget prototype. if another key named "key" is also provided, it will serve as the
  26                  * key under which to cache the prototype, so it need not be rendered again in the future.
  27                  *
  28                  * Given the string for the widget prototype, the following patterns occurring in the string are replaced:
  29                  *
  30                  *   "${FRAMEWORK_ROOT}" - replaced with the path to the root of the framework
  31                  *
  32                  * The function then creates a jQuery $("<div>") object containing the prototype from the string.
  33                  *
  34                  * If @ui is not provided, the jQuery object containing the prototype is returned.
  35                  *
  36                  * If @ui is provided, it is assumed to be a (possibly multi-level) hash containing CSS selectors. For every level of
  37                  * the hash and for each string-valued key at that level, the CSS selector specified as the value is sought in the
  38                  * prototype jQuery object and, if found, the value of the key is replaced with the jQuery object resulting from the
  39                  * search. Additionally, if the CSS selector is of the form "#widgetid", the "id" attribute will be removed from the
  40                  * elements contained within the resulting jQuery object. The resulting hash is returned.
  41                  *
  42                  * Examples:
  43                  *
  44                  * 1.
  45                  * $.mobile.tizen.loadPrototype("mywidget") => Returns a <div> containing the structure from the file
  46                  * mywidget.prototype.html located in the current theme folder of the current framework.
  47                  *
  48                  * 2. $.mobile.tizen.loadPrototype("mywidget", ui):
  49                  * where ui is a hash that looks like this:
  50                  * ui = {
  51                  *   element1: "<css selector 1>",
  52                  *   element2: "<css selector 2>",
  53                  *   group1: {
  54                  *     group1element1: "<css selector 3>",
  55                  *     group1element1: "<css selector 4>"
  56                  *   }
  57                  *  ...
  58                  * }
  59                  *
  60                  * In this case, after loading the prototype as in Example 1, loadPrototype will traverse @ui and replace the CSS
  61                  * selector strings with the result of the search for the selector string upon the prototype. If any of the CSS
  62                  * selectors are of the form "#elementid" then the "id" attribute will be stripped from the elements selected. This
  63                  * means that they will no longer be accessible via the selector used initially. @ui is then returned thus modified.
  64                  */
  65
  66                 loadPrototype: function ( widget, ui ) {
  67                         var ret,
  68                                 theScriptTag = $( "script[data-framework-version][data-framework-root][data-framework-theme]" ),
  69                                 frameworkRootPath = theScriptTag.attr( "data-framework-root" ) + "/" +
  70                                                                         theScriptTag.attr( "data-framework-version" ) + "/",
  71                                 protoPath;
  72
  73                         function replaceVariables( s ) {
  74                                 return s.replace( /\$\{FRAMEWORK_ROOT\}/g, frameworkRootPath );
  75                         }
  76
  77                         function fillObj( obj, uiProto ) {
  78                                 var selector, key;
  79
  80                                 for ( key in obj ) {
  81                                         if ( typeof obj[ key ] === "string" ) {
  82                                                 selector = obj[ key ];
  83                                                 obj[ key ] = uiProto.find( obj[ key ] );
  84                                                 if ( selector.substring( 0, 1 ) === "#" ) {
  85                                                         obj[ key ].removeAttr( "id" );
  86                                                 }
  87                                         } else if (typeof obj[ key ] === "object") {
  88                                                 obj[ key ] = fillObj( obj[ key ], uiProto );
  89                                         }
  90                                 }
  91                                 return obj;
  92                         }
  93
  94                         /* If @widget is a string ... */
  95                         if ( typeof widget === "string" ) {
  96                                 /* ... try to use it as a key into the cached prototype hash ... */
  97                                 ret = $.mobile.tizen._widgetPrototypes[widget];
  98                                 if ( ret === undefined ) {
  99                                         /* ... and if the proto was not found, try to load its definition ... */
 100                                         protoPath = frameworkRootPath + "proto-html" + "/" +
 101                                                                 theScriptTag.attr( "data-framework-theme" );
 102                                         $.ajax( {
 103                                                 url: protoPath + "/" + widget + ".prototype.html",
 104                                                 async: false,
 105                                                 dataType: "html"
 106                                         } )
 107                                                 .success( function ( data, textStatus, jqXHR ) {
 108                                                         /* ... and if loading succeeds, cache it and use a copy of it ... */
 109                                                         $.mobile.tizen._widgetPrototypes[ widget ] = $( "<div>" ).html( replaceVariables( data ) );
 110                                                         ret = $.mobile.tizen._widgetPrototypes[ widget ].clone();
 111                                                 } );
 112                                 }
 113                         } else {
 114                                 /* Otherwise ... */
 115                                 /* ... if a key was provided ... */
 116                                 if ( widget.key !== undefined ) {
 117                                         /* ... try to use it as a key into the cached prototype hash ... */
 118                                         ret = $.mobile.tizen._widgetPrototypes[ widget.key ];
 119                                 }
 120
 121                                 /* ... and if the proto was not found in the cache ... */
 122                                 if ( ret === undefined ) {
 123                                         /* ... and a proto definition string was provided ... */
 124                                         if ( widget.proto !== undefined ) {
 125                                                 /* ... create a new proto from the definition ... */
 126                                                 ret = $( "<div>" ).html(replaceVariables( widget.proto ) );
 127                                                 /* ... and if a key was provided ... */
 128                                                 if ( widget.key !== undefined ) {
 129                                                         /* ... cache a copy of the proto under that key */
 130                                                         $.mobile.tizen._widgetPrototypes[ widget.key ] = ret.clone();
 131                                                 }
 132                                         }
 133                                 } else {
 134                                         /* otherwise, if the proto /was/ found in the cache, return a copy of it */
 135                                         ret = ret.clone();
 136                                 }
 137                         }
 138
 139                         /* If the prototype was found/created successfully ... */
 140                         if ( ret != undefined ) {
 141                                 /* ... and @ui was provided */
 142                                 if ( ui != undefined ) {
 143                                         /* ... return @ui, but replace the CSS selectors it contains with the elements they select */
 144                                         ret = fillObj( ui, ret );
 145                                 }
 146                         }
 147
 148                         return ret;
 149                 }
 150         });
 151 }( jQuery ) );
 152
 153 //>>excludeStart("jqmBuildExclude", pragmas.jqmBuildExclude);
 154 } );
 155 //>>excludeEnd("jqmBuildExclude");