@xbyorange/mercury-prismic

Mercury Prismic

Overview

This package provides a Mercury origin for reading data from Prismic CMS API. As underlay, it uses the prismic-javascript client to provide the Prismic data.

Api

import { Prismic } from "@xbyorange/mercury-prismic"

new Prismic(url, options)

• Arguments
  • url - <String>. Prismic api url.
  • options - <Object> Containing options:
    • defaultValue - <Any> Default value of origin until real data is returned.
    • fullResponse - <Boolean> If true, the full response of the Prismic api will be used as value. If false, only the response.results property will be returned, which is the default behavior.
    • release - <String> Prismic release to be read. This parameter will be passed as ref to the prismic-javascript query.
    • uuid - <String> Unique id to assign to the instance. Useful when using mercury sources handler.
    • tags - <String> or <Array of Strings> Tags to assign to the instance. Useful when using mercury sources handler. A "prismic" tag will be always added to provided tags by default.

Methods

query

prismic.query(queryObject)

• Arguments
  • queryObject - <Object> containing properties:
    • documentType - <String> Prismic document type to filter by. (It will be used to build a prismic-javascript query as in PrismicJs.Predicates.at("document.type", documentType))
• Returns - New queried instance having all common Mercury methods.

config

Configure instance for all next read executions.

prismic.config(options)

• Arguments
  • options - <Object> containing properties:
    • url - <String> Prismic api url.
    • fullResponse - <Boolean> If true, the full response of the Prismic api will be used as value. If false, only the response.results property will be returned, which is the default behavior.
    • release - <String> Prismic release to be read. This parameter will be passed as ref to the prismic-javascript query.

Read about how to configure all mercury-prismic instances at a time using the mercury sources handler.

Example of how to change all mercury-api requests urls at a time:

import { sources } from "@xbyorange/mercury";

sources.getByTag("prismic").config({
  url: "https://foo-prismic-repository.cdn.prismic.io/api/v2"
});

// All mercury-prismic instances will now be configured to request to provided url.

Example

Next example will be easier to understand if you are already familiarized with the mercury syntax.

import { Prismic } from "@xbyorange/mercury-prismic";

const prismic = new Prismic("https://foo-prismic-repository.cdn.prismic.io/api/v2", {
  release: "foo-release"
});

prismic
  .query({ documentType: "home-banner" })
  .read()
  .then(results => {
    console.log("Prismic content for home banner in foo-release", results);
  });

Usage with frameworks

React

Please refer to the react-mercury documentation to see how simple is the data-binding between React Components and Mercury Prismic.

Connect a source to all components that need it. Mercury will fetch data only when needed, and will avoid making it more than once, no matter how many components need the data.