introduction.html 17 KB
Newer Older
Marco Mariani's avatar
Marco Mariani committed
1 2 3 4 5 6 7 8 9 10


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
11
    <title>Introduction &mdash; jIO 2.0.0 documentation</title>
Marco Mariani's avatar
Marco Mariani committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '2.0.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
28
    <link rel="top" title="jIO 2.0.0 documentation" href="index.html" />
Marco Mariani's avatar
Marco Mariani committed
29
    <link rel="next" title="Downloads" href="download.html" />
30
    <link rel="prev" title="Welcome to jIO’s documentation!" href="index.html" /> 
Marco Mariani's avatar
Marco Mariani committed
31 32 33 34 35 36 37 38 39 40 41 42
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="download.html" title="Downloads"
             accesskey="N">next</a> |</li>
        <li class="right" >
43
          <a href="index.html" title="Welcome to jIO’s documentation!"
Marco Mariani's avatar
Marco Mariani committed
44
             accesskey="P">previous</a> |</li>
45
        <li><a href="index.html">jIO 2.0.0 documentation</a> &raquo;</li> 
Marco Mariani's avatar
Marco Mariani committed
46 47 48 49 50 51 52 53 54 55 56 57
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h1>
<div class="section" id="what-is-jio">
<h2>What is jIO?<a class="headerlink" href="#what-is-jio" title="Permalink to this headline"></a></h2>
58
<p>jIO is a JavaScript library that allows to manage JSON documents on local or
Marco Mariani's avatar
Marco Mariani committed
59 60 61 62 63 64 65
remote storages in asynchronous fashion. jIO is an abstracted API mapped after
CouchDB, that offers connectors to multiple storages, special handlers to
enhance functionality (replication, revisions, indexing) and a query module to
retrieve documents and specific information across storage trees.</p>
</div>
<div class="section" id="how-does-it-work">
<h2>How does it work?<a class="headerlink" href="#how-does-it-work" title="Permalink to this headline"></a></h2>
66
<p>jIO is composed of two parts - jIO core and storage library(ies). The core
Marco Mariani's avatar
Marco Mariani committed
67
is using storage libraries (connectors) to interact with the associated remote
68
storage servers. Some queries can be used on top of the jIO <tt class="docutils literal"><span class="pre">allDocs()</span></tt> method to
Marco Mariani's avatar
Marco Mariani committed
69
query documents based on defined criteria.</p>
70
<p>jIO uses a job management system, so every method call adds a job into a
Marco Mariani's avatar
Marco Mariani committed
71
queue. The queue is copied in the browser&#8217;s local storage (by default), so it
72 73
can be restored in case of browser crash. Jobs are invoked
asynchronously and ongoing jobs are not able to re-trigger to prevent
Marco Mariani's avatar
Marco Mariani committed
74 75 76 77 78 79 80
conflicts.</p>
</div>
<div class="section" id="getting-started">
<h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline"></a></h2>
<p>This walkthrough is designed to get you started using a basic jIO instance.</p>
<ol class="arabic">
<li><p class="first">Download jIO core, the storages you want to use as well as the
81
complex-queries scripts and the dependencies required for the storages
Marco Mariani's avatar
Marco Mariani committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
you intend to use.  <a class="reference internal" href="download.html#download-fork"><em>[Download &amp; Fork]</em></a></p>
</li>
<li><p class="first">Add the scripts to your HTML page in the following order:</p>
<div class="highlight-html"><pre>&lt;!-- jio core + dependency --&gt;
&lt;script src="sha256.amd.js"&gt;&lt;/script&gt;
&lt;script src="rsvp-custom.js"&gt;&lt;/script&gt;
&lt;script src="jio.js"&gt;&lt;/script&gt;

&lt;!-- storages + dependencies --&gt;
&lt;script src="complex_queries.js"&gt;&lt;/script&gt;
&lt;script src="localstorage.js"&gt;&lt;/script&gt;
&lt;script src="davstorage.js"&gt;&lt;/script&gt;

&lt;script ...&gt;</pre>
</div>
97
<p>With <a class="reference external" href="http://requirejs.org/">RequireJS</a>, the main.js will look like:</p>
Marco Mariani's avatar
Marco Mariani committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
<div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14</pre></div></td><td class="code"><div class="highlight"><pre><span class="nx">require</span><span class="p">.</span><span class="nx">config</span><span class="p">({</span>
    <span class="s2">&quot;paths&quot;</span><span class="o">:</span> <span class="p">{</span>
        <span class="c1">// jio core + dependency</span>

        <span class="c1">// the AMD compatible version of sha256.js -&gt; see Download and Fork</span>
        <span class="s2">&quot;sha256&quot;</span><span class="o">:</span> <span class="s2">&quot;sha256.amd&quot;</span><span class="p">,</span>
        <span class="s2">&quot;rsvp&quot;</span><span class="o">:</span> <span class="s2">&quot;rsvp-custom&quot;</span><span class="p">,</span>
        <span class="s2">&quot;jio&quot;</span><span class="o">:</span> <span class="s2">&quot;jio&quot;</span><span class="p">,</span>
        <span class="c1">// storages + dependencies</span>
        <span class="s2">&quot;complex_queries&quot;</span><span class="o">:</span> <span class="s2">&quot;complex_queries&quot;</span><span class="p">,</span>
        <span class="s2">&quot;localstorage&quot;</span><span class="o">:</span> <span class="s2">&quot;localstorage&quot;</span><span class="p">,</span>
        <span class="s2">&quot;davstorage&quot;</span><span class="o">:</span> <span class="s2">&quot;davstorage&quot;</span>
    <span class="p">}</span>
<span class="p">});</span>
</pre></div>
</td></tr></table></div>
</li>
128
<li><p class="first">jIO connects to a number of storages and allows adding handlers (or
Marco Mariani's avatar
Marco Mariani committed
129 130 131 132 133 134 135 136 137
functions) to specifc storages.
You can use both handlers and available storages to build a storage
tree across which all documents will be maintained and managed by jIO.</p>
<p>See <a class="reference internal" href="available_storages.html#list-of-available-storages"><em>List of Available Storages</em></a>.</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="c1">// create your jio instance</span>
<span class="kd">var</span> <span class="nx">my_jio</span> <span class="o">=</span> <span class="nx">jIO</span><span class="p">.</span><span class="nx">createJIO</span><span class="p">(</span><span class="nx">storage_description</span><span class="p">);</span>
</pre></div>
</div>
</li>
138
<li><p class="first">The jIO API provides ten main methods to manage documents across the storage(s) specified in your jIO storage tree.</p>
Marco Mariani's avatar
Marco Mariani committed
139 140
<table border="1" class="docutils">
<colgroup>
141 142 143
<col width="19%" />
<col width="46%" />
<col width="35%" />
Marco Mariani's avatar
Marco Mariani committed
144 145 146
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Method</th>
147
<th class="head">Example call</th>
Marco Mariani's avatar
Marco Mariani committed
148 149 150 151
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
152
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">post()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
153 154 155
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">post</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Creates a new document</td>
</tr>
156
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">put()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
157 158 159
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">put</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Creates/Updates a document</td>
</tr>
160
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">putAttachment()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
161 162 163
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">putAttachement</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name other"><span class="pre">attachment</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Updates/Adds an attachment to a document</td>
</tr>
164
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">get()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
165 166 167
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">get</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Reads a document</td>
</tr>
168
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">getAttachment()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
169 170 171
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">getAttachment</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name other"><span class="pre">attachment</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Reads a document attachment</td>
</tr>
172
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">remove()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
173 174 175
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">remove</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Deletes a document and its attachments</td>
</tr>
176
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">removeAttachment()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
177 178 179
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">removeAttachment</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name other"><span class="pre">attachment</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Deletes a document attachment</td>
</tr>
180
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">allDocs()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
181 182 183
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">allDocs</span></span><span class="punctuation"><span class="pre">(</span></span><span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Retrieves a list of existing documents</td>
</tr>
184
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">check()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
185 186 187
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">check</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Check the document state</td>
</tr>
188
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">repair()</span></tt></td>
Marco Mariani's avatar
Marco Mariani committed
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
<td><tt class="code js javascript docutils literal"><span class="name other"><span class="pre">my_jio</span></span><span class="punctuation"><span class="pre">.</span></span><span class="name other"><span class="pre">repair</span></span><span class="punctuation"><span class="pre">(</span></span><span class="name builtin"><span class="pre">document</span></span><span class="punctuation"><span class="pre">,</span></span> <span class="punctuation"><span class="pre">[</span></span><span class="name other"><span class="pre">options</span></span><span class="punctuation"><span class="pre">]);</span></span></tt></td>
<td>Repair the document</td>
</tr>
</tbody>
</table>
</li>
</ol>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
Marco Mariani's avatar
Marco Mariani committed
206
              <img class="logo" src="_static/jio-logo.png" alt="Logo"/>
Marco Mariani's avatar
Marco Mariani committed
207 208 209 210 211 212 213 214 215 216 217 218 219
            </a></p>
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Introduction</a><ul>
<li><a class="reference internal" href="#what-is-jio">What is jIO?</a></li>
<li><a class="reference internal" href="#how-does-it-work">How does it work?</a></li>
<li><a class="reference internal" href="#getting-started">Getting started</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
220
                        title="previous chapter">Welcome to jIO&#8217;s documentation!</a></p>
Marco Mariani's avatar
Marco Mariani committed
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
  <h4>Next topic</h4>
  <p class="topless"><a href="download.html"
                        title="next chapter">Downloads</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/introduction.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="download.html" title="Downloads"
             >next</a> |</li>
        <li class="right" >
256
          <a href="index.html" title="Welcome to jIO’s documentation!"
Marco Mariani's avatar
Marco Mariani committed
257
             >previous</a> |</li>
258
        <li><a href="index.html">jIO 2.0.0 documentation</a> &raquo;</li> 
Marco Mariani's avatar
Marco Mariani committed
259 260 261 262 263 264 265 266
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2013, Nexedi.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
  </body>
</html>