Dojo工具包.doc

实战Dojo工具包内容目录1 简介. 32 Dojo工具包：JavaScript开发的水槽（Kitchen Sink）.33 设置和配置Dojo. 43.1 选择正确的Dojo创建.43.2 动态加载package.53.3 定制的创建. 54 应用：旅行路线编辑器. 65 DOM和HTML效果. 65.1 处理DOM. 75.2 Dojo的HTML效果.86 使用dojo.io.bind()的Ajax远程调用.86.1.1 淡出和移除.96.1.2 使用XMLHttpRequest来告诉服务器发生了什么. 97 拖放操作. 107.1.1 连接所有的天.117.1.2 连接单个的天.117.1.3 onLoad. 118 结论. 129 作者简历. 121 简介当你开始建造一个Ajax应用时，你很快就会遇到一些情形，让你感觉自己好像是在重新发明轮子。大量的开发者一想到Ajax，就会直接扑向XMLHttpRequest对象，但这仅仅只是一个开始，而且是Ajax开发中很容易的部分。当你在建造JavaScript富客户端应用时，你会遇到大量令人烦恼的事情。浏览器的兼容性、对于降级（degradation）的支持、混杂在一起的DOM处理、还有那些鲜血淋淋的hack技巧（例如离线存储），所有这些事情都会冒出来。这篇文章将会为你介绍一个远远超出对XHR进行简单封装的工具包。它是那种每个人只要开发富客户端的Ajax应用都应该使用的工具包。没有了它，你就是一个残废的开发者，只能依靠自己的力量来蹒跚前行。与其列出Dojo工具包可以使用的API，我们不如考察一个简单的应用，看看在实际开发中如何使用这个库的各个部分。我们将会讨论： Dojo是什么？ 如何设置Dojo 实际使用DOM和HTML效果 通过dojo.io.bind()实现Ajax远程调用 拖放（Drag and Drop）操作让我们开始吧！2 Dojo工具包：JavaScript开发的水槽（Kitchen Sink）Dojo工具包是什么？它是一个框架还是一个库？这个名字本身究竟意味着什么？AlexRussell，Dojo工具包的创建者之一，认为它是一个你可以用来建造JavaScript应用的库。它的内涵比你可能想到的更加丰富，因为它_在一个顶级项目的一组package中包含了如此众多的功能。Dojo中包含有很多JavaScript编写的子package，负责处理当你在建造一个JavaScript应用时通常必须要自己来编写的基础（infrastructure）工作。它封装了跨浏览器的令人烦恼的代码，这样你就不必担心它们会来给你捣乱。它可以帮助你更加容易地处理DOM。它在不同的浏览器中可以将XMLHttpRequest对象降级为使用其他的远程调用机制（译者注：例如，那些不支持XMLHttpRequest对象的浏览器），同时为你提供了最简单的和容易使用的API。JavaScript并非仅仅是关于浏览器的，它还可以运行在不同的宿主环境中，Dojo对此也提供了支持。如果你想要在服务器端编写JavaScript，仍然可以使用Dojo来使得代码更加简单。为了使你获得一个关于这个框架的感性认识，我们来列出其中的package： dojo.collections：很有用的集合数据结构（List、Query、Set、Stack、Dictionary.） dojo.crypto：实现加密功能的API（Blowfish、MD5、Rijndael、SHA.） dojo.date：无须编写丑陋的代码来解析日期格式。 dojo.dnd：拖放功能的辅助API。我们将要建造一个支持拖放功能的应用。 dojo.event：事件驱动的API，支持AOP开发，以及主题/队列的功能。 dojo.lfx：HTML和SVG效果库。我们将在例子中使用这些效果。 dojo.animation：基于Dan Pupius在动画方面的工作（http:/pupius.co.uk/js/Toolkit.Drawing.js）的动画package（不再支持，应首选dojo.lfx） dojo.fx：不再支持，应首选dojo.lfx dojo.io：不同的IO管道。cookie、IFrame、发布/订阅功能等等。所有神奇的Ajax工作都在这里完成。 dojo.lang：对于整个JavaScript环境进行增强的功能。包括你所希望拥有的很多特征，例如mixin、基于闭包（closure）的函数，以及大量的其他功能。 dojo.logging：提供日志功能的框架 dojo.math：数学函数（曲线、点、矩阵） dojo.reflect：提供反射功能的函数库 dojo.rpc：与后端服务（例如理解JSON语法的Web服务）进行通信 dojo.storage：将数据保存在本地存储中（例如，在浏览器中利用Flash的本地存储来实现） dojo.string：现在你可以对字符串进行如下的处理，修整、转换为大写、编码、esacpe、填充（pad）等等。 dojo.undo：用来撤销用户操作的栈管理器 dojo.uri：处理URI的函数库 dojo.widget：一个widget框架，允许你建造可重用的HTML/JavaScript widget，可以与简单的HTML标记共同使用（例如，）。支持基于标记的应用开发（例如：XAML、XUL） dojo.xml、dojo.dom：帮助你处理DOM的辅助函数，以及其他的XML辅助函数。我们将在这个例子中使用dojo.dom。 dojo.style：CSS功能，例如访问style的大小、与浏览器的盒模型配合工作，以及更多的功能。这确实是一个很长的列表，然而这个列表仍然未能公正地体现这个框架所做的工作。如果你使用Dojo，在开始编写一些基础的代码之前，最好先在框架中搜索一下这些功能，很可能别的某个人已经为你完成了这些功能！你很快会发现，如果你想要建造任何严肃的Ajax应用，Dojo能够为你提供大量的帮助。它可以帮助你从hack少量的onclick事件，升级到编写具有专业品质的JavaScript应用。3 设置和配置Dojo通常你是如何设置和配置一个JavaScript库的呢？你是不是简单地将JavaScript文件拷贝过来，放在Web服务器上，然后通过script src=.来访问呢？我敢肯定八成你会这样说。简单的JavaScript库就是这样来使用的，Dojo也可以这样来使用。然而，如果能够了解整个大的场景，将能够更好地使用Dojo。3.1 选择正确的Dojo创建因为这个工具包有如此众多的部分，你可以在一组创建中进行选择。为何要添加这种复杂性，而不是仅仅只提供一个下载版本呢？在大量的环境中，只提供一个下载版本不会有任何问题，但是对于浏览器中的JavaScript而言，传输给浏览器的每一K字节都是很要紧的（译者注：延迟会kill掉整个的使用体验）。如果你只想完成单个的Ajax调用，为何要将全套的package都发送给浏览器呢？我们可不想无缘无故地发出额外的比特。当你下载Dojo的一个“版本”时（从/下载zip文件，或者匿名访问Dojo的SVN服务器/dojo/trunk/），你可以在下列选项中进行选择： I/O（XHR）版本：如果所有你需要的仅仅是以Ajax的风格与服务器通信？那么请选择这个版本。 Event+I/O版本：I/O版本加上事件系统。 Ajax版本：在这个版本中你不仅得到了I/O和事件功能，而且还有killer级的可视效果。 Widget版本：如果你爱好分离CSS、内容和JavaScript，那么你可以使用这个创建来开发下一级别（next level）的widget系统 “Kitchen Sink”（水槽）版本：我不想考虑这个版本。如果你确实想要下载这个框架的每一个比特并且使得你的用户接受你的选择，这个版本将会给你想要的东西。使用水槽版本，用户将下载所有的东西，因此你无须在加入一个项目开发早期未曾预测到的package时做任何的修改。尽管如此，仍然不建议使用这个版本。不仅仅是因为你强迫所有的用户下载大量不必要的JavaScript代码，而且它在实际应用中确实会带来一些问题。例如，对于Dojo最近的一些版本而言，如果你使用了水槽版本，一些用户将会看到他们的浏览器状态条永远都告诉他们“仍然在加载.”（Still loading.）。这轻而易举地破坏了整个页面的使用体验。原因是水槽版本包括了所有的package，特别是dojo.storage.*这个package。这个package使用Flash 8来支持本地存储，在没有安装Flash 8的IE浏览器中会引起问题。这真是一个坏消息。为了开始使用一个Dojo创建，简单地从你下载的创建中找到dojo.js文件，然后以正常方式加载它：3.2 动态加载package以编程的方式请求package，使得它们可以为你所用，这不是很好的事情吗？我的意思是说，我们在其他语言中一直都是这样做的。我们在C中使用include，在Java中使用import，在Perl中使用use，在Ruby中使用require。Dojo团队也想要这样做，他们将这个功能加入了平台中。如果你需要使用一个尚未下载的package，你只需要这样做：请求这个package！在我们的例子中，我们将请求拖放、事件系统和fx这3个package：dojo.require(dojo.dnd.*);dojo.require(dojo.event.*);dojo.require(dojo.lfx.*);/ now we are ready to work with any of these packages对require方法的调用将会动态获取那些package所需的JavaScript代码，并且将它们加载进页面中。你也可以编写你自己package，并且也可以加载你的名字空间。每个包中有一些元数据来告诉请求加载器它真正需要什么。例如，这里是包含有拖放package的元数据的_package_.js文件：dojo.hostenv.conditionalLoadModule(common: dojo.dnd.DragAndDrop,browser: dojo.dnd.HtmlDragAndDrop);dojo.hostenv.moduleLoaded(dojo.dnd.*);你将会注意到，依赖于宿主环境，在运行时可以加载不同的源文件。如果你不是在一个浏览器中运行Dojo，你就不需要加载HtmlDragAndDrop的源文件。3.3 定制的创建动态地延迟加载（lazily loading）需要的JavaScript代码是很棒的，但是开发完成之后，你可能想要创建一个JavaScript文件，里面包含所有你的应用所需要的代码。很幸运，Dojo有一个创建系统，可以帮助你来做这件事。你需要下载源文件，并且从这里开始工作。源文件保存在Subversion中，代码库在：/dojo/trunk/（从项目的HEAD分支中获取）。我们可以讨论如何制作定制的创建，但是我们先将它放在一边，回到我们的应用上来。4 应用：旅行路线编辑器现在我们已经知道如何设置Dojo了，我们来使用它，将它的一些package使用在一个真实的应用中。这个页面是一个旅行路线编辑器，你可以使用它来： 为你的旅程添加和删除天 在每一天中添加和删除要访问的站点。 在不同的天之间拖放站点。所有的这些活动将在一个Ajax界面中完成。一个页面，很多操作。这个页面是整个过程中的第二步，在这里用户已经选择了站点并且完成了初始的放置。屏幕看起来像是这样：我们来开发这些功能。5 DOM和HTML效果我们首先应该做什么呢？似乎应该是开发在路线中添加新的一天的功能。为了做这件事，我们需要建造新的一天所需的HTML，包括它的标题、一个空的集合（因为还没有为它添加站点）等等。我们能够使用DOM来建造这些，但是如果我们能够只做一个拷贝，这将变得更加容易。为了做这件事，我们可以在HTML中加入一个空的表格，但是不显示它。这是一组包含列表的div，模板代码的作用是作为一个占位符（例如EMPTY DAY，而不是天号的标题，以及特殊的id，用来在程序中获取）：EMPTY DAYempty.5.1 处理DOM为了创建新的一天，我们需要为上面那段HTML制作一个拷贝，并且将它放置在文档中的正确位置。为了完成这个工作，我们可以使用一些Dojo的辅助方法： dojo.byId：我确信你输入document.getElementById()的次数比你参加宴会的次数还要多。这个简单的辅助方法不仅使你少输入一些字符，而且使你既可以传入一个文本id，也可以传入一个节点本身。这是一种实用主义的做法，它意味着你可以忘记你拥有的实际上是什么，它照样可以工作。有些读者可能会想到这看起来有点像Prototype中的函数$(id)，的确如此。为何Dojo没有决定使用一个更短的名称，例如$呢？因为他们并不想污染名字空间。$用起来很棒，但是如果别人也定义了$，并且定义略有不同，那么会怎样？这样就会有问题了。$()函数有另外一个很好的特征，它可以接受多个id/节点，并且返回它们。你可以在Dojo中使用dojo.byIdArray()来做相同的事情。将“dojo.”放在大多数调用之前的原因是Dojo通过package的语义来保证我们不会遇到这种类型的冲突。 dojo.dom.insertBefore(newElement, elementBefore); dojo.dom拥有大量的dom辅助方法，可以帮助你更好地处理DOM（DOM处理在Ajax开发中不是一件痛苦的事情吗？）我们使用这个功能来将新的一天放置在上一天（unused-sites）之前。AddDay()方法完整的代码如下所示。这里有一点冗余，因为它必须要重置新的天号的id，增加总共的天数，等等：function addDay() var lastDay = dojo.byId(unused-sites);var emptyDayTemplate = dojo.byId(empty-new-day);numberOfDays+; / we have one more day nowvar newDay = emptyDayTemplate.cloneNode(true);newDay.id = fullday- + numberOfDays;/ set the titlenewDay.childNodes1.childNodes1.nodeValue = day + numberOfDays;/ set the new ol idvar ol = newDay.childNodes3;ol.id = day- + numberOfDays;/ set the new empty li idvar li = ol.childNodes1;li.id = empty-day- + numberOfDays;setupDayForDND(newDay); / drag and drop explained laterdojo.dom.insertBefore(newDay, lastDay);dojo.fx.wipeIn(newDay, 500); / effect below你可以看到大量标准的DOM方法，例如node.cloneNode(true)，正是这个调用拷贝了空的一天的模板，然后我们更新其中的字段。我们传递true标志告诉DOM需要拷贝节点中的节点，进行深度遍历。还有哪些其他的dojo.dom辅助方法？你也许能够从名称上判断出这些跨浏览器的辅助方法是做什么的： dojo.dom.isNode dojo.dom.getTagName dojo.dom.firstElement dojo.dom.lastElement dojo.dom.nextElement dojo.dom.prevElement dojo.dom.moveChildren (srcNode, destNode, trim) dojo.dom.copyChildren (srcNode, destNode, trim) dojo.dom.removeChildren(node) dojo.dom.replaceChildren(node, newChild) dojo.dom.removeNode(node) dojo.dom.getAncestors dojo.dom.getAncestorsByTag dojo.dom.innerXML dojo.dom.createDocumentFromText dojo.dom.prependChild dojo.dom.insertAfter dojo.dom.insertAtPosition dojo.dom.textContent: 实现了DOM Level 3的属性5.2 Dojo的HTML效果我们使用dojo.dom来加入新的一天，但是仅仅这样做还不够好。我们并不想使用户的视线移动，我们想在文档改变的地方，同时显示这个变化。Script.aculo.us因为它的killer级的效果库而广为人知，但是很多人并不知道Dojo也有自己的效果库。我们选择使用dojo.lfx.wipeIn()来处理这个节点，使得产生的效果好象是将百叶窗关上。然而我们不必将它擦去。也许你更加喜欢一种淡入/淡出/隐藏的渐变效果、一种幻灯片播放的效果、一种颜色渐变/高亮的效果、或者一种向外/向内的爆炸效果？Dojo支持所有这些效果，并且它们都使用一行代码即可完成，并且还支持为效果添加回调函数的能力。这些效果可能看起来不过是像口红一样的点缀，无关大局，但是它们为你的应用增添了光泽，使得你的用户发出“喔”的一声赞叹，并且它们对于改善应用的可用性也大有帮助。尽管如此，还要记住一个警告，就是你不要想将页面上的所有操作方式都推翻。如果我们这样做，人们会认为我们是Flash开发者。6 使用dojo.io.bind()的Ajax远程调用我们来为这个应用添加一些Ajax功能。我们想要使用户以一种响应迅速的方式删除天和站点。我们不需要页面的刷新，我们仅仅想要愉快地在用户界面上处理天和站点。然而，我们不能仅仅从屏幕上删除元素，而不告诉后端，否则天/站点将仍然存在于后端的状态中。这意味着我们应该遵循一个通用的模式： 通过DOM来动态改变用户界面 发送Ajax请求到后端，告诉后端发生的这个变化（例如，为这个用户删除了第5天）这里是我们用来删除天的高层函数：function deleteDay(removeDay) if (confirm(Are you sure you want to delete this entire day?) / get the actual li site node from the remove buttonvar day = removeDay.parentNode.parentNode.parentNode;fadeAndRemove(day);/ call the back-endremoteDeleteDay(day);return true; else return false;我们确信这个用户想要除去这一天（而不是不小心点击了鼠标），然后我们取消了这一天。6.1.1 淡出和移除首先我们通过函数fadeAndRemove(day)优雅地从用户界面中除去了这一天：function fadeAndRemove(e) dojo.lfx.fadeHide(e,1000,dojo.lfx.easeIn,function(nodes) dojo.lang.forEach(nodes, dom.removeNode);).play();这里再次展示了dojo.dom和dojo.fx的组合使用。我们请求Dojo来淡出指定的元素（在这里是天），并且为它传递一个回调函数，当淡出完成后调用。那个闭包得到了指定的节点，当调用完成时，fadeHide函数很好地为你除去了这个节点。forEach方法展示了可以通过dojo.lang来使用的迭代器的用法。新的dojo.lfx包有一个新的pertyAnimation方法，允许你传递很多属性，以一种简单的方式来定制动画的效果。例如，要实现一个简单的淡入效果，你可以使用：dojo.lfx.fadeIn(node, 200, dojo.lfx.easeOut, callback).play();在更低的层次你可以这样来写：pertyAnimation(node, property: opacity, start: 0, end: 1 , 200).play();现在你可以添加越来越多的属性到数组中，以创造各种生动有趣的动画效果。6.1.2 使用XMLHttpRequest来告诉服务器发生了什么remoteDeleteDay()调用通过Dojo来（可能）使用XMLHttpRequest与服务器通信。当人们在谈论Ajax的时候，你常常会看到大量关于如何实现XMLHttpRequest对象的跨浏览器封装的例行讨论，以及像“4”那样奇怪的状态代码。Dojo为你承担了所有这些工作，为你提供了一个非常清晰的API（译者注：因此你不需要再重新发明轮子），看起来像是这样：dojo.io.bind(url: http:/path/to/server,load: function(type, data, evt) do something onload,error: function(type, error) handle an error ,mimetype: text/plain/ and many more options!);基本上，所有的远程调用都要通过一个dojo.io.bind()方法调用。这个方法作的工作比你能想到的还要多： 如果选择了XMLHttpRequest，Dojo将为给定的浏览器找到那个对象。 使用关键字：transport: “X”来明确使用XMLHttpRequest，或者IFrameIO、或者. 99%的时间你可以将这些工作完全留给Dojo来处理，Dojo将会为你找到最佳的解决方案！ 如果浏览器不支持XHR，Dojo可以降级使用一个隐藏的iframe来实现远程调用。 支持XHR对象的缓存 使用关键字：useCache: true 支持制作书签的能力 使用关键字：changeURL: true（使用一个自动的值）或者使用“ajaxian”作为你自己的值 支持浏览器的Back/Forward按钮 使用关键字：backButton: code, forwardButton: code。例如，在我们的书PragmaticAjax（译者注：中文版名为Ajax修炼之道，电子工业出版社出版）中，我们使用了这个例子：backButton: function() saveCityState();cleanCityState();,forwardButton: function() setupCityState(); 你可以使用XHR来提交一个表单 使用关键字：formNode: dojo.byId(yourFormId) 支持上传整个文件。首先，你需要确信已经加载了iframe的支持（dojo.require(dojo.io.IframeIO)），随后告诉Dojo上传的这个文件。file: name: upload.txt,contentType: plain/text,content: look ma! no form node!不过，为了完成remoteDeleteDay()，你只需要使用一个简单的dojo.io.bind()调用，它会访问你所选择的后端URL，这个URL应该是一个理解你正在做什么的Web服务。对于load: handler你无须做很多工作，因为在这里我们不会基于任何返回的信息来改变UI。然而，在error: 这部分你可能需要撤销你刚才所作的变化，用一个error消息告诉用户这一天不能被删除（使用一个从服务器返回的消息）。7 拖放操作Web用户对于在这种媒体上实现的拖放操作不是很习惯。因为这个原因，我们需要对于提供支持拖放功能的界面保持谨慎，也许需要提供一个可以不单独依赖拖放操作的界面。提供拖放支持可以使得一些任务更加容易使用。在我们的应用中，用户可以在路线中可视化地移动站点，而不是必须要进入一些编辑模式来将它们从奇怪的列表中移动。为dojo配置拖放功能实际上要比你可能想象的更加容易。我们将通过3个阶段来完成这件工作：1. 连接day元素，告诉系统什么可以拖拽，什么可以放置拖拽的元素。2. 给定某一天，连接它的子元素。3. 告诉浏览器来做这个连接7.1.1 连接所有的天最初的函数将遍历所有的天，告诉每一天准备好放置站点，然后将所有的站点设置为可拖拽的对象。一旦天被设置好了，也会配置未使用的站点区域（unused sites area）。function enableSiteMoving() for (var d=1; d = numberOfDays; d+) var dl = dojo.byId(day- + d);setupDayForDND(dl);var lis = dl.getElementsByTagName(li);for(var x=0; xlis.length; x+)new dojo.dnd.HtmlDragSource(lisx, daylist);/ configure the unused sitesvar unusedSitesDiv = dojo.byId(unused-sites);var lis = unusedSitesDiv.getElementsByTagName(li);for (var x=0; xlis.length; x+)new dojo.dnd.HtmlDragSource(lisx, daylist);7.1.2 连接单个的天大量的神奇效果发生在以下的几行代码中。为了设置天，我们获得通过enableSiteMoving()传递进来的天的列表，然后我们初次使用dojo.event的API。这个API允许你连接并且截取DOM节点上的方法，以及任何的JavaScript函数。这正是AOP式开发的用武之地。例如，如果你想要记录（log）某个函数的每一次调用，