Recreate the Banner as 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 explore the concept of breaking a website in to blocks, by the end you learn how to recreate them as components and test them locally.


1. Break the Design into Pieces.

As we will recreate our homepage design as components, we will want to break the page into blocks. We can think of the parts of our website as easily reusable building blocks, with which we can create highly flexible pages.

So if we imagine that the banner at the top of our page is a block that lives on its own, we can begin to imagine what that block is made of. This is pretty straightforward. We will need the following fields:

Description

Rich Text field

"Learn More" Button

 Link field for the clickthrough URL + a Rich Text field for the button text

Background

Here's a video to further show this:

2. Create a Component template

Now that we know what fields are needed to build our banner, we will want to begin the development process. The first step in this process is to generate a component & Slice (Content Model) template which we'll build on top of.

Launch the Slice Builder

To do this we need to open the Slice builder by running the following command:

Copy
prismic sm --develop

💡 What is the Slice Builder?

A visual builder for your Slice Models with all the tools you need to generate data models and mock CMS content locally. This tool includes suggested code snippets & options for customising your mock data output.

Then once the Prismic Builder loads on the default port http://localhost:9999 you will be greeted by the Custom Types tab. In this tab, you'll find the default Page custom type which has no Slices connected yet.

The Prismic Builder
The Prismic Builder

Generate files for the component

To start to build your component you should navigate to the Slices tab and click the purple '+' button. The 'Create Slice' button will create the template files for a new component, content model (Slice), the mock data, and Storybook. It also adds a default @/slices path to your sm.json file. This will give you the power to develop your entire component library locally.

The Slices Tab and Create Slice Button
The Slices Tab and Create Slice Button

Wait, what's a Slice?

Basically, a 'Slice' is the name that we give the content model that will be used to inject content into your component.

Here's an example of what The Prismic 'Create a new Slice' screen looks like. We select the @/slices local library (or create it if it doesn't exist) and we give it a name made of 2 PascalCased words. I'll call mine BannerSlice:

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

Component Naming

You can name your component anything that you wish as long as it's PascalCased words, there's no need to include anything special like 'Slice', 'Component', or anything else. It's up to you :)


3. Create a Slice for your Component

The next step will be to create the content model (Slice) for our component using the previously listed fields

Add your Fields to the Slice

After clicking the 'Create a new Slice', you will be greeted by a visual representation of the component we just created (BannerSlice). Next, click through to the build screen for our newly created Slice, so we can begin to add our fields. Which if you remember, are:

Description

Rich Text field

Learn More" Button

Link field for the clickthrough URL + a Rich Text field for the button text

Background

Use the visual builder to add and name the fields. The 'name' you give these fields are API IDs to reference the fields. You can click the pencil icon if you want to edit any of these fields' settings. Thanks to the template created by the 'Create a new Slice' button previously, 2 of these fields, Title & Description, have already been added.

💡 What's an API ID?

The fields' API ID is the ID corresponding to the data that will come from the content API (Prismic). But, this field will correspond to the mock data that we will generate for developing our component locally when using the Slice Builder.

Then click 'Save model to filesystem'. This will update the model.json file with the fields that will represent our content and the mock.json file containing the mock data that we will use to develop our component. You'll see more about that next.

Customize Mock Data (Optional)

You may want to quickly customize the structure of the mock data that is generated for each of the fields to make it closer to what your actual content will look like. For example, if you want more or less text for a Rich Text field, then you can go to the settings of each field and select the 'Mock Config' Tab. You can then edit the mock data as you see fit.

Remember to click 'Save model to filesystem' after editing these settings so that the mock.json file is updated.


4. Update Component Code

Now we can add the corresponding code to our component file (index.vue) for the fields that we just added.

Using Suggested Code Snippets

You can see the recommended code snippets for your framework with API IDs included by clicking the 'Show code widgets' button. Click the 'Copy code' button on the suggested code snippets in the slice builder, then in your code editor of choice navigate to, and open your component file, in my case ~/slices/BannerSlice/index.vue. Finally, paste this code into your index.vue file.

Custom Changes

A couple of differences from the suggested code snippets will be the background image and the banner title. For the background image, we will take the API ID from that field and add it to the <section> block's inline style and add some styling for this background image here.

For the title, we'll use the asText method to make sure it's output the title as a <h1> and take control of the styling. Next, we'll continue in that vein and explore styling and preview our component locally as we do our CSS.

Full Suggested Code

Below you can see the full code for the fields that we should add:

Copy
<template>
  <section class="section" :style="{ backgroundImage: 'linear-gradient(rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.6)), url(' + slice.primary.background.url + ')' }">
    <h1 class="banner-title">
        {{ $prismic.asText(slice.primary.title) }}
    </h1>
    <prismic-rich-text :field="slice.primary.description" />
    <prismic-link :field="slice.primary.link">{{ slice.primary.linkLabel }}</prismic-link>
  </section>
</template>

5. Preview Locally & Style Component

To do our styling we'll launch our Local Component Dev Environment so that we can see live updates for the changes to our code.

Launch the Local Component Dev Environment

Our Dev Tools come with a built-in local development environment. This tool will put together your component code, Slice model, and mock data to allow you to develop your component in isolation without the need to add data to your Prismic repository.

If it isn't launched yet, open a new terminal window and run the following command:

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

Once you launch it will be automatically prompted to a new browser tab on http://localhost:3003.

What's Storybook?

To learn more about this powerful tool and what else you can do with it, visit our full documentation:

Component Level CSS

Now you'll see what your component will look like with the mock data so you can begin styling and editing your component. As you've seen, the component is quite plain, and the image is probably not aligned and wrapped correctly, so we'll start there.

First give your banner section a class name, like the one below:

Copy
class="banner-background"

Then in the style section of your component, you can add the CSS to improve your component looks. We want the styling here to be specific to this component and not bleed into other components, so we add the scoped attribute to restrict the CSS to this file. We can then add the styling for the banner background as below:

Copy
<style scoped>
.banner-background {
  margin: -70px 0 80px;
  padding: 10em 0 8em;
  background-position: center center;
  background-size: cover;
  color: #ffffff;
  line-height: 1.75;
  text-align: center;
}
</style>

Now save and preview your changes in Storybook, http://localhost:3003. Looks good? Great, let's add the rest of our styling. The first thing to do is to add your class names and then your styles.

Below is our full code for this component:

Copy
<template>
  <section class="banner-background" :style="{ backgroundImage: 'linear-gradient(rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.6)), url(' + slice.primary.background.url + ')' }">
    <div class="banner-content container">
      <h1 class="banner-title">
          {{ $prismic.asText(slice.primary.title) }}
      </h1>
      <prismic-rich-text :field="slice.primary.description"  class="banner-description"/>
      <prismic-link :field="slice.primary.link" class="banner-button">{{ slice.primary.linkLabel }}</prismic-link>
    </div>
  </section>
</template>

<script>
export default {
  props: {
    slice: {
      type: Object,
      required: true,
      default() {
        return {}
      },
    },
  },
}
</script>

<style scoped>
.banner-background {
  margin: 0 0 80px 0;
  padding: 10em 0 8em;
  background-position: center center;
  background-size: cover;
  color: #ffffff;
  line-height: 1.75;
  text-align: center;
}

.banner-content {
  text-align: center;
}

.banner-title, .banner-description {
  width: 90%;
  max-width: 490px;
  margin-left: auto;
  margin-right: auto;
}

.banner-title {
  color: #ffffff;
  font-size: 70px;
  font-weight: 900;
  line-height: 70px;
}

.banner-button {
  background: #ffffff;
  border-radius: 7px;
  color: #484D52;
  font-size: 14px;
  font-weight: 700;
  padding: 15px 40px;
}
.banner-button:hover {
  background: #c8c9cb;
}

@media (max-width: 767px) {
  .banner-background {
    margin: 0 0 40px;
    padding: 10em 0 6em;
  }

  .banner-title {
    font-size: 50px;
    line-height: 50px;
  }
}
</style>

6. Push Slice to Prismic

Finally, now we've finished developing our component, we'll push our Slice to Prismic. Jump back over to The Slice Builder, update your screenshot, which will be used as a preview for your content writers to choose Slices, and send your content model (Slice) to Prismic for future use.

Congratulations you've just built your first component! Now let's do the rest.


Next and Previous articles


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.