vue-slicezone Technical Reference

Introduction

vue-slicezone provides a component named slice-zone that matches Vue components with Prismic Slices. Slices are structured data components from Prismic.

The slice-zone component works in three steps:

1. Scan available components
The slice-zone component scans all available Slice components in your project.

2. Receive Slice data
In Nuxt projects, slice-zone can query a document from Prismic on page generation. Otherwise, it will accept an array of Slices as a prop.

3. Render components with data
It then converts the snake_cased Slice names from the API to PascalCased names which it matches to the Slice components in your project, and renders each component with the corresponding API data.

Dependencies and requirements

This project requires either that you have either @prismicio/vue or @nuxtjs/prismic installed and configured.

In Nuxt projects, you must also install nuxt-sm to resolve components.

Installation

Install the package via a package manager:

  • npm
  • Yarn
Copy
npm i vue-slicezone
Copy
yarn add vue-slicezone

Additional configurations for Nuxt

Nuxt project will automatically take care of scanning and mapping your slices, using the nuxt-sm package. Install it with:

  • npm
  • Yarn
Copy
npm i nuxt-sm
Copy
yarn add nuxt-sm

It is standard to create a slices/ directory at the root of your Nuxt project to store your Slice components.

In your Nuxt project, create a file at the root of your project called sm.json. In this file, you can specify any directories and or library packages (like vue-essential-slices) that contain slices.

Copy
{"libraries": ["@/slices", "vue-essential-slices"]}

In Nuxt projects, you may also need to configure your bundler to transpile from ES6:

Copy
// nuxt.config.js
build: {
  transpile: ['vue-slicezone']
}

Example

Here is an example of a page in a Nuxt project, at ~/pages/_uid.vue:

Copy
<template>
  <slice-zone type="page" :uid="$route.params.uid" />
</template>

<script>
import SliceZone from 'vue-slicezone'

export default {
  components: {
    SliceZone
  }
}
</script>

When a user visits a page, like /dog, the slice-zone component will receive the route parameter dog and make an API call to your Prismic repo for a document with type "page" and UID dog. When that document is returned, slice-zone will match the document's Slices with Slice components from the slices/ directory, and render those components.

Usage

Auto-fetch

The following props tell the slice-zone component how to auto-fetch a document from the Prismic API.

At a minimum, auto-fetch requires type and either uid or queryType.To query a repeatable document, pass the uid. To query a singleton, pass queryType="single".

Auto-fetch only works in Nuxt

Please note: auto-fetch only works in Nuxt projects. Query props will have no effect in a Vue project. See the section on manually resolving content, below, for information on how to render content in Vue.

You can pass query options, such as fetchLinks, with params. You can specify your content locale with lang.

Here's an example query:

Copy
<slice-zone 
  type="homepage" 
  queryType="single" 
  lang="fr-fr"
  :params="{ fetchLinks: 'post.title' }"
/>

In this example, slice-zone will query the API for the singleton document of type "homepage" in French. The fetchLinks option will tell the API to include the titles of any linked documents of type "post".

Here are all of the props:

type

The Custom Type of the Prismic document to query. Required.

uid

The UID of the Prismic document to query. Required if queryType is repeat.

queryType

To specify whether you are querying a singleton or a repeatable Custom Type. Accepts "single" and "repeat" or "repeatable". Defaults to "repeat".

slicesKey

If your slices are stored in a key other than "body" or "slices", the name of the key. (Advanced)

params

To pass a query options object.

lang

To specify the locale code for your content. By default the API will return content from your master locale.

v-bind:sliceProps

Pass props to your Slices. Accepts either an object or a function. The function receives index, slice, and sliceName as arguments. To use the props, you must declare them in your Slice component.

Query and resolve manually

You can also manually pass content to the slice-zone component, and you can manually define the mapping of components to data.

In Nuxt projects, querying can happen automatically (see the previous section) and the mapping is handled by the nuxt-sm package. In Vue, you must do both of these steps manually.

In the example below, the Slices are passed to the slice-zone component manually. The resolver tells the slice-zone how to map your Slice data to your Slice components.

The slice-zone automatically converts the snake_cased Slice names from your Prismic repo to PascalCased names, and the resolver uses the PascalCased names to render the corresponding component.

Copy
<template>
  <SliceZone
    :slices="document.data.body"
    :resolver="({ sliceName }) => slices[sliceName]"
  />
</template>

<script>
import SliceZone from 'vue-slicezone'
import RichText from './../slices/RichText'
import CodeSnippet from './../slices/CodeSnippet'
import BannerImage from './../slices/BannerImage'

export default {
  components: {
    SliceZone
  data () {
    return {
      document: null,
      slices: {
        RichText,
        CodeSnippet,
        BannerImage
      }
    }
  },
  methods: {
    getContent: async () => {
      this.document = await this.$prismic.client.getSingle('homepage')
    }
  },
  created () {
    this.getContent();
  }
}
</script>
slices

An array of Slice data from Prismic.

resolver

A function that maps Slice components to Slice data. As an argument, receives an object containing: the Slice's PascalCased name, the Slice data, and the Slice's index. Should return either: a component, a promise that returns a component (such as an import statement), or an array of promises (such as an array of import statements).

Theming

Inspired by Theme UI, the slice-zone component supports passing a theme object or function to rendered slices. This allows developers and designers to enforce design rules on pages.

The theme prop accept a theme object. How this object works depends on your implementation. For a real-world example, see vue-essential-slices.

Here's an example of what a theme object might look like:

Copy
<template>
    <slice-zone type="page" uid="contact" :theme="theme" />
</template>
<script>
const theme = {
    color: '#FFF',
    wrapper: {
        style: 'background: #111'
    }
}
export default {
    data() {
        return {
            theme
        }
    }
}
</script>

To scope theme values to specific components, use the Slice name as a key. This will override root values.

Copy
const theme = {
    color: '#111',
    CallToAction: {
        color: '#FFF'
    }
}

You can also pass a function as a theme:

Copy
const theme = ({ sliceName, i }) => i % 2 ? { color: '#111' } : { color: 'pink' }

And you can use a function for a scoped theme:

Copy
const theme = {
    CallToAction: ({ sliceName, i }) => i % 2 ? { color: '#111' } : { color: 'pink' }
}

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.