Commit 8ecf02b2 authored by Marco Mariani's avatar Marco Mariani

docs: smaller code samples, typos, etc

parent 212bec60
...@@ -8,6 +8,7 @@ ...@@ -8,6 +8,7 @@
pre { pre {
padding-left: 15px; padding-left: 15px;
padding-righ: 15px; padding-righ: 15px;
font-size: 0.8em;
} }
......
...@@ -142,7 +142,7 @@ Updating to v2.0 ...@@ -142,7 +142,7 @@ Updating to v2.0
Replicate Storage Replicate Storage
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Comming soon Coming soon
Revision Based Handlers Revision Based Handlers
----------------------- -----------------------
......
...@@ -88,8 +88,7 @@ for how to use these methods, in and outside jIO. The module provides: ...@@ -88,8 +88,7 @@ for how to use these methods, in and outside jIO. The module provides:
{ {
parseStringToObject: [Function: parseStringToObject], parseStringToObject: [Function: parseStringToObject],
stringEscapeRegexpCharacters: stringEscapeRegexpCharacters: [Function: stringEscapeRegexpCharacters],
[Function: stringEscapeRegexpCharacters],
select: [Function: select], select: [Function: select],
sortOn: [Function: sortOn], sortOn: [Function: sortOn],
limit: [Function: limit], limit: [Function: limit],
...@@ -120,8 +119,7 @@ Basic example: ...@@ -120,8 +119,7 @@ Basic example:
var query = 'title: "Document number 1"'; var query = 'title: "Document number 1"';
// running the query // running the query
var result = complex_queries.QueryFactory. var result = complex_queries.QueryFactory.create(query).exec(object_list);
create(query).exec(object_list);
// console.log(result); // console.log(result);
// [ { "title": "Document number 1", "creator": "John Doe"} ] // [ { "title": "Document number 1", "creator": "John Doe"} ]
......
...@@ -4,20 +4,27 @@ For developers ...@@ -4,20 +4,27 @@ For developers
Quick start Quick start
----------- -----------
To get started with jIO, clone one of the repositories linked in :ref:`Download & Fork <download-fork>`. The source repository includes ready-to-use files, so in case you do
not want to build jIO yourself, just use *jio.js* as well as *complex_queries.js*
plus the storages and dependencies you need and you will be good to go.
If you want to modify or build jIO yourself, you need to
* Clone from a repository
``$ git clone https://github.com/nexedi/jio.git``
To build the library you have to: * Install `NodeJS <http://nodejs.org/>`_ (including ``npm``)
* Install `NodeJS <http://nodejs.org/>`_ (including NPM) * Install the Grunt command line with ``npm``.
* Install Grunt command line with npm.
``# npm -g install grunt-cli`` ``# npm -g install grunt-cli``
* Install dev dependencies. * Install the dependencies.
``$ npm install`` ``$ npm install``
* Compile JS/CC parser. * Compile the JS/CC parser.
``$ make`` (until we find out how to compile it with grunt) ``$ make`` (until we find out how to compile it with grunt)
...@@ -25,14 +32,11 @@ To build the library you have to: ...@@ -25,14 +32,11 @@ To build the library you have to:
``$ grunt`` ``$ grunt``
The repository also includes the built ready-to-use files, so in case you do
not want to build jIO yourself, just use *jio.js* as well as *complex_queries.js*
plus the storages and dependencies you need and you will be good to go.
Naming Conventions Naming Conventions
------------------ ------------------
All the code follows these :ref:`JavaScript Naming Conventions <naming-conventions>`. All the code follows this :ref:`JavaScript Style Guide <style-guide>`.
How to design your own jIO Storage Library How to design your own jIO Storage Library
------------------------------------------ ------------------------------------------
...@@ -102,15 +106,17 @@ Methods should return the following objects: ...@@ -102,15 +106,17 @@ Methods should return the following objects:
* **post()** --> ``success("created", {"id": new_generated_id})`` * **post()** --> ``success("created", {"id": new_generated_id})``
* **put()**, ``remove``, ``putAttachment`` or ``removeAttachment`` --> ``success(204)`` * **put()**, **remove()**, **putAttachment()** or **removeAttachment()** --> ``success(204)``
* **get()** --> ``success("ok", {"data": document_metadata})`` * **get()** --> ``success("ok", {"data": document_metadata})``
* **getAttachment()** --> * **getAttachment()** -->
``success("ok", {"data": binary_string, "content_type": content_type})`` .. code-block:: javascript
success("ok", {"data": binary_string, "content_type": content_type})
// or // or
``success("ok", {"data": new Blob([data], {"type": content_type})})`` success("ok", {"data": new Blob([data], {"type": content_type})})
* **allDocs()** --> ``success("ok", {"data": row_object})`` * **allDocs()** --> ``success("ok", {"data": row_object})``
...@@ -132,8 +138,7 @@ Methods should return the following objects: ...@@ -132,8 +138,7 @@ Methods should return the following objects:
// if metadata doesn't promides "_id" -> repair storage state // if metadata doesn't promides "_id" -> repair storage state
success("no_content") success("no_content")
// or // or
error("conflict", "corrupted", error("conflict", "corrupted", "impossible to repair document or storage")
"impossible to repair document or storage")
// DON'T DESIGN STORAGES IF THERE IS NO WAY // DON'T DESIGN STORAGES IF THERE IS NO WAY
// TO REPAIR INCOHERENT STATES // TO REPAIR INCOHERENT STATES
......
...@@ -33,8 +33,7 @@ Getting started ...@@ -33,8 +33,7 @@ Getting started
"paths": { "paths": {
// jio core + dependency // jio core + dependency
// the AMD compatible version of sha256.js, // the AMD compatible version of sha256.js, see Download and Fork
// see Download and Fork
"sha256": "sha256.amd", "sha256": "sha256.amd",
"rsvp": "rsvp-custom", "rsvp": "rsvp-custom",
"jio": "jio", "jio": "jio",
...@@ -97,16 +96,16 @@ You can use one of the ZIP packages, which include all the dependencies and stor ...@@ -97,16 +96,16 @@ You can use one of the ZIP packages, which include all the dependencies and stor
`Full download (172k) <_static/jio-2.0.0.zip>`_ `Full download (172k) <_static/jio-2.0.0.zip>`_
`Minified download (87k) <_static/jio-2.0.0-min.zip>`_ `Minified download (87k) <_static/jio-2.0.0-min.zip>`_
or you can create your own set of files using the following links: or you can create your own set of files, which are are provided in the above packages and the source repository:
Core Core
^^^^ ^^^^
* `sha256.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha256.amd.js>`_ * sha256.amd.js
* `rsvp-custom.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/rsvp/rsvp-custom.js>`_, AMD only version: `rsvp-custom.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/rsvp/rsvp-custom.amd.js>`_ * rsvp-custom.js, AMD only version: rsvp-custom.amd.js
* `jio.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/jio.js>`_ * jio.js
* `complex_queries.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/complex_queries.js>`_ * complex_queries.js
Storage dependencies Storage dependencies
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
...@@ -121,27 +120,28 @@ Storage dependencies ...@@ -121,27 +120,28 @@ Storage dependencies
Storage connectors Storage connectors
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
* `localstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/localstorage.js>`_ * localstorage.js
* `davstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/davstorage.js>`_ * davstorage.js
* `s3storage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/s3storage.js>`_ (depends on sha1, jQuery) (WIP) * s3storage.js (depends on sha1, jQuery) (WIP)
* `xwikistorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/xwikistorage.js>`_ (depends on jQuery) (WIP) * xwikistorage.js (depends on jQuery) (WIP)
* `erp5storage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/erp5storage.js>`_ (depends on jQuery) (WIP) * erp5storage.js (depends on jQuery) (WIP)
* restsqlstorage.js (depends on jQuery) (WIP) * restsqlstorage.js (depends on jQuery) (WIP)
* mioga2storage.js (depends on jQuery) (WIP) * mioga2storage.js (depends on jQuery) (WIP)
Storage handlers Storage handlers
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
* `indexstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/indexstorage.js>`_ (WIP) * indexstorage.js (WIP)
* `gidstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/gidstorage.js>`_ (WIP) * gidstorage.js (WIP)
* `splitstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/splitstorage.js>`_ (WIP) * splitstorage.js (WIP)
* replicatestorage.js (WIP) * replicatestorage.js (WIP)
Revision based storage handlers Revision based storage handlers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* `revisionstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/revisionstorage.js>`_ (depends on sha256) (WIP) * revisionstorage.js (depends on sha256) (WIP)
* `replicaterevisionstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/replicatestorage.js>`_ (WIP) * replicaterevisionstorage.js (WIP)
Unit tests Unit tests
^^^^^^^^^^ ^^^^^^^^^^
......
...@@ -48,6 +48,6 @@ jIO documentation ...@@ -48,6 +48,6 @@ jIO documentation
complex_queries complex_queries
metadata metadata
developers developers
naming_conventions style_guide
authors authors
...@@ -141,14 +141,12 @@ To retrieve jIO responses, you have to provide callbacks like this: ...@@ -141,14 +141,12 @@ To retrieve jIO responses, you have to provide callbacks like this:
.. code-block:: javascript .. code-block:: javascript
jio_instance.post(metadata, [options]). jio_instance.post(metadata, [options]).
then([responseCallback], then([responseCallback], [errorCallback], [progressionCallback]);
[errorCallback],
[progressionCallback]);
* On command success, ``responseCallback`` will be called with the jIO response as first parameter. * On command success, ``responseCallback`` is called with the jIO response as first parameter.
* On command error, ``errorCallback`` will be called with the jIO error as first parameter. * On command error, ``errorCallback`` is called with the jIO error as first parameter.
* On command notification, ``progressionCallback`` will be called with the storage notification. * On command notification, ``progressionCallback`` is called with the storage notification.
Here is a list of responses returned by jIO according to methods and options: Here is a list of responses returned by jIO according to methods and options:
...@@ -253,7 +251,7 @@ In case of error, the ``errorCallback`` first parameter will look like: ...@@ -253,7 +251,7 @@ In case of error, the ``errorCallback`` first parameter will look like:
"statusText": "Not Found", "statusText": "Not Found",
"error": "not_found", "error": "not_found",
"reason": "document missing", "reason": "document missing",
"message": "Unable to get the requseted document" "message": "Unable to get the requested document"
} }
...@@ -261,7 +259,7 @@ In case of error, the ``errorCallback`` first parameter will look like: ...@@ -261,7 +259,7 @@ In case of error, the ``errorCallback`` first parameter will look like:
How to store a video on localStorage How to store a video on localStorage
------------------------------------ ------------------------------------
The following example shows how to create a new jIO in localStorage and then post a document with two attachments. The following example creates a new jIO in localStorage and then posts a document with two attachments.
.. code-block:: javascript .. code-block:: javascript
...@@ -271,6 +269,7 @@ The following example shows how to create a new jIO in localStorage and then pos ...@@ -271,6 +269,7 @@ The following example shows how to create a new jIO in localStorage and then pos
"username": "usr", "username": "usr",
"application_name":"app" "application_name":"app"
}); });
// post the document "metadata" // post the document "metadata"
jio_instance.post({ jio_instance.post({
"title" : "My Video", "title" : "My Video",
...@@ -283,6 +282,7 @@ The following example shows how to create a new jIO in localStorage and then pos ...@@ -283,6 +282,7 @@ The following example shows how to create a new jIO in localStorage and then pos
return alert('Error posting the document meta'); return alert('Error posting the document meta');
} }
id = response.id; id = response.id;
// post a thumbnail attachment // post a thumbnail attachment
jio_instance.putAttachment({ jio_instance.putAttachment({
"_id": id, "_id": id,
...@@ -293,6 +293,7 @@ The following example shows how to create a new jIO in localStorage and then pos ...@@ -293,6 +293,7 @@ The following example shows how to create a new jIO in localStorage and then pos
if (err) { if (err) {
return alert('Error attaching thumbnail'); return alert('Error attaching thumbnail');
} }
// post video attachment // post video attachment
jio_instance.putAttachment({ jio_instance.putAttachment({
"_id": id, "_id": id,
...@@ -309,7 +310,7 @@ The following example shows how to create a new jIO in localStorage and then pos ...@@ -309,7 +310,7 @@ The following example shows how to create a new jIO in localStorage and then pos
}); });
localStorage contents: localStorage now contains:
.. code-block:: javascript .. code-block:: javascript
......
...@@ -334,8 +334,7 @@ Posting an image ...@@ -334,8 +334,7 @@ Posting an image
"creator" : "Mr. Someone", "creator" : "Mr. Someone",
"title" : "New York City at Night", "title" : "New York City at Night",
"subject" : ["New York"], "subject" : ["New York"],
"description": "A photo of New York City " + "description": "A photo of New York City taken just after midnight",
"taken just after midnight",
"coverage" : ["New York", "1996-1997"] "coverage" : ["New York", "1996-1997"]
}, callbacks); // send content as attachment }, callbacks); // send content as attachment
......
...@@ -2,17 +2,17 @@ ...@@ -2,17 +2,17 @@
.. role:: js(code) .. role:: js(code)
:language: javascript :language: javascript
.. _naming-conventions: .. _style-guide:
JavaScript Naming Conventions JavaScript Style Guide
============================= ======================
This document defines JavaScript naming conventions, which are split into essential, coding and naming conventions. This document defines JavaScript style conventions, which are split into essential, coding and naming conventions.
Essential Conventions Essential Conventions
--------------------- ---------------------
Essential conventions include generic patterns that should be adhered to in order to write *readable*, *consistent* and *maintainable* code. Essential conventions include generic patterns that you should adhere to in order to write *readable*, *consistent* and *maintainable* code.
Minimizing Globals Minimizing Globals
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
...@@ -48,8 +48,8 @@ Using JSLint ...@@ -48,8 +48,8 @@ Using JSLint
^^^^^^^^^^^^ ^^^^^^^^^^^^
`JSLint <http://www.jslint.com/>`_ is a quality tool that inspects code and warns `JSLint <http://www.jslint.com/>`_ is a quality tool that inspects code and warns
about potential problems. It is available online and can also be integrated about potential problems. It can be used online and can also be integrated
into several development environments, so errors can be highlighted when into several development environments, so errors can be highlighted while
writing code. writing code.
Before validating your code in JSLint, you should use a code Before validating your code in JSLint, you should use a code
...@@ -82,11 +82,11 @@ Some allowed options are: ...@@ -82,11 +82,11 @@ Some allowed options are:
Coding Conventions Coding Conventions
------------------ ------------------
Coding conventions include generic patterns that ensure the written code follows certain formatting conventions. Coding conventions include generic patterns that ensure the written code is consistently formatted.
Uses two-space indentation Using two-space indentation
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
Tabs and 2-space indentation are being used equally. Since a lot of errors on Tabs and 2-space indentation are being used equally. Since a lot of errors on
JSLint often result from mixed use of space and tab, using 2 spaces throughout JSLint often result from mixed use of space and tab, using 2 spaces throughout
...@@ -228,7 +228,6 @@ Bad Example ...@@ -228,7 +228,6 @@ Bad Example
.. code-block:: javascript .. code-block:: javascript
// [...]
return { return {
"namedFunction": function namedFunction() { "namedFunction": function namedFunction() {
return; return;
...@@ -239,7 +238,6 @@ Good Example ...@@ -239,7 +238,6 @@ Good Example
.. code-block:: javascript .. code-block:: javascript
// [...]
function namedFunction() { function namedFunction() {
return; return;
} }
...@@ -319,8 +317,6 @@ Variable names with multiple words should always use an underscore between them. ...@@ -319,8 +317,6 @@ Variable names with multiple words should always use an underscore between them.
Confusing variable names should end with the variable type. Confusing variable names should end with the variable type.
Example
.. code-block:: javascript .. code-block:: javascript
// implicit type // implicit type
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment