cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rakat...@apache.org
Subject docs commit: CB-10353: Make Hooks guide a reference. This closes #489
Date Tue, 23 Feb 2016 00:59:47 GMT
Repository: cordova-docs
Updated Branches:
  refs/heads/master a7aeefa34 -> a9771c823


CB-10353: Make Hooks guide a reference. This closes #489

Making Hooks guide a reference


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/a9771c82
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/a9771c82
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/a9771c82

Branch: refs/heads/master
Commit: a9771c8235e6c3e17f90d38535856250eddc59f7
Parents: a7aeefa
Author: Sarangan Rajamanickam <sarajama@microsoft.com>
Authored: Thu Feb 4 10:38:54 2016 -0800
Committer: Raghav Katyal <rakatyal@microsoft.com>
Committed: Mon Feb 22 16:59:05 2016 -0800

----------------------------------------------------------------------
 www/docs/en/dev/guide/appdev/hooks/index.md | 366 ++++++++++++++++-------
 www/static/css-src/_docs.scss               |  17 ++
 2 files changed, 281 insertions(+), 102 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a9771c82/www/docs/en/dev/guide/appdev/hooks/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/guide/appdev/hooks/index.md b/www/docs/en/dev/guide/appdev/hooks/index.md
index 4c8d453..454f2e5 100644
--- a/www/docs/en/dev/guide/appdev/hooks/index.md
+++ b/www/docs/en/dev/guide/appdev/hooks/index.md
@@ -20,83 +20,186 @@ license: >
 title: Hooks Guide
 ---
 
-# Hooks Guide
+# Hooks
+
+## Introduction
 
 Cordova Hooks represent special scripts which could be added by application and
 plugin developers or even by your own build system  to customize cordova commands.
-Hook scripts could be defined by adding them to the special predefined folder 
-(`/hooks`) or via configuration files (`config.xml` and `plugin.xml`) and run
-serially in the following order:
-
-* Application hooks from `/hooks`;
-* Application hooks from `config.xml`;
-* Plugin hooks from `plugins/.../plugin.xml`.
-
-__Note__: `/hooks` directory is considered deprecated in favor of the hook elements
-in config.xml and plugin.xml.
 
-## Supported hook types
-The following hook types are supported:
-
-    after_build
-    after_compile
-    after_clean
-    after_docs
-    after_emulate
-    after_platform_add
-    after_platform_rm
-    after_platform_ls
-    after_plugin_add
-    after_plugin_ls
-    after_plugin_rm
-    after_plugin_search
-    after_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed
only
-    after_prepare
-    after_run
-    after_serve
-    before_build
-    before_clean
-    before_compile
-    before_docs
-    before_emulate
-    before_platform_add
-    before_platform_rm/
-    before_platform_ls
-    before_plugin_add
-    before_plugin_ls
-    before_plugin_rm
-    before_plugin_search/
-    before_plugin_install // Plugin hooks in plugin.xml are executed for a plugin being installed
only
-    before_plugin_uninstall // Plugin hooks in plugin.xml are executed for a plugin being
uninstalled only
-    before_prepare
-    before_run
-    before_serve
-    pre_package // Windows and Windows Phone only
+Cordova hooks allow you to perform special activities around cordova commands. For example,
+you may have a custom tool that checks for code formatting in your javascript file. And,
you
+would like to run this tool before every build. In such a case, you could use a
+'before_build' hook and instruct the cordova run time to run the custom tool to be invoked
+before every build.
+
+Hooks might be related to your application activities such as such as `before_build`,
+`after_build`, etc. Or, they might be related to the plugins of your application. For example,
+hooks such as `before_plugin_add`, `after_plugin_add`, etc applies to plugin related
+activities. These hooks can be associated with all plugins within your application or
+be specific to only one plugin.
+
+Cordova supports the following hook types:
+
+<!-- START HTML -->
+
+<table class="hooks" width="100%">
+    <thead>
+        <tr>
+            <th>Hook Type</th>
+            <th>Associated Cordova Commands</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <th data-col="beforeplatformadd">before_platform_add</th>
+            <td data-col="code" rowspan="2"><code>cordova platform add</code></td>
+            <td rowspan="2" class="description" data-col="description">To be executed
before and after adding a platform.</td>
+        </tr>
+        <tr>
+            <th data-col="afterplatformadd">after_platform_add</th>
+        </tr>
+        <tr>
+            <th data-col="beforeplatformrm">before_platform_rm</th>
+            <td data-col="code" rowspan="2"><code>cordova platform rm</code></td>
+            <td rowspan="2" class="description" data-col="description">To be executed
before and after removing a platform.</td>
+        </tr>
+        <tr>
+            <th data-col="afterplatformrm">after_platform_rm</th>
+        </tr>
+        <tr>
+            <th data-col="beforeplatformls">before_platform_ls</th>
+            <td data-col="code" rowspan="2"><code>cordova platform ls</code></td>
+            <td rowspan="2" class="description" data-col="description">To be executed
before and after listing the installed and available platforms.</td>
+        </tr>
+        <tr>
+            <th data-col="afterplatformls">after_platform_ls</th>
+        </tr>
+        <tr>
+            <th data-col="beforeprepare">before_prepare</th>
+            <td data-col="code" rowspan="2"><code>cordova prepare</code><br/><code>cordova
platform add</code><br/><code>cordova run</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
preparing your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterprepare">after_prepare</th>
+        </tr>
+        <tr>
+            <th data-col="beforecompile">before_compile</th>
+            <td data-col="code" rowspan="2"><code>cordova compile</code><br/><code>cordova
run</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
compiling your application.</td>
+        </tr>
+        <tr>
+            <th data-col="aftercompile">after_compile</th>
+        </tr>
+        <tr>
+            <th data-col="beforebuild">before_build</th>
+            <td data-col="code" rowspan="2"><code>cordova build</code><br/><code>cordova
run</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
building your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterbuild">after_build</th>
+        </tr>
+        <tr>
+            <th data-col="beforeemulate">before_emulate</th>
+            <td data-col="code" rowspan="2"><code>cordova emulate</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
emulating your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afteremulate">after_emulate</th>
+        </tr>
+        <tr>
+            <th data-col="beforerun">before_run</th>
+            <td data-col="code" rowspan="2"><code>cordova run</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
running your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterrun">after_run</th>
+        </tr>
+        <tr>
+            <th data-col="beforeserve">before_serve</th>
+            <td data-col="code" rowspan="2"><code>cordova serve</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
serving your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterserve">after_serve</th>
+        </tr>
+        <tr>
+            <th data-col="beforeclean">before_clean</th>
+            <td data-col="code" rowspan="2"><code>cordova clean</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
cleaning your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterclean">after_clean</th>
+        </tr>
+        <tr>
+            <th data-col="prepackage">pre_package</td>
+            <td data-col="code">N/A</td>
+            <td data-col="description">Applicable to Windows 8 and Windows Phone only.
This hook is deprecated.</td>
+        </tr>
+        <tr>
+            <th data-col="beforepluginadd">before_plugin_add</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin add</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
adding a plugin.</td>
+        </tr>
+        <tr>
+            <th data-col="afterpluginadd">after_plugin_add</th>
+        </tr>
+        <tr>
+            <th data-col="beforepluginrm">before_plugin_rm</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin rm</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
removing a plugin.</td>
+        </tr>
+        <tr>
+            <th data-col="afterpluginrm">after_plugin_rm</th>
+        </tr>
+        <tr>
+            <th data-col="beforepluginls">before_plugin_ls</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin ls</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
listing the plugins in your application.</td>
+        </tr>
+        <tr>
+            <th data-col="afterpluginls">after_plugin_ls</th>
+        </tr>
+        <tr>
+            <th data-col="beforepluginsearch">before_plugin_search</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin search</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
a plugin search.</td>
+        </tr>
+        <tr>
+            <th data-col="afterpluginsearch">after_plugin_search</th>
+        </tr>
+        <tr>
+            <th data-col="beforeplugininstall">before_plugin_install</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin add</code></td>
+            <td rowspan="2" data-col="description">To be executed before and after
installing a plugin (to the platforms). Plugin hooks in plugin.xml are executed for a plugin
being installed only</td>
+        </tr>
+        <tr>
+            <th data-col="afterplugininstall">after_plugin_install</th>
+        </tr>
+        <tr>
+            <th data-col="beforepluginuninstall">before_plugin_uninstall</th>
+            <td data-col="code" rowspan="2"><code>cordova plugin rm</code></td>
+            <td data-col="description">To be executed before uninstalling a plugin
(from the platforms).Plugin hooks in plugin.xml are executed for a plugin being installed
only</td>
+        </tr>
+    </tbody>
+</table>
+
+<!-- END HTML -->
 
 ## Ways to define hooks
-### Via `/hooks` directory
-
-__Note__: this method is considered deprecated in favor of the hook elements in config.xml
and plugin.xml.
-
-To execute custom action when corresponding hook type is fired, use hook type as a name for
a subfolder inside 'hooks' directory and place you script file here, for example:
-
-    # script file will be automatically executed after each build
-    hooks/after_build/after_build_custom_action.js
-
-When using these hooks, they will always be run as executable files, not as loadable JavaScript
modules.
-__Remember__: Make your scripts executable in this case.
 
 ### Config.xml
 
-Hooks can be defined in project's `config.xml` using `<hook>` elements, for example:
+Hooks could be defined in project's `config.xml` using `<hook>` elements, for example:
 
     <hook type="before_build" src="scripts/appBeforeBuild.bat" />
     <hook type="before_build" src="scripts/appBeforeBuild.js" />
     <hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" />
 
-    <platform name="wp8">
-        <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.bat" />
-        <hook type="before_build" src="scripts/wp8/appWP8BeforeBuild.js" />
+    <platform name="android">
+        <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.bat" />
+        <hook type="before_build" src="scripts/wp8/appAndroidBeforeBuild.js" />
         <hook type="before_plugin_install" src="scripts/wp8/appWP8BeforePluginInstall.js"
/>
         ...
     </platform>
@@ -115,41 +218,86 @@ As a plugin developer you can define hook scripts using `<hook>`
elements in a `
     <hook type="before_plugin_install" src="scripts/beforeInstall.js" />
     <hook type="after_build" src="scripts/afterBuild.js" />
 
-    <platform name="wp8">
-        <hook type="before_plugin_install" src="scripts/wp8BeforeInstall.js" />
-        <hook type="before_build" src="scripts/wp8BeforeBuild.js" />
+    <platform name="android">
+        <hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" />
+        <hook type="before_build" src="scripts/androidBeforeBuild.js" />
         ...
     </platform>
 
-`before_plugin_install`, `after_plugin_install`, `before_plugin_uninstall` plugin hooks will
be fired exclusively for the plugin being installed/uninstalled.
+`before_plugin_install`, `after_plugin_install`, `before_plugin_uninstall` plugin hooks will
be fired
+exclusively for the plugin being installed/uninstalled.
+
+### Via `/hooks` directory (Deprecated)
+
+To execute custom action when corresponding hook type is fired, use hook type as a name for
a subfolder inside 'hooks' directory and place you script file here, for example:
+
+    # script file will be automatically executed after each build
+    hooks/after_build/after_build_custom_action.js
+
+When using these hooks, they will always be run as executable files, not as loadable JavaScript
modules.
+
+__Remember__: Make your scripts executable in this case.
+
+__Note__: this method is considered deprecated in favor of the hook elements in config.xml
and plugin.xml.
+
+### Order of Hooks execution
+
+#### Based on Hooks Definition
+
+Hook scripts could be defined by adding them to the special predefined folder
+(`/hooks`) or via configuration files (`config.xml` and `plugin.xml`) and run
+serially in the following order:
+
+* Application hooks from `/hooks`;
+* Application hooks from `config.xml`;
+* Plugin hooks from `plugins/.../plugin.xml`.
+
+#### Based on the Internal order of execution
+
+The internal order of execution of hooks is fixed.
+
+##### Example 1 (cordova platform add)
+If there are hooks associated with `before_platform_add`, `after_platform_add`, `before_prepare`,
`after_prepare`,
+`before_plugin_install` and `after_plugin_install` (and assuming you have one plugin installed
on your project),
+adding a new platform will execute the hooks in the following order:
+
+    before_platform_add
+        before_prepare
+        after_prepare
+        before_plugin_install
+        after_plugin_install
+    after_platform_add
+
+##### Example 2 (cordova build)
+If there are hooks associated with `before_prepare`, `after_prepare`, `before_compile`, `after_compile`,
`before_build`
+and `after_build` - running a build command will execute the hooks in the following order:
+
+    before_build
+        before_prepare
+        after_prepare
+        before_compile
+        after_compile
+    after_build
 
 ## Script Interface
+### Windows Quirks
+
+If you are working on Windows, and in case your hook (Javascript/Non-Javascript)scripts aren't
bat files (which is recommended, if you want your scripts to work in non-Windows operating
systems) Cordova CLI will expect a shebang line as the first line for it to know the interpreter
it needs to use to launch the script. The shebang line should match the following example:
+
+    #!/usr/bin/env [name_of_interpreter_executable]
 
 ### Javascript
 
 If you are writing hooks using Node.js you should use the following module definition:
+
 ```javascript
 module.exports = function(context) {
     ...
 }
 ```
 
-You can make your scipts async using Q:
-```javascript
-module.exports = function(context) {
-    var Q = context.requireCordovaModule('q');
-    var deferral = new Q.defer();
+`context` object contains hook type, executed script full path, hook options, command-line
arguments passed to Cordova and top-level "cordova" object of the following format:
 
-    setTimeout(function(){
-      console.log('hook.js>> end');
-    deferral.resolve();
-    }, 1000);
-
-    return deferral.promise;
-}
-```
-
-`context` object contains hook type, executed script full path, hook options, command-line
arguments passed to Cordova and top-level "cordova" object:
 ```json
 {
   "hook": "before_plugin_install",
@@ -158,17 +306,17 @@ module.exports = function(context) {
   "opts": {
     "projectRoot":"C:\\path\\to\\the\\project",
     "cordova": {
-      "platforms": ["wp8"],
-      "plugins": ["com.plugin.withhooks"],
+      "platforms": ["android"],
+      "plugins": ["plugin-withhooks"],
       "version": "0.21.7-dev"
     },
     "plugin": {
-      "id": "com.plugin.withhooks",
+      "id": "plugin-withhooks",
       "pluginInfo": {
         ...
       },
-      "platform": "wp8",
-      "dir": "C:\\path\\to\\the\\project\\plugins\\com.plugin.withhooks"
+      "platform": "android",
+      "dir": "C:\\path\\to\\the\\project\\plugins\\plugin-withhooks"
     }
   },
   "cordova": {...}
@@ -178,30 +326,44 @@ module.exports = function(context) {
 `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 Q = context.requireCordovaModule('q');
 ```
 
-__Note__:  new module loader script interface is used for the `.js` files defined via `config.xml`
or `plugin.xml` only.
+You can make your scipts async using Q:
+
+```javascript
+module.exports = function(context) {
+    var Q = context.requireCordovaModule('q');
+    var deferral = new Q.defer();
+
+    setTimeout(function(){
+      console.log('hook.js>> end');
+    deferral.resolve();
+    }, 1000);
+
+    return deferral.promise;
+}
+```
+> __Note__:  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 `/hooks` folders are run via Node child_process
spawn, see 'Non-javascript' section below.
 
 ### Non-javascript
 
-__Note__: we highly recommend writing your hooks using Node.js so that they are cross-platform,
see 'Javascript' section above.
-
 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).
-* CORDOVA_PLUGINS - Comma separated list of plugin IDs that the command applies to (e.g.:
org.apache.cordova.file, org.apache.cordova.file-transfer)
-* CORDOVA_HOOK - Path to the hook that is being executed.
-* CORDOVA_CMDLINE - The exact command-line arguments passed to cordova (e.g.: cordova run
ios --emulate)
+Environment Variable Name     | Description
+------------------------------|--------------------------------------------
+CORDOVA_VERSION               | The version of the Cordova-CLI.
+CORDOVA_PLATFORMS             | Comma separated list of platforms that the command applies
to (e.g: android, ios).
+CORDOVA_PLUGINS               | Comma separated list of plugin IDs that the command applies
to (e.g: cordova-plugin-file-transfer, cordova-plugin-file).
+CORDOVA_HOOK                  | Path to the hook that is being executed.
+CORDOVA_CMDLINE               | The exact command-line arguments passed to cordova (e.g:
cordova run ios --emulate).
 
 If a script returns a non-zero exit code, then the parent cordova command will be aborted.
 
-Also, note that even if you are working on Windows, and in case your hook scripts aren't
bat files (which is recommended, if you want your scripts to work in non-Windows operating
systems) Cordova CLI will expect a shebang line as the first line for it to know the interpreter
it needs to use to launch the script. The shebang line should match the following example:
-
-    #!/usr/bin/env [name_of_interpreter_executable]
+> __Note__: we highly recommend writing your hooks using Node.js so that they are cross-platform,
see [Javascript](#link-javascript) section above.
 
 ## Sample Usage
 
@@ -213,12 +375,12 @@ tell Cordova to run `afterBuild.js` script after each platform build.
 
     <hook type="after_build" src="scripts/afterBuild.js" />
 
-Create `scripts/afterBuild.js` file and add the following implementation. 
+Create `scripts/afterBuild.js` file and add the following implementation.
 We use async version of `fs.stat` method to demonstrate how async functionality
 could be done via hooks.
 
     module.exports = function(ctx) {
-        // make sure android platform is part of build 
+        // make sure android platform is part of build
         if (ctx.opts.platforms.indexOf('android') < 0) {
             return;
         }
@@ -254,6 +416,6 @@ You can now add android platform and execute build.
     ..
     Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193
bytes
 
-More good usage examples could be found here:
+More good usage examples could be found in [Three Hooks Your Cordova Phone Gap Project needs][Devgirl_Hooks_Link]
 
-[http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/](http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/)
+[Devgirl_Hooks_Link]: http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a9771c82/www/static/css-src/_docs.scss
----------------------------------------------------------------------
diff --git a/www/static/css-src/_docs.scss b/www/static/css-src/_docs.scss
index b57fa91..74c35eb 100644
--- a/www/static/css-src/_docs.scss
+++ b/www/static/css-src/_docs.scss
@@ -204,6 +204,23 @@
         }
     }
 
+    .hooks {
+        td[data-col="description"] {
+            text-align: left;
+            vertical-align: middle;
+        }
+
+        td[rowspan="2"], th[colspan="3"], td[data-col="code"] {
+            text-align: center;
+            vertical-align: middle;
+        }
+
+        td[data-col="description"] {
+            text-align: left;
+            vertical-align: middle;
+        }
+    }
+
     // Styling for the /docs/language/version/index.html pages
     #home {
         h1 {


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message