Fetch Icon

Fetch

Installation

Simply copy the Fetch folder into site/addons/. That's it!

Parameters

Name Type Default Description
deep Boolean true Fetch nested data recursively, works for arrays as well as related content.
nested Boolean false Add child pages to the page instead of the root of the response.
depth Integer null Depth of nested page to fetch. Only works nested. null means unlimited.
filter String null Filter published and unpublished data.
taxonomy String null Filter data by a single or multiple taxonomies.
locale String null Fetch data for a specific locale.
limit Integer 0 Limit the total results returned.
offset Integer 0 The number of items the results should by offset by.
query String null The query to search for.
index String null The search index to use during Search (requires a Collection Index).
debug Boolean false Dump all data on the page (useful to check what data is available).
api_key String null When Enable API Key is activated in the settings, make sure to add the api_key to every request.*

*Both GET and POST requests are supported; include the api_key in the url query string or in the body of the request. It is recommended to use POST requests over HTTPS to ensure your api_key remains secure.

Settings

The settings page is accessed via CP > Configure > Addons > Fetch.

Name Type Description
Deep Boolean Site default to 'go deep' when fetching data.
Nested Boolean Site default to 'nested' parameter when fetching data.
Enable API Key Boolean Whether to use the API Key for authentication.
API Key String Generate an API Key. Only used when Enable API Key is set to true.
IP Whitelist Array List of whitelisted IP addresses. Leave blank to allow any.
Domain Whitelist Array List of whitelisted Domains. Leave blank to allow any.

Please note that these Authentication settings are potentially not completely secure, it’s meant as a simple layer to stop ‘general’ access to the API endpoints. If you have any ideas on improvements, please open a PR!

Note

By default, Fetch will 'go deep' and find all nested data recursively within the dataset. This means that any related content (saved as an ID) will also be fetched and returned.

This behavior can be disabled via Fetch's settings (CP > Configure > Addons > Fetch). You can also enable/disable deep fetching per request via a query string/tag option (see below for further details). When disabled, only a shallow fetch will be performed; related data will simply be returned as its ID.

Usage

Types

  • Collection: The Collection's slug.
  • Entry: An Entry's ID or collection + slug.
  • Page: A single Page's URI.
  • Pages: All Pages or a comma-separated list of Page URIs.
  • Global: A single Global slug.
  • Globals: All Globals or a comma-separated list of Global slugs.
  • Taxonomy: A single Taxomony's ID.
  • Taxonomies: All Taxonomies.
  • User: A single User's username or email.
  • Users: All Users.
  • Formset: A single Formset slug.
  • Search: A Search query.

Parameter Examples

Name Example
deep URL: http://domain.com/!/Fetch/collection/blog?deep=true
Tag: {{ fetch:blog deep="true" }}
nested URL: http://domain.com/!/Fetch/collection/blog?nested=true
Tag: {{ fetch:blog nested="true" }}
filter URL: http://domain.com/!/Fetch/collection/blog?filter=published
Tag: {{ fetch:blog filter="published" }}
taxonomy URL: http://domain.com/!/Fetch/collection/blog?taxonomy=tags/news
Tag: {{ fetch:blog taxonomy="tags/news" }}
locale URL: http://domain.com/!/Fetch/collection/blog?locale=nl
Tag: {{ fetch:blog locale="nl" }}
limit URL: http://domain.com/!/Fetch/collection/blog?limit=5
Tag: {{ fetch:blog limit="5" }}
offset URL: http://domain.com/!/Fetch/collection/blog?offset=3
Tag: {{ fetch:blog offset="3" }}
query URL: http://domain.com/!/Fetch/collection/search?query=foo
Tag: {{ fetch:blog query="foo" }}
index URL: http://domain.com/!/Fetch/collection/blog?query=foo&index=collections/news
Tag: {{ fetch:blog query="foo" index="collections/news" }}
debug URL: http://domain.com/!/Fetch/collection/blog?debug=true
Tag: {{ fetch:blog debug="true" }}
api_key URL: http://domain.com/!/Fetch/collection/blog?api_key=[YOUR_KEY_HERE]
Tag: N/A

Collection Examples

JS

axios.get('/!/Fetch/collection/blog').then(...);

Tag

Fetch all blog entries

{{ fetch collection="blog" }}

Shorthand

{{ fetch:blog }}

Example passing data into a Vue component

<my-component :data='{{ fetch:blog }}'></my-component>

Entry Examples

Entries can either be fetched by their ID or by their collection + slug.

JS

axios.get('/!/Fetch/entry/a1880157-2b7e-4d7c-ac8f-01790d821312').then(...);
axios.get('/!/Fetch/entry/blog/my-awesome-blog-post').then(...);

Tag

Fetch a single entry

{{ fetch entry="a1880157-2b7e-4d7c-ac8f-01790d821312" }}
{{ fetch entry="blog/my-awesome-blog-post" }}

Example passing data into a Vue component

<my-component :data='{{ fetch entry="a1880157-2b7e-4d7c-ac8f-01790d821312" }}'></my-component>
<my-component :data='{{ fetch entry="blog/my-awesome-blog-post" }}'></my-component>

Page(s) Examples

JS

Fetch a single page

axios.get('/!/Fetch/page/about').then(...);

Fetch all pages

axios.get('/!/Fetch/pages').then(...);

Fetch multiple pages

var pages = '/, /about, /contact-us';
 
axios.get('/!/Fetch/pages/?pages='+encodeURIComponent(pages)).then(...);

Fetch pages nested

axios.get('/!/Fetch/pages/?nested=true&depth=5').then(...);

Tag

Fetch a single page

{{ fetch page="/about" }}

Fetch all pages

{{ fetch:pages }}

Fetch multiple pages

{{ fetch pages="/,/about,/contact-us" }}

Example passing data into a Vue component

<my-component :data='{{ fetch:pages }}'></my-component>

Global(s) Examples

JS

Fetch a single global

axios.get('/!/Fetch/global/opening_hours').then(...);

Fetch all globals

axios.get('/!/Fetch/globals').then(...);

Fetch multiple globals

var globals = 'general, contact_info, opening_hours';
 
axios.get('/!/Fetch/globals/?globals='+encodeURIComponent(globals)).then(...);

Tag

Fetch a single global

{{ fetch global="opening_hours" }}

Fetch all globals

{{ fetch:globals }}

Fetch multiple globals

{{ fetch globals="general, contact_info, opening_hours" }}

Example passing data into a Vue component

<my-component :data='{{ fetch:globals }}'></my-component>

Taxomomies Examples

JS

Fetch a single taxonomy

axios.get('/!/Fetch/taxonomy/categories').then(...);

Fetch all taxonomies

axios.get('/!/Fetch/taxonomies').then(...);

Tag

Fetch a single taxonomy

{{ fetch taxonomy="categories" }}

Fetch all taxonomies

{{ fetch:taxonomies }}

User(s) Examples

JS

Fetch a single user

axios.get('/!/Fetch/user/admin').then(...);
axios.get('/!/Fetch/user/[email protected]').then(...);

Fetch all users

axios.get('/!/Fetch/users').then(...);

Tag

Fetch a single user

{{ fetch user="admin" }}
{{ fetch user="[email protected]" }}

Fetch all users

{{ fetch:users }}

Formset Examples

JS

Fetch formset data

axios.get('/!/Fetch/formset/contact').then(...);

Perform Statamic Form submission using ajax

const form = document.querySelector('#contact-form');
 
form.addEventListener('submit', e => {
  e.preventDefault();
 
  // First, fetch the formset's data
  axios.get('/!/Fetch/formset/contact').then(resp => {
    // Create a new FormData object from the form element
    const formData = new FormData(form);
 
    // Set the required encrypted params field
    // for Statamic to handle the submission
    formData.set('_params', resp.data.data.params);
 
    // Once `_params` is set, we can perform the POST request
    // Note the additional header being sent as part of the request
    axios.post('/!/Form/create', formData, {
      headers: { 'X-Requested-With': 'XMLHttpRequest' }
    }).then(response => {
      // Success!
      console.log(response.data);
    }).catch(error => {
      // Errors...
      console.log(error.response.data);
    });
  });
});

Search Examples

JS

Fetch search results

axios.get('/!/Fetch/search?query=[search_term]').then(...);

Caching

Caching can be enabled from the settings page. When enabled all endpoints will be remembered for as long as the cache TTL is set, or for the default 24 hours. The following 3 headers are sent when caching is enabled:

Header Value
Statamic-Fetch-Cache-Enabled Boolean telling whether or not caching is enabled
Statamic-Fetch-Cache-Created-At Timestamp of the moment the cache was created
Statamic-Fetch-Cache-TTL Caching TTL in minutes

To manually clear the cache make a GET request to /!/Fetch/clear-cache