grunt-addgears v0.1.2
Grunt Addgears
This package provides grunt tasks which help to package Addgears extensions. Internally, it uses and depends on addgears package.
Installation
Make sure you have node.js installed. Install grunt-cli. If you didn't install Addgears install it using grunt install command:
npm install grunt-addgears
cd grunt-addgears
npm install grunt-cli -g
grunt installInstaller script downloads and installs Addgears application. For additional information on Addgears installation see addgears package.
Extensions architecture
Addgears is implemented on top of node-webkit which makes it easy to extend Addgears leveraging common open standards and technologies: HTML5, CSS3 and node.js. Addgears provides a simple way to distribute various resources. These resources are bundled and delivered as updates or extensions. Each update is a directory containing resources. On Addgears start-up, it checks for update subdirectory in the application directory. When the update is found, Addgears installs its resources and removes the update directory.
First of all, Addgears can access node.js modules. They are located in a node-modules subdirectory of the installation directory. Upon update Addgears moves modules from update/node-modules subdirectory to the installation directory, overriding old modules.
Also Addgears can use Javascript, CSS and HTML resources. Node-webkit allows to load HTML pages directly from disk. While this is the natural and simple approach, regrettably it is not general enough. For example, it can't be used in the browser, in HTML5 applications. Such applications don't have direct access to local file system and it is not practical to reload such resources over network.
To make resource access more portable, Addgears introduces a very thin and simple abstraction layer for resource distribution. Before resources can be used in Addgears environment they should be packed. There are two distinct pack types: pages and files. The page is just a collection of HTML, CSS and Javascript files. It is a most convenient and portable resource type. A file type is a Javascript, loaded on demand (using eval function). For security reasons many environments discourage or even disallow (e.g. in browser's plugins) eval function. Still Addgears widely uses on demand asynchronous loading as it allows for better, modular design.
Addgears' packaging system is not intended as a substitute for the tools like browserify, require.js, _webpack, etc. It is most likely a good idea to use one of these tools to modularize any code base (especially when it becomes big enough). Addgears' packaging system is just a simple packaging and distribution system, which works well on top of all such tools.
All packed Addgears resources are just standard json files. Each has the path field while content varies depending on the resource type. Simple Javascript files are packed as:
{
"path": "some/path.js",
"content": "concatenation of javascript files"
}The HTML page is represented as a collection of HTML, Javascript, and CSS files:
{
"path": "some/path.html",
"entities":[
{type:"html", data:"<html>string with html content</html>"},
{type:"js", data:"the string content of javascript file"},
{type:"css", data:".css-styles{...}"},
...
]
}To load a new resource into Addgears packed json file must be copied into an update subdirectory of the installation directory and listed in a pack file located there. New resource overrides the old ones with the same path.
Grunt
To simplify resource packaging the package provides a few grunt tasks. To load these grunt tasks, add grunt.loadNpmTasks('grunt-addgears') to your Gruntfile.
To package the page resource configure addgears task like this:
addgears:{
hello:{
options:{
sourceUrl:true, // optionally add sourceUrl to *.js files
path:"examples/hello.html" // virtual path to the resource
},
dest:"build/hello.html", // where to save packed file
src: [
'examples/hello-page/*.html', // files in order they are used
'examples/hello-page/*.js'
]
}
} To package the Javascript or HTML or CSS file, use the similar configuration (just with the type : "file") added:
hello:{
options:{
sourceUrl:true, // optionally add sourceUrl to *.js files
path:"test.js", // virtual resource path
type:"file"
},
dest:"build/test.js", // where to save
src: [
'lib/test*.js' // path to the files
]
}
} To copy packed resources to Addgears update directory use addgearsUpdate task:
addgearsUpdate:{
options:{
apply:false // don't load, just copy to update directory
},
hello:{
src:"build/hello.html" // path to resource
},
pack:{
options:{
type:"node", // copy node.js files (to update/node-modules)
root:"examples" // the path prefix (removed from the path, when copied)
},
src:"examples/test-package/**" // path to node.js modules
}
},The addgearsUpdate task overrides files already in update directory each time it is invoked (including the list of resources in the pack file). To apply an update immediately (removing the update directory) use an apply: true configuration option. To clean the update directory use the addgearsUpdateDrop task. To open the page, use addgearsRun task:
addgearsRun:{
hello:{
page:'examples/hello.html' // page path
}
}The package comes with the examples directory and a sample Gruntfile, containing the configuration to pack, load and open simple Hello World page invoking node.js module test-package. Use
grunt helloto pack, load and open _Hello world_page.
License
This package is licensed under MIT license, Addgears is licensed separately. To use it you must agree with the terms and conditions first.