Negligible Psychological Misery

    This package has been deprecated

    Author message:

    prismic-javascript has moved to @prismicio/client! No worries, you're safe to stay on prismic-javascript but it will no longer receive updates nor fixes (excluding security ones). Upgrading to @prismicio/client should be seamless for most users, if any doubt check out the changelog: https://github.com/prismicio/prismic-javascript/releases or reach out to us on our community forum: https://community.prismic.io

    prismic-javascript
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.2 • Public • Published

    JavaScript development for prismic.io API v2

    npm version Build Status

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

    🎉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

    2. Query the content

    3. Integrate the content

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

    4. Contribute to the kit

    Install the kit locally
    Documentation

    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:

    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.

    Copyright 2013-2017 Prismic.io (http://prismic.io).

    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.

    Install

    npm i prismic-javascript

    DownloadsWeekly Downloads

    61,399

    Version

    3.0.2

    License

    Apache-2.0

    Unpacked Size

    470 kB

    Total Files

    29

    Last publish

    Collaborators

    • arnaudlewis
    • levimykel
    • raph22
    • sre