Configuring Dojo with dojoConfig

dojoConfig 对象 (之前是djConfig)允许你设置各种工具包的选项和默认的动作。在这个教程我们将探讨你怎么能把dojoConfig来在您的代码中使用。

介绍

dojoConfig 对象在网页或应用中是配置Dojo的主要机制，它由模块加载器加载,像其他的Dojo组件一样有全局选项。它可以进一步被用作一个配置点为自定义应用程序,如果需要的

话，它可以进一步被用作一个配置点为自定义应用程序。

* djConfig这个老名字已经被弃用了，但是一些使用这个名字的代码还是可以运行的知道2.0。撰写本文的时候，大多数文档还是使用djConfig ，这两个写法是相等的，但我们将采纳和鼓励用新的名字dojoConfig

Getting Started

让我们通过运行一些快速的例子来理解dojoConfig实际上是怎么工作的，首先，一个编程示例的 直接设置dojoConfig：

<script>
    dojoConfig = {
        isDebug: true,
        parseOnLoad: true,
        foo: "bar"
    };
</script>
<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>

*注意,dojoConfig定义在一个脚本dojo(.xd).js被加载之前。这是最重要的，如果颠倒，配置属性将被忽略。

在这个例子中，我们设置了2个标识：isDebug：true ，parseOnload：true。此外，还指定了一个自定义属性：foo：“bar”  。对于此演示,，是在页面中放入一个dijit.Dialog 。在dojo.ready 函数中中运行的代码是把dojo.config的值转化为json格式，然后放到dialog中展示。在结果中是我们的属性，isDebug, parseOnLoad, 和 foo。但还是有些其他的东西。他们是关联到实际演示页面的 跨域,Google-CDN-hosted Dojo 1.6版本。

*注意dojoConfig 和dojo.config 这两个的差异。dojoConfig是纯碎为了输入加载模块参数。在引导过程中，，dojoConfig保存的参数填充到dojo.config中以便之后寻找模块代码

下面是同样的列子的书面声明方式

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"
        data-dojo-config="isDebug: true,parseOnLoad: true,foo: 'bar'">
</script>

在这个例子中，我们在Dojo脚本代码中用类似的属性data-dojo-config来达到例子中的效果。在两个例子中，我们定义的配置选项被完全加入dojo.config 对象中，他可以在引导过程结束马上得到，就想加载dojo(.xd).js那样

你可以在浏览器的控制台检查你所配置的dojo.config对象里的值，dojoConfig是Dojo的一个常用的属性配置包，让我们看看他还有哪里选项我们可以用到。

Debug Configuration

你可能已经对现在的isDebug 配置标识很熟悉，然而, 如果你开发使用的浏览器有其自身的开发控制台，那么这个属性的目的 可能不能完全达到。当它值为false的时候，如果需要它将创建一个虚拟控制台对象,这样您的代码在执行过程中所有的控制台日志不会抛出异常，当值为true时，并且你有Firebug或者其他调试控制台打开，它什么都不做。但如果你没有控制台，它将会被加载Dojo版本的Firebug Lite，并且在页面底部创建控制台UI。这可以方便调试在先前版本的IE或其他没有好的开发工具的浏览器。

下列附加选项可用来进一步配置这个页面内部控制台:

• debugContainerId: 指定一个特定的元素包含控制台UI
• popup: 使用一个弹出式窗口而不是呈现控制台到当前窗口

除了提供这个控制台浏览器在自己的， isDebug也负责发出 dojo.deprecated,和 dojo.deprecated警告;如果isDebug是false的,这些警告会被抑制。

Loading Configuration

dojoConfig的另一个重要功能是通过加载器传递参数，您可能已经注意到,加载一个跨域构建dojo dojo.config自动设置。useXDomain为true在前面的演示，我们也可以设置以下参数:

• xdWaitSeconds: 要等多久才能放弃加载模块当使用跨域加载程序。
• baseUrl: URL从哪个模块路径必须解决要确认。这将默认目录从哪个dojo(.xd)。js被加载。
• require:一个可选模块加载的数组。行为类似于在Dojo脚本标记调用dojo.require。
• modulePaths: 相当于在 dojo脚本标记之后调用dojo.registerModulePath。该值应该是一个dictionary对象中,映射l模块命名空间到urls

让我们来看一个例子。这个baseUrl和modulePaths选项会特别有用,当你想 从一个服务器(例如谷歌CDN)加载Dojo库,除从另一个其他名称空间(如你自己。)之外。

<script>
    dojoConfig = {
        isDebug: true,
        parseOnLoad: true,
        baseUrl: '/documentation/tutorials/1.6/dojo_config/',
        modulePaths: {
            "demo": "demo"
        }
    };
</script>
<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script>
    dojo.require("demo.AuthoredDialog");
 
    dojo.ready(function(){
        var dlg = dijit.byId("dialog");
        dlg.set("content", '<pre>'+dojo.toJson(dojo.config, true)+'</pre>');
        dlg.show();
    });
</script>

在 body内,标记已经略为使用自定义对话框窗口小部件:

<div id="dialog" data-dojo-type="demo.AuthoredDialog"
    data-dojo-props="title: 'dojo.config.baseUrl demo', authorAvatarSrc: '/includes/authors/sam_foster/avatar.jpg', authorName: 'Sam Foster'">
</div>

通过使用baseUrl,我们告诉Dojo路径是这个目录,而不是我们在Dojo加载。js从。此外,modulePaths中的映射对象规定模块在演示名称空间应该加载自“demo”目录,相对于baseUrl。结果是,演示。AuthoredDialog解析为一个目录这台服务器上,而不是CDN。再一次,结果dojo。配置对象被序列化到对话框进行检查。

Lifecycle options

我们可以使用dojo.config在Dojo的处理函数'ready'时，配置那时要处理的代码。它和你之前遇到的parseOnload 配置系统是相同的：

<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script>
    dojo.require("dojo.parser");
    dojo.ready(function(){
        dojo.parser.parse();
    });
</script>

但是有个重要的变化是：当你使用parseOnload时，任何你传到dojo.ready的函数都将不会执行，直到解析器运行后找到的所有部件已经创建并初始化。

你也可以在dojo.config中增加require 和addOnload 选项。在下面的例子中，我们已经设置了一个   demo.logSequenceEntry 方法用于显示时间的发生顺序。

• 这个页面需要2个模块——一个来自dojoConfig的声明，另一个来自于代码块，
• 这个页面设置dojoConfig.parseOnLoad为true或false两个例子
• 这个页面在dojoConfig对象中定义了addOnload函数，和dojo.ready函数一样
• 每个需要的模块在载入后都将记录日志，
  小部件将记录从它的启动function-i.e。创建后,放置,完全初始化的

注意，首先，它没有影响结果，任何ready/addOnLoad 函数总是在所有请求模块都被载入后执行。主要区别是parseOnLoad的影响：当设置为true时，解析并创建小部件，然后ready函数运行。

*在页面加载后如果你是一个构建版本的Dojo注入。设置dojoConfig.afterOnLoad为true。这告诉Dojo在DOM被加载前，执行任何ready函数立即加载依赖项。不过,要记住,这只能通过Dojo构建,而不是源分布。

Locale and Internationalization

Dojo的国际化有自己教程，但我们会在这里只是为了展示dojoConfig的功能

你可以用Dojo的国际化库来配置你的本地化以及任何需要本地化的小部件，locale 选项让你覆盖你浏览器的提供的默认语言。下面是个示例

<script>
	var dojoConfig = {
		isDebug: true,
		parseOnLoad: true,
		// look for a locale=xx query string param, else default to 'en-us'
		locale: location.search.match(/locale=([\w\-]+)/) ? RegExp.$1 : "en-us"
	};
</script>
<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script>
	dojo.require("dojo.i18n");
	dojo.require("dojo.date.locale");
	dojo.require("dijit.Dialog");
	
	dojo.ready(function(){
		var now = new Date();
		var dlg = new dijit.Dialog({
			id: 'dialog',
			// set a title on the dialog of today's date, 
			// using a localized date format
			title: 'Today: '+ dojo.date.locale.format(now, {
					formatLength:'full',selector:'date'
			})
		}).placeAt(dojo.body());
		dlg.startup();
		
		dlg.set("content", '<pre>'+dojo.toJson(dojo.config, true)+'</pre>');
		dlg.show();
	});
</script>

在这个例子中，我们定义dojoConfig对象的locale属性，从查询字符串中查找‘locale=x’参数。这是一个演示工件,通常你可能硬编码的语言环境。设置地区提前任何模块加载确保正确的本地化消息包的依赖关系在必要时加载。在本例中,我们使用dojo.data.locale模块来格式化日期对象到一个本地化的字符串的对话框标题。

*对于多语言页面，除你在locale属性之外，你需要加载绑定多个语言包。在这种情况下，用一个延伸的配置属性extraLocale，值为以本地化名称的数组

Custom Properties

由于，我们知道dojo.config是合理的地方提供用于页面范围配置,其他几个模块在Dojo利用其为自己特定的配置属性。我们看到这在Dijit包中,尤其是在Dojox,模块标识和行为可以设置:

Dijit Editor

allowXdRichTextSave

dojox GFX

dojoxGfxSvgProxyFrameUrl, forceGfxRenderer, gfxRenderer

dojox.html metrics

fontSizeWatch

dojox.io transports and plugins

xipClientUrl, dojoCallbackUrl

dojox.image

preloadImages

dojox.analytics plugins

sendInterval, inTransitRetry, analyticsUrl, sendMethod, maxRequestSize, idleTime, watchMouseOver, sampleDelay, targetProps, windowConnects, urchin

dojox.cometd

cometdRoot

dojox.form.FileUploader

uploaderPath

dojox.mobile

mblApplyPageStyles, mblHideAddressBar, mblAlwaysHideAddressBar, mobileAnim, mblLoadCompatCssFiles

这些为dojox模块怎样工作的，同样也可以为您自己的应用程序和模块工作。dojoConfig 是一个用于配置页面和程序扩展设置的地方。考虑以下几点:

<script>
    dojoConfig = {
        isDebug: true,
        parseOnLoad: true,
        app: {
            userName: "Anonymous"
        }
    };
</script>
<script src="http://ajax.googleapis.com/ajax/libs/dojo/1.6/dojo/dojo.xd.js"></script>
<script>
    dojo.require("dijit.Dialog");
     
    // pull configuration from the query string
    // and mix it into our app config
    var queryParams = dojo.queryToObject(location.search.substring(1));
    dojo.mixin(dojo.config.app, queryParams);
     
    dojo.ready(function(){
        var dlg = dijit.byId("dialog");
        // draw on the app config to put up a personalized message
        dlg.set("title", 'Welcome back ' + dojo.config.app.userName);
        dlg.set("content", '<pre>'+dojo.toJson(dojo.config, true)+'</pre>');
        dlg.show();
    });
</script>

在这个例子中，我们附加了一个dojoconfig属性“app”，我们通过dojo.config用这个 在对话框中设置个性化问候。有很多方法给dojoConfig.app赋值。他可以提前被赋予一个合理的默认值或者混合与特定的值之后。 在编程中,dojoConfig脚本可能被写在服务器端。或者，你可以用一个被json格式的配置赋予它。像我们之前的例子中一样。你可以直接通过查询字符来扩展设置。在开发和测试中，你可以用一个提供虚拟值的模板，或者加载一段脚本或模块来填充这个属性。

Conclusion

在这个教程中，我们介绍了多种常用的方式来填充dojo.config的值，有通过dojoConfig对象赋值的，有在data-dojo-config属性上赋值的，以及他的值影响的行为和dojo模块支持的属性。

dojo.config 的定义位置和角色，以及Dojo脚本中的引导程序和生命周期的意义，相同的概念熟练应用Dojo模块,甚至您自己的模块和应用程序。