prismic-javascript

JavaScript development for prismic.io API v2

The source code is on Github.
The Changelog is on Github's releases tab.
The API reference is on Github.

It's meant to work in pair with the prismic-dom library available here:

prismic-dom is on Github.

🎉Our library will hit v3 soon! That's right, it's the v3 of an API V2 package... You can try it by installing the beta version from npm. Read the changelog!

1. Installation

Prismic API Settings
NPM
CDN
Downloadable version
Polyfills
Demo project
Starter kits

3. Integrate the content

Embed
Image
Text
Number
Date
Timestamp
Select
Color
StructuredText
WebLink
DocumentLink
ImageLink
FileLink
Separator
Group
GeoPoint
Slices

5. License

Installation

Prismic API Settings

Your endpoint must contains "v2" at the end, otherwise it means that you're working on the API V1 so this library won't work for you.

apiEndpoint: your-repo-name.prismic.io/api/v2

NPM

npm install prismic-javascript --save

CDN

https://unpkg.com/prismic-javascript

(You may need to adapt the version number)

Downloadable version

On our release page: https://github.com/prismicio/prismic-javascript/releases.

Polyfills

To support legacy browsers include a promise polyfill.

Starter kits

For new project, you can start from a sample project:

Demo project

You can find an integration of prismic content with the new API V2 in the following project:

Node.js project

Query the content

To fetch documents from your repository, you need to fetch the Api data first.

var Prismic = require('prismic-javascript');
 
Prismic.api("http://your_repository_name.prismic.io/api", function(error, api) {
  var options = {}; // In Node.js, pass the request as 'req' to read the reference from the cookies
  api.query("", options, function(err, response) { // An empty query will return all the documents
    if (err) {
      console.log("Something went wrong: ", err);
    }
    console.log("Documents: ", response.documents);
  });
});

All asynchronous calls return ES2015 promises, so alternatively you can use them instead of callbacks.

var Prismic = require('prismic-javascript');
 
Prismic.api("https://your-repository-name.prismic.io/api").then(function(api) {
  return api.query(""); // An empty query will return all the documents
}).then(function(response) {
  console.log("Documents: ", response.results);
}, function(err) {
  console.log("Something went wrong: ", err);
});

If you included prismic through the script tag (CDN) there is a global variable PrismicJS:

PrismicJS.api("https://your-repository-name.prismic.io/api").then( api => {
  const faq = PrismicJS.Predicates.at('document.type', 'faq');
  api.query(faq, { lang: 'en-en' }).then( response => {
    console.log("Documents: ", response.results);
  })
})

See the developer documentation or the API documentation for more details on how to use it.

Integrate the content

In each case documented below, you will have a snippet of the custom type and another for the code needed to fill the content field into your JS Template. In these examples we have a doc parameter corresponding to the fetched prismic document.

Embed

Custom type

"video" : {
  "type" : "Embed"
}

Template JS

doc.data.video.embed_url

Image

Custom type

"photo" : {
  "type" : "Image",
  "fieldset" : "Image",
  "config" : {
    "constraint" : {
      "width" : 300,
      "height" : 300
    },
    "thumbnails" : [ {
      "name" : "Small",
      "width" : 100,
      "height" : 100
    }, {
      "name" : "Medium",
      "width" : 200,
      "height" : 200
    }, {
      "name" : "Large",
      "width" : 300,
      "height" : 300
    } ]
  }
}

Template JS

//main view
doc.data.photo.url
doc.data.photo.alt
doc.data.photo.width
doc.data.photo.height
 
//thumbnails => example for small view
doc.data.photo.small.url
doc.data.photo.small.alt
doc.data.photo.small.width
doc.data.photo.small.height

Text

Custom type

"title" : {
  "type" : "Text",
}

Template JS

doc.data.title

Number

Custom type

"count" : {
  "type" : "Text",
}

Template JS

doc.data.count

Date

Custom type

"publication" : {
  "type" : "Date",
}

Template JS

import { Date } from 'prismic-dom'
 
// date as string from the API
doc.data.publication
// date as JS Date
Date(doc.data.publication)

Timestamp

Custom type

"time" : {
  "type" : "Timestamp",
}

Template JS

import { Date } from 'prismic-dom'
 
// timestamp as string from the API
doc.data.time
// timestamp as JS Datetime
Date(doc.data.time)

Select

Custom type

"gender" : {
  "type" : "Select",
}

Template JS

doc.data.gender

Color

Custom type

"background" : {
  "type" : "Color",
}

Template JS

doc.data.background

RichText

Custom type

"description" : {
  "type" : "StructuredText",
}

Template JS

import { RichText } from 'prismic-dom'
 
RichText.asText(doc.data.description)
 
//linkResolver must be declare somewhere
RichText.asHtml(doc.data.description, linkResolver)

WebLink

Custom type

"linktoweb" : {
  "type" : "Link",
  "config" : {
    "select" : "web"
  }
}

Template JS

doc.data.linktoweb.url

DocumentLink

Custom type

"linktodoc" : {
  "type" : "Link",
  "config" : {
    "select" : "document",
    "customtypes" : [ <your-custom-type-id> ],
    "tags" : [ <your-tag> ],
  }
}

Template JS

//return url of the document link
doc.data.linktodoc
//return url of the document
linkResolver(doc.data.linktodoc)

ImageLink

Custom type

"linktomedia" : {
  "type" : "Link",
  "config" : {
    "select" : "media"
  }
}

Template JS

doc.data.linktomedia.url

FileLink

Custom type

"linktofile" : {
  "type" : "Link",
  "config" : {
    "select" : "media"
  }
}

Template JS

doc.data.linktofile.url

Group

Custom type

"feature" : {
  "type" : "Group",
  "repeat": true, //default to true but put explicitly for the example
  "config" : {
    "field" : {
        "title" : {
          "type" : "Text",
        },
        "description" : {
          "type" : "StructuredText",
        }
    }
  }
}

Template JS

import { RichText } from 'prismic-dom'
 
doc.data.feature.forEach(item => {
    item.title
    RichText.asHtml(item.description, linkResolver)
})

GeoPoint

Custom type

"location" : {
  "type" : "GeoPoint",
}

Template JS

doc.data.latitude
doc.data.longitude

Slices

Slice with Group as value The Group value will be put directly as Slice value Custom type

"contentAsSlices" : {
    "fieldset" : "Dynamic page zone...",
    "type" : "Slices",
    "config" : {
        "choices" : {
            "slides" : {
                "type" : "Group",
                //required to display name in slice select in the writing room
                "fieldset" : "Slides",
                "config" : {
                    "fields" : {
                        "illustration" : {
                          "type" : "Image"
                        },
                        "title" : {
                          "type" : "StructuredText"
                        }
                    }
                }
            }
        }
    }
}

Template JS

for(slice in doc.data.contentAsSlices) {
    switch(slice.slice_type) {
        case 'slides':
          slice.value.forEach(item => {
            item.illustration.url
            item.title
          })
          break
    }
}

Slice with basic fragment like Text as value The fragment value will be put directly as Slice value Custom type

"contentAsSlices" : {
    "fieldset" : "Dynamic page zone...",
    "type" : "Slices",
    "config" : {
        "choices" : {
            "description" : {
              "type" : "StructuredText"
            }
        }
    }
}

Template JS

import { RichText } from 'prismic-dom'
 
for(slice in doc.contentAsSlices) {
    switch(slice.slice_type) {
        case 'description':
            RichText.asHtml(slice.value, linkResolver)
            break
    }
}

new Slice the new Slice type allow you to create a repeatable area and a non repeatable one.

"contentAsSlices" : {
    "fieldset" : "Dynamic page zone...",
    "type" : "Slices",
    "config" : {
        "choices" : {
            "newslice" : {
              "type" : "Slice",
              "non-repeat": {
                "title": {
                  "type": "Text"
                }
              },
              "repeat": {
                "description": {
                  "type" : "StructuredText"
                }
              }
            }
        }
    }
}

Template JS

import { RichText } from 'prismic-dom'
 
for(slice in doc.contentAsSlices) {
    switch(slice.slice_type) {
        case 'newslice':
          //non repeatable part
          slice.value.primary.title
 
          //repeatable part
          slice.value.items.forEach(item => {
            RichText.asHtml(item.description, linkResolver)
          })
          break
    }
}

Contribute to the kit

Install the kit locally

Source files are in the src/ directory. You only need Node.js and npm to work on the codebase.

npm install
npm run dev

Documentation

Please document any new feature or bugfix using the JSDoc syntax. You don't need to generate the documentation, we'll do that.

If you feel an existing area of code is lacking documentation, feel free to write it; but please do so on its own branch and pull-request.

If you find existing code that is not optimally documented and wish to make it better, we really appreciate it; but you should document it on its own branch and its own pull request.

License

This software is licensed under the Apache 2 license, quoted below.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This package has been deprecated