The Slice Builder
These docs rely on Slice Machine, which is in active development and subject to change. Content Relationships are not currently supported with Slices.
We would like to proudly introduce The Slice Builder!
Slicemachine's answer to modelling and generating CMS data locally.
This local component development environment gives you all the tools you need to generate data models and mock content, which you can use with Storybook to preview how real data will interact with your carefully crafted component libraries.
This article assumes you have:
- You are using version 3.8.3-beta.0 of the CLI, check this by running
- Installed and configured Slicemachine in your project
- Learned how to create a new slice with --create-slice
- Installed and added a Storybook
NOTE: The experimental sm --pull command has been deprecated with this release. Also, previously your Slice models were pushed to Prismic when using --create-slice, this is now the last step when building components with the Slice builder.
Configuring The Slice Builder
First, install slice-machine-ui as a dependency, this will give you all the necessary files to work with The Slice Builder in your local project.
npm install slice-machine-ui
yarn add slice-machine-ui
Then, if not already, run Storybook to preview your components locally:
npm run storybook
yarn run storybook
In a second terminal window start Slicemachine by running the sm --develop command, this starts The Slice Builder:
prismic sm --develop
Now, if you visit http://localhost:9999/ you should be able to see the home screen of The Slice Builder. 😃
What does --develop do?
This command will check if you are logged in to Prismic through the CLI. If not, you will be prompted to do so, this is necessary to push your Slices to Prismic. Then it will run npm run slicemachine to launch The Slice Builder. In the future we will allow you to log in through The Slice Builder window.
Using The Slice Builder
The first thing you'll see, if you have previously created Slices/Components in your repo, are representations of these on the home screen.
If any of these Slices have conflicts with the Slices in the repository you'll see a warning and the option to overwrite the Slices so that only one source of truth exists. Once there are no conflicts you can enter The Slice Builder to begin model your data.
This is where the fun begins. With the The Slice Builder you can now visually manage the fields that you will require in your repository, locally. 😀 Simply drag and drop the fields in to the visual editor, much like in the Custom Type builder.
Once you've chosen your fields and added their API IDs, click 'Save model to file system', this will update the local files in your project. The files it will update are the model.json with the Slice Model and the mocks.json with dummy data for each new field.
Now you will have all the content that you need to test with. The next part is up to you. You will need to update your component with the corresponding code to handle the dummy data. This is done simply by linking the API IDs of the fields to the relevant places in your components:
- In the index.vue file in Nuxt.js
- In the index.js file in Next.js
You can now generate the preview.png of your component by clicking the refresh button on the image in The Slice Builder and also preview your full new component in the storybook route, all locally. 🎉🎉🎉
Some times the builder might not be able to generate the screenshot. This can be caused by 2 things:
1. Storybook is re-rendering your Slice, in that case re-clicking the 'Push to file system' button will resolve the issue.
2. Updating or deleting a field might cause the component to break, in this case you will need to update your component first and make sure it renders correctly.
Push and use Slices in custom types.
Finally after all your hard work you'll want to give your content creators the ability to use your newly created Slice in the Prismic repository. Simply hit the ‘Push to prismic’ button to send your Slice to your 'Shared Slices' library.
That's right, now any Slices created with The Slice Builder will be 'Shared Slices' available to use in any custom type, making the process of maintaining and updating Slices much easier.
What does this look like in the custom type builder? Well there's a new tab in the custom type builder for Shared Slices where you can select the Slice you've just pushed.
There you can choose which Slices you want for that custom type and the source of truth for this Slice remains in the code. Now your content writers can use your Slices & components in whichever document you see fit. 😁