Slice Machine

With SliceMachine, you can build page sections, define their model, edit properties, deploy them, and deliver a visual interface with Prismic that allows content creators to easily build pages without any further help from you.


Slice Machine is a local Custom Type and Slice builder that connects your component code with Prismic. It also allows you to simulate live content using mock data so you can develop your components fast. Your project then becomes the one source of truth as you can version your content models and code with Git.

💡 Framework compatibility

For the moment, Slice Machine is only compatible with Next.js and Nuxt.js projects.

Launch Slice Machine

Visit the documentation for your chosen technology to learn how to install and run Slice Machine in your project.

Custom Types

Custom Types are models for your documents. They are the place where you define and configure Fields and Slices for your content.

Adding a Custom type

Clicking the purple + button opens the 'Create a new custom type' modal with the following options.

  • Repeatable Type: A content model you would use many times. (Blog posts, Product pages)
  • Single Type: A content model you will use only once. (Home page, Contact Page)
  • Custom Type Name: A label display name for the Custom Type.
  • Custom Type ID: The API ID to query the Custom Type. (e.g. 'BlogPost', ‘blog-post’)

    After saving you'll see your new Custom Type. This Custom Type contains a 'Static Zone' where you can add fields that only appear once per document and the 'SliceZone', where you can mix and match your 'Shared Slices'.

Static Zone

You can add fixed top-level fields in your Custom Types. The fields in the Static Zone appear once on a document and are usually fields you want your content creators to always use, for example, metadata fields, the most common being the UID field for repeatable document types.

  • In the Static Zone, click +Add a new field
  • Select a field from the list: UID, Group, Rich Text, Image, Link, Link to Media, Content Relationship, Select, Boolean, Date, Timestamp, Embed, Number, Geopoint, Color, Key Text.

The Slice Zone

The Slice Zone of the Custom Type allows you to select and group all the Slices you want to make available in a Custom Type.

Tabs

Within a Custom Type, you can use tabs to organize your content fields and make document editing more user-friendly. In the Custom Type builder, click the '+ Add a new tab' button to add a tab. Click the ‘gear’ icon to edit or delete a tab.

In the API response, ‘Static Zone’ fields across tabs are all delivered together in the data object. ‘Slice Zones’ created in different tabs will be returned to the data object separately with unique API IDs.

In this example, you see the Slice Zones returned with the API IDs slices and slices1.

Copy
{
  "id": "XJ45pREAACEAfEOA",
  "uid": "george-best-the-man-the-myth-the-legend",
  "url": null,
  "type": "post",
  "href": "https://blog-tester-phil.cdn.prismic.io/api/v2/documents/search?ref=Yd7lkhAAACIAlprA&q=%5B%5B%3Ad+%3D+at%28document.id%2C+%22XJ45pREAACEAfEOA%22%29+%5D%5D",
  "tags": [],
  "first_publication_date": "2019-03-29T15:29:39+0000",
  "last_publication_date": "2022-01-12T14:28:34+0000",
  "slugs": [],
  "linked_documents": [],
  "lang": "en-gb",
  "alternate_languages": [],
  "data": {
    "title": [],
    "date": "2019-02-01",
    "author_link": {},
    "links": [],
    "slices": [],
    "seo_title": null,
    "seo_description": null,
    "slices1": []
  }
},

Saving and pushing to Prismic

To make your models available on your repository first, click on 'Save to filesystem' so that the Custom Types can exist locally in the customtypes folder of your project. This gives you the ability to version your Custom Types as your project evolves by using a code versioning service like GitHub or Bitbucket.

Afterward, select 'Push to Prismic'. Clicking this button will send the model to Prismic and make it available to use in the repository UI when creating a new document.

💡 Syncing Slices as a group

Once you push your Custom Type to Prismic, any selected Slices will also be synced with your Prismic repository.

Slices

Slices are website sections that you’d build as React or Vue components. Once each component is ready, you can ship it to a Page Builder (Prismic). It becomes one of the sections your content team can use to compose their pages. Learn more about Slices.

Slice Simulations

Slice Machine generates a mock API response for each Slice to allow you to develop components in isolation without live data. The Simulator is a plugin that uses an iframe running in your local project to allow you to combine the mock data with your component code. This saves you time as you don't need to add content to the Prismic repository before you can test your components.

Generating a new Slice

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

  • Enter the name of your Slice. It should be in the PascalCase.
  • 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.

Once you click save on the 'Create a new Slice' screen you'll see your new Slice in the UI, Slice Machine will add the following files to your project:

File

Path to file

Description

index.js

~/slices/YourSlice/index.(js|vue|tsx)

The component code.

model.json

~/slices/YourSlice/model.json

The JSON that contains the Slice 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 your slices in the Slice Zone.

index.stories.js

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

A configuration file for Storybook if you wish to use it.

mock.json

~/.slicemachine/assets/slices/YourSlice/mock.json

A mock API response used to develop the component locally.

Adding Fields

New Slices will have a couple of default fields that you can replace. Add a field by clicking on the '+Add a new field' button in the repeatable or non-repeatable zones, give the field an ID (this is used to reference the field in the code).

  • The Non-repeatable zone: For fields that you want to appear only once in a Slice (e.g. a title).
  • The Repeatable zone: For fields that you a user to be able to add more than once in a Slice (e.g. Image fields for an image gallery).

Field settings

You can configure the field settings by clicking on the pencil icon of any field. In the Field Model tab, you can edit the following field settings:

  • Label: Label for content creators (defaults to field type)
  • API ID: A unique identifier for the field (e.g. buttonLink)
  • Placeholder: Placeholder text for content creators

Other field configurations include:

  • Rich Text configuration: Enable Allow target blank for links checkbox, Enable Allow multiple paragraphs check box, and a section to enable all the available types of element.
  • Select field: Set options and click the checkbox to use the first value as default (" ").
  • Content Relationship: Select Custom Type constraints.
  • Image: Set responsive views.
  • Boolean: True and False placeholders.

Code Snippets

Slice Machine provides suggested code snippets based on your framework for each of the fields that you add. The snippets are already connected with the API IDs necessary to get the data from Prismic. If the code snippet doesn’t match your use case the important part is the API ID.

Customize Mock data

Slice Machine generates mock data for each Slice and its fields so you can simulate how a Slice will look with live content. Customizing this mock data allows you to closely match your use case and test other possible use cases.

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.

The options to edit mock data include:

  • Title and Rich Text field: A pattern is an array of Rich Text options and repeated "block" times.
  • Link field: Add link value URL in the box. You can only have 'link to web" configuration mock data.
  • GeoPoint: You can select some "Presets" mock data or add "Google Maps URL" for your location.
  • Date and Timestamp: Select date value in mm/dd/yy formats.
  • Color: Custom hue for the Color**.**
  • Select: A random selection from the ‘Options’ input.
  • Number: A random numeric value.
  • Boolean: A random, or fixed true or false value.
  • Key text: Add arbitrary text here.
  • Embed: Add a valid Embed URL.

Add a Slice variation

With Slice Machine, 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 Slice Machine:

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 Slice Machine 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.

Once your variations are set up, you'll be able to access them in your components in slice.variation.

Slice Screenshots

You can choose to have preview images for each of your Slices so that they appear in the UI of your documents. There are a few options for doing this.

  • Automatic Screenshots: These images are auto-generated by Slice Machine. The mock data that you use in your fields will appear here. To use them, open your Slice and click 'Take Screenshot'. Then, a preview of your component will appear in Slice Machine.
  • Custom Images: To add custom images, navigate to the Variation you want to update and click the 'Custom Screenshot' button - add an image named preview.png. Doing so will overwrite the default Slice Machine image.
  • Placeholders: If you haven't created a Screenshot for your component and you push your Slice to Prismic, the Slice will be represented by a placeholder.

Saving and Pushing Slices

To make your Slice available to use in your Custom Types, click on 'Save to filesystem', this updates the following files mentioned when generating a new Slice, including the index.(js|vue|tsx) & model.json files.

Selecting 'Push to Prismic' will send the Slice JSON to Prismic and make it available to use in the repository UI when creating a new document.

Updating Shared Slices

If your Slice is already connected to a Custom Type(s), when you save and push an update on the Slice level it will be updated on all Custom Types.

Slice Libraries

Slice Machine chooses a default slices folder to save Slices. To add another collection of Slices to your project modify or add a path in the libraries setting in the sm.json file.

  • Open sm.json file in your local project
  • Add or modify the path to the new library inside libraries. For example:
Copy
{
  "apiEndpoint": "https://your-repo-name.cdn.prismic.io/api/v2",
  "libraries": [
    "@/slices",
    "@/my-second-slice-lib"
  ],
  "_latest": "0.1.0",
  "localSliceSimURL": "http://localhost:3000/_simulator"
}

After that, you’re able to select the new library from the Target Library dropdown when adding a new Slice with the + button.

Custom component templates

You can modify the default component template generated when you create a new Slice.

There can be many use-cases where you might need to customize the default Slice template, such as modifying the component HTML structure, generating post CSS files, or even adding your own typings if you are using TypeScript.

To do this, create a folder at the base of your project called .prismic. Then, inside this folder, add another folder called slice-template which should contain at least index.(js|vue|tsx) and model.json files. The folder name will let Slice Machine know that this is the new template. You can see an example of this below:

Copy
.prismic / slice-template
├── index.tsx
└── model.json

Legacy Slices

Non-shared Slices or legacy Slices, at the moment, can not be edited from Slice Machine. Although they are represented in the Custom Types, to give the developer more information on the contents of existing Custom Types.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.