By now, setting up a theme should be second nature. We practiced this numerous times in Chapter 4, Getting Started – Creating Themes. But, in case we need a refresher, we can refer to that chapter for any outstanding questions.

We can begin by navigating to the themes folder and create a new folder named octo. This new folder will contain all of the files we will be using to develop our theme:

Next, we will create five additional subfolders within our main themes folder that will contain our CSS, Images, JavaScript, Twig templates, and any third-party vendor libraries such as Twitter Bootstrap. To ensure that we are all able to follow along without any naming conflicts, please make sure to name the five subfolders as follows:

We will be referencing these subfolders throughout the development of our theme with each folder containing the following files:

Go ahead and copy screenshot.png from the Chapter05/start/themes/octo folder and place it within the themes/octo folder. Drupal will use this screenshot within the Appearance page to help visually identify our theme.

Any new theme must contain an *.info.yml file to define metadata, style sheets, libraries, and regions so that Drupal 8 recognizes that there is a new theme available to be installed. Let's begin by opening up our favorite text editor and creating a new file named octo.info.yml.

Our new configuration file will contain the following required metadata to start with:

name: Octo
type: theme
description: 'A responsive Drupal 8 theme.'
core: 8.x
base theme: false

Make sure to save our changes and clear Drupal's cache. This will ensure that the theme registry picks up our changes.

Navigate to /admin/appearance and locate our new theme on the Appearance page. If we look within the Uninstalled themes section, we will see the Octo theme available to install, as shown in the following screenshot:

To install our theme, click on the Install and set as default link. With our new theme now installed, we can browse the homepage by clicking on the Back to site link in the admin menu. We will see that the original Bartik theme styling has been replaced with the non-styled look of our Octo theme, as shown in the following screenshot:

Currently, our theme is using the default Drupal 8 regions as we have not specified any within our configuration file. This would be fine if the content in our Mockup worked nicely with those regions, but as we discovered earlier, there are definitely some regions outside of the default that will need to be defined.

For example, Drupal 8 provides only a single Footer region, and we will clearly need more than one region in our footer to accomplish the three blocks of content, as well as the two additional blocks of content that fall below our footer.

Let's edit our octo.info.yml file and define the specific regions we will need to place blocks of content needed by our homepage and interior pages. Begin by adding a new block of metadata to define regions with the following:

regions:
  header_top: 'Header Top'
  header: 'Header'
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  page_top: 'Page top'
  page_bottom: 'Page bottom'
  highlighted: Highlighted
  headline: 'Headline'
  breadcrumb: Breadcrumb
  before_content: 'Before Content'
  content: Content
  sidebar_first: 'Sidebar first'
  sidebar_second: 'Sidebar second'
  after_content: 'After Content'
  footer_first: 'Footer first'
  footer_second: 'Footer second'
  footer_third: 'Footer third'
  footer_bottom_left: 'Footer Bottom Left'
  footer_bottom_right: 'Footer Bottom Right'

Make sure to save any changes to our octo.info.yml file and then clear Drupal's cache. Finally, we will want to confirm that our newly defined regions are available to be used by navigating to /admin/structure/block and looking at the Block layout page to verify that our regions are now available, as shown in the following image:

So far, we are progressing very nicely with adding our required metadata and regions that our theme will need, sort of a wash, rinse, and repeat pattern; with options like adding configuration information, clearing cache, and verifying changes being available. How about taking a look at adding some assets that we will need before we start tackling different page sections of our site?

Drupal 8 definitely manages assets in a different way than we were used to in Drupal 7. With the introduction of Yaml configuration and asset libraries, we now have a separation of how CSS and JavaScript is referenced and used. Of course, we should be experts by now, but to recap, the process contains two steps.

We will be using the Twitter Bootstrap library again with our theme. To ensure that we all use the same version of Bootstrap, we have provided a copy within the exercise files.

Begin by copying the Bootstrap folder contained in the Chapter05/start/themes/octo/vendor folder and place it within the themes/octo/vendor folder.

With Bootstrap accessible by our theme, we can create a new file named octo.libraries.yml and save it within the root of our theme. Next, we will want to add the following metadata to our octo.libraries.yml file:

bootstrap:
  version: 3.3.6
  css:
    theme:
      vendor/bootstrap/css/bootstrap.min.css: {}
      vendor/bootstrap/css/bootstrap-theme.min.css: {}
  js:
    vendor/bootstrap/js/bootstrap.min.js: {}
  dependencies:
    - core/jquery

The metadata we added basically starts with a variable name for how we want to access the library from our configuration file such as octo/bootstrap. Next, we need to make sure that we reference the version of the library we are adding followed by the path to the CSS, JS, and any dependencies. When dealing with YAML files, it is important to make sure that you have the proper indentations or else we may experience errors.

Now that we have our octo.libraries.yml file in place and have added a reference to Bootstrap, we need to open up our octo.info.yml file and add a pointer to our library in order for Drupal to recognize any assets that need to be loaded into our theme.

Open up the octo.info.yml file, and add the following prior to our regions section:

libraries:
  - octo/bootstrap

Make sure to save our changes and then clear Drupal's cache. If everything was successful, we should be able to navigate back to our homepage and note the Bootstrap CSS affecting out page elements. We can also confirm this by inspecting the page with Google Chrome and see in fact that Bootstrap is being loaded properly, as shown in the following screenshot:

Now that we have a sense of how libraries are added to our theme, we will need to add additional assets including our images, CSS, and JavaScript files that we will be using to create our theme throughout the remaining lessons.

Begin by opening the Chapter05/start/themes/octo folder and copying the contents of the css, img and js folders and placing them into their respective folders inside the themes/octo folder, as shown in the following screenshot:

With our base assets in place, we will need to open back up our octo.libraries.yml file within our editor and add a global library entry that points to our new files.

Open up octo.libraries.yml and add the following entry directly below the bootstrap entry:

base:
  version: VERSION
  css:
    theme:
      css/styles.css: {}
  js:
    js/octo.js: {}
  dependencies:
    - core/jquery

It's important to remember that the formatting and order of these entries is crucial in making sure that we don't experience any Drupal errors, so feel free to look at the completed octo.libraries.yml file located in the Chapter05/end/themes/octo folder as a reference. Just to clarify, we want to make sure that Twitter Bootstrap loads first, then our base styling and scripts.

Once we have completed adding the new entry, make sure to save the file, then open up octo.info.yml, and add the following reference to our base library so that it reads as follows:

libraries:
  - octo/bootstrap
  - octo/base

Save the file and don't forget to clear Drupal's cache, this will ensure that our changes take effect. Now if we browse back to our homepage and inspect the markup, we will see that the new references have been added to our page and our styling has changed again:

We will be adding additional assets to our octo.libraries.yml file as we address each page of our site that needs additional functionality, so it is important to be comfortable with this process.

One last thing we need to make sure that we take care of before finishing this chapter is considering how Drupal handles default files. That is, files that we upload such as a logo, an image field on a content type, or any inline images that we would place directly in the content of our page.

Since we are using database snapshots to save time on having to recreate content, we want to make sure that any images that the database may be referencing are available to us and we don't encounter broken image paths.

We can take care of this by copying the contents of our files folder located within the Chatper05/start/sites/default/files folder and placing them into the sites/default/files folder of our Drupal 8 instance. If prompted to replace or overwrite files, go ahead and say yes to ensure that we have all the files needed.

Once we are done, our sites/default/files folder should contain subfolders with images organized based on the upload date, inline images, and styles for image derivatives, as shown in the following screenshot:

We have now completed adding all the assets and initial libraries that our new custom theme will need—a great start to strengthen our theming skills.