You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/07/18 21:28:29 UTC
[05/12] Version 3.0.0rc1
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/parameters/size.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/parameters/size.md b/docs/en/3.0.0rc1/cordova/storage/parameters/size.md
new file mode 100644
index 0000000..7d9585e
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/parameters/size.md
@@ -0,0 +1,23 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+database_size
+==============
+
+The size of the database in bytes.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/parameters/version.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/parameters/version.md b/docs/en/3.0.0rc1/cordova/storage/parameters/version.md
new file mode 100644
index 0000000..2e72923
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/parameters/version.md
@@ -0,0 +1,23 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+database_version
+=============
+
+The version of the database.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/sqlerror/sqlerror.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/sqlerror/sqlerror.md b/docs/en/3.0.0rc1/cordova/storage/sqlerror/sqlerror.md
new file mode 100644
index 0000000..5515103
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/sqlerror/sqlerror.md
@@ -0,0 +1,46 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+SQLError
+========
+
+A `SQLError` object is thrown when an error occurs.
+
+Properties
+----------
+
+- __code__: One of the predefined error codes listed below.
+- __message__: A description of the error.
+
+Constants
+---------
+
+- `SQLError.UNKNOWN_ERR`
+- `SQLError.DATABASE_ERR`
+- `SQLError.VERSION_ERR`
+- `SQLError.TOO_LARGE_ERR`
+- `SQLError.QUOTA_ERR`
+- `SQLError.SYNTAX_ERR`
+- `SQLError.CONSTRAINT_ERR`
+- `SQLError.TIMEOUT_ERR`
+
+Description
+-----------
+
+The `SQLError` object is thrown when an error occurs when manipulating a database.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/sqlresultset/sqlresultset.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/sqlresultset/sqlresultset.md b/docs/en/3.0.0rc1/cordova/storage/sqlresultset/sqlresultset.md
new file mode 100644
index 0000000..f302ee8
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/sqlresultset/sqlresultset.md
@@ -0,0 +1,153 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+SQLResultSet
+=======
+
+When a `SQLTransaction` object's `executeSql` method is called, the
+specified callback executes with a `SQLResultSet` parameter.
+
+Properties
+-------
+
+- __insertId__: The row ID of the row that the `SQLResultSet` object's SQL statement inserted into the database.
+- __rowsAffected__: The number of rows changed by the SQL statement, zero if the statement did not affect any rows.
+- __rows__: a `SQLResultSetRowList` representing the rows returned, empty if no rows are returned.
+
+Details
+-------
+
+When a `SQLTransaction` object's `executeSql` method is called, the
+specified callback executes with a `SQLResultSet` parameter containing
+three properties:
+
+* The `insertId` returns the row number of a successly SQL insertion
+ statement. If the SQL does not insert any rows, the `insertId` is
+ not set.
+
+* The `rowsAffected` is always `0` for a SQL `select` statement. For
+ `insert` or `update` statements it returns the number of modified
+ rows.
+
+* The final `SQLResultSetList` contains the data returned from a SQL
+ select statement.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 6.0 and higher)
+- iOS
+- Tizen
+
+Execute SQL Quick Example
+------------------
+
+ function queryDB(tx) {
+ tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
+ }
+
+ function querySuccess(tx, results) {
+ console.log("Returned rows = " + results.rows.length);
+ // this will be true since it was a select statement and so rowsAffected was 0
+ if (!results.rowsAffected) {
+ console.log('No rows affected!');
+ return false;
+ }
+ // for an insert statement, this property will return the ID of the last inserted row
+ console.log("Last inserted row ID = " + results.insertId);
+ }
+
+ function errorCB(err) {
+ alert("Error processing SQL: "+err.code);
+ }
+
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(queryDB, errorCB);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Storage Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova-3.0.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // Populate the database
+ //
+ function populateDB(tx) {
+ tx.executeSql('DROP TABLE IF EXISTS DEMO');
+ tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
+ }
+
+ // Query the database
+ //
+ function queryDB(tx) {
+ tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
+ }
+
+ // Query the success callback
+ //
+ function querySuccess(tx, results) {
+ console.log("Returned rows = " + results.rows.length);
+ // this will be true since it was a select statement and so rowsAffected was 0
+ if (!results.rowsAffected) {
+ console.log('No rows affected!');
+ return false;
+ }
+ // for an insert statement, this property will return the ID of the last inserted row
+ console.log("Last inserted row ID = " + results.insertId);
+ }
+
+ // Transaction error callback
+ //
+ function errorCB(err) {
+ console.log("Error processing SQL: "+err.code);
+ }
+
+ // Transaction success callback
+ //
+ function successCB() {
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(queryDB, errorCB);
+ }
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(populateDB, errorCB, successCB);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Database</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/sqlresultsetrowlist/sqlresultsetrowlist.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/sqlresultsetrowlist/sqlresultsetrowlist.md b/docs/en/3.0.0rc1/cordova/storage/sqlresultsetrowlist/sqlresultsetrowlist.md
new file mode 100644
index 0000000..ca83868
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/sqlresultsetrowlist/sqlresultsetrowlist.md
@@ -0,0 +1,142 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+SQLResultSetRowList
+=======
+
+One of the properties of the `SQLResultSet` containing the rows
+returned from a SQL query.
+
+Properties
+-------
+
+- __length__: the number of rows returned by the SQL query.
+
+Methods
+-------
+
+- __item__: returns the row at the specified index represented by a JavaScript object.
+
+Details
+-------
+
+The `SQLResultSetRowList` contains the data returned from a SQL
+`select` statement. The object contains a `length` property
+indicating how many rows the `select` statement returns. To get a row
+of data, call the `item` method to specify an index. It returns a
+JavaScript `Object` whose properties are the database columns the
+`select` statement was executed against.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 6.0 and higher)
+- iOS
+- Tizen
+
+Execute SQL Quick Example
+------------------
+
+ function queryDB(tx) {
+ tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
+ }
+
+ function querySuccess(tx, results) {
+ var len = results.rows.length;
+ console.log("DEMO table: " + len + " rows found.");
+ for (var i=0; i<len; i++){
+ console.log("Row = " + i + " ID = " + results.rows.item(i).id + " Data = " + results.rows.item(i).data);
+ }
+ }
+
+ function errorCB(err) {
+ alert("Error processing SQL: "+err.code);
+ }
+
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(queryDB, errorCB);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Storage Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova-3.0.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // Populate the database
+ //
+ function populateDB(tx) {
+ tx.executeSql('DROP TABLE IF EXISTS DEMO');
+ tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
+ }
+
+ // Query the database
+ //
+ function queryDB(tx) {
+ tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
+ }
+
+ // Query the success callback
+ //
+ function querySuccess(tx, results) {
+ var len = results.rows.length;
+ console.log("DEMO table: " + len + " rows found.");
+ for (var i=0; i<len; i++){
+ console.log("Row = " + i + " ID = " + results.rows.item(i).id + " Data = " + results.rows.item(i).data);
+ }
+ }
+
+ // Transaction error callback
+ //
+ function errorCB(err) {
+ console.log("Error processing SQL: "+err.code);
+ }
+
+ // Transaction success callback
+ //
+ function successCB() {
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(queryDB, errorCB);
+ }
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(populateDB, errorCB, successCB);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Database</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/sqltransaction/sqltransaction.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/sqltransaction/sqltransaction.md b/docs/en/3.0.0rc1/cordova/storage/sqltransaction/sqltransaction.md
new file mode 100644
index 0000000..3c98feb
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/sqltransaction/sqltransaction.md
@@ -0,0 +1,114 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+SQLTransaction
+=======
+
+Allows execution of SQL statements against the Database.
+
+Methods
+-------
+
+- __executeSql__: executes a SQL statement.
+
+Details
+-------
+
+Calling a `Database` object's transaction method, passes a
+`SQLTransaction` object to the specified callback method.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 6.0 and higher)
+- iOS
+- Tizen
+
+Execute SQL Quick Example
+------------------
+
+ function populateDB(tx) {
+ tx.executeSql('DROP TABLE IF EXISTS DEMO');
+ tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
+ }
+
+ function errorCB(err) {
+ alert("Error processing SQL: "+err);
+ }
+
+ function successCB() {
+ alert("success!");
+ }
+
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(populateDB, errorCB, successCB);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Storage Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova-3.0.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
+ db.transaction(populateDB, errorCB, successCB);
+ }
+
+ // Populate the database
+ //
+ function populateDB(tx) {
+ tx.executeSql('DROP TABLE IF EXISTS DEMO');
+ tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
+ tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
+ }
+
+ // Transaction error callback
+ //
+ function errorCB(err) {
+ alert("Error processing SQL: "+err);
+ }
+
+ // Transaction success callback
+ //
+ function successCB() {
+ alert("success!");
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>SQLTransaction</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/storage.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/storage.md b/docs/en/3.0.0rc1/cordova/storage/storage.md
new file mode 100644
index 0000000..1f703fd
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/storage.md
@@ -0,0 +1,80 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+Storage
+==========
+
+> Provides access to the device's storage options.
+
+This API is based on the [W3C Web SQL Database
+Specification](http://dev.w3.org/html5/webdatabase/) and [W3C Web
+Storage API Specification](http://dev.w3.org/html5/webstorage/). Some
+devices already provide an implementation of these specifications, in
+which case the built-in support applies. Cordova's implementation
+offers compatible support for those that don't.
+
+Methods
+-------
+
+- openDatabase
+
+Arguments
+---------
+
+- database_name
+- database_version
+- database_displayname
+- database_size
+
+Objects
+-------
+
+- Database
+- SQLTransaction
+- SQLResultSet
+- SQLResultSetRowList
+- SQLError
+- localStorage
+
+Permissions
+-----------
+
+### Android
+
+#### app/res/xml/config.xml
+
+ <plugin name="Storage" value="org.apache.cordova.Storage" />
+
+### BlackBerry WebWorks
+
+#### www/config.xml
+
+ <feature id="blackberry.widgetcache" required="true" version="1.0.0.0" />
+
+### iOS
+
+ No permissions are required.
+
+### Windows Phone
+
+ No permissions are required.
+
+### Tizen
+
+ No permissions are required.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/cordova/storage/storage.opendatabase.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/cordova/storage/storage.opendatabase.md b/docs/en/3.0.0rc1/cordova/storage/storage.opendatabase.md
new file mode 100644
index 0000000..cc6b111
--- /dev/null
+++ b/docs/en/3.0.0rc1/cordova/storage/storage.opendatabase.md
@@ -0,0 +1,73 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+openDatabase
+===============
+
+Returns a new `Database` object.
+
+ var dbShell = window.openDatabase(database_name, database_version, database_displayname, database_size);
+
+Description
+-----------
+
+The method creates a new SQL Lite Database and returns a `Database`
+object that allows manipulation of the data.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 6.0 and higher)
+- iOS
+- Tizen
+
+Quick Example
+-------------
+
+ var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Storage Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova-3.0.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Open Database</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/cli/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/cli/index.md b/docs/en/3.0.0rc1/guide/cli/index.md
new file mode 100644
index 0000000..2650932
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/cli/index.md
@@ -0,0 +1,288 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+---
+
+# The Command-line Interface
+
+This guide shows you how to create applications and deploy them to
+various native mobile platforms using the `cordova` command-line
+interface (CLI). This tool allows you to create new projects, build
+them on different platforms, and run them within an emulator. You can
+also use the CLI to initialize project code, after which you use
+various platforms' SDKs to develop them further.
+
+## Prerequisites
+
+Before running any command-line tools, you need to install SDKs for
+each platform you wish to target.
+(See the Platform Guides for more details.)
+
+To add support or rebuild a project for any platform, you need to run
+the command-line interface from the same machine that supports the
+platform's SDK. The CLI supports the following combinations:
+
+* iOS (Mac)
+* Android (Mac, Linux)
+* BlackBerry (Mac, Windows)
+* Windows Phone 7 (Windows)
+* Windows Phone 8 (Windows)
+
+On the Mac, the command-line is available via the _Terminal_
+application. On the PC, it's available as _Command Prompt_ under
+_Accessories_.
+
+The more likely it is that you run the CLI from different machines,
+the more it makes sense to maintain a remote source code repository,
+whose assets you pull down to local working directories.
+
+To install the `cordova` command-line tool, follow these steps:
+
+1. Download and install [Node.js](http://nodejs.org/). Following
+ installation, you should be able to invoke `node` or `npm` on your
+ command line.
+
+1. Install the `cordova` utility. In Unix, prefixing the additional
+ `sudo` command may be necessary to install development utilities in
+ otherwise restricted directories:
+
+ $ sudo npm install -g cordova
+
+ The installation log may produce errors for any uninstalled
+ platform SDKs. Following installation, you should be able to run
+ `cordova` on the command line.
+
+## Create the App
+
+Go to the directory where you maintain your source code, and run a
+command such as the following:
+
+ $ cordova create HelloWorld com.example.hello "Hello World"
+
+The first argument specifies a _HelloWorld_ directory to be generated
+for your project. Its `www` subdirectory houses your application's
+home page, along with various resources under `css`, `js`, and `img`,
+which follow common web development file-naming conventions. The
+`config.xml` file contains important metadata needed to generate and
+distribute the application.
+
+The other two arguments are optional: the `com.example.hello` argument
+provides your project with a reverse domain-style identifier, and the
+`"Hello World!"` provides the application's display text. You can edit
+both of these values later in the `config.xml` file.
+
+## Add Platforms
+
+All subsequent commands need to be run within the project's directory,
+or any subdirectories within its scope:
+
+ $ cd HelloWorld
+
+Before you can build the project, you need to specify a set of target
+platforms. Your ability to run these commands depends on whether your
+machine supports each SDK, and whether you have already installed each
+SDK. Run any of these from a Mac:
+
+ $ cordova platform add ios
+ $ cordova platform add android
+ $ cordova platform add blackberry
+
+Run any of these from a Windows machine, where _wp_ refers to
+different versions of the Windows Phone operating system:
+
+ $ cordova platform add wp7
+ $ cordova platform add wp8
+ $ cordova platform add android
+ $ cordova platform add blackberry
+
+Run this to check your current set of platforms:
+
+ $ cordova platforms ls
+
+(Note the `platform` and `platforms` commands are synonymous.)
+
+Run either of the following synonymous commands to remove a platform:
+
+ $ cordova platform remove blackberry
+ $ cordova platform rm android
+
+Running commands to add or remove platforms affects the contents of
+the project's _platforms_ directory, where each specified platform
+appears as a subdirectory. The _www_ source directory is reproduced
+within each platform's subdirectory, appearing for example in
+`platforms/ios/www` or `platforms/android/assets/www`. By default,
+each platform's configuration file is set up to be able to access all
+of Cordova's APIs.
+
+If you wish, you can use an SDK at this point to open the project you
+created. However, any edits you make to the project within an SDK
+affect the derivative set of assets, not the original cross-platform
+source files. Use this approach if you simply want to initialize a
+project.
+(See the Platform Guides for information on how to develop applications within each SDK.)
+Read on if you wish to use command-line tools for the entire
+development cycle.
+
+## Build the App
+
+By default, the `cordova create` script generates a skeletal web-based
+application whose home page is the project's `www/index.html` file.
+Edit this application however you want, but any initialization should
+be specified as part of the `deviceready` event handler, referenced by
+default from `www/js/index.js`.
+<!-- XREF
+(See Application Development Guide for details.)
+XREF -->
+
+Run the following command to iteratively build the project:
+
+ $ cordova build
+
+This generates platform-specific code within the project's `platforms`
+subdirectory. You can optionally limit the scope of each build to
+specific platforms:
+
+ $ cordova build ios
+
+The `cordova build` command is a shorthand for the following, which in
+this example is also targeted to a single platform:
+
+ $ cordova prepare ios
+ $ cordova compile ios
+
+In this case, once you run `prepare`, you can use Apple's Xcode SDK as
+an alternative to modify and compile the platform-specific code that
+Cordova generates within `platforms/ios`. You can use the same
+approach with other platforms' SDKs.
+
+## View the App in an Emulator
+
+SDKs for mobile platforms often come bundled with emulators that
+execute a device image, so that you can launch the app from the home
+screen and see how it interacts with many platform features. Run a
+command such as the following to rebuild the app and view it within a
+specific platform's emulator:
+
+ $ cordova emulate android
+
+Some mobile platforms emulate a particular device by default, such as
+the iPhone for iOS projects. For other platforms, you may need to
+first associate a device with an emulator.
+(See the Platform Guides for details.)
+For example, you may first run the `android` command to launch the
+Android SDK, then run a particular device image, which launches it
+according to its default behavior:
+
+
+
+Following up with the `cordova emulate` command refreshes the emulator
+image to display the latest application, which is now available for
+launch from the home screen:
+
+
+
+## Add Features
+
+When you build and view a new project, the default application that
+appears doesn't do very much. You can modify the app in many ways to
+take advantage of standard web technologies, but for the app to
+communicate closely with various device-level features, you need to
+add plugins that provide access to core Cordova APIs.
+
+A _plugin_ is a bit of add-on code that provides an interface to
+native components. You can design your own plugin interface, for
+example when designing a hybrid app that mixes a Cordova WebView with
+native components. (See Embedding WebViews and Plugin Development Guide for details.) More commonly, you would add a plugin to enable
+one of Cordova's basic device-level features
+<!-- XREF
+discussed in the Application Development Guide and
+XREF -->
+detailed in the API Reference.
+
+The `cordova plugin add` command requires you to specify the
+repository for the plugin code. Here are examples of features you
+might add:
+
+* Basic device information:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
+* Network and battery status:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git
+* Accelerometer, compass, and geolocation:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
+* Camera, media capture, and media playback:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-media-capture.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-media.git
+* Access files on device or network:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer.git
+* Notifications via dialog box or vibration:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git
+* Contacts:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git
+* Globalization:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git
+* Splash Screen:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git
+* In-app browser:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git
+* Debug console:
+ $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git
+
+Use `plugin ls` (or `plugin list`) to view currently installed
+plugins. Each displays by its identifier:
+
+ $ cordova plugin ls # or 'plugin list'
+ [ 'org.apache.cordova.core.console' ]
+
+To remove a plugin, refer to it by the same identifier that appears in
+the listing. For example, here is how you would remove support for a
+debug console from a release version:
+
+ $ cordova plugin rm org.apache.cordova.core.console
+ $ cordova plugin remove org.apache.cordova.core.console # same
+
+You can batch-remove or add plugins by specifying more than one
+argument for each command.
+
+<!--
+
+## Run the App on the Device
+
+-->
+
+## Update the App
+
+After installing installing the `cordova` utility, you can always
+update it to the latest version by running the following command:
+
+ $ sudo npm update -g cordova
+
+Use this syntax to install a specific version:
+
+ $ sudo npm install -g cordova@2.8.0
+
+Run the `info` command for a listing that includes the current version
+along with other available version numbers:
+
+ $ npm info cordova
+
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/overview/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/overview/index.md b/docs/en/3.0.0rc1/guide/overview/index.md
new file mode 100644
index 0000000..195c84e
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/overview/index.md
@@ -0,0 +1,383 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+---
+
+# Overview
+
+Cordova is an open-source mobile development framework. It allows you
+to use standard web technologies such as HTML5, CSS3, and JavaScript
+for cross-platform development, avoiding each mobile platforms' native
+development language. Applications execute within wrappers targeted
+to each platform, and rely on standards-compliant API bindings to
+access each device's sensors, data, and network status.
+
+Use Cordova if you are:
+
+* a mobile developer and want to extend an application across more
+ than one platform, without having to re-implement it with each
+ platform's language and tool set.
+
+* a web developer and want to deploy a web app that's packaged for
+ distribution in various app store portals.
+
+* a mobile developer interested in mixing native application
+ components with a _WebView_ (browser window) that can access
+ device-level APIs, or if you want to develop a plug-in interface
+ between native and WebView components.
+
+## Basic Components
+
+Cordova applications rely on a common `config.xml` file that provides
+information about the app and specifies parameters affecting how it
+works, such as whether it responds to orientation shifts. This file
+adheres to the W3C's
+[Packaged Web App](http://www.w3.org/TR/widgets/),
+or _widget_, specification.
+
+The application itself is implemented as a web page, named
+_index.html_ by default, that references whatever CSS, JavaScript,
+images, media files, or other resources are necessary for it to run.
+The app executes as a _WebView_ within the native application wrapper,
+which you distribute to app stores. For the web app to interact with
+various device features the way native apps do, it must also reference
+a `cordova.js` file, which provides API bindings.
+<!-- XREF
+(See the API Reference for an overview, and the API and Configuration
+Guide for examples of how to use them.)
+XREF -->
+
+The Cordova-enabled WebView may provide the application with its
+entire user interface. It can also be a component within a larger,
+hybrid application that mixes the WebView with native application
+components. Cordova provides a _plug-in_ interface for these
+components to communicate with each other.
+
+## Development Paths
+
+The easiest way to set up an application is to run the `cordova`
+command-line utility, also known as the _command-line interface_
+(CLI). (To install the CLI, see The Command-line Interface.)
+Depending on the set of platforms you wish to target, you can rely on
+the CLI for progressively greater shares of the development cycle:
+
+* In the most basic scenario, you can use the CLI simply to create a
+ new project that is populated with default configuration for you to
+ modify.
+
+* For many mobile platforms, you can also use the CLI to set up
+ additional project files required to compile within each SDK. For
+ this to work, you must install each targeted platform's SDK.
+ (See the Platform Guides for instructions.)
+ As indicated in the Platform Support table below, you may need to
+ run the CLI on different operating systems depending on the targeted
+ platform.
+
+* For supporting platforms, the CLI can compile executible
+ applications and run them in an SDK-based device emulator.
+ <!-- XREF
+ (See Application Development Guide for details.)
+ XREF -->
+ For comprehensive testing, you can also generate application files
+ and install them directly on a device.
+
+At any point in the development cycle, you can also rely on
+platform-specific SDK tools, which may provide a richer set of
+options.
+(See the Platform Guides for details about each platform's SDK tool set.)
+An SDK environment is more appropriate if you want implement a hybrid
+app that mixes web-based and native application components.
+<!-- XREF
+(See Hybrid Application Guide for more information.)
+XREF -->
+You may use the command-line utility to initially generate the app, or
+iteratively thereafter to feed updated code to SDK tools. You may
+also build the app's configuration file yourself.
+<!-- XREF
+(See Configuration Reference for details.)
+XREF -->
+
+<!-- XREF
+To build projects on some platforms, you may need to apply digital signatures.
+See Distributing Applications for information on how to upload your app to various store portals.
+XREF -->
+
+## Platform Support
+
+The following shows the set of development tools and device APIs
+available for each mobile platform:
+
+<!-- START HTML -->
+
+<table class="compat" width="100%">
+
+<thead>
+ <tr>
+ <th></td>
+ <th>Android</th>
+ <th>BlackBerry</th>
+ <th>BlackBerry 10</th>
+ <th>iOS</th>
+ <th>Windows<br/>Phone 7</th>
+ <th>Windows<br/>Phone 8</th>
+ <th>Windows<br/>8</th>
+ </tr>
+
+</thead>
+
+<tbody>
+ <tr>
+ <th><a href="#">cordova<br/>CLI</a></th>
+ <td data-col="android" class="y">Mac, Windows, Linux</td>
+ <td data-col="blackberry" class="y">Mac, Windows</td>
+ <td data-col="blackberry10" class="y">Mac, Windows</td>
+ <td data-col="ios" class="y">Mac</td>
+ <td data-col="winphone7" class="y">Windows</td>
+ <td data-col="winphone8" class="y">Windows</td>
+ <td data-col="win8" class="u"></td>
+ </tr>
+
+ <tr>
+ <th><a href="#">PhoneGap<br/>Build</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="u"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="u"></td>
+ </tr>
+
+ <tr>
+ <th><a href="guide_platforms_index.md.html">SDK platform support</a></th>
+ <td data-col="android" class="y"><a href="guide_platforms_android_index.md.html"> </a></td>
+ <td data-col="blackberry" class="y"><a href="guide_platforms_blackberry_index.md.html"> </a></td>
+ <td data-col="blackberry10" class="y"><a href="guide_platforms_blackberry10_index.md.html"> </a></td>
+ <td data-col="ios" class="y"><a href="guide_platforms_ios_index.md.html"> </a></td>
+ <td data-col="winphone7" class="y"><a href="guide_platforms_wp7_index.md.html"> </a></td>
+ <td data-col="winphone8" class="y"><a href="guide_platforms_windows-phone-8_index.md.html"> </a></td>
+ <td data-col="win8" class="y"><a href="guide_platforms_windows-8_index.md.html"> </a></td>
+ </tr>
+
+ <tr>
+ <th><a href="#">Embedded<br/>WebView</a></th>
+ <td data-col="android" class="y"><a href="guide_platforms_android_webview.md.html"></a></td>
+ <td data-col="blackberry" class="n"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="y"><a href="guide_platforms_ios_webview.md.html"></a></td>
+ <td data-col="winphone7" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win8" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="guide_plugin-development_index.md.html">Plug-in<br/>Interface</a></th>
+ <td data-col="android" class="y"><a href="guide_guide_platforms_android_plugin.md.html"></a></td>
+ <td data-col="blackberry" class="y"><a href="guide_guide_platforms_blackberry_plugin.md.html"></a></td>
+ <td data-col="blackberry10" class="y"><a href="guide_guide_platforms_blackberry10_plugin.md.html"></a></td>
+ <td data-col="ios" class="y"><a href="guide_guide_platforms_ios_plugin.md.html"></a></td>
+ <td data-col="winphone7" class="y"><a href="guide_guide_platforms_wp8_plugin.md.html"></a></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win8" class="n"></td>
+ </tr>
+
+ <tr>
+ <th></th>
+ <th colspan="20">Platform APIs</th>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_accelerometer_accelerometer.md.html">Accelerometer</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_camera_camera.md.html">Camera</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_media_capture_capture.md.html">Capture</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_compass_compass.md.html">Compass</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="n"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="y">(3GS+)</td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_connection_connection.md.html">Connection</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_contacts_contacts.md.html">Contacts</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_device_device.md.html">Device</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_events_events.md.html">Events</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_file_file.md.html">File</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_geolocation_geolocation.md.html">Geolocation</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_globalization_globalization.md.html">Globalization</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="n"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_inappbrowser_inappbrowser.md.html">InAppBrowser</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_media_media.md.html">Media</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="n"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_notification_notification.md.html">Notification</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_splashscreen_splashscreen.md.html">Splashscreen</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="n"></td>
+ <td data-col="blackberry10" class="n"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="n"></td>
+ <td data-col="winphone8" class="n"></td>
+ <td data-col="win8" class="n"></td>
+ </tr>
+
+ <tr>
+ <th><a href="cordova_storage_storage.md.html">Storage</a></th>
+ <td data-col="android" class="y"></td>
+ <td data-col="blackberry" class="y"></td>
+ <td data-col="blackberry10" class="y"></td>
+ <td data-col="ios" class="y"></td>
+ <td data-col="winphone7" class="y"></td>
+ <td data-col="winphone8" class="y"></td>
+ <td data-col="win8" class="y"></td>
+ </tr>
+
+</tbody>
+</table>
+
+<!-- END HTML -->
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/android/config.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/android/config.md b/docs/en/3.0.0rc1/guide/platforms/android/config.md
new file mode 100644
index 0000000..00a1ecd
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/android/config.md
@@ -0,0 +1,40 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Configuration
+
+The `config.xml` settings file controls various settings of Cordova. This is application wide, and not set per CordovaWebView Instance.
+
+## <preference>
+
+Various **other** preferences (as **<preference>** tags) default on not breaking existing apps. The available preferences are:
+
+1. **useBrowserHistory (boolean, defaults to true)** - set to false if you want to use the history shim that was used to work around the hashtag error present in Android 3.x prior to the history fix. (Note: This setting will be deprecated in April 2013)
+2. **loadingDialog** - Display a native loading dialog when loading the app. The value's format is _Title, Message_
+3. **loadingPageDialog** - Display a native loading dialog when loading sub-pages. The value's format is _Title, Message_
+4. **errorUrl** - Set the error page for your application. Should be located in your Android project in file://android_asset/www/
+5. **backgroundColor** - Set the background color for your application. Supports a four-byte hex value, with the first byte representing alpha value, and the following three bytes with standard RGB values. (i.e. 0x00000000 = Black)
+6. **loadUrlTimeoutValue** - How much time Cordova should wait before throwing a timeout error on the application.
+7. **keepRunning (boolean, defaults to true)** - Determines whether Cordova will keep running in the background or not
+8. **splashscreen** - The name of the file minus its extension in the `res/drawable` directory. If you have multiple assets, they all must share this common name in their respective directories.
+9. **disallowOverscroll (boolean, defaults to false)** - set to true if you want to disable the glow when a user scrolls beyond the edge of the webview.
+
+## <plugin>
+
+Android supports using <feature> as analogues to <plugin> elements.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/android/index.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/android/index.md b/docs/en/3.0.0rc1/guide/platforms/android/index.md
new file mode 100644
index 0000000..ddad02e
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/android/index.md
@@ -0,0 +1,200 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Platform Guide
+
+This guide shows how to set up your SDK development environment to
+deploy Cordova apps for Android devices. See the following for more
+detailed platform-specific information:
+
+* Android Configuration
+* Android WebViews
+* Android Plugins
+* Upgrading Android
+* Android Command-line Tools
+
+The command-line tools above refer to versions prior to Cordova 3.0.
+See The Cordova Command-line Interface for information about the
+current interface.
+
+## Requirements and Support
+
+See the [System Requirements](http://developer.android.com/sdk/index.html)
+for the Android SDK.
+
+Cordova supports Android 2.2, 2.3, and 4.x. As a general rule,
+platforms are deprecated as they dip below 5% on Google's
+[distribution dashboard](http://developer.android.com/about/dashboards/index.html).
+
+<!--
+NOTE, doc said:
+- Android 2.1 (Deprecated May 2013)
+- Android 3.x (Deprecated May 2013)
+-->
+
+Developers should use the `cordova` utility in conjunction with
+the Android SDK. See The Command-line Interface for
+information how to install it, add projects, then build and deploy a
+project.
+
+## Install the SDK
+
+Install the Android SDK from
+[developer.android.com/sdk](http://developer.android.com/sdk/). You
+may be presented with a choice of where to install the SDK, otherwise
+move the downloaded `adt-bundle` tree to wherever you store
+development tools.
+
+For Cordova command-line tools to work, you need to include the SDK's
+`tools` and `platform-tools` directories in your PATH environment. On
+Mac, you can use a text editor to create or modify the
+`~/.bash_profile` file, adding a line such as the following, depending
+on where the SDK installs:
+
+ export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools
+
+This exposes SDK tools in newly opened terminal windows. Otherwise run
+this to make them available in the current session:
+
+ $ source ~/.bash_profile
+
+To modify the PATH environment on Windows 7:
+
+* Click on the __Start__ menu in the lower-left corner of the desktop,
+ right-click on __Computer__, then click __Properties__.
+
+* Click __Advanced System Settings__ in the column on the left.
+
+* In the resulting dialog box, press __Environment Variables__.
+
+* Select the __PATH__ variable and press __Edit__.
+
+* Append the following to the PATH based on where you installed the
+ SDK, for example:
+
+ ;C:\Development\adt-bundle\sdk\platform-tools;C:\Development\adt-bundle\sdk\tools
+
+* Save the value and close both dialog boxes.
+
+You may also need to enable Java and Ant. Open a command prompt and
+type `java`, and also type `ant`. Append to the PATH whichever fail to
+run:
+
+ ;%JAVA_HOME%\bin;%ANT_HOME%\bin
+
+## Open a Project in the SDK
+
+Use the `cordova` utility to set up a new project, as described in The
+Cordova The Command-line Interface. For example, in a source-code directory:
+
+ $ cordova create hello com.example.hello "Hello World"
+ $ cd hello
+ $ cordova platform add android
+ $ cordova build
+
+Once created, here's how to use the SDK to modify it:
+
+* Launch the __Eclipse__ application.
+* Select the __New Project__ menu item.
+* Choose __Android Project from Existing Code__ from the resulting dialog box, and press __Next__:
+ 
+* Navigate to `hello`, or whichever directory you created for the project, then to the `platforms/android` subdirectory.
+* Press __Finish__.
+
+Once the Eclipse window opens, a red __X__ may appear to indicate
+unresolved problems. If so, follow these additional steps:
+
+* Right-click on the project folder.
+* In the resulting __Properties__ dialog, select __Android__ from the navigation pane.
+* For the project build target, select the highest Android API level you have installed.
+* Click __OK__.
+* Select __Clean__ from the __Project__ menu. This should correct all the errors in the project.
+
+## Deploy to Emulator
+
+You can use the `cordova` utility to run an app in an emulator, or you
+can run it within the SDK. Either way, the SDK must first be
+configured to display at least one device. To do so, use the Android
+SDK Manager, a Java application that runs separately from Eclipse.
+There are two ways to open it:
+
+* Run `android` on the command line.
+
+* From within Eclipse, press this toolbar icon:
+
+ 
+
+Once open, the Android SDK Manager displays various runtime libraries:
+
+
+
+Choose __Tools → Manage AVDs__ (Android Virtual Devices), then
+choose any item from __Device Definitions__ in the resulting dialog
+box:
+
+
+
+Press __Create AVD__, optionally modifying the name, then press __OK__
+to accept the changes:
+
+
+
+The AVD then appears in the __Android Virtual Devices__ list:
+
+
+
+To open the emulator as a separate application, select the AVD and
+press __Start__. It launches much as it would on the device, with
+additional controls available for hardware buttons:
+
+
+
+At this point you can use the `cordova` utility to deploy the
+application to the emulator from the command line:
+
+ $ cordova emulate android
+
+If instead you are working within Eclipse, right-click the project and
+choose __Run As → Android Application__. You may be asked to
+specify an AVD if none are already open.
+
+For a faster experience, use an Intel-based emulator image:
+
+* Install one or more `Intel x86 Atom` System Images as well as the
+ `Intel Hardware Accelerated Execution Manager`, available under
+ __Extras__.
+* Run the Intel installer, which is available within your Android SDK
+ at `extras/intel/Hardware_Accelerated_Execution_Manager`.
+* Create a new AVD with the target set to an Intel image.
+* When starting the emulator, ensure there are no error messages
+ indicating a failure to load HAX modules.
+
+## Deploy to Device
+
+To push an app directly to the device, make sure USB debugging is
+enabled on your device as described on the
+[Android Developer Site](http://developer.android.com/tools/device.html),
+and use a mini USB cable to plug it into your system.
+
+You can push the app to the device from the command line:
+
+ $ cordova run android
+
+Alternately within Eclipse, right-click the project and choose __Run
+As → Android Application__.
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/android/plugin.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/android/plugin.md b/docs/en/3.0.0rc1/guide/platforms/android/plugin.md
new file mode 100644
index 0000000..dba4f2d
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/android/plugin.md
@@ -0,0 +1,192 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Plugins
+
+Writing a plugin requires an understanding of the architecture of Cordova-Android. Cordova-Android consists
+of an Android WebView with hooks attached to it. These plugins are represented as class mappings in the config.xml
+file.
+
+A plugin consists of at least one Java class that extends the `CordovaPlugin` class. A plugin must override one
+of the `execute` methods from `CordovaPlugin`.
+As best practice, the plugin should handle `pause` and `resume` events, and any message passing between plugins.
+Plugins with long-running requests, background activity such as media payback, listeners, or internal state should implement the `onReset()` method as well. This method is run when the `WebView` navigates to a new page or refreshes, which reloads the JavaScript.
+
+## Plugin Class Mapping
+
+The JavaScript portion of a plugin always uses the `cordova.exec` method as follows:
+
+ exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);
+
+This marshals a request from the WebView to the Android native side,
+more or less boiling down to calling the `action` method on the
+`service` class, with the arguments passed in the `args` Array.
+
+Whether you distribute your plugin as Java file or as a JAR of its own, the plugin must be added to the `config.xml` file in your Cordova-Android application's `res/xml/` folder.
+
+ <plugin name="<service_name>" value="<full_name_including_namespace>"/>
+
+The service name should match the one used in the JavaScript `exec`
+call, and the value is the Java classes full name, including the
+namespace. Otherwise the plugin may compile but still be unreachable
+by Cordova.
+
+## Writing an Android Java Plugin
+
+JavaScript fires off a plugin request to the native side. The Android
+Java plugin is mapped properly via the `config.xml` file. So what
+does the final Android Java Plugin class look like?
+
+What gets dispatched to the plugin via JavaScript's `exec` function gets
+passed into the Plugin class's `execute` method. Most `execute`
+implementations look like this:
+
+ @Override
+ public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ this.beep(args.getLong(0));
+ callbackContext.success();
+ return true;
+ }
+ return false; // Returning false results in a "MethodNotFound" error.
+ }
+
+We compare the value of the `action` parameter, and dispatch the
+request off to a (private) method in the class, optionally passing
+some of the parameters to the method.
+
+When catching exceptions and returning errors, it's important for the
+sake of clarity that errors returned to JavaScript match Java's
+exception names as much as possible.
+
+### Threading
+
+JavaScript in the WebView does *not* run on the UI thread. It runs on
+the WebCore thread. The `execute` method also runs on the WebCore thread.
+
+If you need to interact with the UI, you should use the following:
+
+ @Override
+ public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ final long duration = args.getLong(0);
+ cordova.getActivity().runOnUiThread(new Runnable() {
+ public void run() {
+ ...
+ callbackContext.success(); // Thread-safe.
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+If you do not need to run on the UI thread, but do not want to block the WebCore thread:
+
+ @Override
+ public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
+ if ("beep".equals(action)) {
+ final long duration = args.getLong(0);
+ cordova.getThreadPool().execute(new Runnable() {
+ public void run() {
+ ...
+ callbackContext.success(); // Thread-safe.
+ }
+ });
+ return true;
+ }
+ return false;
+ }
+
+### Echo Android Plugin Example
+
+Add the following to our `config.xml` file:
+
+ <plugin name="Echo" value="org.apache.cordova.plugin.Echo" />
+
+Then add the following file to
+`src/org/apache/cordova/plugin/Echo.java` inside our Cordova-Android
+application:
+
+ package org.apache.cordova.plugin;
+
+ import org.apache.cordova.api.CordovaPlugin;
+ import org.apache.cordova.api.PluginResult;
+ import org.json.JSONArray;
+ import org.json.JSONException;
+ import org.json.JSONObject;
+
+ /**
+ * This class echoes a string called from JavaScript.
+ */
+ public class Echo extends CordovaPlugin {
+ @Override
+ public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
+ if (action.equals("echo")) {
+ String message = args.getString(0);
+ this.echo(message, callbackContext);
+ return true;
+ }
+ return false;
+ }
+
+ private void echo(String message, CallbackContext callbackContext) {
+ if (message != null && message.length() > 0) {
+ callbackContext.success(message);
+ } else {
+ callbackContext.error("Expected one non-empty string argument.");
+ }
+ }
+ }
+
+Let's take a look at the code. The necessary `imports` are at
+the top. Our class extends from `CordovaPlugin`. We override the
+execute() method in order to recieve messages from exec(). Our method
+first compares against `action`: this plugin only supports one action,
+the `echo` action. Any other action returns false, which results in an
+error of type `INVALID_ACTION`, which translates into an error
+callback invocation on the JavaScript side. Next, we grab the echo
+string using the `getString` method on our `args`, telling it we want
+to get the 0th parameter in the parameter array. We do a bit of
+parameter checking: make sure it is not `null`, and make sure it is
+not a zero-length string. If it is, we call `callbackContext.error()`
+(which, by now, you should know invokes the error callback). If all of
+those checks pass, then we call `callbackContext.success()` and pass
+in the `message` string we received as a parameter. This finally
+translates into a success callback invocation on the JavaScript
+side. It also passes the `message` parameter as a parameter into the
+JavaScript success callback function.
+
+## Debugging Plugins
+
+Eclipse can be used to debug an Android project, and the plugins can be debugged if the Java source is included in the project. Only the latest version of the Android Developer Tools is known to allow source code attachment to JAR dependencies, so this is not fully supported at this time.
+
+## Common Pitfalls
+
+* Plugins have access to a `CordovaInterface` object. This object has access to the Android `Activity` that is running the application. This is the `Context` required to launch
+a new Android `Intent`. The `CordovaInterface` allows plugins to start an `Activity` for a result, and to set the callback plugin for when the `Intent` comes back to the application. This is important, since the
+`Intent`s system is how Android communicates between processes.
+* Plugins do not have direct access to the `Context` as they have in the past. The legacy `ctx` member is deprecated, and will be removed six months after 2.0 is released. All of `ctx` methods exist on the `Context`, so both `getContext()` and `getActivity()` are capable of returning the proper object required.
+
+## Use the Source
+
+One of the best ways to prepare yourself to write your own plugin is to
+[look over existing plugins](https://github.com/apache/cordova-android/tree/master/framework/src/org/apache/cordova).
+
+You should also read through the comments in [CordovaPlugin.java](https://github.com/apache/cordova-android/blob/master/framework/src/org/apache/cordova/api/CordovaPlugin.java).
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/17ffa3e5/docs/en/3.0.0rc1/guide/platforms/android/tools.md
----------------------------------------------------------------------
diff --git a/docs/en/3.0.0rc1/guide/platforms/android/tools.md b/docs/en/3.0.0rc1/guide/platforms/android/tools.md
new file mode 100644
index 0000000..09fcfdc
--- /dev/null
+++ b/docs/en/3.0.0rc1/guide/platforms/android/tools.md
@@ -0,0 +1,80 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+---
+
+# Android Command-line Tools
+
+The `cordova` command-line utility is a high-level tool that allows
+you to build applications across several platforms at once. An older
+version of the Cordova framework provides sets of command-line tools
+specific to each platform. To use them as an alternative to the CLI,
+you need to download this version of Cordova from
+[cordova.apache.org](http://cordova.apache.org). The download contains
+separate archives for each platform. Expand the platform you wish to
+target. The tools described here are typically available in the
+top-level `bin` directory, otherwise consult the __README__ file for
+more detailed directions.
+
+## Create a project
+
+Run the `create` command, specifying the existing path to the project,
+the reverse-domain-style package identifier, and the app's display
+name. Here is the syntax for both Mac and Windows:
+
+ $ /path/to/cordova-android/bin/create /path/to/project com.example.project_name ProjectName
+ $ C:\path\to\cordova-android\bin\create.bat C:\path\to\project com.example.project_name ProjectName
+
+## Build
+
+This cleans then builds a project.
+
+Debug, on Mac or Windows:
+
+ $ /path/to/project/cordova/build --debug
+ $ C:\path\to\project\cordova\build.bat --debug
+
+Release, on Mac or Windows:
+
+ $ /path/to/project/cordova/build --release
+ $ C:\path\to\project\cordova\build.bat --release
+
+## Run the App
+
+The `run` command accepts the following _optional_ parameters:
+
+* Target specification. This includes `--emulator`, `--device`, or `--target=<targetID>`.
+* Build specification. This includes `--debug`, `--release`, or `--nobuild`.
+
+ $ /path/to/project/cordova/run [Target] [Build]
+ $ C:\path\to\project\cordova\run.bat [Target] [Build]
+
+Make sure you create at least one Android Virtual Device, otherwise
+you're prompted to do so with the `android` command. If more than one
+AVD is available as a target, you're prompted to select one. By
+default the `run` command detects a connected device, or a currently
+running emulator if no device is found.
+
+## Logging
+
+ $ /path/to/project/cordova/log
+ $ C:\path\to\project\cordova\log.bat
+
+### Cleaning
+
+ $ /path/to/project/cordova/clean
+ $ C:\path\to\project\cordova\clean.bat