UNPKG

prismic.io

Version:

JavaScript development kit for prismic.io

3,095 lines (779 loc) 36.3 kB
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>JSDoc: Class: Api</title> <script src="scripts/prettify/prettify.js"> </script> <script src="scripts/prettify/lang-css.js"> </script> <!--[if lt IE 9]> <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> <![endif]--> <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> </head> <body> <div id="main"> <h1 class="page-title">Class: Api</h1> <section> <header> <h2>Api</h2> </header> <article> <div class="container-overview"> <h4 class="name" id="Api"><span class="type-signature"></span>new Api<span class="signature">(url)</span><span class="type-signature"> &rarr; {<a href="Api.html">Api</a>}</span></h4> <div class="description"> The kit's main entry point; initialize your API like this: Prismic.api(url, {accessToken: "XXX"}) </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>url</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">The mandatory URL of the prismic.io API endpoint (like: https://lesbonneschoses.prismic.io/api)</td> </tr> <tr> <td class="name"><code>options.callback</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">Optional callback function that is called after the API was retrieved, which will be called with two parameters: a potential error object and the API object</td> </tr> <tr> <td class="name"><code>options.accessToken</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">The accessToken, necessary if the API is set as private</td> </tr> <tr> <td class="name"><code>options.req</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">The NodeJS request (only use in a NodeJS context)</td> </tr> <tr> <td class="name"><code>options.requestHandler</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">Environment specific HTTP request handling function</td> </tr> <tr> <td class="name"><code>options.apiCache</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">A cache object with get/set functions for caching API responses</td> </tr> <tr> <td class="name"><code>options.apiDataTTL</code></td> <td class="type"> <span class="param-type">int</span> </td> <td class="description last">How long (in seconds) to cache data used by the client to make calls (e.g. refs). Defaults to 5 seconds</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="prismic.js.html">prismic.js</a>, <a href="prismic.js.html#line28">line 28</a> </li></ul></dd> </dl> <h5>Returns:</h5> <div class="param-desc"> - The Api object that can be manipulated </div> <dl> <dt> Type </dt> <dd> <span class="param-type"><a href="Api.html">Api</a></span> </dd> </dl> </div> <h3 class="subsection-title">Methods</h3> <h4 class="name" id="currentExperiment"><span class="type-signature"></span>currentExperiment<span class="signature">()</span><span class="type-signature"> &rarr; {Experiment}</span></h4> <div class="description"> The current experiment, or null </div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line270">line 270</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">Experiment</span> </dd> </dl> <h4 class="name" id="form"><span class="type-signature"></span>form<span class="signature">(formId)</span><span class="type-signature"> &rarr; {<a href="SearchForm.html">SearchForm</a>}</span></h4> <div class="description"> Returns a useable form from its id, as described in the RESTful description of the API. For instance: api.form("everything") works on every repository (as "everything" exists by default) You can then chain the calls: api.form("everything").query('[[:d = at(document.id, "UkL0gMuvzYUANCpf")]]').ref(ref).submit() </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>formId</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">The id of a form, like "everything", or "products"</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line230">line 230</a> </li></ul></dd> </dl> <h5>Returns:</h5> <div class="param-desc"> - the SearchForm that can be used. </div> <dl> <dt> Type </dt> <dd> <span class="param-type"><a href="SearchForm.html">SearchForm</a></span> </dd> </dl> <h4 class="name" id="forms"><span class="type-signature"></span>forms<span class="signature">(formId)</span><span class="type-signature"> &rarr; {<a href="SearchForm.html">SearchForm</a>}</span></h4> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>formId</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">The id of a form, like "everything", or "products"</td> </tr> </tbody> </table> <dl class="details"> <dt class="important tag-deprecated">Deprecated:</dt><dd><ul class="dummy"><li>use form() now</li></ul></dd> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line218">line 218</a> </li></ul></dd> </dl> <h5>Returns:</h5> <div class="param-desc"> - the SearchForm that can be used. </div> <dl> <dt> Type </dt> <dd> <span class="param-type"><a href="SearchForm.html">SearchForm</a></span> </dd> </dl> <h4 class="name" id="get"><span class="type-signature"></span>get<span class="signature">(callback)</span><span class="type-signature"> &rarr; {Promise}</span></h4> <div class="description"> Fetches data used to construct the api client, from cache if it's present, otherwise from calling the prismic api endpoint (which is then cached). </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>callback</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">Callback to receive the data. Optional, you can use the promise result.</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line69">line 69</a> </li></ul></dd> </dl> <h5>Returns:</h5> <div class="param-desc"> Promise holding the data or error </div> <dl> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> <h4 class="name" id="getBookmark"><span class="type-signature"></span>getBookmark<span class="signature">(bookmark, additional, callback(err,)</span><span class="type-signature"> &rarr; {Promise}</span></h4> <div class="description"> Retrieve the document with the given bookmark </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>bookmark</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">name</td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">response)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line409">line 409</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> <h4 class="name" id="getByID"><span class="type-signature"></span>getByID<span class="signature">(id, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Retrieve the document with the given id </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>id</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last"></td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">doc)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line361">line 361</a> </li></ul></dd> </dl> <h4 class="name" id="getByIDs"><span class="type-signature"></span>getByIDs<span class="signature">(ids, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Retrieve multiple documents from an array of id </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>ids</code></td> <td class="type"> <span class="param-type">array</span> </td> <td class="description last"></td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">response)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line373">line 373</a> </li></ul></dd> </dl> <h4 class="name" id="getByUID"><span class="type-signature"></span>getByUID<span class="signature">(type, uid, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Retrieve the document with the given uid </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>type</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">the custom type of the document</td> </tr> <tr> <td class="name"><code>uid</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last"></td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">response)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line386">line 386</a> </li></ul></dd> </dl> <h4 class="name" id="getSingle"><span class="type-signature"></span>getSingle<span class="signature">(type, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Retrieve the singleton document with the given type </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>type</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">the custom type of the document</td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">response)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line398">line 398</a> </li></ul></dd> </dl> <h4 class="name" id="master"><span class="type-signature"></span>master<span class="signature">()</span><span class="type-signature"> &rarr; {string}</span></h4> <div class="description"> The ID of the master ref on this prismic.io API. Do not use like this: searchForm.ref(api.master()). Instead, set your ref once in a variable, and call it when you need it; this will allow to change the ref you're viewing easily for your entire page. </div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line245">line 245</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">string</span> </dd> </dl> <h4 class="name" id="previewSession"><span class="type-signature"></span>previewSession<span class="signature">(token, linkResolver, defaultUrl, callback)</span><span class="type-signature"> &rarr; {Promise}</span></h4> <div class="description"> Return the URL to display a given preview </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>token</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">as received from Prismic server to identify the content to preview</td> </tr> <tr> <td class="name"><code>linkResolver</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">the link resolver to build URL for your site</td> </tr> <tr> <td class="name"><code>defaultUrl</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">the URL to default to return if the preview doesn't correspond to a document (usually the home page of your site)</td> </tr> <tr> <td class="name"><code>callback</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">to get the resulting URL (optional, you can get it from the Promise result)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line433">line 433</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> <h4 class="name" id="query"><span class="type-signature"></span>query<span class="signature">(the, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Query the repository </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>the</code></td> <td class="type"> <span class="param-type">string</span> | <span class="param-type">array</span> | <span class="param-type">Predicate</span> </td> <td class="description last">query itself</td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters. In NodeJS, pass the request as 'req'.</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">response)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line298">line 298</a> </li></ul></dd> </dl> <h4 class="name" id="queryFirst"><span class="type-signature"></span>queryFirst<span class="signature">(the, additional, callback(err,)</span><span class="type-signature"></span></h4> <div class="description"> Retrieve the document returned by the given query </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>the</code></td> <td class="type"> <span class="param-type">string</span> | <span class="param-type">array</span> | <span class="param-type">Predicate</span> </td> <td class="description last">query</td> </tr> <tr> <td class="name"><code>additional</code></td> <td class="type"> <span class="param-type">object</span> </td> <td class="description last">parameters. In NodeJS, pass the request as 'req'.</td> </tr> <tr> <td class="name"><code>callback(err,</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">doc)</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line334">line 334</a> </li></ul></dd> </dl> <h4 class="name" id="quickRoutes"><span class="type-signature"></span>quickRoutes<span class="signature">()</span><span class="type-signature"></span></h4> <div class="description"> Retrieve quick routes definitions </div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line281">line 281</a> </li></ul></dd> </dl> <h4 class="name" id="ref"><span class="type-signature"></span>ref<span class="signature">(label)</span><span class="type-signature"> &rarr; {string}</span></h4> <div class="description"> Returns the ref ID for a given ref's label. Do not use like this: searchForm.ref(api.ref("Future release label")). Instead, set your ref once in a variable, and call it when you need it; this will allow to change the ref you're viewing easily for your entire page. </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>label</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last">the ref's label</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line257">line 257</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">string</span> </dd> </dl> <h4 class="name" id="refresh"><span class="type-signature"></span>refresh<span class="signature">(callback)</span><span class="type-signature"> &rarr; {Promise}</span></h4> <div class="description"> Cleans api data from the cache and fetches an up to date copy. </div> <h5>Parameters:</h5> <table class="params"> <thead> <tr> <th>Name</th> <th>Type</th> <th class="last">Description</th> </tr> </thead> <tbody> <tr> <td class="name"><code>callback</code></td> <td class="type"> <span class="param-type">function</span> </td> <td class="description last">Optional callback function that is called after the data has been refreshed</td> </tr> </tbody> </table> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line108">line 108</a> </li></ul></dd> </dl> <h5>Returns:</h5> <dl> <dt> Type </dt> <dd> <span class="param-type">Promise</span> </dd> </dl> <h4 class="name" id="request"><span class="type-signature"></span>request<span class="signature">()</span><span class="type-signature"></span></h4> <div class="description"> Fetch a URL corresponding to a query, and parse the response as a Response object </div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line479">line 479</a> </li></ul></dd> </dl> <h4 class="name" id="response"><span class="type-signature"></span>response<span class="signature">()</span><span class="type-signature"></span></h4> <div class="description"> JSON documents to Response object </div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="api.js.html">api.js</a>, <a href="api.js.html#line521">line 521</a> </li></ul></dd> </dl> </article> </section> </div> <nav> <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Api.html">Api</a></li><li><a href="Doc.html">Doc</a></li><li><a href="Experiments.html">Experiments</a></li><li><a href="Fragments_Color.html">Fragments:Color</a></li><li><a href="Fragments_CompositeSlice.html">Fragments:CompositeSlice</a></li><li><a href="Fragments_Date.html">Fragments:Date</a></li><li><a href="Fragments_DocumentLink.html">Fragments:DocumentLink</a></li><li><a href="Fragments_Embed.html">Fragments:Embed</a></li><li><a href="Fragments_FileLink.html">Fragments:FileLink</a></li><li><a href="Fragments_GeoPoint.html">Fragments:GeoPoint</a></li><li><a href="Fragments_Group.html">Fragments:Group</a></li><li><a href="Fragments_ImageEl.html">Fragments:ImageEl</a></li><li><a href="Fragments_ImageLink.html">Fragments:ImageLink</a></li><li><a href="Fragments_ImageView.html">Fragments:ImageView</a></li><li><a href="Fragments_Num.html">Fragments:Num</a></li><li><a href="Fragments_Select.html">Fragments:Select</a></li><li><a href="Fragments_Separator.html">Fragments:Separator</a></li><li><a href="Fragments_SimpleSlice.html">Fragments:SimpleSlice</a></li><li><a href="Fragments_SliceZone.html">Fragments:SliceZone</a></li><li><a href="Fragments_StructuredText.html">Fragments:StructuredText</a></li><li><a href="Fragments_Text.html">Fragments:Text</a></li><li><a href="Fragments_Timestamp.html">Fragments:Timestamp</a></li><li><a href="Fragments_WebLink.html">Fragments:WebLink</a></li><li><a href="Ref.html">Ref</a></li><li><a href="Response.html">Response</a></li><li><a href="SearchForm.html">SearchForm</a></li><li><a href="WithFragments.html">WithFragments</a></li></ul><h3>Namespaces</h3><ul><li><a href="Predicates.html">Predicates</a></li></ul><h3>Global</h3><ul><li><a href="global.html#ApiCache">ApiCache</a></li><li><a href="global.html#data">data</a></li><li><a href="global.html#fragments">fragments</a></li><li><a href="global.html#insertSpans">insertSpans</a></li><li><a href="global.html#LRUCache">LRUCache</a></li><li><a href="global.html#parseDoc">parseDoc</a></li></ul> </nav> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.3</a> on Fri Apr 28 2017 17:29:54 GMT+0200 (CEST) </footer> <script> prettyPrint(); </script> <script src="scripts/linenumber.js"> </script> </body> </html>