Skip to content
Snippets Groups Projects
Select Git revision
  • master protected
  • develop default
  • feature/schema
  • 0.1.1
  • 0.1.0
5 results
Name Last commit Last update
css
design-system/it-osu-pl-drupal
images/osu-logos
js
node_modules
sass
templates
.gitignore
README.md
composer.json
composer.lock
gulpfile.js
package-lock.json
package.json
wcm8_theme.breakpoints.yml
wcm8_theme.info.yml
wcm8_theme.libraries.yml
wcm8_theme.theme
README.md

WCM8 Theme

Overview

This base theme will enabled by default for all sites built via the WCM8 starter kit. For now, we will build this as a stand-alone theme. Once we begin working on individual sites, we will transition to using this as the base theme if/when custom themes become necessary.

This theme uses the IT@OSU Pattern Lab as its base. The IT@OSU Pattern Lab incorporates many elements from Foundation v6, including the XY Grid.

You may think of this theme as the third layer of a theme system that gets more specific with each layer.

Layers:

  1. Foundation — Grid system, breakpoints, rem-calc function, other basic settings.
  2. IT@OSU Pattern Lab — OSU-specific design, framework-agnostic design elements, various mixins and settings.
  3. WCM8 Theme — This theme. Translates the PL components to a Drupal theme and adds other Drupal-specific elements.
  4. An optional sub theme — Adds various site specific elements.

(return to index)

Requirements

  1. Docksal
  2. Composer
  3. Node + NPM
  4. Gitflow
  5. A local version of the WCM8 Reference Site
  6. Components!*
  7. Bamboo Twig*
  • These can be required in the theme info file starting with Drupal 8.9, but for now they must be enabled before enabling theme.

(return to index)

Installation and Local Development Setup

  1. Follow these instructions to set up you local site.
  2. Navigate to the theme folder: cd web/themes/contrib/wcm8_theme.
  3. Run fin composer install to install any dev dependencies (all other composer dependencies should've been installed with the local site).
  4. Run npm install to download node-based dependencies.
  5. Run gulp to compile the theme and start watching for sass and js changes.

Gulp default task

The default gulp task (gulp) will compile the theme and then begin watching for changes to recompile as necessary. Type ^c to stop the task.

Contributing to this project

Never commit directly to the develop or master branches. All contributions should be added via pull requests. We will be using the git-flow branching model. This requires a one-time setup on your machine. And a one-time initialization of your local repo. Run git flow init within the root directory of the repo and accept all defaults during the init process.

Starting a new feature

From the develop branch run git flow feature start [featurename]. This action creates a new feature branch based on 'develop' and switches to it. Publish your local branch. Do all of your work on this branch, making as many commits as necessary.

Finishing a feature

When you are finished with a feature, run git flow feature finish [featurename]. If someone else was also working on the same feature branch with you, make sure you also pull in all of their changes before finishing the feature. In order to avoid unwanted conflicts, the person who started the feature should be the one to finish it.

Publishing a new release

TBD -- for now we will be using the develop branch on our reference site. Once we start creating individual sites, we will be using a tagged release of this theme. Tagging and releases will be handled by the theme maintainer(s).

(return to index)

Pattern Lab Integration

An exported version of our pattern lab is included in our theme as a dev-dependency and is located at design-system/it-osu-pl-drupal.

The scss files will get compiled with the theme's scss files, but the js and twig files will be actively referenced in production. Therefore this whole directory will be committed with the theme's repository.

You should not alter these files, but are able to use them downstream when building the theme. Because the scss files are recompiled with this theme's scss files, any variables or mixins included within the pattern lab files will be available to use in this theme. Similarly, you should also be able to extend any classes provided by the pattern lab scss files.

The Components! module is a requirement when using this theme. It allows for the mapping of twig files from pattern lab to this theme. In this case we create a namespace for each pattern lab category. See the wcm8_theme.info.yml file for our implementation.

(return to index)

Theme Structure

Libraries

All css and js must be registered as a library within the theme's libraries file. See the wcm8_theme.libraries.yml file for usage examples. You may also reference Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme on Drupal.org.

Any library that should be applied globally will need to be listed in the theme's info file. See wcm8_theme.info.yml for an example. You can see the global libraries listed in the following snippet:

libraries:
  - wcm8_theme/global-css
  - wcm8_theme/global-js
  - wcm8_theme/fontawesome

Libraries that are not attached globally can be attached within individual twig templates using the attach_library() function. See templates/navigation/menu--main.html.twig for usage example.

SASS Files

The sass directory contains two directories (base and components) and two top-level files (_hacks.scss and main.scss).

base

The base directory contains sass partials for global html elements or common Drupal elements that do not pertain to specific site components. These are often global styles and building blocks for other elements. This directory should be pretty small as many of these elements should originate in the Pattern Lab.

components

The components directory contains sass partials for specific components for a Drupal site built with the WCM8 starter kit. Examples include: content types, views, menus, regions, and other compound elements.

_hacks.scss

This file will load after all other scss and is used for quick, temporary hacks necessary to achieve your immediate theming goals. Everything in this partial should be considered temporary and eventually integrated into its own partial or ported back to Pattern Lab as necessary.

main.scss

This files imports all scss partials — Foundation, Pattern Lab, Base, Components, and Hacks — and then gets compiled into the theme's production css at css/main.css.

Javascript

Javascript should be added to this theme in one of two ways, globally via the behaviors directory, or packaged with a Pattern Lab component. There are also some special cases where js can be added via an external package (ex. FontAwesome). But in all cases, the js must be registered via the wcm8_theme.libraries.yml file.

Behaviors

Use this method when something needs to be available globally, or for something that is Drupal-specific and therefore wasn't included within the Pattern Lab.

There is a behaviors directory at js/behaviors. Behaviors work much the same way that they did in D7. However, instead of creating one massive behaviors file, we will be creating an individual file per behavior (or group of related behaviors) so that we can be better organized. Everything in the behaviors directory will be compiled and minimized to main.js.

main.js is already registered as a global library, so files that are added to the behaviors directory will not need to be registered individually in the wcm8_theme.libraries.yml file.

Pattern-Specific Javascript

In certain cases js will be added at the pattern level in the IT@OSU Pattern Lab project. These files can be found within the following directory: design-system/it-osu-pl-drupal/js/patterns. Each js file must then be registered as a library with the wcm8_theme.libraries.yml file. These libraries can then be added globally via the theme's info file or attached to a specific twig template. See Libraries for usage information.

Templates

The templates directory contains the actual twig files that Drupal will use to render the markup. Templates follow the same inheritance patterns we are used to from D7.

To integrate a component from pattern lab, you can include it in the theme-specific template file using either include, extends, or embed. See templates/navigation/breadcrumb.html.twig for an example from this theme.

See Twig and Template Resources for more information.

Images

Theme-specific images, such as those necessary for the header and footer, are stored in the images directory.

Breakpoints

Sass breakpoints are set in via the _settings.scss file that comes with IT@OSU Pattern Lab.

$breakpoints: (
  small: 0,
  medium: 640px,
  large: 960px,
  xlarge: 1280px,
  xxlarge: 1440px,
);

Breakpoints can be used within sass files with the include syntax such as the following:

.sample-class-name {
  width: 100%
  @include breakpoint(medium) {
    width: 50%;
  }
}

Furthermore, we replicate these breakpoints in the wcm8_theme.breakpoints.yml file to create configuration to interact with Drupal core's Breakpoints module. The primary need for this file is to interact with responsive image styles, but it could be used for other purposes in the future.

wcm8_theme.theme

This is the file where you can include various theme functions such as theme settings, template suggestions, preprocess functions, etc...

More info coming soon. See wcm8_theme.theme for existing usage examples.

(return to index)

Theme Methodology

When possible you should first look to alter the markup rather than solely use css or js to style the default markup that is provided.

Ways to alter the markup include:

  1. Template files — View modes can be very helpful for this, use them!
  2. Preprocess functions
  3. Admin UI saved to config (such as in views)

(return to index)

Creating a sub theme

TBD

(return to index)

Working with Foundation

(return to index)

Twig and Template Resources

  • The Bamboo Twig module (and most of its sub-modules) will be installed on all sites using this theme and provides some very helpful twig extensions. This is a great article that provides examples of how to use it.

  • Twig Debugging should be enabled on your local install to see template suggestions and theme hooks when inspecting a page.

  • Use Twig Vardumper to inspect variables available to your twig templates. This module is a dev requirement on our sites, but you will need to enable the module on your local install to use it.

  • Look at Working With Twig Templates from Drupal.org.

  • Official Twig Documentation

(return to index)

Other Theming Resources

SASS

BEM methodology

(return to index)