Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 139 lines (92 sloc) 5.027 kb
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
1 .. _dojo/require:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
2
f89feb8 @wkeese regex change of level 1 headers to ====\nTEXT\n==== and level 2 headers ...
wkeese authored
3 ============
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
4 dojo.require
5 ============
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
6
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
7 :Status: Draft
8 :Version: 1.0
9 :Available: since V?
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
10
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
11 .. contents::
12 :depth: 2
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
13
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
14 Loads a Dojo module, by name.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
15
16
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
17 Introduction
18 ============
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
19
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
20 In order to use a Dojo module or widget, you have to load the module with dojo.require('modulename'). If you don't do that, your scripts will throw a "dojo.some not defined" or "dojo.some.randomFunction not defined". There are a few exceptions to this rule, which are explained below.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
21
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
22 Dojo's package concept
23 ----------------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
24
aa84a72 @wkeese dojo/ spelling
wkeese authored
25 Dojo's code is split into modules which are similar to packages in Java except that in Dojo a module can contain both constructors (like classes in Java) and simple functions. For example, the "dojo.string" module contains a number of functions, such as :ref:`dojo.string.substitute() <dojo/string>`. The ":ref:`dojo.dnd <dojo/dnd>`" module contains a number of constructors such as dojo.dnd.Container dojo.dnd.Source in addition to top-level functions and properties on the dojo.dnd object.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
26
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
27 Naming conventions
28 ------------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
29
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
30 Note the naming convention - functions, properties, and namespace objects start with a lowercase letter, and constructors (which are technically functions but act more like classes) start with a capital letter. Classes in Dijit preceded by an underscore typically denote a mixin, or baseClass.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
31
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
32 dojo.require()'s comfort
33 ------------------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
34
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
35 At first, it may seem painful to require all modules, but Dojo rewards by:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
36
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
37 * Loading any dependent scripts for you.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
38
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
39 If :ref:`dijit.form.NumberTextBox <dijit/form/NumberTextBox>` requires :ref:`dojo.number <dojo/number>`, you still need only require dijit.form.NumberTextBox.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
40
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
41 * Preventing loading Dojo packages twice.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
42
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
43 dojo.require will simply return if the package is already loaded.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
44
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
45 * Allowing you to build streamlined versions of dojo.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
46
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
47 If you use dijit.form.TextBox a lot, you can build a custom version of dojo that loads dijit.form.TextBox quickly. Dojo.require() knows whether the function is already loaded, and so you don't have to change any of your code. See The Build System for a discussion.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
48
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
49 So you might wonder "So, don't I have to require the dojo module itself to use dojo.require?" Nope. Any function in the top-level package "dojo" is loaded automatically (dojo.query(), dojo.byId(), etc.). These are Dojo's Core functions, and represent the most used functions according to usage patterns in the community. This is similar to the Java package java.lang, which is automatically available to all Java programs.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
50
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
51 Cooperation with addOnLoad
52 ---------------------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
53
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
54 dojo.require works directly with :ref:`dojo.addOnLoad <dojo/addOnLoad>`. While modules are being loaded, any addOnLoad functions will wait until all dependencies are solved before firing again.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
55
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
56 Additionally, you can re-call addOnLoad anytime you immediately call dojo.require, in order to ensure the modules and dependencies are ready. Even after page load!
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
57
c49c87d @phiggins42 normalization
phiggins42 authored
58 .. js ::
ffa767c @phiggins42 removing :linenos: rather than reverting previous commit. revert both fo...
phiggins42 authored
59
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
60 //Dojo 1.7 (AMD)
61 require(["dojo/ready","dojo/fx"], function(ready,fx) {
62 ready(function(){
63 require(["dijit/form/Button","dojo/_base/window"], function(btn,win) {
64 ready(function(){
65 new dijit.form.Button({}).placeAt(win.body());
66 });
67 });
68 });
69 });
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
70
71
c49c87d @phiggins42 normalization
phiggins42 authored
72 .. js ::
ffa767c @phiggins42 removing :linenos: rather than reverting previous commit. revert both fo...
phiggins42 authored
73
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
74 //Dojo < 1.7
75 dojo.require("dojo.fx");
76 dojo.addOnLoad(function(){
77 dojo.require("dijit.form.Button");
78 dojo.addOnLoad(function(){
79 new dijit.form.Button({}).placeAt(dojo.body());
80 });
81 });
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
82
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
83 Usage
84 =====
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
85
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
86 Simply pass it a string:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
87
c49c87d @phiggins42 normalization
phiggins42 authored
88 .. js ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
89
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
90 //Dojo 1.7 (AMD)
91 // load dojo/fx.js:
92 require(["dojo/fx"], function(fx) {
93 //Write your code here
94 });
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
95
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
96 // load dojox/widget/Toaster.js:
97 require(["dojo/widget/Toaster"], function(Toaster) {
98 //Write your code here
99 });
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
100
c49c87d @phiggins42 normalization
phiggins42 authored
101 .. js ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
102
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
103 //Dojo <1.7
104 // load dojo/fx.js:
105 dojo.require("dojo.fx");
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
106
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
107 // load dojox/widget/Toaster.js:
108 dojo.require("dojox.widget.Toaster");
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
109
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
110 Throughout Dojo, the pattern above remains consistent. However, by using :ref:`dojo.registerModulePath <dojo/registerModulePath>` in your code, you are able to redefine the meaning of parts of namespaces.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
111
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
112 Examples
113 ========
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
114
1f9b928 @phiggins42 bulk deprecated removal and normalization
phiggins42 authored
115 .. code-example ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
116
1f9b928 @phiggins42 bulk deprecated removal and normalization
phiggins42 authored
117 .. js ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
118
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
119 <script type="text/javascript">
120 // The following line will load the Dijit Widget "dijit.form.Button".
121 // Without this line you will get a "dijit.form.Button not defined" error.
122 dojo.require("dijit.form.Button");
123 </script>
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
124
1f9b928 @phiggins42 bulk deprecated removal and normalization
phiggins42 authored
125 .. html ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
126
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
127 <div data-dojo-type="dijit.form.Button">
128 Just an example button, please don't click
129 <script type="dojo/method" data-dojo-event="onClick" data-dojo-args="evt">
130 alert("I said, please don't click!");
131 </script>
132 </div>
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
133
134
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
135 See Also
136 ========
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
137
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
138 * `Understanding dojo.declare, dojo.require, and dojo.provide <http://dojocampus.org/content/2008/06/03/understanding-dojodeclare-dojorequire-and-dojoprovide/>`_ - 2008-06-03 - Dojo Cookie article
Something went wrong with that request. Please try again.