revelrylabs/wp-harmonium

Revelry's fork of wd_s, a fork of Automattic's _s

WP Harmonium

Build Badges

Site	Build Status
Staging	TBD
Production	TBD

Harmonium Theme

Product Owner: John Hawkins

• Project Start Date: January 15, 2019
• Product Launch Date: TBD
• Current End of Contract Date: N/A

Links to relevant docs, repos, etc.

Thing	Location
Google Drive	link
Sprint Reports	TBD
Continuous Integration	TBD
Staging	link
Production	TBD

Compatibility Targets

Web App Browser Compatibility Targets

OS	Browsers
Windows	IE 11+, Chrome (latest), Firefox (latest), Edge (latest)
Mac	Chrome (latest), Firefox (latest), Safari (latest)
iOS	Safari (latest)
Android	Chrome (latest)

The Project Brief

The Idea

Create a WordPress theme that incorporates the Harmonium asset library to be used as our internal starter theme for future WordPress projects.

Who are we building for?

Initially, this project is being built for the developers at Revelry. The theme will provide developers a consistant starting point for kicking off WordPress based projects.

The long term plan for the project is to create a starter theme that is released as Open Source Software. This serves the double-purpose of giving back to the WordPress community while expanding the visibility of the Harmonium asset library.

What is the main problem we are trying to solve?

Each time a new WordPress project is started at Revelry, a developer spends valuable time incorporating Harmonium into a 3rd-party theme. Without a standard process, this has resulted in no two WordPress projects being built the same way. This theme will save our developers hours of startup time on each project and will ensure our projects are built in a consistant fashion.

What is the core loop?

Developers at Revelry will use the new Harmonium theme as the basis for future WordPress-based projects. As we work on new projects, this theme will act as the starter theme. As we work on individual projects, changes that we feel should be made part of our starter theme will be pushed upstream to this starter theme.

Nouns & Verbs

• WordPress: The Content Manegement System software used to run a website
• Harmonium: A React based asset library for adding consistant, yet flexible elements to a website
• Harmonium Theme: The WordPress theme we are building to be used as the starting point for future WordPress projects.
• Parent Theme: A WordPress theme that can be used as a framework and should not be edited directly so that the theme can be overwritten with an updated version without losing customizations.
• Theme: A collection of files that dictates how a website will look when viewed in a browser.
• Page: Static content on a website. For example, the Contact Us or About Us page on a site. These are considered static pages as they are not based on a specific date.
• Post: Chronological content on a website are considered posts. For example, a blog or latest news would be considered a post.
• Header: The top section of the website that contains a logo and site navigation. The header is typically the same across all pages of the website.
• Footer: The bottom section of the website. The footer typically contains copyright information and can contain information and links that remain consistant across the entire website.
• CSS: CSS stands for Cascading Style Sheet. This code defines how elements on the site display. Colors, font sizes, padding, margin, alignment, etc.. that's all handled with CSS.

Team

Role	Person	Email
Product Owner	John Hawkins	[email protected]
Product Manager	Aline Adams	[email protected]
Tech Lead	John Hawkins	[email protected]
Engineer	John Hawkins	[email protected]
Designer	Laura Hill	[email protected]
QA
Business Analyst
Account Manager

Important Note

This repo and the instructions to follow are related to working on the WP Harmonium starter theme. DO NOT push website project specific code to this repo.

For complete information on starting a new WordPress project, please visit the Starting a New Project section on the Rev Wiki WordPress page.

Project Setup

This repo is not a complete WordPress install. It only consists of the Harmonium theme. In order to set it up for local development, see Local Development below.

Tech Stack

• Based on wd_s, which was based on underscores
• Has the Harmonium Asset Library baked in

Local Development

Note: The build system has recently changed from gulp to npm. There may be some changes to this section still to come.

To set up your local environment to work on this project:

Before you start, make sure that you're running Node version 10 or higher.

• Start MAMP and point apache at an empty folder
• Install WordPress
• From the command line, run the following commands
  • cd wp-content/themes/
  • git clone [email protected]:revelrylabs/wp-harmonium.git harmonium
• In WordPress, activate the Harmonium Theme
• From the command line, run the following commands
  • cd harmonium
  • npm i

You may also need to run npm run-s build && composer install

Install dependencies

All of the dependencies have been included as part of the Github Repo. That may change in the future, but for the time being, everything that's needed will be installed as part of the Local Development setup process above.

While working on the project

Create a feature branch off of master. When ready, push the feature branch to Github and create a pull request.

Post any questions in the WP-Harmonium channel on Slack

wp-harmonium's Issues

Prepare namespace in base theme

Background
The theme we forked uses _s as the namespace for pretty much everything in the theme. Need to switch that to harmonium

Scenario: Update namespace

Following the themes from the original theme, take the following steps:

You'll need to change all instances of the names: _s.

• Search for: '_s' and replace with: 'project-name' (inside single quotations) to capture the text domain
• Search for: s and replace with: project-name_ to capture all the function names
• Search for: Text Domain: _s and replace with: Text Domain: project-name in style.css
• Search for (and include the leading space): _s and replace with: Project Name (with a space before it) to capture DocBlocks
• Search for: _s- and replace with: project-name- to capture prefixed handles
• Search for _s.pot and replace with: project-name.pot to capture translation files
• Search for _s.com and replace with: project-name.dev to match your local development URL
• Edit the theme information in the header of style.scss to meet your needs

Add Harmonium Components

Scenario: Add Harmonium Components

As an engineer, I:

• Incorporate the Harmonium Components into the theme

Rework readme.md

Background
After forking the theme and copy/pasting our original readme, the result is a bit of a mess.

Scenario: Clean up the readme

• Review the current readme.md file
• Strip out what doesn't need to be there
• Ensure that another user could come in and understand how to start a project.

Anchor links scrolling under static topbar

Background
On sites where the top bar has been set to remain static at the top of the page, if you try to use an anchor link to content further down the page, the content scrolls to the top of the screen and is hidden behind the top bar.

Scenario

As a visitor to a site with a static top bar;

• when I click a link to an anchor on a page
• I see the content scroll to the top of the screen,
• and the desired content is displayed starting just under the top bar

Remove extra styles for content blocks

Backstory

During the course of working on a client project, it was found that we have a couple of extra styles attached to content blacks that aren't needed and were linked to some issues with the Safari browser. So, rather than have them there by default, we're going to remove them from the default and they can be added back in as needed (assuming no issues with Safari)

Scenario

As a WordPress Developer, I:

• review all files in the template-parts/content-blocks/ folder
• locate and remove instances of rev-Row--justifyCenter and display-flex in div containers

Add rev-row wrapper to existing acf blocks

Background
The theme we're using has a bunch of pre-built ACF rows. Need to add the harmonium rev-row / rev-column structure to each for future development.

Scenario: Update Content Block templates with rev scaffolding

• in the template-parts/content-blocks/ folder
• locate all existing block templates
• Add rev-row / rev-column scaffolding
• Ensure it doesn't break the default functionality/style

Design - Theme screenshot

Background
The theme screenshot shows up on the Themes page when a user has the theme installed and navigates to Appearance -> Themes. While we should create a project-specific screenshot for the Child theme, the parent theme should be something that stays the same across all projects.

Instructions from WordPress.org
Create a screenshot for your theme. The screenshot should be named screenshot.png, and should be placed in the top level directory. The screenshot should accurately show the theme design and saved in PNG format. While .jpg, .jpeg, and .gif are also valid extensions and file formats for the screenshot, they are not recommended.

The recommended image size is 1200px wide by 900px tall. The screenshot will usually be shown smaller but the over-sized image allows for high-resolution viewing on HiDPI displays. Note that because the Manage Themes screen is responsive, the top and bottom of the screenshot image might not be viewable so keep graphics near the center.

Scenario: Create Screenshot graphic

As a designer, I:

• Decide on a look for the screenshot
• Create screenshot.png using the side requirements above
• Add the screenshot.png file to root of the harmonium theme folder

Full-width page template

Create a full with page template that is available from the dropdown list

Create parent theme

Background
We will be using a parent/child theme setup for WordPress projects moving forward. To do this, we will use this theme as a Parent Theme that will NOT be modified on a project-by-project basis. Instead, we will use a Child Theme for handling the project development.

As an engineer, I:

• Create a production-ready WordPress theme to be used as the parent theme on WordPress projects.