knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into gh-pages

Browse Source
This commit is contained in:
Rufus Pollock
2012-04-07 13:53:08 +01:00
parent 890aff7378 debcfbbb7a
commit 44706ad6cb
3 changed files with 300 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/model.html
View File

@@ -1,19 +1,31 @@
<!DOCTYPE html> <html> <head> <title>model.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <div id="jump_to"> Jump To &hellip; <div id="jump_wrapper"> <div id="jump_page"> <a class="source" href="model.html"> model.js </a> <a class="source" href="view-flot-graph.html"> view-flot-graph.js </a> <a class="source" href="view-grid.html"> view-grid.js </a> <a class="source" href="view.html"> view.js </a> </div> </div> </div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> model.js </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">&#182;</a> </div> <h1>Recline Backbone Models</h1> </td> <td class="code"> <div class="highlight"><pre><span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">||</span> <span class="p">{};</span> <!DOCTYPE html> <html> <head> <title>model.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <div id="jump_to"> Jump To &hellip; <div id="jump_wrapper"> <div id="jump_page"> <a class="source" href="model.html"> model.js </a> <a class="source" href="view-flot-graph.html"> view-flot-graph.js </a> <a class="source" href="view-grid.html"> view-grid.js </a> <a class="source" href="view.html"> view.js </a> </div> </div> </div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> model.js </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">&#182;</a> </div> <h1>Recline Backbone Models</h1> </td> <td class="code"> <div class="highlight"><pre><span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span> <span class="o">||</span> <span class="p">{};</span>
<span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Model</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Model</span> <span class="o">||</span> <span class="p">{};</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Model</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">recline</span><span class="p">.</span><span class="nx">Model</span> <span class="o">||</span> <span class="p">{};</span>
<span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">$</span><span class="p">,</span> <span class="nx">my</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">&#182;</a> </div> <h2>A Dataset model</h2> <span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">$</span><span class="p">,</span> <span class="nx">my</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">&#182;</a> </div> <h2><a id="dataset">A Dataset model</a></h2>
<p>A model has the following (non-Backbone) attributes:</p> <p>A model has the following (non-Backbone) attributes:</p>
<ul> <p>@property {FieldList} fields: (aka columns) is a <code>FieldList</code> listing all the
<li>fields: (aka columns) is a FieldList listing all the fields on this fields on this Dataset (this can be set explicitly, or, will be set by
Dataset (this can be set explicitly, or, will be set by Dataset.fetch() or Dataset.query()</li> Dataset.fetch() or Dataset.query()</p>
<li>currentDocuments: a DocumentList containing the Documents we have
currently loaded for viewing (you update currentDocuments by calling query)</li> <p>@property {DocumentList} currentDocuments: a <code>DocumentList</code> containing the
<li>docCount: total number of documents in this dataset</li> Documents we have currently loaded for viewing (updated by calling query
</ul> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Dataset</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> method)</p>
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;Dataset&#39;</span><span class="p">,</span>
<span class="nx">initialize</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">model</span><span class="p">,</span> <span class="nx">backend</span><span class="p">)</span> <span class="p">{</span> <p>@property {number} docCount: total number of documents in this dataset</p>
<p>@property {Backend} backend: the Backend (instance) for this Dataset</p>
<p>@property {Query} queryState: <code>Query</code> object which stores current
queryState. queryState may be edited by other components (e.g. a query
editor view) changes will trigger a Dataset query.</p>
<p>@property {FacetList} facets: FacetList object containing all current
Facets.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Dataset</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;Dataset&#39;</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">&#182;</a> </div> <h3>initialize</h3>
<p>Sets up instance properties (see above)</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">initialize</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">model</span><span class="p">,</span> <span class="nx">backend</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">_</span><span class="p">.</span><span class="nx">bindAll</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="s1">&#39;query&#39;</span><span class="p">);</span> <span class="nx">_</span><span class="p">.</span><span class="nx">bindAll</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="s1">&#39;query&#39;</span><span class="p">);</span>
<span class="k">this</span><span class="p">.</span><span class="nx">backend</span> <span class="o">=</span> <span class="nx">backend</span><span class="p">;</span> <span class="k">this</span><span class="p">.</span><span class="nx">backend</span> <span class="o">=</span> <span class="nx">backend</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">backend</span> <span class="o">&amp;&amp;</span> <span class="nx">backend</span><span class="p">.</span><span class="nx">constructor</span> <span class="o">==</span> <span class="nb">String</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nx">backend</span> <span class="o">&amp;&amp;</span> <span class="nx">backend</span><span class="p">.</span><span class="nx">constructor</span> <span class="o">==</span> <span class="nb">String</span><span class="p">)</span> <span class="p">{</span>
@@ -26,7 +38,7 @@ currently loaded for viewing (you update currentDocuments by calling query)</li>
<span class="k">this</span><span class="p">.</span><span class="nx">queryState</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Query</span><span class="p">();</span> <span class="k">this</span><span class="p">.</span><span class="nx">queryState</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Query</span><span class="p">();</span>
<span class="k">this</span><span class="p">.</span><span class="nx">queryState</span><span class="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="s1">&#39;change&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">query</span><span class="p">);</span> <span class="k">this</span><span class="p">.</span><span class="nx">queryState</span><span class="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="s1">&#39;change&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">query</span><span class="p">);</span>
<span class="k">this</span><span class="p">.</span><span class="nx">queryState</span><span class="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="s1">&#39;facet:add&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">query</span><span class="p">);</span> <span class="k">this</span><span class="p">.</span><span class="nx">queryState</span><span class="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="s1">&#39;facet:add&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">query</span><span class="p">);</span>
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">&#182;</a> </div> <h3>query</h3> <span class="p">},</span></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">&#182;</a> </div> <h3>query</h3>
<p>AJAX method with promise API to get documents from the backend.</p> <p>AJAX method with promise API to get documents from the backend.</p>
@@ -79,14 +91,14 @@ also returned.</p> </td> <td class="code">
<span class="nx">data</span><span class="p">.</span><span class="nx">fields</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">fields</span><span class="p">.</span><span class="nx">toJSON</span><span class="p">();</span> <span class="nx">data</span><span class="p">.</span><span class="nx">fields</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">fields</span><span class="p">.</span><span class="nx">toJSON</span><span class="p">();</span>
<span class="k">return</span> <span class="nx">data</span><span class="p">;</span> <span class="k">return</span> <span class="nx">data</span><span class="p">;</span>
<span class="p">}</span> <span class="p">}</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">&#182;</a> </div> <h2>A Document (aka Row)</h2> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">&#182;</a> </div> <h2><a id="document">A Document (aka Row)</a></h2>
<p>A single entry or row in the dataset</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Document</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <p>A single entry or row in the dataset</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Document</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;Document&#39;</span> <span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;Document&#39;</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">&#182;</a> </div> <h2>A Backbone collection of Documents</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">DocumentList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">&#182;</a> </div> <h2>A Backbone collection of Documents</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">DocumentList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;DocumentList&#39;</span><span class="p">,</span> <span class="nx">__type__</span><span class="o">:</span> <span class="s1">&#39;DocumentList&#39;</span><span class="p">,</span>
<span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Document</span> <span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Document</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">&#182;</a> </div> <h2>A Field (aka Column) on a Dataset</h2> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">&#182;</a> </div> <h2><a id="field">A Field (aka Column) on a Dataset</a></h2>
<p>Following attributes as standard:</p> <p>Following attributes as standard:</p>
@@ -99,8 +111,8 @@ also returned.</p> </td> <td class="code">
<span class="nx">id</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span> <span class="nx">id</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nx">label</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span> <span class="nx">label</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span>
<span class="nx">type</span><span class="o">:</span> <span class="s1">&#39;String&#39;</span> <span class="nx">type</span><span class="o">:</span> <span class="s1">&#39;String&#39;</span>
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">&#182;</a> </div> <p>In addition to normal backbone initialization via a Hash you can also <span class="p">},</span>
just pass a single argument representing id to the ctor</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">initialize</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">data</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">&#182;</a> </div> <p>if a hash not passed in the first argument is set as value for key 0</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="s1">&#39;0&#39;</span> <span class="k">in</span> <span class="nx">data</span><span class="p">)</span> <span class="p">{</span> <span class="nx">initialize</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">data</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">&#182;</a> </div> <p>if a hash not passed in the first argument throw error</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="s1">&#39;0&#39;</span> <span class="k">in</span> <span class="nx">data</span><span class="p">)</span> <span class="p">{</span>
<span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s1">&#39;Looks like you did not pass a proper hash with id to Field constructor&#39;</span><span class="p">);</span> <span class="k">throw</span> <span class="k">new</span> <span class="nb">Error</span><span class="p">(</span><span class="s1">&#39;Looks like you did not pass a proper hash with id to Field constructor&#39;</span><span class="p">);</span>
<span class="p">}</span> <span class="p">}</span>
<span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">attributes</span><span class="p">.</span><span class="nx">label</span> <span class="o">==</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="k">this</span><span class="p">.</span><span class="nx">attributes</span><span class="p">.</span><span class="nx">label</span> <span class="o">==</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span>
@@ -111,25 +123,81 @@ just pass a single argument representing id to the ctor</p> </td>
<span class="nx">my</span><span class="p">.</span><span class="nx">FieldList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <span class="nx">my</span><span class="p">.</span><span class="nx">FieldList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Field</span> <span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Field</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">&#182;</a> </div> <h2>A Query object storing Dataset Query state</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Query</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">&#182;</a> </div> <h2><a id="query">Query</a></h2>
<p>Query instances encapsulate a query to the backend (see <a
href="backend/base.html">query method on backend</a>). Useful both
for creating queries and for storing and manipulating query state -
e.g. from a query editor).</p>
<p><strong>Query Structure and format</strong></p>
<p>Query structure should follow that of <a href="http://www.elasticsearch.org/guide/reference/api/search/">ElasticSearch query
language</a>.</p>
<p><strong>NB: It is up to specific backends how to implement and support this query
structure. Different backends might choose to implement things differently
or not support certain features. Please check your backend for details.</strong></p>
<p>Query object has the following key attributes:</p>
<ul>
<li>size (=limit): number of results to return</li>
<li>from (=offset): offset into result set - http://www.elasticsearch.org/guide/reference/api/search/from-size.html</li>
<li>sort: sort order - <a href="http://www.elasticsearch.org/guide/reference/api/search/sort.html">http://www.elasticsearch.org/guide/reference/api/search/sort.html</a></li>
<li>query: Query in ES Query DSL <a href="http://www.elasticsearch.org/guide/reference/api/search/query.html">http://www.elasticsearch.org/guide/reference/api/search/query.html</a></li>
<li>filter: See filters and <a href="http://www.elasticsearch.org/guide/reference/query-dsl/filtered-query.html">Filtered Query</a></li>
<li>fields: set of fields to return - http://www.elasticsearch.org/guide/reference/api/search/fields.html</li>
<li>facets: TODO - see http://www.elasticsearch.org/guide/reference/api/search/facets/</li>
</ul>
<p>Additions:</p>
<ul>
<li><p>q: either straight text or a hash will map directly onto a <a href="http://www.elasticsearch.org/guide/reference/query-dsl/query-string-query.html">query_string
query</a>
in backend</p>
<ul><li>Of course this can be re-interpreted by different backends. E.g. some
may just pass this straight through e.g. for an SQL backend this could be
the full SQL query</li></ul></li>
<li><p>filters: dict of ElasticSearch filters. These will be and-ed together for
execution.</p></li>
</ul>
<p><strong>Examples</strong></p>
<pre>
{
q: 'quick brown fox',
filters: [
{ term: { 'owner': 'jones' } }
]
}
</pre> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Query</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">defaults</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> <span class="nx">defaults</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">{</span> <span class="k">return</span> <span class="p">{</span>
<span class="nx">size</span><span class="o">:</span> <span class="mi">100</span> <span class="nx">size</span><span class="o">:</span> <span class="mi">100</span>
<span class="p">,</span> <span class="nx">from</span><span class="o">:</span> <span class="mi">0</span> <span class="p">,</span> <span class="nx">from</span><span class="o">:</span> <span class="mi">0</span>
<span class="p">,</span> <span class="nx">facets</span><span class="o">:</span> <span class="p">{}</span></pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">&#182;</a> </div> <p>http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html <span class="p">,</span> <span class="nx">facets</span><span class="o">:</span> <span class="p">{}</span></pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">&#182;</a> </div> <p><a href="http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html">http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html</a>
, filter: {} , filter: {}</p> </td> <td class="code"> <div class="highlight"><pre> </pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">&#182;</a> </div> <p>list of simple filters which will be add to 'add' filter of filter</p> </td> <td class="code"> <div class="highlight"><pre> <span class="p">,</span> <span class="nx">filters</span><span class="o">:</span> <span class="p">[]</span>
list of simple filters which will be add to 'add' filter of filter</p> </td> <td class="code"> <div class="highlight"><pre> <span class="p">,</span> <span class="nx">filters</span><span class="o">:</span> <span class="p">[]</span>
<span class="p">}</span> <span class="p">}</span>
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">&#182;</a> </div> <p>Set (update or add) a terms filter <span class="p">},</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">&#182;</a> </div> <h4>addTermFilter</h4>
http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">addTermFilter</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">fieldId</span><span class="p">,</span> <span class="nx">value</span><span class="p">)</span> <span class="p">{</span>
<p>Set (update or add) a terms filter to filters</p>
<p>See <a href="http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html">http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html</a></p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">addTermFilter</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">fieldId</span><span class="p">,</span> <span class="nx">value</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">filters</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">&#39;filters&#39;</span><span class="p">);</span> <span class="kd">var</span> <span class="nx">filters</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">&#39;filters&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">filter</span> <span class="o">=</span> <span class="p">{</span> <span class="nx">term</span><span class="o">:</span> <span class="p">{}</span> <span class="p">};</span> <span class="kd">var</span> <span class="nx">filter</span> <span class="o">=</span> <span class="p">{</span> <span class="nx">term</span><span class="o">:</span> <span class="p">{}</span> <span class="p">};</span>
<span class="nx">filter</span><span class="p">.</span><span class="nx">term</span><span class="p">[</span><span class="nx">fieldId</span><span class="p">]</span> <span class="o">=</span> <span class="nx">value</span><span class="p">;</span> <span class="nx">filter</span><span class="p">.</span><span class="nx">term</span><span class="p">[</span><span class="nx">fieldId</span><span class="p">]</span> <span class="o">=</span> <span class="nx">value</span><span class="p">;</span>
<span class="nx">filters</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">filter</span><span class="p">);</span> <span class="nx">filters</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">filter</span><span class="p">);</span>
<span class="k">this</span><span class="p">.</span><span class="nx">set</span><span class="p">({</span><span class="nx">filters</span><span class="o">:</span> <span class="nx">filters</span><span class="p">});</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">&#182;</a> </div> <p>change does not seem to be triggered ...</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">trigger</span><span class="p">(</span><span class="s1">&#39;change&#39;</span><span class="p">);</span> <span class="k">this</span><span class="p">.</span><span class="nx">set</span><span class="p">({</span><span class="nx">filters</span><span class="o">:</span> <span class="nx">filters</span><span class="p">});</span></pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">&#182;</a> </div> <p>change does not seem to be triggered ...</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">trigger</span><span class="p">(</span><span class="s1">&#39;change&#39;</span><span class="p">);</span>
<span class="p">},</span> <span class="p">},</span></pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">&#182;</a> </div> <h3>addFacet</h3>
<span class="nx">addFacet</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">fieldId</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">facets</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">&#39;facets&#39;</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">&#182;</a> </div> <p>Assume id and fieldId should be the same (TODO: this need not be true if we want to add two different type of facets on same field)</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">contains</span><span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">facets</span><span class="p">),</span> <span class="nx">fieldId</span><span class="p">))</span> <span class="p">{</span> <p>Add a Facet to this query</p>
<p>See <a href="http://www.elasticsearch.org/guide/reference/api/search/facets/">http://www.elasticsearch.org/guide/reference/api/search/facets/</a></p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">addFacet</span><span class="o">:</span> <span class="kd">function</span><span class="p">(</span><span class="nx">fieldId</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">facets</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">get</span><span class="p">(</span><span class="s1">&#39;facets&#39;</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">&#182;</a> </div> <p>Assume id and fieldId should be the same (TODO: this need not be true if we want to add two different type of facets on same field)</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">contains</span><span class="p">(</span><span class="nx">_</span><span class="p">.</span><span class="nx">keys</span><span class="p">(</span><span class="nx">facets</span><span class="p">),</span> <span class="nx">fieldId</span><span class="p">))</span> <span class="p">{</span>
<span class="k">return</span><span class="p">;</span> <span class="k">return</span><span class="p">;</span>
<span class="p">}</span> <span class="p">}</span>
<span class="nx">facets</span><span class="p">[</span><span class="nx">fieldId</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="nx">facets</span><span class="p">[</span><span class="nx">fieldId</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span>
@@ -138,15 +206,56 @@ http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html</p>
<span class="k">this</span><span class="p">.</span><span class="nx">set</span><span class="p">({</span><span class="nx">facets</span><span class="o">:</span> <span class="nx">facets</span><span class="p">},</span> <span class="p">{</span><span class="nx">silent</span><span class="o">:</span> <span class="kc">true</span><span class="p">});</span> <span class="k">this</span><span class="p">.</span><span class="nx">set</span><span class="p">({</span><span class="nx">facets</span><span class="o">:</span> <span class="nx">facets</span><span class="p">},</span> <span class="p">{</span><span class="nx">silent</span><span class="o">:</span> <span class="kc">true</span><span class="p">});</span>
<span class="k">this</span><span class="p">.</span><span class="nx">trigger</span><span class="p">(</span><span class="s1">&#39;facet:add&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">);</span> <span class="k">this</span><span class="p">.</span><span class="nx">trigger</span><span class="p">(</span><span class="s1">&#39;facet:add&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">);</span>
<span class="p">}</span> <span class="p">}</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">&#182;</a> </div> <h2>A Facet (Result)</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Facet</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">&#182;</a> </div> <h2><a id="facet">A Facet (Result)</a></h2>
<p>Object to store Facet information, that is summary information (e.g. values
and counts) about a field obtained by some faceting method on the
backend.</p>
<p>Structure of a facet follows that of Facet results in ElasticSearch, see:
<a href="http://www.elasticsearch.org/guide/reference/api/search/facets/">http://www.elasticsearch.org/guide/reference/api/search/facets/</a></p>
<p>Specifically the object structure of a facet looks like (there is one
addition compared to ElasticSearch: the "id" field which corresponds to the
key used to specify this facet in the facet query):</p>
<pre>
{
"id": "id-of-facet",
// type of this facet (terms, range, histogram etc)
"_type" : "terms",
// total number of tokens in the facet
"total": 5,
// @property {number} number of documents which have no value for the field
"missing" : 0,
// number of facet values not included in the returned facets
"other": 0,
// term object ({term: , count: ...})
"terms" : [ {
"term" : "foo",
"count" : 2
}, {
"term" : "bar",
"count" : 2
}, {
"term" : "baz",
"count" : 1
}
]
}
</pre> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">Facet</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Model</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">defaults</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span> <span class="nx">defaults</span><span class="o">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">{</span> <span class="k">return</span> <span class="p">{</span>
<span class="nx">_type</span><span class="o">:</span> <span class="s1">&#39;terms&#39;</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">&#182;</a> </div> <p>total number of tokens in the facet</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">total</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">&#182;</a> </div> <p>number of facet values not included in the returned facets</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">other</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">&#182;</a> </div> <p>number of documents which have no value for the field</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">missing</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">&#182;</a> </div> <p>term object ({term: , count: ...})</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">terms</span><span class="o">:</span> <span class="p">[]</span> <span class="nx">_type</span><span class="o">:</span> <span class="s1">&#39;terms&#39;</span><span class="p">,</span>
<span class="nx">total</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nx">other</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nx">missing</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nx">terms</span><span class="o">:</span> <span class="p">[]</span>
<span class="p">}</span> <span class="p">}</span>
<span class="p">}</span> <span class="p">}</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">&#182;</a> </div> <h2>A Collection/List of Facets</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">FacetList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">&#182;</a> </div> <h2>A Collection/List of Facets</h2> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">FacetList</span> <span class="o">=</span> <span class="nx">Backbone</span><span class="p">.</span><span class="nx">Collection</span><span class="p">.</span><span class="nx">extend</span><span class="p">({</span>
<span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Facet</span> <span class="nx">model</span><span class="o">:</span> <span class="nx">my</span><span class="p">.</span><span class="nx">Facet</span>
<span class="p">});</span></pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">&#182;</a> </div> <h2>Backend registry</h2> <span class="p">});</span></pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">&#182;</a> </div> <h2>Backend registry</h2>
<p>Backends will register themselves by id into this registry</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">backends</span> <span class="o">=</span> <span class="p">{};</span> <p>Backends will register themselves by id into this registry</p> </td> <td class="code"> <div class="highlight"><pre><span class="nx">my</span><span class="p">.</span><span class="nx">backends</span> <span class="o">=</span> <span class="p">{};</span>

47
index.html
View File

@@ -84,11 +84,11 @@
<h1> <h1>
Recline Data Explorer and Library<br /> Recline Data Explorer and Library<br />
<small> <small>
A. Powerful data explorer using only javascript and html A. Powerful data explorer built in pure javascript and html
<br /> <br />
B. Suite of data components - grid, graphing and data connectors B. Suite of data components - grid, graphing and data connectors
<br /> <br />
&mdash; All built on <a href="http://backbonejs.org/">Backbone</a></small> &mdash; All built with <a href="http://backbonejs.org/">Backbone</a></small>
</h1> </h1>
</div> </div>
@@ -207,20 +207,34 @@ var dataset = recline.Model.Dataset({
<p>Recline has a simple structure layered on top of the basic Model/View <p>Recline has a simple structure layered on top of the basic Model/View
distinction inherent in Backbone.</p> distinction inherent in Backbone.</p>
<p><strong>Models</strong>: there are two main model objects:</p> <h4>Models</h4>
<p>There are two main model objects:</p>
<ul> <ul>
<li><a href="docs/model.html#section-2">Dataset</a>: represents the dataset. <li><a href="docs/model.html#dataset">Dataset</a>: represents the dataset.
Holds dataset info and a pointer to list of data items (Documents in our Holds dataset info and a pointer to list of data items (Documents in our
terminology) which it can load from the relevant Backend.</li> terminology) which it can load from the relevant Backend.</li>
<li><a href="docs/model.html#section-4">Document</a>: an individual data item <li><a href="docs/model.html#document">Document</a>: an individual data item
(e.g. a row from a relational database or a spreadsheet, a document from from (e.g. a row from a relational database or a spreadsheet, a document from from
a document DB like CouchDB or MongoDB).</li> a document DB like CouchDB or MongoDB).</li>
</ul> </ul>
<p>Additional, related models:</p>
<ul>
<li><a href="docs/model.html#field">Field</a>: a field/column on a
dataset.</li>
<li><a href="docs/model.html#query">Query</a>: an object to encapsulate a
query to the backend (useful both for creating queries and for storing and
manipulating query state - e.g. from a query editor).</li>
<li><a href="docs/model.html#facte">Facet</a>: Object to store Facet
information, that is summary information (e.g. values and counts) about a
field obtained by some faceting method on the backend.</li>
</ul>
<p>More detail of how these work can be found in the <a <p>More detail of how these work can be found in the <a
href="docs/model.html">Model source docs</a>.</p> href="docs/model.html">Model source docs</a>.</p>
<p><strong>Backends</strong> connect Dataset and Documents to data from a <h4>Backends</h4>
<p>Backends connect Dataset and Documents to data from a
specific 'Backend' data source. They provide methods for loading and saving specific 'Backend' data source. They provide methods for loading and saving
Datasets and individuals Documents as well as for bulk loading via a query API Datasets and individuals Documents as well as for bulk loading via a query API
and doing bulk transforms on the backend.</p> and doing bulk transforms on the backend.</p>
@@ -231,7 +245,8 @@ methods a Backend must have and (optionally) provides a base 'class' for
inheritance. You can also find detailed examples of backend implementations in inheritance. You can also find detailed examples of backend implementations in
the source documentation below.</p> the source documentation below.</p>
<p><strong>Views</strong>: complementing the model are various Views (you can <h4>Views</h4>
<p>Complementing the model are various Views (you can
also easily write your own). Each view holds a pointer to a Dataset:</p> also easily write your own). Each view holds a pointer to a Dataset:</p>
<ul> <ul>
<li>DataExplorer: the parent view which manages the overall app and sets up <li>DataExplorer: the parent view which manages the overall app and sets up
@@ -239,14 +254,28 @@ also easily write your own). Each view holds a pointer to a Dataset:</p>
<li>DataGrid: the data grid view.</li> <li>DataGrid: the data grid view.</li>
<li>FlotGraph: a simple graphing view using <a <li>FlotGraph: a simple graphing view using <a
href="http://code.google.com/p/flot/">Flot</a>.</li> href="http://code.google.com/p/flot/">Flot</a>.</li>
<li>Map: a map view using Leaflet.</li>
</ul> </ul>
<p>There are additional views which do not display a whole dataset but which
are useful:</p>
<ul>
<li>QueryEditor: a query editor view</li>
<li>FacetViewer: display facets</li>
</ul>
<h3 id="docs-source">Source Docs (via Docco)</h3> <h3 id="docs-source">Source Docs (via Docco)</h3>
<h4>Models and Views (Widgets)</h4>
<ul> <ul>
<li><a href="docs/model.html">Models</a></li> <li><a href="docs/model.html">Models</a></li>
<li><a href="docs/view.html">DataExplorer View (plus common view code)</a></li> <li><a href="docs/view.html">DataExplorer View (plus common view code)</a></li>
<li><a href="docs/view-grid.html">DataGrid View</a></li> <li><a href="docs/view-grid.html">DataGrid View</a></li>
<li><a href="docs/view-flot-graph.html">Graph View (based on Flot)</a></li> <li><a href="docs/view-flot-graph.html">Graph View (based on Flot)</a></li>
</ul>
<h4>Backends</h4>
<ul>
<li><a href="docs/backend/base.html">Backend: Base (base class providing a template for backends)</a></li> <li><a href="docs/backend/base.html">Backend: Base (base class providing a template for backends)</a></li>
<li><a href="docs/backend/memory.html">Backend: Memory (local data)</a></li> <li><a href="docs/backend/memory.html">Backend: Memory (local data)</a></li>
<li><a href="docs/backend/elasticsearch.html">Backend: ElasticSearch</a></li> <li><a href="docs/backend/elasticsearch.html">Backend: ElasticSearch</a></li>
@@ -280,9 +309,9 @@ However, it has been rewritten from the ground up using Backbone.</p>
</div></div> <!-- /span9 /content --> </div></div> <!-- /span9 /content -->
<div class="span3 sidebar"> <div class="span3 sidebar">
<div class="well sidebar-nav"> <div class="well sidebar-nav">
<h3 class="nav-header">Use It</h3> <h3 class="nav-header">Use the Explorer</h3>
<p class="getit-btn"><a href="app/" class="btn primary">Visit the Data Explorer &raquo;</a></p> <p class="getit-btn"><a href="app/" class="btn primary">Visit the Data Explorer &raquo;</a></p>
<h3 class="nav-header">Get It</h3> <h3 class="nav-header">Get the Library</h3>
<p class="getit-btn"><a href="recline.js" class="btn primary">Development Version<br />v0.3 (67k)</a></p> <p class="getit-btn"><a href="recline.js" class="btn primary">Development Version<br />v0.3 (67k)</a></p>
<h4>Dependencies</h4> <h4>Dependencies</h4>
<ul class="deps"> <ul class="deps">

144
src/model.js
View File

@@ -4,17 +4,33 @@ this.recline.Model = this.recline.Model || {};
(function($, my) { (function($, my) {
// ## A Dataset model // ## <a id="dataset">A Dataset model</a>
// //
// A model has the following (non-Backbone) attributes: // A model has the following (non-Backbone) attributes:
// //
// * fields: (aka columns) is a FieldList listing all the fields on this // @property {FieldList} fields: (aka columns) is a `FieldList` listing all the
// Dataset (this can be set explicitly, or, will be set by Dataset.fetch() or Dataset.query() // fields on this Dataset (this can be set explicitly, or, will be set by
// * currentDocuments: a DocumentList containing the Documents we have // Dataset.fetch() or Dataset.query()
// currently loaded for viewing (you update currentDocuments by calling query) //
// * docCount: total number of documents in this dataset // @property {DocumentList} currentDocuments: a `DocumentList` containing the
// Documents we have currently loaded for viewing (updated by calling query
// method)
//
// @property {number} docCount: total number of documents in this dataset
//
// @property {Backend} backend: the Backend (instance) for this Dataset
//
// @property {Query} queryState: `Query` object which stores current
// queryState. queryState may be edited by other components (e.g. a query
// editor view) changes will trigger a Dataset query.
//
// @property {FacetList} facets: FacetList object containing all current
// Facets.
my.Dataset = Backbone.Model.extend({ my.Dataset = Backbone.Model.extend({
__type__: 'Dataset', __type__: 'Dataset',
// ### initialize
//
// Sets up instance properties (see above)
initialize: function(model, backend) { initialize: function(model, backend) {
_.bindAll(this, 'query'); _.bindAll(this, 'query');
this.backend = backend; this.backend = backend;
@@ -86,7 +102,7 @@ my.Dataset = Backbone.Model.extend({
} }
}); });
// ## A Document (aka Row) // ## <a id="document">A Document (aka Row)</a>
// //
// A single entry or row in the dataset // A single entry or row in the dataset
my.Document = Backbone.Model.extend({ my.Document = Backbone.Model.extend({
@@ -99,7 +115,7 @@ my.DocumentList = Backbone.Collection.extend({
model: my.Document model: my.Document
}); });
// ## A Field (aka Column) on a Dataset // ## <a id="field">A Field (aka Column) on a Dataset</a>
// //
// Following attributes as standard: // Following attributes as standard:
// //
@@ -112,10 +128,8 @@ my.Field = Backbone.Model.extend({
label: null, label: null,
type: 'String' type: 'String'
}, },
// In addition to normal backbone initialization via a Hash you can also
// just pass a single argument representing id to the ctor
initialize: function(data) { initialize: function(data) {
// if a hash not passed in the first argument is set as value for key 0 // if a hash not passed in the first argument throw error
if ('0' in data) { if ('0' in data) {
throw new Error('Looks like you did not pass a proper hash with id to Field constructor'); throw new Error('Looks like you did not pass a proper hash with id to Field constructor');
} }
@@ -129,21 +143,71 @@ my.FieldList = Backbone.Collection.extend({
model: my.Field model: my.Field
}); });
// ## A Query object storing Dataset Query state // ## <a id="query">Query</a>
//
// Query instances encapsulate a query to the backend (see <a
// href="backend/base.html">query method on backend</a>). Useful both
// for creating queries and for storing and manipulating query state -
// e.g. from a query editor).
//
// **Query Structure and format**
//
// Query structure should follow that of [ElasticSearch query
// language](http://www.elasticsearch.org/guide/reference/api/search/).
//
// **NB: It is up to specific backends how to implement and support this query
// structure. Different backends might choose to implement things differently
// or not support certain features. Please check your backend for details.**
//
// Query object has the following key attributes:
//
// * size (=limit): number of results to return
// * from (=offset): offset into result set - http://www.elasticsearch.org/guide/reference/api/search/from-size.html
// * sort: sort order - <http://www.elasticsearch.org/guide/reference/api/search/sort.html>
// * query: Query in ES Query DSL <http://www.elasticsearch.org/guide/reference/api/search/query.html>
// * filter: See filters and <a href="http://www.elasticsearch.org/guide/reference/query-dsl/filtered-query.html">Filtered Query</a>
// * fields: set of fields to return - http://www.elasticsearch.org/guide/reference/api/search/fields.html
// * facets: TODO - see http://www.elasticsearch.org/guide/reference/api/search/facets/
//
// Additions:
//
// * q: either straight text or a hash will map directly onto a [query_string
// query](http://www.elasticsearch.org/guide/reference/query-dsl/query-string-query.html)
// in backend
//
// * Of course this can be re-interpreted by different backends. E.g. some
// may just pass this straight through e.g. for an SQL backend this could be
// the full SQL query
//
// * filters: dict of ElasticSearch filters. These will be and-ed together for
// execution.
//
// **Examples**
//
// <pre>
// {
// q: 'quick brown fox',
// filters: [
// { term: { 'owner': 'jones' } }
// ]
// }
// </pre>
my.Query = Backbone.Model.extend({ my.Query = Backbone.Model.extend({
defaults: function() { defaults: function() {
return { return {
size: 100 size: 100
, from: 0 , from: 0
, facets: {} , facets: {}
// http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html // <http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html>
// , filter: {} // , filter: {}
// list of simple filters which will be add to 'add' filter of filter
, filters: [] , filters: []
} }
}, },
// Set (update or add) a terms filter // #### addTermFilter
// http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html //
// Set (update or add) a terms filter to filters
//
// See <http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html>
addTermFilter: function(fieldId, value) { addTermFilter: function(fieldId, value) {
var filters = this.get('filters'); var filters = this.get('filters');
var filter = { term: {} }; var filter = { term: {} };
@@ -153,6 +217,11 @@ my.Query = Backbone.Model.extend({
// change does not seem to be triggered ... // change does not seem to be triggered ...
this.trigger('change'); this.trigger('change');
}, },
// ### addFacet
//
// Add a Facet to this query
//
// See <http://www.elasticsearch.org/guide/reference/api/search/facets/>
addFacet: function(fieldId) { addFacet: function(fieldId) {
var facets = this.get('facets'); var facets = this.get('facets');
// Assume id and fieldId should be the same (TODO: this need not be true if we want to add two different type of facets on same field) // Assume id and fieldId should be the same (TODO: this need not be true if we want to add two different type of facets on same field)
@@ -168,18 +237,51 @@ my.Query = Backbone.Model.extend({
}); });
// ## A Facet (Result) // ## <a id="facet">A Facet (Result)</a>
//
// Object to store Facet information, that is summary information (e.g. values
// and counts) about a field obtained by some faceting method on the
// backend.
//
// Structure of a facet follows that of Facet results in ElasticSearch, see:
// <http://www.elasticsearch.org/guide/reference/api/search/facets/>
//
// Specifically the object structure of a facet looks like (there is one
// addition compared to ElasticSearch: the "id" field which corresponds to the
// key used to specify this facet in the facet query):
//
// <pre>
// {
// "id": "id-of-facet",
// // type of this facet (terms, range, histogram etc)
// "_type" : "terms",
// // total number of tokens in the facet
// "total": 5,
// // @property {number} number of documents which have no value for the field
// "missing" : 0,
// // number of facet values not included in the returned facets
// "other": 0,
// // term object ({term: , count: ...})
// "terms" : [ {
// "term" : "foo",
// "count" : 2
// }, {
// "term" : "bar",
// "count" : 2
// }, {
// "term" : "baz",
// "count" : 1
// }
// ]
// }
// </pre>
my.Facet = Backbone.Model.extend({ my.Facet = Backbone.Model.extend({
defaults: function() { defaults: function() {
return { return {
_type: 'terms', _type: 'terms',
// total number of tokens in the facet
total: 0, total: 0,
// number of facet values not included in the returned facets
other: 0, other: 0,
// number of documents which have no value for the field
missing: 0, missing: 0,
// term object ({term: , count: ...})
terms: [] terms: []
} }
} }