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.

This article will teach you how to generate a component template and model the CMS data with the Slice Builder. On top of that, you will also learn how to create slice variation in the Slice 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 Next.js. Launch a boilerplate project.

Are you using your own project?

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

Generate a model with the Slice Builder

The very first step is to generate a model with the Slice Builder. The Slice Builder is a tool with which you can create content models, mock CMS data, Custom Types, and variations for a Slice. This tool includes suggested code snippets & options for customizing your mock data output

Launch the Slice Builder

To launch the Slice Builder, open a new terminal window and run the following command:

Copy
prismic sm --develop

The Slice Builder, by default, will be running on http://localhost:9999.

Run the Storybook

Once you launch the Slice Builder, you will see a warning message "Storybook is not running". This is necessary to create a preview of the component. Learn how to install Storybook.

Warning image for Storybook is not running

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

In these steps, we'll guide you through all the stages of creating a Slice. The Slice Builder environment opens with two options in the side navigation tab: Custom Types and Slice.

Navigate to the Slice button tab, click on the + sign on the top right.

SliceBuilder that showing different navigation
  • Enter the name of your Slice. It should be in the PascalCase. For this example, we will call our Slice "TextImageRight."
  • Select the default /slices target library or create a new one. This is the local path in your sm.json file to the folder that contains your Slices.
Pop-up to create new Slice

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.js

〜/slices/TextImageRight/index.js

The actual next.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.
  • Add any new field by clicking on the '+Add a new field' button in the repeatable or non-repeatable zones.
  • The 'field id' is the API ID used to reference the field in the component code.

Now for our example, go to the Slices > TextImageRight Slice in the Slice Builder. Here are the fields we will add to the non-repeatable zone with their API IDs. The field id you enter here is the API ID that we will use to reference the field in the component code.

Added different fields to the Slice

Once you've added your fields, click the Save model to file system button. This will update the template files for a component in ~/slices/TextImageRight folder in 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

With the Slice Builder tool, you can change the field settings, add mock data and create multiple Slice variations.

Configure the field settings

You can configure the field settings by clicking on the pencil icon of any field it will open a pop-up with the two tabs. Select the Field Model tab to change the configuration of the field. This will give you more control over what restrictions and options there are for fields.

In the Field Model tab, you can do the following field's settings:

  • Add the Label
  • Modify the API ID
  • For Rich Text configuration, we have a check box for allowing multiple paragraphs, allow target blanks for links. You can also restrict to use of any element.
  • Set options and click the checkbox to use the first value as default (" ") for the Select field.
  • Select Custom Type constraints for the Content Relationship field.
  • Set responsive views for the Image field.

    In our example: For the Rich Text field, we will restrict the field only to use the <p> tag. To use this, click on unselect all and choose only the <p> tag and Save the configuration.
Restrict the field only to use the <p> tag

Customize your mock data

In the 'Mock Config' tab, you'll be given different options to output different mock data patterns so you can see how components look with multiple variations or with a pattern that matches your design.

To generate mock content, we will use the selected patterns.

  • For Title and Rich Text field: A pattern is an array of Rich Text options and repeated "block" times.
  • For the Link field: Add link value URL in the box. You can have 'link to web" configuration mock data.
  • For GeoPoint: You can select some "Presets" mock data or add "Google Maps Url" for your location.
  • For Date and Timestamp field: Select date value in mm/dd/yy formats.
  • You can customize the color for the Color field.
  • And more.
    In our example:
    For the Image field: Click the edit button, select the Mock config tab, pick an image of your choice, and Save the configuration.
Mock config for the Image field

Add a Slice variation

With the Slice Builder, you can create multiple versions of your Slice so that your content creators have the ability to choose between different variations of the Slice in the document editor to show on their website.

You can create as many variations of a single Slice. You might want to add an extra field, change the position of the image with the CSS, or present an image gallery in different views. The possibilities are as broad as the use cases!

How to create a variation in the Slice Builder

Click on the dropdown arrow that shows already the 'Default slice' settings. To add a Slice variation to your Slice, select + Add new variation. It will open a pop up **to add more information like:

  • Variation Name: Enter the name of a variation. The variation name will appear in the Slice Builder in the same dropdown and in the page editor in Prismic.
  • Variation ID: It's generated automatically based on the variation name and will appear in the "variation" key in the API responses.
  • Duplicate from: Choose the Slice from the dropdown from which you want to duplicate the variation. For this one, I am choosing "Default Slice".
Pop-pup to add new variation

Click on Submit button. All of your variations will be available in the dropdown menu.

For our example: We will create two variations: TextImageLeft and TitleImage.

  • TextImageLeft: To show the position of the image left in the text. In the Default slice, the image position will be right in the text.
  • TitleImage: In this variation, we'll remove the Rich Text field add a Title field. The Image field will be the same.

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:8888"
}

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 for your components. So your Slice library folder might look like this:

Copy
Slices
|_ AccordianSlice
  |_ index.ts
  |_ 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:


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.