A WordPress theme that builds on top of ASU's canonical design tokens, and the official ASU Bootstrap theme, to deliver standards-compliant and accessible WordPress websites across ASU.
- ASU Web Standards 2.0
- Based on ASU's official design token libray for consistent adherence to Web Standards 2.0
- Utilizes the official ASU Bootstrap theme built on top of the design token library
- Accessibilty built-in: all Bootstrap markup and styling is approved by the ASU Accessibility community before release
- WordPress
- Utilizes standard WordPress features, such as page templates, widgets, and shortcodes, for easy and rapid development of standards-compliant WordPress sites
- Table of Contents
- Getting Started
- For Developers
- Project Structure
The theme provides a widget area, and corresponding widget, for displaying UDS-compliant banners across the top of every page in your site. These banners will appear below the hero area, and above all other content.
To create a banner, add the provided Notification Banner widget to the Global Banner Area on the WordPress widgets admin screen (or via the Customizer) and configure the banner as desired using the options provided. Make sure to set the Show Banner option to Yes in order to have the banner appear on your site.
To remove a page banner, either delete the widget from the Global Banner widget area, or set the Show Banner option to No.
The UDS-WordPress theme has three assignable menu areas:
- The main navigation menu, at the top of every page
- The main footer menu, at the bottom of every page
- The social media icons menu, shown above the main footer area
You build the main menu of your site using the built-in WordPress menu builder. The menu-building code behind the scenes, however, will enforce certain ASU Web Standards when it comes to the main navigation menu:
- menu items can be nested no more than three levels deep. Any menu you item to drag to the fourth level (or any level beyond that) will not appear in the menu.
- First level menu items will appear as entries in the main navigation menu
- Second level menu items will form dropdown menus beneath their parent item, unless there are also third-level items beneath them. In that case:
- the second level item will become a non-clickable column header, and all third-level items below it will form links in a single column
- any sub-menu with more than two columns will be rendered as a full-width 'mega-menu'
Here is an example of a main menu hierarchy, and how each item would be rendered in this theme.
You need to set up your development environment before you can do anything.
Install Node.js and NPM
- on OSX use homebrew
brew install node - on Windows use chocolatey
choco install nodejs
This is a WordPress theme, and you will need to have access, and administrative rights, to a WordPress site in order to do any development on the theme. It is not recommended to attempt theme development on a live server.
There are several solutions available for hosting local WordPress development sites on your own computer, including:
- Local by Flywheel
- Lando
- wp-local-docker by 10up
- VVV
- Visit Local by Flywheel and click the
Downloadbutton. - Choose your platform and enter some information (only the email field is mandatory), the download should start and you’ll be taken to a start-up screen, where you will select the
Let’s Go!button. After installation, you’ll be taken to the dashboard. - Proceed to create a new local WordPress install or connect to a remote service like WP Engine.
We are currently using WP Engine to manage our WordPress sites and to connect your Local By Flywheel installation to WP Engine you will need a WP Engine account and API key.
- To connect select the
Connecticon on the left hand side of your Local dashboard.
- After you have connected to WP Engine you will see all of the site available to your account listed within the
Connectarea.
- In order to connect to WP Engine you must click the
My Hostsbutton in the upper right corner of theConnectarea.
Then you will see a list of hosting providers to choose from.
- Select
WP Engineand sign in.
This will give you access to pull sites locally to work on.
For new project's select: ASU UDS Quickstart
* After you have pulled the site to to your local machine disconnect it from the host to ensure premature development is not deployed in the background. You can do this by clicking the same button used to Pull To Local to Disconnect.
You are now ready to clone the theme within the projects wp-content/themes folder.
- Review Lando Requirements to check your system against the hardware requirements.
- Install Lando
Lando will install all necessary underlying dependencies to run.
Lando constructs a Docker based development environment according to YAML files called recipes that guides the containers it builds, services available and tooling provided.
Within the theme's repository is a .lando.yml file that will be used to start Lando and build the development environment.
The process will look like this.
- Change directory to project folder or make one.
- Start Lando:
$ lando start - Install WordPress core:
$ lando wp download core - Create wp-config:
$ wp config create --dbname=wordpress --dbuser=wordpress --dbpass=wordpress --dbhost=database - Download and import the database:
$ lando db-import site-database-export-file.sql
You are now ready to clone the theme within the projects wp-content/themes folder.
Once you have been able to install and run a local version of WordPress, clone theme repository into the wp-content/themes folder and continue with the installation process below.
- Make sure you have installed Node.js and Browser-Sync (optional) on your computer globally
- Then open your terminal and browse to the location of the theme
- Run:
$ composer install - Run:
$ npm install
The ASU-produced packages in this theme are loaded from the ASU Unity Private NPM (Verdaccio) package repository. This requires you to sign-in and create a user account on the NPM server. Doing so, npm will automatically save your authentication token into a local .npmrc file located in your home directory.
- Visit the ASU Unity NPM Package server and follow directions to add yourself as a user: https://registry.web.asu.edu/
- Create your npm user account by executing in a terminal:
npm adduser --registry https://registry.web.asu.edu - It is recommended that you use your ASU.edu email address. You can use any password; be sure to save it in LastPass!
- Configure npm to use this private registry. Add the following line to the .npmrc file in your home directory (existing lines can be left in-place):
@asu-design-system:registry=https://registry.web.asu.edu/
This config tells npm that all packages from ‘@asu-design-system’ should be requested from the ASU private registry. If it says you are not authorized, sign in using:
npm login --registry https://registry.web.asu.edu/
Once you have successfully signed-in, npm will automatically save a new line to your .npmrc, saving your login token for the future.
Welcoming paragraph here with general contribution notes
The theme is set up with tools to help you write PHP that conforms to the WordPress Coding Standards. After initially cloning the theme repo, run composer install to install these tools in the /vendor directory.
The theme contains two composer scripts to help you write code that conforms to the WordPress standards:
composer check:cswill process all.phpfiles in the theme and check them for compliance with the WordPress standards. Any code that does not meet the standard will be indicated, and you can fix most of them with another script...composer fix:cswill fix errors marked with an[x]in the output ofcomposer check:cs. You will need to correct any other issues manually.
It is important to run the composer check:cs command and fix any issues before pushing your code to Github, as these commands will run on every single .php file in the theme. If you don't check your work, any issues with your code will surface when another developer checks their code, making it more difficult for any developer to know if it is their code causing the errors.
If needed, you can manually run these commands and target a specific file, or files. From the root folder of the theme:
- To check files:
./vendor/bin/phpcs {path-to-the-php-file} - To fix errors:
./vendor/bin/phpcbf {path-to-the-php-file}
We use Gulp as our task runner. While can run Gulp tasks directly from the command line, we have created some NPM aliases for common tasks.
npm run buildwill compile theme assets from the files in the/srcdirectories and copy them to/css,/js, and/imgdirectories. This includes minifying CSS, uglifying and concating JS files, and running all images throughimageoptim. If you are not using thewatchoption, this is the command to run after you have made any changes to Javascript or CSS files. This step also cleans out and replaces all files in the\distdirectory. This is equivalent to directly runninggulp compile.npm run imagesdoes only the image optimization step of the build process. It will optimize all images in/src/imgand copying the optimized images to/img. This is equivalent to directly runninggulp imagemin.npm run syncstarts BrowserSync and watches SCSS and JS files for changes, automatically processing those files when they are saved (using a subset of the tasks that would run withnpm run build). This is equivalent to directly runninggulp watch-bsor justgulp, as it is the default Gulp task. See the BrowserSync section below to help you set up BrowserSync before running any of these commands.npm run assetswill delete the files in the/src/image,/src/js,/src/sassand/src/fontawesomedirectories and replace them with the current files in the appropriate/node-modulessub-directories. This is equivalent to directly runninggulp reset-assets. This command was formerly known aspostinstall.npm run scriptswill rebundle javascript files in/src/jsbased on the gulp file settings. Currently there is an admin js build, and a production js build file.
To work with and compile your Sass files on the fly start:$ gulp watch
Or, to run with Browser-Sync:
- First create a new .json file in the theme root, name it "browserSyncOptions.json", copy and paste the lines below into the new created file:
{
"browserSyncOptions" : {
"proxy": "localhost/theme_test/", // <----- CHANGE HERE
"notify": false
},
...
};- Change the browser-sync options to reflect your environment in the file
/browserSyncOptions.jsonin the beginning of the file: - The
proxyproperty needs to match the appserver URL (created by your local server application, i.e. Lando) - then run:
$ gulp watch-bsornpm run sync
The UDS-WordPress theme is a complete theme which includes all of the required WordPress template files and assets for the theme to work.
It can also function as the parent for a customized child theme. A child theme allows developers to make modifications to any part of the existing theme and to keep their customizations separate from the parent theme functions.
The UDS-WordPress theme also includes several action hooks that can be used either by a child theme or a plugin to add or alter functionality of the parent theme.
A "starter" child theme template has been made available for use in creating your custom solution for WordPress. That theme template is located here:
Out of the box, the child theme template:
- Compiles its own set of CSS rules so that styles from the parent can be overwritten by the child theme's CSS.
- Includes a reference to the UDS-Boostrap-4 design token library, so that you can include these standardized references in your child theme's codebase.
- Includes both the child and the parent's
functions.php(and related) files. This follows the best practices of the WordPress project.
Further instructions on how to best use the child theme template can be found the GitHub repository.
The UDS-WordPress-Theme includes hooks in the following places.
| Hook | Location |
|---|---|
| uds_wp_after_global_header | header.php |
| uds_wp_before_global_footer | footer.php |
| uds_wp_before_global_footer_columns | footer.php |
uds_wp_after_global_header - fires immediately after the closing </header><!-- end #asu-header --> statement in header.php. Serves as an ideal place for a small banner or other alert mechanism to be added before a potential hero image across multiple pages on the site.
uds_wp_before_global_footer - fires immediately before the closing global <footer> tag in footer.php. Allows for a persistent block of code to appear across multiple pages of the site, just above the point at which the global footer begins.
uds_wp_before_global_footer_columns - fires immediately before the <div id="wrapper-footer-columns"> landmark within footer.php. In conjunction with the theme option to turn off the native footer column feature, this would be a handy way to replace the native functionality for the footer columns with your own solution.
You can take advantage of these hooks within a child theme or plugin using a function like the following:
/**
* Adds a section of content immediately above the global footer.
* Looks for a template called '/templates/content-prefooter.php'
*/
function your_project_add_prefooter_content() {
get_template_part( 'templates/content', 'prefooter' );
}
add_action( 'uds_wp_before_global_footer', 'your_project_add_prefooter_content' );
[is this needed?]
This theme is built on top of Understrap, with minor adjustments specific to the needs of the theme. Most traditional WordPress theme files are where you would expect them. Files and folders of interest include:
| Name | Description |
|---|---|
| functions.php | A lean file that loads code from multiple files in the /inc directory |
| /inc | WordPress hooks and callbacks, organized by their purpose in the theme and loaded into functions.php at runtime |
| /templates-loop | Partial templates for displaying content from posts and pages (the WordPress 'loop') |
| /templates-page | Multiple full-page layout templates |
| /templates-sidebar | Templates for the various widget areas in the theme (aka 'sidebars') |
| /sass/theme/_theme | An SCSS file for styling rules that are not covered by the Bootstrap theme, or other SCSS files in the /sass directory. The first place to put your custom styles |