lib/dojo/text.js.uncompressed.js

   1 define("dojo/text", ["./_base/kernel", "require", "./has", "./_base/xhr"], function(dojo, require, has, xhr){
   2         // module:
   3         //              dojo/text
   4
   5         var getText;
   6         if( 1 ){
   7                 getText= function(url, sync, load){
   8                         xhr("GET", {url: url, sync:!!sync, load: load, headers: dojo.config.textPluginHeaders || {}});
   9                 };
  10         }else{
  11                 // TODOC: only works for dojo AMD loader
  12                 if(require.getText){
  13                         getText= require.getText;
  14                 }else{
  15                         console.error("dojo/text plugin failed to load because loader does not support getText");
  16                 }
  17         }
  18
  19         var
  20                 theCache = {},
  21
  22                 strip= function(text){
  23                         //Strips <?xml ...?> declarations so that external SVG and XML
  24                         //documents can be added to a document without worry. Also, if the string
  25                         //is an HTML document, only the part inside the body tag is returned.
  26                         if(text){
  27                                 text= text.replace(/^\s*<\?xml(\s)+version=[\'\"](\d)*.(\d)*[\'\"](\s)*\?>/im, "");
  28                                 var matches= text.match(/<body[^>]*>\s*([\s\S]+)\s*<\/body>/im);
  29                                 if(matches){
  30                                         text= matches[1];
  31                                 }
  32                         }else{
  33                                 text = "";
  34                         }
  35                         return text;
  36                 },
  37
  38                 notFound = {},
  39
  40                 pending = {};
  41
  42         dojo.cache = function(/*String||Object*/module, /*String*/url, /*String||Object?*/value){
  43                 // summary:
  44                 //              A getter and setter for storing the string content associated with the
  45                 //              module and url arguments.
  46                 // description:
  47                 //              If module is a string that contains slashes, then it is interpretted as a fully
  48                 //              resolved path (typically a result returned by require.toUrl), and url should not be
  49                 //              provided. This is the preferred signature. If module is a string that does not
  50                 //              contain slashes, then url must also be provided and module and url are used to
  51                 //              call `dojo.moduleUrl()` to generate a module URL. This signature is deprecated.
  52                 //              If value is specified, the cache value for the moduleUrl will be set to
  53                 //              that value. Otherwise, dojo.cache will fetch the moduleUrl and store it
  54                 //              in its internal cache and return that cached value for the URL. To clear
  55                 //              a cache value pass null for value. Since XMLHttpRequest (XHR) is used to fetch the
  56                 //              the URL contents, only modules on the same domain of the page can use this capability.
  57                 //              The build system can inline the cache values though, to allow for xdomain hosting.
  58                 // module: String||Object
  59                 //              If a String with slashes, a fully resolved path; if a String without slashes, the
  60                 //              module name to use for the base part of the URL, similar to module argument
  61                 //              to `dojo.moduleUrl`. If an Object, something that has a .toString() method that
  62                 //              generates a valid path for the cache item. For example, a dojo._Url object.
  63                 // url: String
  64                 //              The rest of the path to append to the path derived from the module argument. If
  65                 //              module is an object, then this second argument should be the "value" argument instead.
  66                 // value: String||Object?
  67                 //              If a String, the value to use in the cache for the module/url combination.
  68                 //              If an Object, it can have two properties: value and sanitize. The value property
  69                 //              should be the value to use in the cache, and sanitize can be set to true or false,
  70                 //              to indicate if XML declarations should be removed from the value and if the HTML
  71                 //              inside a body tag in the value should be extracted as the real value. The value argument
  72                 //              or the value property on the value argument are usually only used by the build system
  73                 //              as it inlines cache content.
  74                 // example:
  75                 //              To ask dojo.cache to fetch content and store it in the cache (the dojo["cache"] style
  76                 //              of call is used to avoid an issue with the build system erroneously trying to intern
  77                 //              this example. To get the build system to intern your dojo.cache calls, use the
  78                 //              "dojo.cache" style of call):
  79                 //              | //If template.html contains "<h1>Hello</h1>" that will be
  80                 //              | //the value for the text variable.
  81                 //              | var text = dojo["cache"]("my.module", "template.html");
  82                 // example:
  83                 //              To ask dojo.cache to fetch content and store it in the cache, and sanitize the input
  84                 //               (the dojo["cache"] style of call is used to avoid an issue with the build system
  85                 //              erroneously trying to intern this example. To get the build system to intern your
  86                 //              dojo.cache calls, use the "dojo.cache" style of call):
  87                 //              | //If template.html contains "<html><body><h1>Hello</h1></body></html>", the
  88                 //              | //text variable will contain just "<h1>Hello</h1>".
  89                 //              | var text = dojo["cache"]("my.module", "template.html", {sanitize: true});
  90                 // example:
  91                 //              Same example as previous, but demonstrates how an object can be passed in as
  92                 //              the first argument, then the value argument can then be the second argument.
  93                 //              | //If template.html contains "<html><body><h1>Hello</h1></body></html>", the
  94                 //              | //text variable will contain just "<h1>Hello</h1>".
  95                 //              | var text = dojo["cache"](new dojo._Url("my/module/template.html"), {sanitize: true});
  96
  97                 //       * (string string [value]) => (module, url, value)
  98                 //       * (object [value])        => (module, value), url defaults to ""
  99                 //
 100                 //       * if module is an object, then it must be convertable to a string
 101                 //       * (module, url) module + (url ? ("/" + url) : "") must be a legal argument to require.toUrl
 102                 //       * value may be a string or an object; if an object then may have the properties "value" and/or "sanitize"
 103                 var key;
 104                 if(typeof module=="string"){
 105                         if(/\//.test(module)){
 106                                 // module is a version 1.7+ resolved path
 107                                 key = module;
 108                                 value = url;
 109                         }else{
 110                                 // module is a version 1.6- argument to dojo.moduleUrl
 111                                 key = require.toUrl(module.replace(/\./g, "/") + (url ? ("/" + url) : ""));
 112                         }
 113                 }else{
 114                         key = module + "";
 115                         value = url;
 116                 }
 117                 var
 118                         val = (value != undefined && typeof value != "string") ? value.value : value,
 119                         sanitize = value && value.sanitize;
 120
 121                 if(typeof val == "string"){
 122                         //We have a string, set cache value
 123                         theCache[key] = val;
 124                         return sanitize ? strip(val) : val;
 125                 }else if(val === null){
 126                         //Remove cached value
 127                         delete theCache[key];
 128                         return null;
 129                 }else{
 130                         //Allow cache values to be empty strings. If key property does
 131                         //not exist, fetch it.
 132                         if(!(key in theCache)){
 133                                 getText(key, true, function(text){
 134                                         theCache[key]= text;
 135                                 });
 136                         }
 137                         return sanitize ? strip(theCache[key]) : theCache[key];
 138                 }
 139         };
 140
 141         return {
 142                 // summary:
 143                 //              This module implements the dojo/text! plugin and the dojo.cache API.
 144                 // description:
 145                 //              We choose to include our own plugin to leverage functionality already contained in dojo
 146                 //              and thereby reduce the size of the plugin compared to various foreign loader implementations.
 147                 //              Also, this allows foreign AMD loaders to be used without their plugins.
 148                 //
 149                 //              CAUTION: this module is designed to optionally function synchronously to support the dojo v1.x synchronous
 150                 //              loader. This feature is outside the scope of the CommonJS plugins specification.
 151
 152                 // the dojo/text caches it's own resources because of dojo.cache
 153                 dynamic: true,
 154
 155                 normalize: function(id, toAbsMid){
 156                         // id is something like (path may be relative):
 157                         //
 158                         //       "path/to/text.html"
 159                         //       "path/to/text.html!strip"
 160                         var parts= id.split("!"),
 161                                 url= parts[0];
 162                         return (/^\./.test(url) ? toAbsMid(url) : url) + (parts[1] ? "!" + parts[1] : "");
 163                 },
 164
 165                 load: function(id, require, load){
 166                         // id: String
 167                         //              Path to the resource.
 168                         // require: Function
 169                         //              Object that include the function toUrl with given id returns a valid URL from which to load the text.
 170                         // load: Function
 171                         //              Callback function which will be called, when the loading finished.
 172
 173                         // id is something like (path is always absolute):
 174                         //
 175                         //       "path/to/text.html"
 176                         //       "path/to/text.html!strip"
 177                         var
 178                                 parts= id.split("!"),
 179                                 stripFlag= parts.length>1,
 180                                 absMid= parts[0],
 181                                 url = require.toUrl(parts[0]),
 182                                 requireCacheUrl = "url:" + url,
 183                                 text = notFound,
 184                                 finish = function(text){
 185                                         load(stripFlag ? strip(text) : text);
 186                                 };
 187                         if(absMid in theCache){
 188                                 text = theCache[absMid];
 189                         }else if(requireCacheUrl in require.cache){
 190                                 text = require.cache[requireCacheUrl];
 191                         }else if(url in theCache){
 192                                 text = theCache[url];
 193                         }
 194                         if(text===notFound){
 195                                 if(pending[url]){
 196                                         pending[url].push(finish);
 197                                 }else{
 198                                         var pendingList = pending[url] = [finish];
 199                                         getText(url, !require.async, function(text){
 200                                                 theCache[absMid]= theCache[url]= text;
 201                                                 for(var i = 0; i<pendingList.length;){
 202                                                         pendingList[i++](text);
 203                                                 }
 204                                                 delete pending[url];
 205                                         });
 206                                 }
 207                         }else{
 208                                 finish(text);
 209                         }
 210                 }
 211         };
 212
 213 });
 214