Skip to content
Browse files

Added more docs

  • Loading branch information...
1 parent a9a16ea commit 274c9ddd6b70976e29d668004ccb0ff07f37a61c @asciidisco committed Dec 3, 2012
Showing with 133 additions and 49 deletions.
  1. +1 −1 CHANGELOG
  2. +18 −5 README.md
  3. +19 −1 docs/almondIntegration.md
  4. +24 −1 docs/customBuilder.md
  5. +14 −0 docs/customrjs.md
  6. +14 −2 docs/hybridBuilds.md
  7. +5 −1 docs/sourcemaps.md
  8. +38 −37 lib/almondify.js
  9. +0 −1 lib/helper/errorhandler.js
View
2 CHANGELOG
@@ -19,7 +19,7 @@ v0.3.0:
- Added support for sourceMaps when using 'uglify2'
- Preparation for the merge with grunt-contrib-requirejs
- Removed not needed Dual Config
- - Added needed code comments
+ - Added code comments
v0.2.14:
commit: c6258f7a00d2fdb7927e5b9c3be3dc75546f1a98
View
23 README.md
@@ -51,32 +51,45 @@ You see, there is no difference in declaring your require config when your using
instead of using a separate requirejs config file.
## Almond
-If you like to replace require.js with almond.js during the build process, grunt-requirejs comes with an [almond](https://github.com/jrburke/almond) injection mode.
-It even can be used to convert your require script calls in your html files to call the 'almondyfied' module, instead of calling require.js
-that then calls (e.g. loads) the module.
+_grunt-requirejs is capable of replacing require.js with almond.js automatically_
For more infos please take a look at the [Almond Integration](https://github.com/asciidisco/grunt-requirejs/blob/master/docs/almondIntegration.md) document
## Custom builds
+_grunt-requirejs can generate custom jQuery, Lo-Dash & Backbone.js versions during the optimization_
+
For more infos please take a look at the [Using Custom Builds](https://github.com/asciidisco/grunt-requirejs/blob/master/docs/customBuilder.md) document
## Hybrid minification
+_grunt-requirejs can minify your optimized output files using an hybrid strategy utilitizing uglifyjs & closure compiler_
+
For more infos please take a look at the [Using Hybrid Builds](https://github.com/asciidisco/grunt-requirejs/blob/master/docs/hybridbuilds.md) document
## Using custom r.js versions
+_grunt-requirejs lets you specify a custom r.js for your build_
+
For more infos please take a look at the [Using Custom r.js versions](https://github.com/asciidisco/grunt-requirejs/blob/master/docs/customrjs.md) document
## Using source maps
+_grunt-requirejs can generate sourcemaps when using the r.js v2.1.2 or higher_
+
For more infos please take a look at the [Using Source Maps](https://github.com/asciidisco/grunt-requirejs/blob/master/docs/sourcemaps.md) document
## Examples
-xxx
+
+There are some project & configuration examples to get you startet:
+
+ - [libglobal](https://github.com/asciidisco/grunt-requirejs/tree/master/examples/libglobal)
+ - [libgloabl-hybrid](https://github.com/asciidisco/grunt-requirejs/tree/master/examples/libglobal-hybrid)
+ - [multipage](https://github.com/asciidisco/grunt-requirejs/tree/master/examples/mutlipage)
+ - [multipage-shim](https://github.com/asciidisco/grunt-requirejs/tree/master/examples/multipage-shim)
+
## Release History
Check the [Changleog](https://github.com/asciidisco/grunt-requirejs/blob/master/CHANGELOG) for more information
## Contributing
-If you like to file an issue or submit a pull request, please check the [contributing guidelines](https://github.com/asciidisco/grunt-requirejs/blob/master/CONTRIBUTION.md)
+If you like to file an issue or submit a pull request, please check the [contributing guidelines](https://github.com/asciidisco/grunt-requirejs/blob/master/CONTRIBUTING.md)
## Contributors
Check the [AUTHORS File](https://github.com/asciidisco/grunt-requirejs/blob/master/AUTHORS.md) for more information
View
20 docs/almondIntegration.md
@@ -1,8 +1,23 @@
# Almond
+If you like to replace require.js with almond.js during the build process, grunt-requirejs comes with an [almond](https://github.com/jrburke/almond) injection mode.
+It even can be used to convert your require script calls in your html files to call the 'almondyfied' module, instead of calling require.js
+that then calls (e.g. loads) the module.
+
+## Options
+
+### almond ```boolean``` (optional)
+
+This is used indicate if grunt-requirejs should include almond in your combined js file.
+
+
+### replaceRequireScript ```array``` (optional)
+
+This is used to define the files where the script tag attributes should be replaced
+and which modules should be taken into account.
+
## Including almond
-```javascript
requirejs: {
myTaskDefinition: {
options: {
@@ -23,6 +38,9 @@
## Including almond & replacing ´script´ tags in html sources
+grunt-requirejs is also capable of automatically changing the src attribute
+in your html script tags.
+
```javascript
requirejs: {
myTaskDefinition: {
View
25 docs/customBuilder.md
@@ -1,6 +1,23 @@
# Custom builder support
-_grunt-requirejs supports multiple custom build options_
+grunt-requirejs supports multiple custom build options, based on the functionality of already available grunt plugins
+
+## Options
+
+### builder ```object``` (optional)
+
+This property is used to define the custom build options
+
+
+### builder:alias ```string``` (optional)
+
+The alias property of each custom build task lets you define the library that should
+be replaced with the custom build.
+
+For example, if you like tp replace uinderscore.js with a custom lodash.js build,
+alias the lodash builder with ```alias: 'underscore'```.
+If not set, the builders default to 'jquery', 'backbone' & 'lodash'.
+
## General information
@@ -30,6 +47,8 @@ _grunt-requirejs supports multiple custom build options_
## Lo-Dash
+See all available options [here](https://gihtub.com/asciidisco/grunt-lodashbuilder)
+
```javascript
builder: {
lodash: {
@@ -41,6 +60,8 @@ _grunt-requirejs supports multiple custom build options_
## jQuery
+See all available options [here](https://gihtub.com/asciidisco/grunt-jquerybuilder)
+
```javascript
builder: {
jquery: {
@@ -51,6 +72,8 @@ _grunt-requirejs supports multiple custom build options_
## Backbone
+See all available options [here](https://gihtub.com/asciidisco/grunt-backbonebuilder)
+
```javascript
builder: {
backbone: {
View
14 docs/customrjs.md
@@ -1,5 +1,19 @@
# Using custom r.js versions
+Normally, grunt-requirejs instruments the latest r.js version to build your project.
+If you need to build your project against an older r.js version, you can do so by adding
+the special ´rjs´ option.
+
+## Options
+
+### rjs ```string``` (optional)
+
+This is used to define a path to a custom r.js version
+
+If you´re custom requirejs npm module is stored under ```node_modules/requirejs```,
+the rjs property should point to that folder.
+
+
## Example
```javascript
View
16 docs/hybridBuilds.md
@@ -1,5 +1,17 @@
# Hybrid builds
+Inspired by [Lo-Dashs](http://lodash.com/) custom build strategy, grunt-requirejs
+can minify your output with uglify & closure-compiler, checking which version is the smallest.
+
+## Options
+
+### optimize ```string```
+
+Optimizes a the builder output with ulgify, closure-compiler & a combination of both optimizers,
+checking which is the smallest output file & using this.
+
+Note: Sometimes closure-compilers screws up your files, use this optimizer strategy with caution.
+
## Example
```javascript
@@ -8,8 +20,8 @@
options: {
baseUrl: 'my/project',
name: 'project',
- out: 'dist/main-sourcemapped.js',
- optimize: "hybrid"
+ out: 'dist/main.js',
+ optimize: 'hybrid'
}
},
```
View
6 docs/sourcemaps.md
@@ -1,5 +1,9 @@
# Sourcemaps
+Sourcemaps can be used like described in the [requirejs docs](http://requirejs.org/docs/optimization.html#sourcemaps)
+
+Note: Make sure to set the optimize property to ´uglify2´!
+
## Example
```javascript
@@ -9,7 +13,7 @@
baseUrl: 'my/project',
name: 'project',
out: 'dist/main-sourcemapped.js',
- optimize: "uglify2",
+ optimize: 'uglify2',
generateSourceMaps: true,
preserveLicenseComments: false,
useSourceUrl: true
View
75 lib/almondify.js
@@ -22,53 +22,54 @@ exports.init = function(grunt) {
// check if we should inline almond
if (config.almond === true) {
- // log that we´re including almond
- grunt.verbose.writeln('Including almond.js');
- // prepare the paths object (in case it hasn´t been set yet)
- configClone.paths = configClone.paths || {};
+ // log that we´re including almond
+ grunt.verbose.writeln('Including almond.js');
- // set almond path
- configClone.paths.almond = require.resolve('almond').replace('.js', '');
+ // prepare the paths object (in case it hasn´t been set yet)
+ configClone.paths = configClone.paths || {};
- // check if the 'removeCombined' option is enabled
- // then use a temporary almond file to ensure that the
- // almond.js source file doesn´t get deleted
- if (config.removeCombined === true) {
- configClone.__origAlmond = String(fs.readFileSync(configClone.paths.almond + '.js'));
- }
+ // set almond path
+ configClone.paths.almond = require.resolve('almond').replace('.js', '');
- // modify modules data
- if (!util._.isArray(moduleIterator)) {
- moduleIterator = [{name: config.name}];
+ // check if the 'removeCombined' option is enabled
+ // then use a temporary almond file to ensure that the
+ // almond.js source file doesn´t get deleted
+ if (config.removeCombined === true) {
+ configClone.__origAlmond = String(fs.readFileSync(configClone.paths.almond + '.js'));
+ }
- if (!util._.isArray(configClone.include)) {
- configClone.include = [configClone.name];
- } else {
- configClone.include.unshift(configClone.name);
- }
+ // modify modules data
+ if (!util._.isArray(moduleIterator)) {
+ moduleIterator = [{name: config.name}];
- configClone.name = 'almond';
+ if (!util._.isArray(configClone.include)) {
+ configClone.include = [configClone.name];
+ } else {
+ configClone.include.unshift(configClone.name);
}
- // modify modules data
- moduleIterator.forEach(function(module, idx) {
- // log adding of almond to a specific module
- grunt.verbose.writeln('Adding almond to module: ' + module.name);
-
- // check if the module has its own includes
- // then append almond to them
- // else generate a new includes property
- if (util._.isArray(module.include)) {
- configClone.modules[idx].include.unshift(configClone.modules[idx].name);
- configClone.modules[idx].name = 'almond';
- } else {
- if (!util._.isUndefined(configClone.modules)) {
- configClone.modules[idx].include = ['almond'];
- }
+ configClone.name = 'almond';
+ }
+
+ // modify modules data
+ moduleIterator.forEach(function(module, idx) {
+ // log adding of almond to a specific module
+ grunt.verbose.writeln('Adding almond to module: ' + module.name);
+
+ // check if the module has its own includes
+ // then append almond to them
+ // else generate a new includes property
+ if (util._.isArray(module.include)) {
+ configClone.modules[idx].include.unshift(configClone.modules[idx].name);
+ configClone.modules[idx].name = 'almond';
+ } else {
+ if (!util._.isUndefined(configClone.modules)) {
+ configClone.modules[idx].include = ['almond'];
}
+ }
- });
+ });
}
View
1 lib/helper/errorhandler.js
@@ -11,7 +11,6 @@ module.exports = function(grunt) {
// fail task & log the error
return function(error) {
- console.log(error);
grunt.log.error(error);
// this.done referres to grunts ´async´ method
this.done(false);

0 comments on commit 274c9dd

Please sign in to comment.
Something went wrong with that request. Please try again.