Skip to main content
  • Home
  • Tutorials
  • Creating a CleanSlate Theme Using the WVU Design System

Creating a CleanSlate Theme Using the WVU Design System

Initial Theme Setup

Follow these instructions to set up your theme:

  1. Request an account/site in CleanSlate. Select the WVU Design System base theme option. Our team will create a repo on Bitbucket, grant you permission to write to the repo, and send you the link. We will also set up a space for your new site in CleanSlate and give you access. If you do not have a Bitbucket account, email Steven Spriggs from University Relations - Digital.
  2. Visit your repo’s URL and clone your theme (we recommend storing your local projects in a directory called sites/cleanslate_themes).
  3. Using terminal (we recommend using iTerm2), cd into your project directory.
  4. Type npm ci. This will pull in any dependencies, for example Bootstrap.
  5. Edit your theme’s readme.md file to reflect the new author and theme instructions.
  6. Make an initial commit. In your terminal window, make sure you are in your project directory. Type git add --all, git commit -m "Initial commit.", then git push origin master. Visit your site’s repo in Bitbucket to make sure your edits went through (the main page of your repo should contain the contents of your readme.md file). You are now ready to build your theme.

Build Your Theme

To begin building your theme, cd into your project directory via terminal, edit the theme files in a text editor, and make sure you are running Gulp (when you are in your project directory in terminal, type gulp). For general information about editing theme files, see the CleanSlate Getting Started Guide. Then check out our documentation on using the WVU Design System to create a theme and build templates. If you have questions, check out the FAQs.

Test Locally With Hammer VM

Test your theme locally with Hammer VM. This way you can make sure your site won’t break when you update your theme files. See the Hammer VM docs on Github to install and use.

Commit Your Theme

Once you’ve made edits and tested in Hammer VM, you are ready to commit your theme. In order to do this, y ou need to know Git or use some sort of version control software. Once you have installed Git, use the command line to cd into your project directory. Type git add --all, git commit -m "{enter a coremmit message that describes your edits}", then git push origin master.

Sync Your Theme

Once you’ve committed your changes to the repo, it’s time to sync your theme with CleanSlate. Log in to CleanSlate, navigate to your site, then in the top navbar, click Sync Theme. You and your editors are now ready to begin editing and publishing content.

Configure Your Theme

Below are basic instructions to get a site configured, along with creating/configuring a basic home page and back page..

Sitewide Configuration

Some elements are configured at the site level. Want to tell CleanSlate how many levels your dropdown menu should be? Want to set styles for your backpage headers? Want to add links to your social media accounts and have them auto-populate in components that display them? No problem. You can set these options in Site Data (go to your dashboard, then click Settings, then click the Data tab). Here are some basic site configuration options.

Below is a reference guide for your custom site data, along with what each data field does, and the version in which it was introduced.

Data Field Description Version
apply_link_1 Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the text of the button. 1.0.0
apply_link_1_url Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the URL of the button. 1.0.0
apply_link_2 Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the text of the button. 1.0.0
apply_link_2_url Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the text of the button. 1.0.0
apply_link_3 Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the text of the button. 1.0.0
apply_link_3_url Use this if you want colored buttons to show up in either your masthead or nav bar (use masthead--buttons or nav--buttons). This is the text of the button. 1.0.0
classes_wvu_backpage_header Apply classes to your wvu-backpage-header components accross your entire site. 1.0.10
classes_wvu_backpage_header__h1 Apply classes to your backpage header <h1>s accross your entire site. 1.0.0
classes_wvu-footer-links Apply classes to the links in your footer across your entire site. 1.0.0
co_brand_subtitle If you are using co-branding in your masthead, add a subtitle (useful for faculty sites to list a faculty member’s title). 1.0.0
disable_component_styler Disable the component styler if you don’t want content editors to use be able to use it. 1.0.0
disable_primary_nav Disable the primary navigation, for example if your site is only a landing page. 1.1.1
facebook_url Enter your Facebook URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
flickr_url Enter your Flickr URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
github_url Enter your GitHub URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
has_alternate_logo The URL of your logo (you must upload to CleanSlate). Omit the https:// part of the URL. 1.0.0
has_co_brand Set to true if you your site is co-branded in the masthead. 1.0.0
instagram_url Enter your Instagram URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
linkedin_url Enter your LinkedIn URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
masthead_college_link_address URL of college link. 1.0.0
masthead_college_link_title URL of college title. 1.0.0
masthead_color Enter 'gold' if you want a gold masthead. 1.0.0
masthead_logo_url URL of alternate logo for masthead. 1.0.0
masthead_title If using the standard masthead, this is what shows up below the “West Virginia University” signature. 1.0.0
nav_dropdowns Enter 'true' if you want dropdowns. 1.0.0
slot_{11,12,13}_{property}

You can add components to all of your pages using the same properties found in slots.

NOTE: this has been removed as of Version 1.2.5.

1.0.0
syndication_url Enter your RSS feed URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
twitter_handle Enter your Twitter handle for the Twitter Widget component. 1.0.0
twitter_url Enter your Twitter URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0
youtube_url Enter your YouTube URL if you want it to show up in the masthead, nav, or social media pattern. 1.0.0

Page-specific Configuration

Each page has a set of data attributes that you can populate in order to make use of certain components. For example, let’s say I have a back page that requires a landing page header instead of the standard header. I would want to remove the standard header by checking the box next to “Remove header” in the page’s custom data attributes.

Here are the page-specific custom data attributes:

Data Field Description Version
Alternate URL If this page represents content that is being pulled into a featurette, but you want the featurette to links elsewhere, add the URL here. 1.0.0
Remove header Removes the standard backpage header. Useful if you want to add a fancy landing page header. 1.0.0
If blog article, show hero Removes standard blog header and adds a hero component above your blog body copy. 1.0.0
Hide blog index author? Hides the author of blog articles in a blog index. 1.0.0
Remove breadcrumbs Removes breadcrumbs from a the page. 1.0.0
Description If this page has content that is being pulled into a featurettes component, this is the description that is pulled into the featurettes. 1.0.0
Show header label If your header needs a label above it, check this box. 1.0.0
Show header subhead If your header needs a subhead, check this box. 1.0.0
Link text If this page has content that is being pulled into a featurettes component, this is the text that will appear in the call to action. 1.0.0
Search action If you are using the Big Search component, this is the search action of the form. 1.0.0
Search index ID If you are using the Big Search component, this is the ID of the parent page of the pages you will search. 1.0.0
Content Keys for Big Search If you are using the Big Search component, these are keywords that can be searched. 1.0.0
Thumbnail alt text If this page has content that is being pulled into a featurettes component, this is the text that will appear at the alt text of the thumbnail. 1.0.0
Thumbnail URL

URL of an image you have uploaded to CleanSlate. If this page has content that is being pulled into a featurettes component, this is the URL of the thumbnail image. Also gets pulled in when sharing on social media.

Do not use the full URL of the image. Your URL will look like this: http://supertheme.sandbox.wvu.edu/files/d/8bb6c9ef-41e9-4528-b6ba-91cda89c597c/27518a0052xx.jpg but you need to omit beginning http://supertheme.sandbox.wvu.edu part, the d/ and whatever is after the trailing slash (including the slash), in this case /27518a0052xx.jpg. So you would paste in /files/8bb6c9ef-41e9-4528-b6ba-91cda89c597c.

1.0.0
Thumbnail URL square

URL of an image you have uploaded to CleanSlate. If this page has content that is being pulled into a featurettes, this is the URL of the thumbnail image. This is when the image has a 1:1 aspect ratio. You’d want to use this for a testimonials component or a profiles component.

Do not use the full URL of the image. Your URL will look like this: http://supertheme.sandbox.wvu.edu/files/d/8bb6c9ef-41e9-4528-b6ba-91cda89c597c/27518a0052xx.jpg but you need to omit beginning http://supertheme.sandbox.wvu.edu part, the d/ and whatever is after the trailing slash (including the slash), in this case /27518a0052xx.jpg. So you would paste in /files/8bb6c9ef-41e9-4528-b6ba-91cda89c597c.

1.0.0

Adding Components via the Super Template

You will notice your theme has a template called the Super Template. This lets you add components through the CleanSlate admin, rather than hard-coding components into your templates. This is done through “slots.” To add a component to a slot, check out our tutorial on using slots with the Super Template.

Testing the Super Template with Hammer VM

See our tutorial on Testing Shared Partials/Super Theme with Hammer VM.