README

Demetra

A utility library for WordPress custom API interaction, using the adora-theme endpoint.

Installation

# Install package
npm install @adoratorio/demetra

Usage

Since this package has a pkg.module field, it’s highly recommended importing it as an ES6 module with some bundlers like Webpack or Rollup:

import Demetra from '@adoratorio/demetra';
const demetra = new Demetra(options: Object);

Available options

Demetra accepts in the constructor an option object with the following possible props.

parameter	type	default	description
endpoint	string	`''`	The URL for the custom theme API endpoint
uploadEndpoint	string	`{$endpoint}/upload.php`	The URL for the custom theme API endpoint for uploading files
site	string	`'default'`	In the Wordpress multi-site installation the site id to fetch data from
lang	string	`'en'`	The language in which data is retrieved
debug	boolean	`false`	If You need extra log in browser console about what Demetra is doing
version	number	`2`	The API version used (V2 is now available!)
cacheMaxAge	number	`3600000`	Maximum cache age in ms. If the request will use the local cache (LRU Cache)
proxy	AxiosProxyConfig	`false`	An http/https proxy to use for requests described as axios proxy config object

APIs

fetchPage()

Use this method to get pages details, the method accept the following params

Demetra.fetchPage(id : string | number, options : object);

Accepted parameters

parameter	required	description
id	`true`	The id or the slug of the page to fetch
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
type	string	`'page'`	The custom post type id or 'page' if you need an actual page not a post.
siblings	object	`{ fields: [], prev: false, next: false, loop: false }`	If you also need information about adjacent siblings
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved
i18n	boolean	`true`	If you need to get the i18n object in the response containing all information about the other languages available for this page

Siblings can take an object with the following keys

parameter	type	default	description
fields	Array	`[]`	An array of fields you need for siblings, identified by their frontId
prev	boolean	`false`	If you need the prev sibling
next	boolean	`false`	If you need the next sibling
loop	Boolean	`false`	If the requested page is the last or the first, treat the siblings as a circle, returning the first one or the previous one depending on the position

The returned object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "id": 1,
    "title": "Homepage",
    "path": "/homepage/",
    "fullPath": "/en/homepage/",
    "slug": "homepage",
    "structure": [
      {
        "frontId": "Component Name"
        // ... Other item data
      }
        // ... Other item components
    ],
    "lang": "en",
    "type": "page",
    "i18n": {
      "it": {
        "id": 111,
        "slug": "homepage",
        "path": "/homepage",
        "fullPath": "/it/homepage"
      }
    },
    "siblings": {
      "next": {
        "id": 222,
          "title": "Siblings Title",
          "path": "/sibligns-path/",
          "fullPath": "/en/sibligns-path/",
          "structure": [
            false
          ],
          "lang": null,
          "type": "page",
          "i18n": null,
          "siblings": null,
          "date": null
        },
        "prev": null
    },
    "date": null // Filled only wen the requested type is a post
  }
}

fetchArchive()

Retrieve the information and content for an archive (a collection of items)

Demetra.fetchArchive(id: string, options : object);

Accepted parameters

parameter	required	description
id	`true`	The slug of the archive to fetch
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
fields	string	`[]`	Array of frontId used to identify the fields for the items
pagination	object	`{ start: 0, count: -1 }`	A pagination object used to define if you need pagination
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved
i18n	boolean	`true`	If you need to get in response the i18n object containing all the information about the other available languages for this page

Pagination can take an object with the following keys

parameter	type	default	description
start	number	`0`
count	number	`-1`

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "items": [
      {
        "id": 111,
        "title": "First Article",
        "path": "/first-article/",
        "fullPath": "/en/first-article/",
        "structure": [
          {
            "frontId": "Component Name",
            // ... Other item data
          }
          // ... Other item components
        ],
        "lang": "en",
        "type": "press",
        "i18n": null,
        "siblings": null,
        "date": null
      }
    ],
    "pagination": {
      "start": 0,
      "count": -1,
      "more": true,
      "total": 7
    }
  }
}

fetchExtra()

Fetch data considered to be extra in the Wordpress setup

Demetra.fetchExtra(id: string, options? : object);

Accepted parameters

parameter	required	description
id	`true`	The slug of the extra to fetch
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved
i18n	boolean	`true`	If you need to get in response the i18n object containing all the information about the other available languages for this page

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "privacy": "",
    "cookies": "",
    "email": ""
    // ... Extra data with key : value here
  }
}

fetchMenu()

Fetch content for a menu

Demetra.fetchMenu(id: string, options : object);

Accepted params

parameter	required	description
id	`true`	The slug of the menu to fetch
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved
i18n	boolean	`true`	If you need to get in response the i18n object containing all the information about the other available languages for this page

The returned object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "items": [
      {
        "caption": "Home",
        "link": {
          "title": "Home",
          "url": "https://xyz/about/",
          "target": ""
        }
      }
      // ... Other menu item
    ]
  }
}

fetchTaxonomy()

Fetch a single taxonomy with all terms

Demetra.fetchTaxonomy(id: string | [string], options? : object);

Accepted parameters

parameter	required	description
id	`true`	The slug or an array of slug of the taxonomy to fetch
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved
i18n	boolean	`true`	If you need to get in response the i18n object containing all the information about the other available languages for this page

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "items": [
      {
        "term_id": 1,
        "name": "TERM NAME",
        "slug": "termname",
        "term_group": 0,
        "term_taxonomy_id": 1,
        "taxonomy": "taxonomy id",
        "description": "",
        "parent": 0,
        "count": 0,
        "filter": "raw"
      }
      // ... Other terms following
    ]
  }  
}

fetchLanguages()

Use this method to get locales details such as:

code
iso
default_locale
name
translated_name

the method accept the following params

Demetra.fetchLanguages(site : string, options : object);

Accepted parameters

parameter	required	description
site	`true`	the id of the reference site
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)
lang	string	`Demetra.lang`	The language in which data is retrieved

The returned object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded",
    "cache": false
  },
  "data": {
    "locales": [
      {
        "code": "en",
        "iso": "en",
        "default_locale": "en_US",
        "name": "English",
        "translated_name": "Inglese",
        "hidden": false
      },
      {
        "code": "it",
        "iso": "it",
        "default_locale": "it_IT",
        "name": "Italiano",
        "translated_name": "Italiano",
        "hidden": false
      }
    ],
    "defaultLocale": "en"
  }
}

fetchSitemap()

Use this method to get a list with all the project route.

Demetra.fetchLanguages(site : string, options : object);

Accepted parameters

parameter	required	description
site	`true`	the id of the reference site
options	`false`	The configuration object

Options can take an object with the following keys

parameter	type	default	description
wpCache	boolean	`true`	If the endpoint will use the API cache
localCache	boolean	`false`	If you want to save the data in a local cache (LruCache)

The returned object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded",
    "cache": false
  },
  "data": [
    "/explore/",
    "/about/",
    "/dining/bar-aperitifs/",
    "/dining/breakfast/",
    "/dining/restaurants/second-restaurant/",
    "/dining/restaurants/first-restaurant/",
    "/dining/",
    "/suites/second-suite/",
    "/suites/first-suite/",
    "/suites/",
    "/",
    "/it/explore/",
    "/it/about/",
    "/it/pasti/bar-aperitifs/",
    "/it/pasti/breakfast/",
    "/it/pasti/restaurants/second-restaurant/",
    "/it/pasti/restaurants/first-restaurant/",
    "/it/pasti/",
    "/camere/second-suite/",
    "/camere/first-suite/",
    "/camere/",
    "/it/home"
  ]
}

subscribe()

Use configured MailChimp settings in order to subscribe an email to a list

Demetra.subscribe(email : string);

Accepted parameters

parameter	required	description
email	`true`	The e-mail to subscribe to the newsletter

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "response": 1, // The request result 0 in case of error
    "message": "SUCCESS!", // The message associated with the result
    "mailchimp": "", // Contains mailchimp messages and debug informations
  },  
}

send()

Use a preconfigured form on WP to send an email

Demetra.send(id : number, recipients : string, data : object, files : array);

Accepted parameters

parameter	required	description
id	`true`	the form ID
recipients	`true`	should be a single email, or a comma separated list of email addresses
data	`true`	`data` should be a valid JSON parsable string, containing only one level key/value pairs, one for each field defined in form options on WP side
files	`false`	should be a list of files handler to upload as attachments to the reques

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Data loaded!",
    "cache": false
  },
  "data": {
    "saved": 1, // How many requests have been saved in the db
    "sended": true // If the email has been sended to the recipients
  }
}

upload()

Upload one or multiple files to the Wordpress media library

Demetra.upload(files : file | array<file>);

The returning object will be in the following form

{
  "status": {
    "code": 200,
    "message": "Upload successful",
  },
  "data": [
    {
      "upload_id": 1, // The post id of the uploaded file
      "url": "https://..." // The url of the uploaded file
    }
  ]  
}

fetchQueue()

Fetch all the DemetraRequest in the queue in three different ways: all together, simultaneously or one at time.

fetchQueue(sendModes: string)

Accepted parameters

parameter	type	required	default	description
id	`string`	`false`	`Demetra.SEND_MODES.ONCE`	A string indicating the send mode you wish to use, it can be 'once', 'simultaneously' or 'await'. Also static enumerators are exposed to help: • `Demetra.MODE.ONCE` • `Demetra.MODE.SIMULTANEOUSLY` • `Demetra.MODE.AWAIT`.

Modes:

Once: create a request package and send thath package.
Simultaneously: simultaneously sends all requests independently of each other
Await: Wait a response before send the next request

Queue

Internally Demetra uses a request queue which is used together with the fetchQueue() function

add()

Adds a request to the queue.

Demetra.add(request : DemetraRequestPage | DemetraRequestArchive | DemetraRequestExtra | DemetraRequestMenu | DemetraRequestTaxonomy)

Clear()

Clear the queue.

Demetra.clear()

DemetraRequests

In V2 you can directly create a DemetraRequest thath can be directly sent via fetchQueue() . You can instantiate one or more of the following class:

DemetraRequestArchive(id : string | number, options : object, lang : string, site : string, version : number)
DemetraRequestExtra(id : string | number, options : object, lang : string, site : string, version : number)
DemetraRequestMenu(id : string | number, options : object, lang : string, site : string, version : number)
DemetraRequestPage(id : string | number, options : object, lang : string, site : string, version : number)
DemetraRequestTaxonomy(id : string | number, options : object, lang : string, site : string, version : number)
DemetraRequestLanguages(site : string, options : object, lang : string, version : number)
DemetraRequestSitemap(site : string, options : object, version : number)

NB: The request doesn't inherit the global parameters of Demetra. Tho you can pass the lang, site and version params directly in the options

Accepted parameters

parameter	type	required	default	description
id	string \| number	`true`		The slug or id of the archive \| extra \| page \| menu \| taxonomy to fetch
options	object	`false`		The configuration object (look the fetch API above to understand how to fill the object for each request)
lang	string	`false`	`'en'`	The language in which data is retrieved
site	string	`false`	`'default'`	In multi-site installation Wordpress the site id to fetch data from
version	number	`false`	`2`	The API version used

Usage no npm install needed!

README

Demetra

Installation

Usage

Available options

APIs

fetchPage()

fetchArchive()

fetchExtra()

fetchMenu()

fetchTaxonomy()

fetchLanguages()

fetchSitemap()

subscribe()

send()

upload()

fetchQueue()

Queue

add()

Clear()

DemetraRequests