You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by sg...@apache.org on 2014/09/26 23:20:03 UTC
[04/13] git commit: CB-6481 Updated hooks documentation
CB-6481 Updated hooks documentation
Project: http://git-wip-us.apache.org/repos/asf/cordova-lib/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-lib/commit/f1398408
Tree: http://git-wip-us.apache.org/repos/asf/cordova-lib/tree/f1398408
Diff: http://git-wip-us.apache.org/repos/asf/cordova-lib/diff/f1398408
Branch: refs/heads/master
Commit: f1398408ee9e506b7e92e48f6b11a5a2fb3a9900
Parents: a972451
Author: daserge <da...@yandex.ru>
Authored: Wed Jul 9 16:20:11 2014 +0400
Committer: daserge <da...@yandex.ru>
Committed: Thu Sep 25 18:59:08 2014 +0400
----------------------------------------------------------------------
cordova-lib/templates/hooks-README.md | 123 ++++++++++++++++++++++++++++-
1 file changed, 120 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-lib/blob/f1398408/cordova-lib/templates/hooks-README.md
----------------------------------------------------------------------
diff --git a/cordova-lib/templates/hooks-README.md b/cordova-lib/templates/hooks-README.md
index accfa3a..464bd3d 100644
--- a/cordova-lib/templates/hooks-README.md
+++ b/cordova-lib/templates/hooks-README.md
@@ -25,11 +25,18 @@ directory used to exist at `.cordova/hooks`, but has now been moved to the
project root. Any scripts you add to these directories will be executed before
and after the commands corresponding to the directory name. Useful for
integrating your own build systems or integrating with version control systems.
+Hook scripts can also be defined in `config.xml` and `plugins/.../plugin.xml`
+and will be run serially in the following order:
+* Application hooks from `.cordova/hooks`;
+* Application hooks from `/hooks`;
+* Application hooks from `config.xml`;
+* Plugin hooks from `plugins/.../plugin.xml`.
__Remember__: Make your scripts executable.
-## Hook Directories
-The following subdirectories will be used for hooks:
+## Ways to define hooks
+### Hook Directories
+The following subdirectories of `.cordova/hooks` and `/hooks` will be used for hooks:
after_build/
after_compile/
@@ -42,6 +49,7 @@ The following subdirectories will be used for hooks:
after_plugin_ls/
after_plugin_rm/
after_plugin_search/
+ after_plugin_install/ <-- Plugin hooks defined in plugin.xml are executed exclusively for a plugin being installed
after_prepare/
after_run/
after_serve/
@@ -56,14 +64,123 @@ The following subdirectories will be used for hooks:
before_plugin_ls/
before_plugin_rm/
before_plugin_search/
+ before_plugin_install/ <-- Plugin hooks defined in plugin.xml are executed exclusively for a plugin being installed
+ before_plugin_uninstall/ <-- Plugin hooks defined in plugin.xml are executed exclusively for a plugin being uninstalled
before_prepare/
before_run/
before_serve/
pre_package/ <-- Windows 8 and Windows Phone only.
+### Config.xml
+
+Hooks can be defined in project's `config.xml` in the following way:
+
+ <script type="before_build" src="scripts/appBeforeBuild.bat" />
+ <script type="before_build" src="scripts/appBeforeBuild.js" />
+ <script type="before_plugin_install" src="scripts/appBeforePluginInstall.js" />
+
+ <platform name="wp8">
+ <script type="before_build" src="scripts/wp8/appWP8BeforeBuild.bat" />
+ <script type="before_build" src="scripts/wp8/appWP8BeforeBuild.js" />
+ <script type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js" />
+ ...
+ </platform>
+
+ <platform name="windows8">
+ <script type="before_build" src="scripts/windows8/appWin8BeforeBuild.bat" />
+ <script type="before_build" src="scripts/windows8/appWin8BeforeBuild.js" />
+ <script type="before_plugin_install" src="scripts/windows8/appWin8BeforePluginInstall.js" />
+ ...
+ </platform>
+
+### Plugin hooks (plugin.xml)
+
+As a plugin developer you can define hook scripts using `<script>` elements in a `plugin.xml` like that:
+
+ <script type="before_plugin_install" src="scripts/beforeInstall.js" />
+ <script type="after_build" src="scripts/afterBuild.js" />
+
+ <platform name="wp8">
+ <script type="before_plugin_install" src="scripts/wp8BeforeInstall.js" />
+ <script type="before_build" src="scripts/wp8BeforeBuild.js" />
+ ...
+ </platform>
+
+`before_plugin_install`, `after_plugin_install`, `before_plugin_uninstall` plugin hooks will be fired exclusively for the plugin being installed/uninstalled.
+
## Script Interface
-All scripts are run from the project's root directory and have the root directory passes as the first argument. All other options are passed to the script using environment variables:
+### Javascript
+
+If you are writing hooks in Javascript you should use the following module definition:
+```javascript
+module.exports = function(context) {
+ ...
+}
+```
+
+You can make your scipts async using Q, which can be retrieved from `context.commonModules`:
+```javascript
+module.exports = function(context) {
+ var Q = context.commonModules.Q;
+ var deferral = new Q.defer();
+
+ setTimeout(function(){
+ console.log('hook.js>> end');
+ deferral.resolve();
+ }, 1000);
+
+ return deferral.promise;
+}
+```
+
+`context` object contains hook type, executed script full path, hook options, common modules, and command-line arguments passed to Cordova:
+```json
+{
+ "hook": "before_plugin_install",
+ "scriptLocation": "c:\\script\\full\\path\\appBeforePluginInstall.js",
+ "cmdLine": "The\\exact\\command\\cordova\\run\\with arguments",
+ "opts": {
+ "projectRoot":"C:\\path\\to\\the\\project",
+ "cordova": {
+ "platforms": ["wp8"],
+ "plugins": ["com.plugin.withhooks"],
+ "version": "0.21.7-dev"
+ },
+ "plugin": {
+ "id": "com.plugin.withhooks",
+ "pluginInfo": {
+ ...
+ },
+ "platform": "wp8",
+ "dir": "C:\\path\\to\\the\\project\\plugins\\com.plugin.withhooks"
+ }
+ },
+ "commonModules": {
+ "fs": { ... },
+ "path": { ... },
+ "os": { ... },
+ "events": { ... },
+ "util": { ... },
+ "cordovaUtil": { ... }
+ }
+}
+
+```
+`context.opts.plugin` object will only be passed to plugin hooks scripts.
+
+You can also require additional Cordova modules in your script using `context.requireCordovaModule` in the following way:
+```javascript
+var et = context.requireCordovaModule('elementtree');
+var xmlHelpers = context.requireCordovaModule('../util/xml-helpers');
+```
+
+New module loader script interface is used for the `.js` files defined via `config.xml` or `plugin.xml` only.
+For compatibility reasons hook files specified via `.cordova/hooks` and `/hooks` folders are run via Node child_process spawn, see 'Non-javascript' section below.
+
+### Non-javascript
+
+Non-javascript scripts are run via Node child_process spawn from the project's root directory and have the root directory passes as the first argument. All other options are passed to the script using environment variables:
* CORDOVA_VERSION - The version of the Cordova-CLI.
* CORDOVA_PLATFORMS - Comma separated list of platforms that the command applies to (e.g.: android, ios).