One Theme Documentation

Prologue

This documentation will change and grow over time. What is below as of September 12, 2018 is very minimal information to get people started working with the One template. More and detailed information will be added over the following weeks and update notices will go out to users when major changes have occurred.

Known issues

The One theme has some known issues with work arounds. This section of the document discusses those issues and how to fix them.

Problem:
There are pages showing up in breadcrumbs and the Explore menu that have not been published and are not linked.

Why:
This happens when a sub page is published, but the parent page is not. 

Solution:
The solution is to publish the parent page with hide in nav selected on the parent page.

The One theme processes tables of information created in the Text component so they will appear better on mobile devices and have better attributes for screen readers. Tables being used for layout purposes will experience issues. It is not recommnded to use tables for layout purposes as this practice is not good for people that use assistive technologies to view web pages. If you are unsure how to format information on a page in the CMS without using a table, please file a JIRA ticket using the "Request CMS Support" button in the bottom right-hand corner of the browser window on this web site and someone will contact you to help with your layout issue.

There is an issue with FontAwesome icons in Text components that will make the component uneditable via the Expanded text editing interface inside the author interface after they have been inserted. You should not use FontAwesome icons in the Text component. If you need to use them please use the HTML component for the icons and any associated text.

UPDATE (09/19/2018): A fix for this was merged to the production server that will deactivate FontAwesome icons in the Edit mode within Ensemble. They will appear in Preview and in published pages and you will still be able to add them within a Text component via the HTML view. Please note that we are using FontAwesome 5 Pro, so you will need to use the classes for that version of FontAwesome, e.g., class="fab fa-facebook".

Switching site design theme

The process for switching the site design to the One theme is manual and is detailed below. If you encounter any issues you can easily change the site back to the Moss theme before publishing the site level page using the instructions below and substituting Moss for One. The site will not switch until you have published the site level page, but all pages will gain the One theme in the authoring environment instantly. Make sure your content contributors know you are doing this change and that it will not affect live pages, or pages that need to be changed before the site level is published. That means, until the site level is published all pages under it that are published will still have the old theme.

1. Click the checkbox next to the site name in the My SItes view

2. Click the View Properties button

3. Click the Edit button

4. Click the Advanced tab (if you cannot see the Advanced tab then your user does not have web_admin level permission and you cannot switch the site theme)

5. Click the icon at the far-right of the Design input field

6. Click on the One title in the left column of the design selection dialog

7. Click the blue checkmark in the top-right corner of the dialog

8. Click the Done button in the top-right of the properties dialog

The theme is now active in the authoring environment. In order to publish the theme:

9. Go back to the My Sites page

10. Click the checkbox next to the site you just changed

11. Click the Publish button in top toolbar and then choose Publish

The change may take a few minutes to propagate across pages, and you may need to publish the home page in order to speed things along.

Note: The following areas of the template are not to be modified for any reason without prior consent from Advancement | University Relations. Modifying these areas will violate the 80/20 rule that has been established for Virginia Tech branding as well as the consistent user experience the CMS is supposed to provide all users.

  1. The header - the black bar and main white header area
  2. The main navigation and search drawers
  3. The default footer

Modifying is defined as anything that changes styles, behaviors, or content within these areas beyond what the theme and CMS provide by default.

Parent organizations

Websites in Ensemble are able to list an organization as its “parent”. This informs the user that a website is affiliated with another group on campus. For example, a research institute or department may fall under one or more colleges. To set a parent organization on your site, follow the steps listed in the documentation: 

Home page design

If you’re moving from Moss to One, you will notice some differences about the home page type. There is no longer a default gallery component embedded at the top of the page. Instead, there is an optional call to action (CTA) component. Underneath the call to action component is a space for any component, should you decide not to use the CTA.

The home page content type no longer includes an embedded gallery component. The CTA component is now embedded at the top of the page by default. However, a gallery component may still be the first thing on the page if you wish. Follow these steps to place a gallery component at the beginning of your home page content:

  1. From My Sites, select your home page.
  2. Click Open.
  3. Leave the call to action component unconfigured. Find the drop zone directly underneath it.
    • Note: The default call to action component will NOT display on the published page if left unconfigured, but will STILL SHOW UP in edit mode.
  4. Drag a gallery component out of the left-panel, and into the drop-zone below the call to action.
  5. Click the gallery component to reveal its toolbar.
  6. Click the wrench icon to open the gallery’s properties window.
  7. Select Carousel from the Gallery Type select box.
  8. Select Hidden from the Controls Style select box.
  9. Click the Items tab.
  10. Click Add Field.
  11. Drag an image from the assets library onto the gallery component.
  12. Click the checkmark icon to save the gallery component.

The featured component is a drop-zone just beneath the embedded call to action component on home pages. You may put any component you like in it, but pay attention to the space around the component in the published page. You may need to create some left and right margins. To do this, use the following steps:

  1. From My Sites, select your home page.
  2. Click Open.
  3. Leave the call to action component unconfigured. Find the drop zone directly underneath it.
    • Note: The default call to action component will NOT display on the published page if left unconfigured, but will STILL SHOW UP in edit mode.
  4. Drag a container component out of the left-panel, and into the drop-zone below the call to action.
  5. Click the container component to reveal its toolbar.
  6. Click the wrench icon to open the container’s properties window.
  7. Locate the CSS Styles textarea.
  8. Copy and paste this code into it:
  9. padding: 0 5%;margin-top: 2em;
  10. Click the checkmark icon to save the container.
  11. The container is now ready to receive any component.

The call to action link component is meant to encourage the user to take a specific action, such as: donating, applying, visiting, etc. It may be placed anywhere you need an attractive link, and is embedded inside the call to action component. It comes pre-configured with different color and font variations. Please refer to the official documentation for the call to action link component, listed here:

The call to action component (CTA) is meant to draw the user’s attention to a brief, but important, message, and entice the user to take an action. It is now included at the top of the home page type by default, but its use is not mandatory. Simply leave a CTA unconfigured, and it will not display on the published page. Note – it will still display on the page in edit mode. Please refer to the official documentation on the call to action component, listed here:

Widgets

Widgets are combinations of components, classes, and content that yield a specific look within the theme. The vt.edu home page contains examples of all the widgets documented below. The documentation includes step-by-step instructions and screen shots of component configurations to help you build the widgets within your own site.

NOTE: Most of the widgets can be made and maintained by the novice user with base experience with Enseble. The Featured Item Grid widget is the only exception and is for advanced users only until a component can be built to supply the functionality to everyone.

 

FontAwesome changes to 5.x Pro

The One theme is using FontAwesome 5 Pro and does not use the actual font any longer. This is due to accessibility concerns that we switched the implementation from the font to the SVG method. You can still insert elements into Text components via the HTML view in the Expanded editing mode. There are new classes that need to be used and they are described on the FontAwesome site.

Note: There is a known issue at the moment with adding FontAwesome icons to Text components and not being able to edit the text in the Expanded view after doing so. We are actively working on this issue and should have a fix soon. If you need assistance editing content in a Text component with FontAwesome icons in it, please file a ticket or send an email to: askvt@vt.edu

UPDATE (09/19/2018): A fix for this was merged to the production server that will deactivate FontAwesome icons in the Edit mode within Ensemble. They will appear in Preview and in published pages and you will still be able to add them within a Text component via the HTML view. Please note that we are using FontAwesome 5 Pro, so you will need to use the classes for that version of FontAwesome, e.g., class="fab fa-facebook".

Utility classes

The One theme uses and extends existing utility classes while also adding new classes specifically for the One theme. This section of the document will cover the utility classes enhancements and the new ones that are specfic to the One theme.

Utility classes get applied to components by:

  1. Click on the component
  2. Click the wrench icon to access the configuration dialog
  3. Type or paste the class into the CSS Class field on the first page of component configuration options.

This utility class works on images that have transparent backgrounds as before, but it will now turn off the portrait and square image treatment within the theme. Add this class to Image or List components that you don't want to have reformatted with the new treatment. The images below show the effects of adding the class to a portrait image.

Below is a portrait formatted image with the deafult theme effect applied to it.

Portrait Image With Processing

Below is a portrait formatted image without the default theme effect applied to it by using the vt-transparent-bg class on the component.

Portrait Image No Process

This utility class prevents the table processing script in the One theme from operating on a table or all tables within a Text component. This will not put the header information into the table data cells for the mobile view of the table. It does not override the mobile formatting of the table and should be used only as a last resort.

This utility class is specific to the List component table display option. If you have a List that uses the DisplayType -> Table under Display Options in the configuration dialog you can hide the header row of the table with this class. This class should be used only when there is sufficient context elsewhere around the List component table to explain its contents as hiding the table header without proper context could be considered an accessibility violation.

The image below shows a List component with DisplayType set to Table and the table header is visible.

The image below shows a List component with DisplayType set to Table and the table header is not visible because the utility class was added to the component.

This utility class is specific to the List component and will make unequal hieght list items stretch to match their heights. The images below show the effects of the class on a List component.

Below is a List component with the default item rendering for DisplayType -> Columns.

Below is a List component with the utility class item rendering for DisplayType -> Columns.

This utility class allows you to hide footer items that don't display information on a page, e.g., Analytics components, custom styles or scripts in an HTML component, etc. so the grey in-page/inherited footer area won't display the grey box above the default footer should there be nothing else in it that might need to be displayed. The non-display items with this class will still apply scripts and styles, but will not cause the grey box to appear unnecessarily.

The image below shows a grey bar above the default footer due to an HTML component being inherited with only style and script tags for site customizations.

The image below shows the grey bar above the default footer removed by adding the utility class to the HTML component with the style and script tags.

The vt-text-margins class can be applied to any component you want to have match the standard Text component margins.

The vt-open-newTab class will add a target="_blank" to ALL links in a component so they open a new tab or window with the link URL.

Accessibility

A major feature of the One theme is its orientation to accessible best practices. There are new tools at your disposal to help you create accessible web sites in ensemble. Using One will improve your page’s accessibility in many ways under the hood, by providing good, semantic HTML, and adhering to accessible user interface paradigms.

Alternative text for images

Images generally need alternative text for assistive technology. The alternative text is read by screen readers to describe images to users, and displays in place of the image should it fail to load. It is also indexed by search engines that are crawling the page. Writing good alt text takes some effort; pay attention to the context of the image as that will determine the level of detail needed to describe it. Here are some guidelines:

  • If you’re using a caption on an image, avoid any redundancy between the alt text and the image caption. The alt text can be less descriptive in this case because it has the supporting caption text.

  • If the image falls within a paragraph, think about the context of the image. The more thoroughly the surrounding text describes the image, the more brief your alt text can be.

  • Never use a phrase like “image of…” because it is unnecessary. The user already knows you are describing an image in this case.

  • Alt text should be as succinct as possible.

  • If the image also serves as a link, do not include a phrase like, “link to…” because the screen reader will identify the link before reading the alt text.

Page headings

Use page heading elements (h1 - h6) for meaningful sections of content within the page, and never use them for styling purposes. Using page headings incorrectly will alter the document outline, which screen readers use to help users navigate the page.

Heading levels

The call to action component and the call to action link component work together, but can create accessibility issues under certain circumstances. For example, it is possible to choose a maroon background for the CTA, while also choosing a maroon background for the CTA link. This is inaccessible and does not meet our legal obligations for accessibility.

CTA with bad accessibility
CTA with good accessibility

The One theme has improved keyboard navigation built-in. Focus states are consistently visible throughout the theme.

A major new feature to the One theme is the universal access menu. The universal access menu is an accessibility focused modal dialog, which contains tools to help consume information on the page. Over time, as more tools become available, they will be located in this menu. The universal access menu is also where users go to report accessibility issues. To open the universal access menu, tab to or click the universal access icon in the topmost menu bar of the page.

Local assets and customization

You may still customize your site using local assets. However we ask that you please consider the main menu and other navigational elements such as breadcrumbs and the explore menu, the header, and the footer as special entities. They must have a consistent look-and-feel throughout the site so that users do not find themselves lost or learning new interface patterns between sites. The header, main menu, and footer are known as the C-clamp, since it forms a backwards letter-c-like shape around the main body of content. While content such as menu items within the C-clamp may change from site to site, these items always look the same, have the same behavior, and are always in the same locations.

While we ask that no changes be made to the functionality and design of the header, we realize that some organizations have situations like industry partnerships which may require changing the logo. This is acceptable but will be done on a case-by-case basis, with permission from University Relations.

Yellow border showing the header
Header Section
Yellow border showing the main menu
Main menu
Yellow border showing the footer
Footer Section
Yellow border showing the breadcrumb and explore menu sections
Breadcrumbs and Explore menu