2. Building pages

A preview of what you’ll build:

This tutorial has an accompanying GitHub repository called carbon-tutorial-vue that we’ll use as a starting point for each step. If you haven’t forked and cloned that repository yet, and haven’t added the upstream remote, go ahead and do so by following the step 1 instructions.

With your repository all set up, let’s check out the branch for this tutorial step’s starting point.

Note: This builds on top of step 1, but be sure to check out the upstream step 2 branch because it includes the static assets and fixes required to get through this step.

Install the app’s dependencies (in case you’re starting fresh in your current directory and not continuing from the previous step):

Then, start the app:

You should see something similar to where the previous step left off.

In our last step we added our styles, component and icon packages. Now that we’re building the pages with grid, we need to install one more Carbon package. Stop your development environment (CTRL-C) and:

In _carbon.scss, we need to configure our grid to use 16 columns instead of the default 12 columns. We do this by adding grid-columns-16: true in our $feature-flags.

Note: Like before, the feature flag still needs to come before the Carbon styles.scss import.

Run yarn serve so we can begin building.

Let’s add our grid elements to LandingPage.vue.

In order to use the grid, we need to wrap everything in a <div class="bx--grid">. We can continue to make rows by adding a <div class="bx--row"> inside the grid, as well as make columns within those rows by adding <div class="bx--col-[breakpoint]-[size]">.

Our column sizes are specified by the number of columns they’ll be spanning. If we use bx--col-lg-4, it means it’ll span 4 of the 16 columns. If we use bx--col-lg-8 it means it’ll span 8 of the 16 columns, and so on.

We’ve included the designs for this tutorial app in the design.sketch file found as a top-level file in the carbon-tutorial-vue repository. But, if you don’t have Sketch installed and available to inspect the design, we’ll provide screenshots.

Pro tip: CTRL-L toggles the layout in Sketch.

We’ll break this down into three rows. The first row with the gray background doesn’t appear to need any columns. The second row with the white background looks like it has two columns of different widths. The third row with the gray background looks like it has four columns of equal width.

We’ll make rows like so:

We added a class of bx--grid--full-width to the grid container since our rows need to expand the whole page without any margins. We also added some custom classes like landing-page, landing-page__banner, landing-page__r2, etc., which we will use later.

Also, take notice of the second row. The tab content only covers 7 columns at this large viewport to prevent overly-large line lengths, so we needed to add a 1 column offset bx--offset-lg-1 to second column to fill the full 16 columns in the grid. Then, both of those columns have bx--col-md-4 classes so they are of equal width at medium-sized viewports.

We’ll start adding HTML elements and components by row.

In our first row we’ll use a CvBreadcrumb component.

We can now add our component to the first row, along with a header, like so:

You may notice that the styles look off. Don’t worry, we’ll fix these later.

In our second row we’ll use CvTabs and CvButton components.

Modify the second row to use the Tab component.

Note: We’re using the grid for the page layout, but we also need to apply the grid within the tab content. When doing so, make sure the nested grid has the expected grid > row > col DOM structure.

Hold up! If you were to run DAP to check for accessibility violations, you’d see Multiple navigation landmarks must have unique labels specified with aria-label or aria-labelledby because both the CvBreadcrumb and CvTabs components use <nav> elements. To fix, add aria-label to the CvBreadcrumb opening tag:

Same goes for the CvTabs opening tag:

Give yourself a pat on the back if you actually ran the DAP tool. We’ll install the DAP tool in a later step, so don’t worry if you didn’t.

Next, we’ll need to add a styling override to move the tabs to the right on large viewports. Create a file _carbon-overrides.scss in src/views/LandingPage with this declaration block.

Then in LandingPage.vue add a style section with this import.

Note: We don’t have to include this in a separate file, but it’s nice to keep overrides separate from your application’s styling so when migrating to future Carbon versions and if there are breaking changes via different class names, you have a consolidated list of styling declaration blocks to review. We can now add our images and text for each column in the first CvTab in LandingPage.vue.

Now let’s set the image size in the style section of LandingPage.vue:

Assuming that the second and third tab would have a similar design, we would set them up in the same way. However, since our design specs don’t show those tabs, we’ll leave the code as is.

The third row will be created in a later tutorial, so we’ll just add the headers for now.

We’ve added basic layout styles in LandingPage.vue, so now let’s add type, color and spacing styles to match the design. We’ll be using our spacing tokens. In a new file src/styles/_carbon-utils.scss, add these imports at the top of the file so we can use Carbon breakpoints, tokens, and typography Sass mixins and functions:

Adding these tokesn, mixins etc. here means we can import them with a single line into any component that needs them.

Pro tip: CTRL-G toggles the grid in Sketch.

Back to LandingPage.vue, we need to add space above the breadcrumb and below the heading. For that, add:

with the other imports and

Referencing the spacing token table, 16px can be set with the $spacing-05 token. The design calls for 128px of space below the heading and that’s not in the spacing scale, we can achieve that in Sass by multiplying 32px ($spacing-07) by 4. We could use 128px or 8rem directly in our styling, but using our tokens preserves consistency should the token values get updated in the future.

Looking at the design, we need a wall-to-wall light gray background behind the banner and also behind the third row. This is a great opportunity to use a Sass mixin. We could put this at the top of LandingPage.vue, but it’s best practice to place mixins in a dedicated file, so create a _mixins.scss file in src/views/LandingPage.

Add the following in _mixins.scss. Per the design we need to use Gray 10 for our banner background color, which can be set with the $ui-01 color token. Also, we want the background to extend into the grid’s outermost gutters to go the full width of the viewport, so given the DOM structure, we can achieve that by setting the background in an absolutely positioned pseudo element.

After you have created _mixins.scss, import it at the top of LandingPage.vue. By now you should have three imports:

Now to use the new mixin, update the .landing-page__banner declaration block to:

Next, we can see that the h1 is using the heading-05 type token.

The Sketch symbol naming is consistent with the development Sass tokens to help translate design to development. So, looking up the type token, we know to use productive-heading-05:

For our second row, we need to fix the tabs vertical positioning to match the design. By inspecting the tabs component, you can see that the tab height computes to 40px. We can use that to create our negative top margin in rem units.

We also need to adust our vertical spacing and type treatment. Like before, it’s a matter of using spacing and type tokens like so:

Note: You may be wondering why there are vertical gaps between the type and spacers. Each type token has a line height that’s suited for its font size. The vertical spacers adjacently touch the line height boundaries and not the baseline, for consistency as well as development ease so margins and paddings don’t need to offset line heights.

Let’s also add some styles for the last row, even though that will get used later in the tutorial. You’ll notice that we get to re-use the landing-page-background mixin that we just created.

Ta-da! You should see a finished landing page! Now we can move on to the repo page.

Now in our RepoPage.vue we’ll add our grid containers in the template section.

We currently have RepoPage.vue that just contains a grid and placeholder content for the time being. In the next tutorial step we’re going to be querying an API to populate the CvDataTable component in this page. As a best practice to separate data fetching from the presentation components, go ahead and create a RepoTable.vue as a sibling to RepoPage.vue in src/views/RepoPage.

First, let’s pretend we’ve already built our table component and update RepoPage.vue with a script section.

Import RepoTable in RepoPage.vue.

Then below the import, include the following arrays to pass into the RepoTable component. We’ll be setting the rows array from an API in the next tutorial step, but for now, static example rows will suffice.

Next we need to make sure the RepoTable component and these arrays are available to our RepoPage component template. Your component export should look like the following to achieve this.

Here we used the data method of the component as the values logically are data in our component.

Lastly in the RepoPage.vue template, we need to simply replace Data table will go here with:

OK. So now our RepoPage.vue component is ready to use a component called ‘RepoTable’ so let’s create it so our page displays again.

First create a script section as follows:

In this component script we:

Next, let’s create the RepoTable template starting with the cv-data-table component.

Here we pass in the columns, title and helper text. If you view this you will see an empty table with headings.

Next add the rows inside of cv-data-table.

Here we use v-for to iterate through the data assigning a key and value to each row. The rendered output may not appear to have changed, although if you inspect using the developer tools you will find three empty rows. Next add the cell data inside the cv-data-table-row component.

Again we’ve used the v-for directive to iterate through our data adding key, value and the contents of the cell.

The last item we need to add is the description shown in the expanded content. Add the following as a sibling of cv-data-table-cell component.

Now you should have a working page rendering the sample content from the rows array.

This component consumes our properties and returns a Carbon CvDataTable. As for where the various CvDataTable* components came from? The CvDataTable story in Storybook was used to put together the data table structure.

Our styles for the repo page are mostly fine. We just need to update a few vertical spacing issues.

In RepoPage.vue, add the following style section:

Congratulations! We’ve now created our static repo page!

We’re going to submit a pull request to verify completion of this tutorial step.

Run the CI check to make sure we’re all set to submit a pull request.

Note: Having issues running the CI check? Step 1 has troubleshooting notes that may help.

Before we can create a pull request, stage and commit all of your changes:

Then, push to your repository:

Note: Having issues pushing your changes? Step 1 has troubleshooting notes that may help.

Finally, visit carbon-tutorial-vue to “Compare & pull request”. In doing so, make sure that you are comparing to vue-step-2 into base: vue-step-2.

Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We’ll close your PR so we can keep the repository’s remote branches pristine and ready for the next person!