Create and Model a Component

Beta

These docs rely on Slice Machine, which is in active development and subject to change. Content Relationships are not currently supported with Slices.

On this article you'll learn how to generate a component template and model your content with the Prismic Builder.


Are you using our starter project?

This article works best when using our pre-configured boilerplate project, which allows you to jump right in and explore Prismic with Nuxt.js. Launch the project.

Are you using your own project?

Learn how to Configure Slice Machine and Prismic in your project first and then return.

Create a Slice with the Prismic Builder

The first step is to launch the Prismic Builder, a visual editor where you create and model Custom Types and shared Slices. It provides code snippets for Nuxt and mock content to preview the components locally using Storybook.

Launch The Slice Builder

Navigate to your project folder and run the following command:

Copy
prismic sm --develop

Once the Prismic Builder loads on the default port http://localhost:9999. You may see a warning notification in the bottom left asking you to install and run Storybook. This is necessary to create a preview of the component. Learn how to install Storybook.

Slice Builder warnings
Slice Builder warnings

Once this is installed (if you use the pre-configured sample project, this is already installed), so just run the following command:

  • npm
  • Yarn
Copy
npm run storybook
Copy
yarn run storybook

Build your Content Model (Slice)

Once you run the prismic sm --develop command, The Slice Builder will run on http://localhost:9999. Head to the Slices page and click on the + button in the top right of the page to create a new Slice.

An empty Slices screen
An empty Slices screen

Then you'll see the pop-up to Create a new Slice. Select the default /slices target library or create a new one. Give the Slice a name made of two PascalCased words, and save. In this example, we want a Slice with the image positioned to the right. We'll call it TextImageRight:

The 'Create a new Slice' screen.
The 'Create a new Slice' screen.

Once you click save on the 'Create a new Slice' screen, the builder will add the following files to your project:

File

Path to file

Description

index.vue

〜/slices/TextImageRight/index.vue

The actual vue.js component file.

model.json

〜/slices/TextImageRight/model.json

The JSON that contains the Slice fields that will be pushed to Prismic.

Library index.js

〜/slices/index.js

Added or update to the root of your Slice library to import all you Slices in the Slice Zone.

index.stories.js

〜/.slicemachine/assets/slices/TextImageRight/index.stories.js

The configuration file for Storybook.

mocks.json

〜/.slicemachine/assets/slices/TextImageRight/mocks.json

A mock API response used to develop the component locally.

After saving, you'll see your new Slice in the Builder.

The Slice will have a couple of default fields that you can replace. Click on the +Add a new field button in the repeatable or non-repeatable zones to add any new field.

The 'field id' is the API ID used to reference the field in the component code.

In this example, we'll add a Rich Text and an Image field.

The default Slice content.
The default Slice content.

Click on +Add a new field and add these two fields, copy and paste the API IDs shown below:

API ID

Type of field

textField

image

Once you've added your fields, click on Save model to file system. Now, head over to the next article to learn how to code and style this Slice on your project.

The Slice Builder example

Here's a walkthrough video of all we've seen so far:

⚠️ Conflicting components?

If the component you've just created has a naming conflict with any components in the repository, you'll see a warning and the option to overwrite the components so that only one copy exists. Once there are no conflicts, you can enter the Slice Builder to begin modeling your data.

Customization

The Prismic Builder gives you the freedom to create, edit, remove and change the fields you add into your Slices. You can change each field's configuration and API IDs, add mock data and create Slice variations.

Configure the field settings

Click the pencil button of any field. The configuration window will pop up so you can start customizing its settings.

In the Field Model tab, you can edit elements like the Label, API ID, the Placeholder, and any particular configuration settings that each Field has.

Let's try it out with the Rich Text field we added before:

  • textField: Click the edit button, and in the Field Model tab, unselect the default options and choose only the p tag. This will restrict the Rich Text field to allow paragraph content. Then, Save.
The 'Field Model' settings screen.
The 'Field Model' settings screen.

Add mock data

Click the pencil button of any Field. The configuration window will pop up so you can start customizing its settings.

In the Mock config tab, you'll have different options to output mock data patterns so you can see a preview of the component with a pattern that better matches your design.

Let's try it out with the Image field we added before:

  • image: Click the edit button, select the Mock config tab, pick an image of your choice, and save.
The 'Mock Config' settings screen.
The 'Mock Config' settings screen.

Add a Slice Variation

The Slice builder allows you to add variations of your Slices, which work as different versions of each Slice.

You can change the variations as much as you want. You may add a subtle change—for example, a Hero slice with or without a call to action. Or even entirely change the structure of the Slice. The possibilities are as broad as the use cases!

To add a variation, click on any Slice. You'll see a dropdown below the Slice title that says Default slice; click on it and then select  + Add a new variation. Give a name, and duplicate the new variation from an existing one or the default Slice. Then, click Submit.

Once your variations are set up, you'll be able to access them in your components in slice.variation. Learn more about how to template Slices and variations.

Example

Continuing with our TextImageRight Slice example from earlier, click the '+ Add a new variation' button, for this example we'll create two variations.

  1. TextImageLeft
  2. TitleImage

For the first one TextImageLeft, we'll use this variation to reposition the image to the left on the frontend of the website. This only happens in the code so the TextImageLeft variation itself keeps the same shape and content as the default variation.

The 'Add new Variation' screen.
The 'Add new Variation' screen.

Then, for the second variation TitleImage, we'll add a Title field with the API ID of title, remove the textField and position the image to the centre. Open the edit configuration screen of the title field and unselect the default options and choose only the h2 tag. This will restrict the Rich Text field to allow title content. Save.

The new variation.
The new variation.

Once you've added your changes, click on Save model to file system.

Add a new Slice library

If you want to add another collection of Slices to your local project you must first add the name of this library to the libraries section of your sm.json file. In the example below, we add a new library called my-second-slice-lib.

Once this is done you will be able to select this library from the 'Target Library' dropdown when adding a new Slice with the + button.

Copy
{
  "apiEndpoint": "https://your-repo-name.cdn.prismic.io/api/v2",
  "libraries": [
    "@/slices",
    "@/my-second-slice-lib"
  ],
  "_latest": "0.1.0",
  "storybook": "http://localhost:3003"
}

Non-JS files

With the latest update to the slice-machine-ui package, you can use non-javascript files in your Slice folders. The main use case here is to use typescript files. So your Slice library folder might look like this:

Copy
Slices
|_ AccordianSlice
  |_ index.vue
  |_ model.json
|_ index.ts (import file)

Customization example

Here's the walkthrough of all the changes we've done to our TextImageRight Slice so far:

Code Your Component

Now, we recommend you read the next article, which will show you how to edit the Slices and their styles in your project code.


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.