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

docs: smaller code samples, typos, etc

parent 212bec60
......@@ -8,6 +8,7 @@
pre {
padding-left: 15px;
padding-righ: 15px;
font-size: 0.8em;
}
......
......@@ -142,7 +142,7 @@ Updating to v2.0
Replicate Storage
^^^^^^^^^^^^^^^^^
Comming soon
Coming soon
Revision Based Handlers
-----------------------
......
......@@ -88,8 +88,7 @@ for how to use these methods, in and outside jIO. The module provides:
{
parseStringToObject: [Function: parseStringToObject],
stringEscapeRegexpCharacters:
[Function: stringEscapeRegexpCharacters],
stringEscapeRegexpCharacters: [Function: stringEscapeRegexpCharacters],
select: [Function: select],
sortOn: [Function: sortOn],
limit: [Function: limit],
......@@ -120,8 +119,7 @@ Basic example:
var query = 'title: "Document number 1"';
// running the query
var result = complex_queries.QueryFactory.
create(query).exec(object_list);
var result = complex_queries.QueryFactory.create(query).exec(object_list);
// console.log(result);
// [ { "title": "Document number 1", "creator": "John Doe"} ]
......
......@@ -4,20 +4,27 @@ For developers
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 Grunt command line with npm.
* Install the Grunt command line with ``npm``.
``# npm -g install grunt-cli``
* Install dev dependencies.
* Install the dependencies.
``$ npm install``
* Compile JS/CC parser.
* Compile the JS/CC parser.
``$ make`` (until we find out how to compile it with grunt)
......@@ -25,14 +32,11 @@ To build the library you have to:
``$ 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
------------------
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
------------------------------------------
......@@ -102,15 +106,17 @@ Methods should return the following objects:
* **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})``
* **getAttachment()** -->
``success("ok", {"data": binary_string, "content_type": content_type})``
// or
``success("ok", {"data": new Blob([data], {"type": content_type})})``
.. code-block:: javascript
success("ok", {"data": binary_string, "content_type": content_type})
// or
success("ok", {"data": new Blob([data], {"type": content_type})})
* **allDocs()** --> ``success("ok", {"data": row_object})``
......@@ -132,8 +138,7 @@ Methods should return the following objects:
// if metadata doesn't promides "_id" -> repair storage state
success("no_content")
// or
error("conflict", "corrupted",
"impossible to repair document or storage")
error("conflict", "corrupted", "impossible to repair document or storage")
// DON'T DESIGN STORAGES IF THERE IS NO WAY
// TO REPAIR INCOHERENT STATES
......
......@@ -33,8 +33,7 @@ Getting started
"paths": {
// jio core + dependency
// the AMD compatible version of sha256.js,
// see Download and Fork
// the AMD compatible version of sha256.js, see Download and Fork
"sha256": "sha256.amd",
"rsvp": "rsvp-custom",
"jio": "jio",
......@@ -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>`_
`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
^^^^
* `sha256.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/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>`_
* `jio.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/jio.js>`_
* `complex_queries.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/complex_queries.js>`_
* sha256.amd.js
* rsvp-custom.js, AMD only version: rsvp-custom.amd.js
* jio.js
* complex_queries.js
Storage dependencies
^^^^^^^^^^^^^^^^^^^^
......@@ -121,27 +120,28 @@ Storage dependencies
Storage connectors
^^^^^^^^^^^^^^^^^^
* `localstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/localstorage.js>`_
* `davstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/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)
* `xwikistorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/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)
* localstorage.js
* davstorage.js
* s3storage.js (depends on sha1, jQuery) (WIP)
* xwikistorage.js (depends on jQuery) (WIP)
* erp5storage.js (depends on jQuery) (WIP)
* restsqlstorage.js (depends on jQuery) (WIP)
* mioga2storage.js (depends on jQuery) (WIP)
Storage handlers
^^^^^^^^^^^^^^^^
* `indexstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/indexstorage.js>`_ (WIP)
* `gidstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/gidstorage.js>`_ (WIP)
* `splitstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/splitstorage.js>`_ (WIP)
* indexstorage.js (WIP)
* gidstorage.js (WIP)
* splitstorage.js (WIP)
* replicatestorage.js (WIP)
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)
* `replicaterevisionstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/replicatestorage.js>`_ (WIP)
* revisionstorage.js (depends on sha256) (WIP)
* replicaterevisionstorage.js (WIP)
Unit tests
^^^^^^^^^^
......
......@@ -48,6 +48,6 @@ jIO documentation
complex_queries
metadata
developers
naming_conventions
style_guide
authors
......@@ -141,14 +141,12 @@ To retrieve jIO responses, you have to provide callbacks like this:
.. code-block:: javascript
jio_instance.post(metadata, [options]).
then([responseCallback],
[errorCallback],
[progressionCallback]);
then([responseCallback], [errorCallback], [progressionCallback]);
* On command success, ``responseCallback`` will be called with the jIO response as first parameter.
* On command error, ``errorCallback`` will be called with the jIO error as first parameter.
* On command notification, ``progressionCallback`` will be called with the storage notification.
* On command success, ``responseCallback`` is called with the jIO response as first parameter.
* On command error, ``errorCallback`` is called with the jIO error as first parameter.
* On command notification, ``progressionCallback`` is called with the storage notification.
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:
"statusText": "Not Found",
"error": "not_found",
"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:
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
......@@ -271,6 +269,7 @@ The following example shows how to create a new jIO in localStorage and then pos
"username": "usr",
"application_name":"app"
});
// post the document "metadata"
jio_instance.post({
"title" : "My Video",
......@@ -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');
}
id = response.id;
// post a thumbnail attachment
jio_instance.putAttachment({
"_id": id,
......@@ -293,6 +293,7 @@ The following example shows how to create a new jIO in localStorage and then pos
if (err) {
return alert('Error attaching thumbnail');
}
// post video attachment
jio_instance.putAttachment({
"_id": id,
......@@ -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
......
......@@ -334,8 +334,7 @@ Posting an image
"creator" : "Mr. Someone",
"title" : "New York City at Night",
"subject" : ["New York"],
"description": "A photo of New York City " +
"taken just after midnight",
"description": "A photo of New York City taken just after midnight",
"coverage" : ["New York", "1996-1997"]
}, callbacks); // send content as attachment
......
......@@ -2,17 +2,17 @@
.. role:: js(code)
: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 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
^^^^^^^^^^^^^^^^^^
......@@ -48,8 +48,8 @@ Using JSLint
^^^^^^^^^^^^
`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
into several development environments, so errors can be highlighted when
about potential problems. It can be used online and can also be integrated
into several development environments, so errors can be highlighted while
writing code.
Before validating your code in JSLint, you should use a code
......@@ -82,11 +82,11 @@ Some allowed options are:
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
JSLint often result from mixed use of space and tab, using 2 spaces throughout
......@@ -228,7 +228,6 @@ Bad Example
.. code-block:: javascript
// [...]
return {
"namedFunction": function namedFunction() {
return;
......@@ -239,7 +238,6 @@ Good Example
.. code-block:: javascript
// [...]
function namedFunction() {
return;
}
......@@ -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.
Example
.. code-block:: javascript
// 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