Prismic Releases Slice Variations and Local Custom Types in Alpha

Written by Phil Snow in Misc on May 26,2021

Why have we added Slice Variations & local Custom Types?

We've heard the question a lot from users recently "Is Slice Machine ready for production websites?", while it might not have all the features that some people need for production websites, these latest updates take the project a huge step closer to having everything you would need for a production-ready website.

Please note: The features mentioned in this article are in Alpha, which means they are subject to change and what you see now is no guarantee of what the finished version of these features will be. Also, the Alpha phase is meant to allow us to find any issues in the code or features.

Changes to the Custom Types location

This is a big one. Custom Types exist currently within the Prismic Dashboard, with this update we will make them available to use in the local Builder, so the Custom Types JSON will exist within your project code. One of the main reasons that we implemented local Custom Types is to allow for content relationships within Slices. Content Relationships are essential for grabbing the content from linked documents, currently in Prismic if you want to link to a document then you must specify that documents 'Type'. Therein lay the problem for adding Content Relationships in locally created Slices, how can you specify a Custom Type in a Content Relationship when you don't know what the Custom Types are?

The answer is local Custom Types, now the Slice Builder has access to that data and we can define the Custom Types within our Slices. Another advantage to having the Custom Types locally is versioning, we had that power previously with having Slices locally, but no we have that for the Custom Types themselves. By having all of these locally you will be able to use your code versioning tool of choice to keep track of changes to your Custom Types.

The final advantage of having Custom Types in your code is that you will be able to control access to who can edit them. With Custom Types being beside the code then there are no worries about a content editor accidentally having access and making a mistake in the content model. For the moment Custom Types will still be available within the Prismic Dashboard, but there's a possibility that in the future these could live solely in the code. If this ever happens it will be communicated WELL IN ADVANCE and we would prepare the necessary migration tools and support for this change.

Your Custom Types will be pulled automatically by your Slice Builder once you install the Alpha version of the package and they will be shown like the screen below. Any non-Slice Machine Slices will not appear in the local Custom Types, they would need to be recreated using the new 'create slice' button in the Builder.

Slice Variations

The is an exciting one. If you've been developing Slices then you might have seen the need to have small differences in how a Slice might be presented and you might have wanted to give your content creators the ability to choose how the Slice is presented. In the past, in the Prismic Dashboard, this was done with Slice Labels. Now in Slice Machine, this is handled much better with Variations. Variations allow you to create another version of your Slice in the Slice Builder and allow your content creators to choose from these different versions when using the Slice in the document editor.

Whereas labels allowed you to add fields in a dropdown that could be used on the front end to change a Slice's component, Slice Variations allow you to change the shape of the entire Slice. This also means that if your content creators select one of the Slice Variations from the dropdown in the document then they will see a visual change that represents better how the data will be shown in the frontend of the website.

These variations will also be reflected and documented in your projects Storybook, with screenshots being generated for each variation.

Installation and migration

The steps to start testing these new features with your project are pretty straightforward. You will need to update your Slice Builder package and do a couple of configurations in your project.

Slice Machine UI

This is the one that does all the magic in presenting your local Custom Types and Slice Variations. To do this, run:

npm install slice-machine-ui@0.1.0-alpha.4

Mocks and Stories migration

When you run your Slice Builder for the first time after the update with the command:

prismic sm --develop

you will be asked if you want to move mocks.json and index.stories.js files alongside your component preview images in the ~/.slicemachine/assets/slices directory. Select yes and move to the next step.

Storybook configuration

The first time you launch your new Slice Builder you'll be greeted by the following screen, which will give you instructions for Next.js or Nuxt.js on how to update the Storybook settings of your project with the necessary information to allow for variations in your Storybook.

Usage

This is the fun part. Now that you've got everything set up you can dive into the new look Slice Builder and start building your Slices with variations and Content Relationships. Let's go through a quick example of how to do this.

Add a variation to a Slice

Here we have a gallery Slice from our Next.js tutorial series project. The Gallery items contain an image, some text and a link. The items are arranged in 2 columns. We would like to give the content creators the option to choose between presenting the gallery with 2 or 3 coumns.

To do this we navigate to our Slice, then from the dropdown select '+ Add new variation'. For this one we give it the name 3-column-grid, we can also diverge the model from the original by adding a Rich Text field in the repeatable zone with the API ID itemTitle, then save.

Update the component code

The next thing we need to do is edit our code in our component to reflect this new variation. So in our code we'll edit the class name on our gallery item to change when the variation does, this will then update the CSS from 2 columns to 3.

The original code looked like this:

<div key={i} className="gallery-item">

It now looks like this:

<div key={i} className={'gallery-item-'+slice.variation}>

We need to also edit the original CSS:

.gallery-item {
-webkit-box-flex: 0 1 48%;
-moz-box-flex: 0 1 48%;
-webkit-flex: 0 1 48%;
-ms-flex: 0 1 48%;
flex: 0 1 48%;
}

To reflect this new switch:

.gallery-item-default-slice {
-webkit-box-flex: 0 1 48%;
-moz-box-flex: 0 1 48%;
-webkit-flex: 0 1 48%;
-ms-flex: 0 1 48%;
flex: 0 1 48%;
}
.gallery-item-3ColumnGrid {
-webkit-box-flex: 0 1 33%;
-moz-box-flex: 0 1 33%;
-webkit-flex: 0 1 33%;
-ms-flex: 0 1 33%;
flex: 0 1 33%;
}

We can also add the itemTitle Rich Text field within the gallery item depending on the variation:

{ slice.variation === '3ColumnGrid' ? 
<RichText render={item.itemTitle} /> : null
}

You can then see these changes reflected with mock data in Storybook by clicking the 'Open in Storybook' button in the Slice Builder:

Add to Page type - Push page to Prismic

This example has already been added in the custom type, otherwise we would have to select it there first. But since it's already part of the page custom type we can go ahead and push the Slice to Prismic and it will be available to use in your document right away.

Use in a document

Now run your local project, then jump over to Prismic and start to use your variations in your Prismic documents as shown in the video below.

That's it! You've got everything that's needed to start testing the latest features of Slice Machine, enjoy!

Phil Snow

One of the education team, who lives the phrase "every day is a school day".