[#52,docs/model][m]: document all model elements in detail.
* List more items in main index doc page * Major extension of source docs including * Query object with its spec * Facet * etc
This commit is contained in:
Rufus Pollock
parent
0155d4dec5
commit
2cd9192480
169
docs/model.html
169
docs/model.html
@ -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 … <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">¶</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="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">¶</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">¶</a> </div> <h2><a id="dataset">A Dataset model</a></h2>
|
||||
|
||||
<p>A model has the following (non-Backbone) attributes:</p>
|
||||
|
||||
<ul>
|
||||
<li>fields: (aka columns) is a FieldList listing all the fields on this
|
||||
Dataset (this can be set explicitly, or, will be set by Dataset.fetch() or Dataset.query()</li>
|
||||
<li>currentDocuments: a DocumentList containing the Documents we have
|
||||
currently loaded for viewing (you update currentDocuments by calling query)</li>
|
||||
<li>docCount: total number of documents in this dataset</li>
|
||||
</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>
|
||||
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">'Dataset'</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 {FieldList} fields: (aka columns) is a <code>FieldList</code> listing all the
|
||||
fields on this Dataset (this can be set explicitly, or, will be set by
|
||||
Dataset.fetch() or Dataset.query()</p>
|
||||
|
||||
<p>@property {DocumentList} currentDocuments: a <code>DocumentList</code> containing the
|
||||
Documents we have currently loaded for viewing (updated by calling query
|
||||
method)</p>
|
||||
|
||||
<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">'Dataset'</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">¶</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">'query'</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">&&</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="p">.</span><span class="nx">bind</span><span class="p">(</span><span class="s1">'change'</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">'facet:add'</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">¶</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">¶</a> </div> <h3>query</h3>
|
||||
|
||||
<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="k">return</span> <span class="nx">data</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">¶</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">¶</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>
|
||||
<span class="nx">__type__</span><span class="o">:</span> <span class="s1">'Document'</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">¶</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">¶</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">'DocumentList'</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="p">});</span></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</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">¶</a> </div> <h2><a id="field">A Field (aka Column) on a Dataset</a></h2>
|
||||
|
||||
<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">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">'String'</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">¶</a> </div> <p>In addition to normal backbone initialization via a Hash you can also
|
||||
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">¶</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">'0'</span> <span class="k">in</span> <span class="nx">data</span><span class="p">)</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">¶</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">'0'</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">'Looks like you did not pass a proper hash with id to Field constructor'</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">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">¶</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">¶</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="k">return</span> <span class="p">{</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">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">¶</a> </div> <p>http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html
|
||||
, filter: {}
|
||||
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="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">¶</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: {}</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">¶</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>
|
||||
<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">¶</a> </div> <p>Set (update or add) a terms filter
|
||||
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>
|
||||
<span class="p">},</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> <h4>addTermFilter</h4>
|
||||
|
||||
<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">'filters'</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">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">¶</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">'change'</span><span class="p">);</span>
|
||||
<span class="p">},</span>
|
||||
<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">'facets'</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">¶</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">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">¶</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">'change'</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">¶</a> </div> <h3>addFacet</h3>
|
||||
|
||||
<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">'facets'</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">¶</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="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">trigger</span><span class="p">(</span><span class="s1">'facet:add'</span><span class="p">,</span> <span class="k">this</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">¶</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">¶</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="k">return</span> <span class="p">{</span>
|
||||
<span class="nx">_type</span><span class="o">:</span> <span class="s1">'terms'</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">¶</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">¶</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">¶</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">¶</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">'terms'</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></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</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">¶</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="p">});</span></pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</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">¶</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>
|
||||
|
||||
|
||||
43
index.html
43
index.html
@ -84,11 +84,11 @@
|
||||
<h1>
|
||||
Recline Data Explorer and Library<br />
|
||||
<small>
|
||||
A. Powerful data explorer using only javascript and html
|
||||
A. Powerful data explorer built in pure javascript and html
|
||||
<br />
|
||||
B. Suite of data components - grid, graphing and data connectors
|
||||
<br />
|
||||
— All built on <a href="http://backbonejs.org/">Backbone</a></small>
|
||||
— All built with <a href="http://backbonejs.org/">Backbone</a></small>
|
||||
</h1>
|
||||
</div>
|
||||
|
||||
@ -207,20 +207,34 @@ var dataset = recline.Model.Dataset({
|
||||
<p>Recline has a simple structure layered on top of the basic Model/View
|
||||
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>
|
||||
<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
|
||||
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
|
||||
a document DB like CouchDB or MongoDB).</li>
|
||||
</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
|
||||
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
|
||||
Datasets and individuals Documents as well as for bulk loading via a query API
|
||||
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
|
||||
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>
|
||||
<ul>
|
||||
<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>FlotGraph: a simple graphing view using <a
|
||||
href="http://code.google.com/p/flot/">Flot</a>.</li>
|
||||
<li>Map: a map view using Leaflet.</li>
|
||||
</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>
|
||||
<h4>Models and Views (Widgets)</h4>
|
||||
<ul>
|
||||
<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-grid.html">DataGrid View</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/memory.html">Backend: Memory (local data)</a></li>
|
||||
<li><a href="docs/backend/elasticsearch.html">Backend: ElasticSearch</a></li>
|
||||
|
||||
144
src/model.js
144
src/model.js
@ -4,17 +4,33 @@ this.recline.Model = this.recline.Model || {};
|
||||
|
||||
(function($, my) {
|
||||
|
||||
// ## A Dataset model
|
||||
// ## <a id="dataset">A Dataset model</a>
|
||||
//
|
||||
// A model has the following (non-Backbone) attributes:
|
||||
//
|
||||
// * fields: (aka columns) is a FieldList listing all the fields on this
|
||||
// Dataset (this can be set explicitly, or, will be set by Dataset.fetch() or Dataset.query()
|
||||
// * currentDocuments: a DocumentList containing the Documents we have
|
||||
// currently loaded for viewing (you update currentDocuments by calling query)
|
||||
// * docCount: total number of documents in this dataset
|
||||
// @property {FieldList} fields: (aka columns) is a `FieldList` listing all the
|
||||
// fields on this Dataset (this can be set explicitly, or, will be set by
|
||||
// Dataset.fetch() or Dataset.query()
|
||||
//
|
||||
// @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({
|
||||
__type__: 'Dataset',
|
||||
// ### initialize
|
||||
//
|
||||
// Sets up instance properties (see above)
|
||||
initialize: function(model, backend) {
|
||||
_.bindAll(this, 'query');
|
||||
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
|
||||
my.Document = Backbone.Model.extend({
|
||||
@ -99,7 +115,7 @@ my.DocumentList = Backbone.Collection.extend({
|
||||
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:
|
||||
//
|
||||
@ -112,10 +128,8 @@ my.Field = Backbone.Model.extend({
|
||||
label: null,
|
||||
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) {
|
||||
// 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) {
|
||||
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
|
||||
});
|
||||
|
||||
// ## 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({
|
||||
defaults: function() {
|
||||
return {
|
||||
size: 100
|
||||
, from: 0
|
||||
, facets: {}
|
||||
// http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html
|
||||
// <http://www.elasticsearch.org/guide/reference/query-dsl/and-filter.html>
|
||||
// , filter: {}
|
||||
// list of simple filters which will be add to 'add' filter of filter
|
||||
, filters: []
|
||||
}
|
||||
},
|
||||
// Set (update or add) a terms filter
|
||||
// http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html
|
||||
// #### addTermFilter
|
||||
//
|
||||
// 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) {
|
||||
var filters = this.get('filters');
|
||||
var filter = { term: {} };
|
||||
@ -153,6 +217,11 @@ my.Query = Backbone.Model.extend({
|
||||
// change does not seem to be triggered ...
|
||||
this.trigger('change');
|
||||
},
|
||||
// ### addFacet
|
||||
//
|
||||
// Add a Facet to this query
|
||||
//
|
||||
// See <http://www.elasticsearch.org/guide/reference/api/search/facets/>
|
||||
addFacet: function(fieldId) {
|
||||
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)
|
||||
@ -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({
|
||||
defaults: function() {
|
||||
return {
|
||||
_type: 'terms',
|
||||
// total number of tokens in the facet
|
||||
total: 0,
|
||||
// number of facet values not included in the returned facets
|
||||
other: 0,
|
||||
// number of documents which have no value for the field
|
||||
missing: 0,
|
||||
// term object ({term: , count: ...})
|
||||
terms: []
|
||||
}
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user