• 多平台支持： 默认的，Dojo loader包含浏览器端，node.js 及 rhino的配置
  
• Has.js API: Dojo loader实现了has.js的API,使用这个api 可以排除一些不需要的功能， 结合 dojo build工具，可以将整个loader的代码缩小到3kb(压缩及gzip过后)
  
• 配置API: 加载器包括一个可以由客户端应用程序配置API.
  

Dojo.js

<script src="path/to/dojo/dojo.js"></script>
<script>
  // the dojo base API is available here
</script>

<script data-dojo-config="async:1" src="path/to/dojo/dojo.js"></script>
<script>
  // ATTENTION: nothing but the AMD API is available here
</script>

配置及特征检测

配置

1. 在loader被定义之前，通过全部对象dojoConfig。
   
2. 在<script src=”path/loader”> 里面，对过data-dojo-config参数
   
3. 在加载完loader后，通过全局的require方法。
   

<script
  data-dojo-config="async:true,cacheBust:new Date(),waitSeconds:5"
  src="path/to/dojo/dojo.js">
</script>

<script>
  var dojoConfig = {
    async:true,waitSeconds:5
  };
</script>
<script src="path/to/dojo/dojo.js"></script>

require({
  cacheBust:new Date(),waitSeconds:5
});

1. config: 配置对象传递给加载器时，加载器触发” config” event.
   
2. rawConfig: require.rawConfig的值
   

特征检测

has.add("dom-addeventlistener",!!document.addEventListener);

if(has("dom-addeventlistener")){
  node.addEventListener("click",handler);
}else{
  node.attachEvent("onclick",handler);
}

0 && has.add("dom-addeventlistener",!!document.addEventListener);

if(1){
  node.addEventListener("click",handler);
}

node.addEventListener("click",handler);

• 测试的结果会缓存在 has.cache
  
• 函数has.add 包含第四个可选参数,force. 将会被用来重写已经存在的测试（正常的， 第一次定义的值一直使用，借一个常量）
  

<script>
  var dojoConfig = {
    has: {
      "config-tlmSiblingOfDojo":0,"myApp-someFeature":1
    }
  };
</script>

<script>
  var dojoConfig = {
    has: {
      "myApp-someFeature":function(){
        return !!document.addEventListener;
      }
    }
  };
</script>

<script data-dojo-config="tlmSiblingOfDojo:0" src="path/to/dojo/dojo.js"></script>

选项及特点

AMD API

require(
  configuration,// (optional; object) configuration object
  dependencies,// (optional; array of strings) list of module identifiers to load before calling callback
  callback       // (optional; function) function to call when dependencies are loaded
) -> undefined

require([ "my/app","dojo" ],function(app,dojo){
  // do something with app and dojo...
});

require(
  moduleId // (string) a module identifier
) -> any

define(
  moduleId,// (optional; string) an explicit module identifier naming the module being defined
  dependencies,// (optional; array of strings) list of module identifiers to load before calling factory
  factory        // (function or value) the value of the module,or a function that returns the value of the module
)

• 模块的创建是懒惰和异步的，不会在调用define时立即运行。这个意思就是factory 不会被执行。并且依赖的模块也不会下载并解析。直到有运行的代码需要这个模块。
  
• 一旦一个模块的值进入模块空间，它将只会计算一次，而不会每次请求而进行重新计算。在实践层面上， 这个意思是factory只会被调用一次，运算完后返回的值会被缓存并共享给所有请求只模块的代码使用。（注意：dojo loader 有一个非标准的函数require.undef,表明没有返回值）;
  

require(
  ["dijit/layout/TabContainer","bd/widgets/stateButton"],function(TabContainer,stateButton){
    // do something with TabContainer and stateButton...
  }
);

define(
  ["dijit/layout/TabContainer",stateButton){
    // do something with TabContainer and stateButton...
    return definedValue;
  }
);

模块标识符

• baseUrl:(string) 默认指定的根目录为dojo.js所在的目录，如”lib/dojo/dojo.js” 则baseUrl为 lib/dojo/. 在require([‘dojo/dom’]) 下， baseUrl应该指定为lib/dojo. 如果被定义， has的config-tlmSiblingOfDojo为false.否则为true.
  
• Paths: (object). 自定义路径。会将模块标识符的一部分映射到路径的一部分。 指定的越详细，优先级越高，如，’a/b/c” 的优先级高于a及’a/b’.

dojoConfig={
	paths:{
	‘a/b’:”./custom”
}
}
Require([‘a/b/dom’]) 将会加载custom下的dom.js文件。

• Aliases: (object). 将模块标识符映射为另一个模块标识符。如：

require({
  aliases:[
    ["text","dojo/text"]
  ]
});
require(["text"],function(text){ //...
require(["dojo/text"],function(text){ //...
define(["text"],function(text){ //...
define(["dojo/text"],function(text){ //...

• Packages: (package 对象数据) 明确定义的包列表。Dojo及dijit是两个packages的列子。 一个包对象包含四个属性：

Name: (string) 包名字。（例:’myapp’）;
	Location: (string) 包存在的路径;
	Main: (可选，string) 包的入口文件，给定的值为一个模块标识符。
{  
name: 'dijit',location: 'dojo/dijit',main:'lib/main'                     
}
	

• packageMap(可选，object) 一个映射关系，允许在这个包内，指定的包可以映射到别外一个包;(这个只在dojo的loader里面存在)， 如下例，在utill1的包中，dojox包，指向dojox1. 已被弃用，用map代替

{name: "util1",location: "packages/util1",packageMap: {dojox:"dojox1"}

模块标识符的相对关系

// this is "myPackage/myModule/mySubmodule"
define(
  ["myPackage/utils","myPackage/myModule/mySubmodule2"],function(utils,submodule){
    // do something spectacular
  }
);

// this is "myPackage/myModule/mySubmodule"
define(
  ["../utils","./mySubmodule2"],submodule){
  // do something spectacular
  }
);

上下文相关的 require

// this is "myApp/topLevelHandlers"
define(["dojo"],function(dojo){
  dojo.connect(dojo.byId("debugButton"),"click",function(){
    require(["myApp/perspectives/debug"],function(perspective){
      perspective.open();
    });
  });
});

// this is "myApp/topLevelHandlers"
define(["dojo","require"],function(dojo,require){
  dojo.connect(dojo.byId("debugButton"),function(){
    require(["./perspectives/debug"],function(perspective){
      perspective.open();
    });
  });
});

一般的javascript角本注入

require(["http://acmecorp.com/stuff.js"],function(){
  // etc.
});

• 以协议开送的string(如： http 或 https)
  
• 以 斜线/ 开头的字符串(如”/acmecorp.com/stuff”)
  
• 以 .js 结尾的字符。
  

模块别名

require({
  aliases:[
    ["text","dojo/text"]
  ]
});

require(["text"],function(text){ //...

require({
  paths:{
    "text":"./text"
  }
});

解析模块标识符(源代码为getModuleInfo_函数)

1. 如果moduleId 协议或者斜线开台，又或者以”.js”结尾。假设该请求的是任意数量的javascript代码，而不是一个模块。在这种情况下，剩下的步骤会直接跳过。
   
2. 如果moduleId是一个相对的（例如，第一个字节为”.”），但没有给定reference module。会抛出一个错误：moduleId is not resolvable. 模块无法解析。（注意：源代码里把这种情况归类到第一步，当以”.”开头，而没有referenceModule,会直接相对于网页的路径去加载moduleId. 如果没有moduleId这个路径，会直接找不到相应文件错误。）,所以在全局require中是不能使用相对模块，相对模块主要用于包内的模块定义或者上下文。
   
3. 如果moduleId是相对的，而且给定了参考模块， 设置moduleId为 referenceModule + “/../”+ moduleId,并且通过compactPath函数删除所有相对的路径，如 “..”,“.” ; 以过compactPath处理后，moduleId不会在有相对路径的片段。当经过compactPath处理后，还有 “.” 标识，会抛出一个 moduleId不能解析的错误,源代码是 makeError("irrationalPath",mid) .
   
4. 如果给定了referenceModule， 而且referenceModule是packages配置变量下其中的一个包内， 并且那个包也是packageMap 配置变量的一项，那么用在packageMap中的包名替换最左名的部分（第一个”/”前面那一段，即包名）， 主要用于多版本的兼容,可以查看一下 loader 高级使用教程下中的map选项。
   
5. 在配置变量aliases 中查找 第3步计算出来来的moduleId,如果这个moduleId存在别名， 从aliases中获得这个moduleId得到的别名，重新计算（调用getModuleInfo_),很重要一点是， aliases是在packageMap生效之后在引用的。
6. 如果moduleId 仅有一部会（没有 "/")， 并且这部分与packages内的包名称相同。 在moduleId末尾添加一个"/" 和 包配置中的 "main" 配置变量的值(例如：moduleId 为 "dojo" 那么而这个真正的模块为 "dojo/main")。

dojo ⇒ dojo/main (Step 6)
dojo/main ⇒ ./main (Step 8)
./main ⇒ path/to/dojo/ + ./main ⇒ path/to/dojo/main (Step 10)
path/to/dojo/main.js (Step 11)

dojo/store/api/Store ⇒ ./store/api/Store (Step 8)
./store/api/Store ⇒ path/to/dojo/ + ./store/api/Store ⇒ path/to/dojo/store/api/Store (Step 10)
path/to/dojo/store/api/Store.js (Step 11)

../../_base/Deferred ⇒ dojo/store/util/QueryResults + /../ + ../../_base/Deferred ⇒
dojo/store/util/QueryResults/../../../_base/Deferred ⇒ dojo/_base/Deferred (Step 3)
dojo/_base/Deferred ⇒ ./_base/Deferred (Step 8)
./_base/Deferred ⇒ path/to/dojo/ + ./_base/Deferred ⇒ path/to/dojo/_base/Deferred (Step 10)
path/to/dojo/_base/Deferred.js (Step 11)

myApp ⇒ ../myApp (Step 9)
../myApp ⇒ path/to/dtk + ../myApp ⇒ path/to/myApp (Step 10)
path/to/myApp.js (Step 11)

myApp/someSubmodule ⇒ ../myApp/someSubmodule (Step 9)
../myApp/someSubmodule ⇒ path/to + ../myApp/someSubmodule ⇒ path/to/myApp/someSubmodule (Step 10)
path/to/myApp/someSubmodule.js (Step 11)

var dojoConfig = {
  paths:{
    "myApp":"/other/path/to/myApp"
  }
};

myApp ⇒ /other/path/to/myApp (Step 7)
/other/path/to/myApp.js (Step 11)

myApp/someSubmodule ⇒ /other/path/to/myApp/someSubmodule (Step 7)
/other/path/to/myApp/someSubmodule.js (Step 11)

scripts/
  dtk/
    dojo/
    dijit/
    dojox/
  myApp/
  experimental/

var dojoConfig = {
  paths:{
    "myApp":"../../myApp"
  }
};

myApp ⇒ ../../myApp (Step 7)
../../myApp ⇒ path/to/dtk/dojo/ + ../../myApp ⇒ path/to/myApp (Step 10)
path/to/myApp ⇒ path/to/myApp.js (Step 11)

myApp ⇒ ../../myApp/someSubmodule (Step 7)
../../myApp/someSubmodule ⇒ path/to/dtk/dojo/ + ../../myApp ⇒ path/to/myApp/someSubmodule (Step 10)
path/to/myApp/someSubmodule ⇒ path/to/myApp/someSubmodule.js (Step 11)

var dojoConfig = {
  baseUrl:"scripts",packages:[{
    name:'dojo',location:'dtk/dojo'
  },{
    name:'dijit',location:'dtk/dijit'
  }]
}

myApp ⇒ scripts/ + myApp ⇒ script/myApp (Step 10)
scripts/myApp ⇒ scripts/myApp.js (Step 11)

myApp ⇒ scripts/ + myApp/someSubmodule ⇒ script/myApp/someSubmodule (Step 10)
scripts/myApp/someSubmodule ⇒ scripts/myApp/someSubmodule.js (Step 11)

dojo ⇒ dojo/main (Step 4)
dojo/main ⇒ dtk/dojo/main (Step 8)
dtk/dojo/main ⇒ scripts/dtk/dojo/ + ./main ⇒ scripts/dtk/dojo/main (Step 10)
scripts/dtk/dojo/main.js (Step 11)

dojo/behavior ⇒ dtk/dojo/behavior (Step 8)
dtk/dojo/behavior ⇒ scripts/dtk/dojo/ + ./behavior ⇒ scripts/dtk/dojo/behavior (Step 10)
scripts/dojo/behavior.js (Step 11)

var dojoConfig = {
  baseUrl:"scripts"
  packages:[{
    name:'myApp',location:'myApp'
  },location:'dtk/dijit'
  },location:'dtk/dijit'
  }]
};

myApp ⇒ myApp/main (Step 4)
myApp/main ⇒ myApp/main (Step 8)
myApp/main ⇒ scripts/ + myApp/main ⇒ scripts/myApp/main (Step 10)
scripts/myApp/main.js (Step 11)

var dojoConfig = {
  paths:{
    "dojo/cookie":"../../experimental/dojo/cookie"
  }
}

scripts/
  myApp/
    myApi.js
    myApi/
      helper1.js
      helper2.js

var dojoConfig = {
  paths:{
    "myApp/myApi":"path/to/another/myApi","myApp/myApi/helper1":"path/to/original/myApi/helper1","myApp/myApi/helper2":"path/to/original/myApi/helper2"
  }
}

重定位模块命名空间

var dojoConfig = {
  baseUrl: "./",packages: [{
      name: "util1",location: "packages/util1"
    },{
      name: "util2",location: "packages/util2"
    }]
};

define(["util1","util2"],function(util1,util2){
  // well that was easy.
});

var dojoConfig = {
  packages: [{
    name: "util1",packageMap: {dojox:"dojox1"}
  },{
    name: "util2",location: "packages/util2",packageMap: {dojox:"dojox2"}
  },{
    name: "dojox1",location: "packages/dojox-version-1-6"
  },{
    name: "dojox2",location: "packages/dojox-version-1-4"
  }]
};

var dojoConfig = {
  packages: [{
    name: "util1",},location: "packages/dojox-version-1-4"
  }],map:{
	util1:{
		dojox:"dojox1"
	},util2:{
		dojox:"dojox2"
	}
	}
};

实现功能

require.toUrl(
  id // (string) a resource identifier that is prefixed by a module identifier
) -> string

define(["require",...],function(require,...){
     ... require.toUrl("./images/foo.jpg") ...
}

require.toAbsMid(
  moduleId // (string) a module identifier
) -> string

require.undef(
  moduleId // (string) a module identifier
) -> undefined

require.log(
  // (...rest) one or more messages to log
) -> undefined

Commonjs 的 require,exports,module

• id: 一个唯一的模块标识符字符串， 当它被传递给require时，会返回这个模块的值。
• uri: 模块资源被加载完后的一个URI（有时没用）
• exports: 详情如下

define([],function(){
  return {
    someProperty:"hello",someOtherProperty:"world"
  };
});


define(["exports"],function(exports){
  exports.someProperty = "hello";
  exports.someOtherProperty = "world";
});

define(["module"],function(module){
  module.exports = dojo.declare(/*...*/);
});

define(["require","module"],module){
  // define a module
});

define(function(require,module){
  // define a module
});

插件

• dojo/domReady: 延迟模块工厂函数的执行， 直到整个文档被解析（相当于jQuery 中的 $(document).ready(function(){}) )
• dojo/text: 加载文本资源， 它是RequireJS文本插件的一个超集， 并将加载的结果存入 dojo.cache.
• dojo/i18n: 加载国际化资源包， 包括老版本的格式（v1.6 - i18n API) 及AMD的格式， 是RequireJS 国际资源包的超集。
• dojo/has: 允许使用 has.js的表达式，有条件的加载模块。
• dojo/load: 在运行时加载经过计算得到的模块依赖
• dojo/require: 下载一个老版本的模块而不加载它，就是之前版本中的dojo.require。
• dojo/loadInit: 调用dojo.loadinit函数，这样其它的老版本的 API函数可以被执行，特别是dojo.require来下载的模块。

load(
  id,// the string to the right of the !
  require,// AMD require; usually a context-sensitive require bound to the module making the plugin request
  callback   // the function the plugin should call with the return value once it is done
) -> undefined

// this is "myApp/myModule"
define(["text!./templates/myModule.html"],function(template){
  // template is a string loaded from the resource implied by myApp/templates/myModule.html
});

define(["dojo/_base/xhr"],function(xhr){
  return {
    load: function(id,require,callback){
      xhr.get({
        url: require.toUrl(id),load: function(text){
          callback(text);
        }
      });
    }
  };
});

define(["dojo"],function(dojo){
  var cache = {};
  return {
    load: function(id,callback){
      var url = require.toUrl(id);
      if(url in cache){
        callback(cache[url]);
      }else{
        dojo.xhrGet({
          url: url,load: function(text){
            callback(cache[url] = text);
          }
        });
      }
    }
  };
});

Window 的 Load事件检测

微事件(loader内部事件）API

require.on = function(
  eventName,// (string) the event name to connect to
  listener   // (function) called upon event
)

require.signal = function(
  eventName,// (string) the event name to signal
  args       // (array) the arguments to apply to each listener
)

var handle = require.on("config",function(config,rawConfig){
      if(config.myApp.myConfigVar){
        // do something
  }
});

错误报告

function handleError(error){
  console.log(error.src,error.id);
}

require.on("error",handleError);

调试

• 老版本的loader API最常见的程序错误是在模块标识符中使用"."而不是"/"。
• 最常见的语法错误是在依赖列表里缺少一个逗号，而有的浏览器不会报告这个错误。
• 常见的程序错误是，依赖列表的顺序跟回调函数或者工厂方法的顺依不一样。 通常会出现" object is not a constructor" 或者 "method dose not exist" 或 相类似的。
• 在一些浏览器的某些情况下，插入一个断点的过程中将会改变异步请求的顺序， 断点被插入时导致应用程序失败。 这表明模块在被定义时已经确定了依赖的顺序。精心设计的AMD应用程序将不会有这些规定。

• result 模块的值
• injected 加载的状态( 0 表示 "requested",1 表示 "arrived")
• executed 工厂函数执行的状态 （ 0 表示 "executing",1 表示 "executed")
• pid 模块包的名称（如果有的话）
• url 模块中定义的资源的地址
• def 工厂函数

追踪

require.trace = function(
  groupId,// (string) the tracing group identifier to which this trace message belongs  
  args     // (array of any) additional data to send with trace 
) -> undefined

require.trace.set(
  groupId,// (string) a tracing group identifier  
  enable   // (boolean) enable or disable tracing of messages from groupId 
) -> undefined

require.trace.set(
  groupMap  // (object:groupId --> boolean) a map from trace group identifier to on/off value 
) -> undefined

require.trace.on // (boolean) enable/disable all tracing 

require.trace.group // (object) a map from trace group id to boolean  

1. 如果 trace.on 为 false,则直接返回，不做任何事情。
2. 如果trace.group[groupId] 为false,直接返回
3. 通过 micro event API( loader的内部事件处理 API) 发现一个trace event 信号，信号的参数为 [groupId,args]
4. 连接groupId 以及 args中的每一个用逗号隔开的字符串， 并调用require.log输出结果字符串。
5. 调用require.log 输出args中的值。

require({
  trace:{
    "loader-inject":1,// turn the loader-inject group on
    "loader-define":0 // turn the loader-define group off
  }
});

require.trace.set({
  "loader-inject":1,// turn the loader-inject group on
  "loader-define":0 // turn the loader-define group off
});

require.trace.set("loader-inject", 1);
require.trace.set("loader-define", 0);

非浏览器环境

#!/bin/bash
node dojo/dojo.js load=config load=main

#!/bin/bash
java -jar util/shrinksafe/js.jar dojo/dojo.js baseUrl=file:///full/path/to/dojo/dojo load=config load=main

老版本API

dojo.provide("module.that.defines.a.global");
var someVariable = anAwesomeCalculation();

dojo.provide("module.that.defines.a.global");
dojo.global.someVariable = anAwesomeCalculation();

工作模式

Legacy Synchronous 模式

配置参考

配置变量

packagePaths:{
  "path/to/some/place":[
    "myPackage",{
      name:"yourPackage",main:"base"
    }
  ]
}

packages:[{
  name:"myPackage",location:"path/to/some/place/myPackage"
},{
  name:"yourPackage",location:"path/to/some/place/youPackage"
}]

默认的配置

{
    // the default configuration for a browser; this will be modified by other environments
    hasCache:{
        "host-browser":1,"dom":1,"dojo-amd-factory-scan":1,"dojo-loader":1,"dojo-has-api":1,"dojo-inject-api":1,"dojo-timeout-api":1,"dojo-trace-api":1,"dojo-log-api":1,"dojo-dom-ready-api":1,"dojo-publish-privates":1,"dojo-config-api":1,"dojo-sniff":1,"dojo-sync-loader":1,"dojo-test-sniff":1,"config-tlmSiblingOfDojo":1
    },packages:[{
        // note: like v1.6-,this bootstrap computes baseUrl to be the dojo directory
        name:'dojo',location:'.'
    },{
        name:'tests',location:'./tests'
    },{
        name:'dijit',location:'../dijit'
    },{
        name:'build',location:'../util/build'
    },{
        name:'doh',location:'../util/doh'
    },{
        name:'dojox',location:'../dojox'
    },{
        name:'demos',location:'../demos'
    }],trace:{
        // these are listed so it's simple to turn them on/off while debugging loading
        "loader-inject":0,"loader-define":0,"loader-exec-module":0,"loader-run-factory":0,"loader-finish-exec":0,"loader-define-module":0,"loader-circular-dependency":0
    },async:0
}

• 上一篇：dojo1.8 培训教材 新手老手适用 - 下一篇：dojo中取查询出来的地市维表数据的