Permalink
Browse files

updated readme

  • Loading branch information...
1 parent 152e8f4 commit 704c418af94870033be1adc90b1d7793e4913d1c @rmurphey rmurphey committed Mar 6, 2011
Showing with 50 additions and 20 deletions.
  1. +50 −20 README.md
View
@@ -1,33 +1,63 @@
dojo-boilerplate
================
-dojo-boilerplate is a base set of files that anyone can use to get up and running immediately with the Dojo Toolkit
-(DTK) when starting development of complex Web apps. It illustrates some basic best practices when working with DTK and
-includes a working build system with asynchronous loader (courtesy of [RequireJS](http://requirejs.org)) for
-effortless development and tiny, blazing fast production builds.
+The Dojo boilerplate is a set of files to get you up and running with the Dojo
+Toolkit (DTK). It illustrates some basic best practices when working with DTK,
+and includes a build system that uses [RequireJS](http://requirejs.org) for
+efficient development and tiny, blazing fast production builds. The goal of
+this repository is to provide an up-to-date tool for JavaScript developers to
+rapidly get up and running with Dojo. We welcome patches and pull requests.
-Huge thanks go out to [neonstalwart](https://github.com/neonstalwart) for his no longer maintained
-[dojo-requirejs-template](https://github.com/neonstalwart/dojo-requirejs-template) project, which was instrumental in
-providing guidance for integrating RequireJS with Dojo 1.6. Unlike dojo-requirejs-template, this boilerplate will
-be continually updated to reflect current best practices and track new releases of DTK, and we encourage everyone to
-submit issues and pull requests.
+Huge thanks go out to [neonstalwart](https://github.com/neonstalwart) for his
+original
+[dojo-requirejs-template](https://github.com/neonstalwart/dojo-requirejs-template)
+project. Though that repository is no longer maintained, it was instrumental in
+providing guidance for integrating RequireJS with Dojo 1.6.
-How does use these dojo-boilerplates!?
---------------------------------------
+Using the boilerplate
+---------------------
+0. Clone the repository.
1. Run `util/setup.sh` to automatically download all required dependencies.
-2. Develop your stuff in `src/` until it is amazing.
+2. Develop your project in `src/` until it is amazing.
3. Run `util/build.sh`, which will create an awesome optimised build in `dist/`.
-4. Upload `dist/` somewhere for millions of people the world over to enjoy.
+4. Upload `dist/` for millions of people the world over to enjoy.
5. Hapyness.
-Potential issues
+If you are on Windows, we have not yet created build scripts to download the
+required files automatically. Pull requests are welcome :)
+
+A brief tour
+------------
+
+* The boilerplate provides the file `src/js/app/base.js` as the starting point
+ for your development
+* The `src/index.html` file loads the configuration file located at
+ `src/js/app/_base.js`, which in turn asynchronously loads
+ `src/js/app/base.js`.
+* The file `util/build.sh` reads the profile file at `profiles/app.js`, which
+ contains instructions to RequireJS on how to build the files for production.
+ The profile instructs RequireJS to create a single file that includes Dojo,
+ your application's code, and all associated dependencies as specified within
+ your application's code.
+
+Useful resources
----------------
-* Current releases of DTK don’t include an asynchronous loader. We use RequireJS as a stand-in until the official
-loader and build system are complete. (Since both RequireJS and bdLoad both comply with the CommonJS AMD standard, you
-will be ready to go with no changes to your application’s code when the new official loader is ready. Yay for
-standards!)
+* [DTK Reference Guide](http://dojotoolkit.org/reference-guide/)
+* [RequireJS documentation](http://requirejs.org/docs/api.html)
+
+Potential issues
+----------------
-* Because DTK currently uses `dojo.cache` for its widget templates instead of the AMD `text!` plugin, those strings
-will end up being loaded twice. This has been reported upstream at [ticket #12383](http://bugs.dojotoolkit.org/ticket/12383).
+* Current releases of DTK don’t include an asynchronous loader. We use
+ RequireJS as a stand-in until the official loader and build system are
+ complete. Current discussions suggest that Dojo will ultimately use bdLoad as
+ its loader; however, it does not presently include a build system. Since both
+ RequireJS and bdLoad both comply with the CommonJS AMD standard, you will be
+ ready to go with no changes to your application’s code when the new official
+ loader is ready. Yay standards!
+* DTK currently uses `dojo.cache` for its widget templates instead of the AMD
+ `text!` plugin; this means that strings included by widgets using
+ `dojo.cache` will end up being loaded twice. This has been reported upstream
+ at [ticket #12383](http://bugs.dojotoolkit.org/ticket/12383).

0 comments on commit 704c418

Please sign in to comment.