Coding Rules and Guides

These are code style rules, guides and examples of ProteusThemes development team. Everyone contributing code to ProteusThemes should be familiar with the contents of this document.

Code style guides and naming conventions

HTML

Adhere to the Code Guide and additionally:

• Use real tabs instead of spaces for indentation.
• Use BEM for naming HTML classes where appropriate, see the CSS below.
• Things like language attributes and charset should be left to the CMS, and not hardcoded - WordPress in our case.

CSS

Word CSS is used for simplicity and general understanding. We actually write SASS, more specifically SCSS syntax.

Adhere to the Code Guide and additionally:

• Use real tabs instead of spaces for indentation.
• Don't use shorthand hex values. Good: #ffffff, wrong: #fff.
• When possible follow the BEM naming of HTML classes.
• Each BEM component has its own _component-name.scss file, in folder components/ relative to main CSS file.
• Main SCSS file in the theme has a filename style.scss (for the WordPress themes compatibility).
• Classes representing state should start with .is-*, example: .is-focus, .is-hover.
• The main CSS file in WP theme must include a class .screen-reader-text.
• Other related links:
  • WordPress CSS Coding Standards
  • CSS Guidelines - very comprehensive guide by Harry Roberts.

JavaScript

For now follow the WP JavaScript Coding Standards.

• Variables names: var camelCase (no underscores).
• Prepend jQuery variables which hold cached jQuery selectors with a dollar sign: var $elements = jQuery( '.selector' );.

PHP

As we write 99% PHP for WP, follow their PHP Coding Standards. The only difference is the brace style - mind additional new line after closing }:

if ( condition ) {
  action1();
  action2();
}
else if ( condition2 && condition3 ) {
  action3();
  action4();
}
else {
  defaultaction();
}

WordPress

Menus and navigation

We use [WordPress navigation] (https://codex.wordpress.org/Function_Reference/wp_nav_menu) with the [Bootstrap] (http://getbootstrap.com/components/#navbar) elements (for collapsed mobile navbar).

• Add semantic <nav> element around the WordPress code for menu.
• Add arrays for wp_nav_menu:

'theme_location' => 'main-menu',
'container' => false,
'menu_class' => 'main-navigation'

Change main with different name if there is more menus.

Standard scripts/styles handles

Follow rules from the WP Standard Handles guide. See the mentioned link for:

• How to name script/style handles.
• How to properly register/enqueue Google Fonts.
• How to name image size handles added via add_image_size.

Additionally, follow these rules when naming handles:

• The handles should be prefixed (if they are not in the list of the standard handles).

• Name the handles for the main scripts/styles like this:

  • <prefix>-admin-script for the main JS file used in wp-admin
  • <prefix>-admin-style for the main CSS file used in wp-admin
  • <prefix>-script for the main JS file used on frontend
  • <prefix>-style for the main CSS file used on frontend

• All the custom scripts/styles should have the same version as the plugin, defined dynamically (so there is no need to update the handles once the plugin/theme is updated to the newer version). Use like this:

wp_enqueue_style( '-admin', _URL . 'assets/stylesheets/admin.css', array( 'dep1', 'dep2' ), _VERSION );

### Prefixing and scopes

http://themereview.co/prefix-all-the-things/

### Accessibility

- Hide [screen reader text](https://make.wordpress.org/accessibility/2015/02/09/hiding-text-for-screen-readers-with-wordpress-core/) with this code:

  ```css
  .screen-reader-text {
    clip: rect(1px, 1px, 1px, 1px);
    position: absolute !important;
    height: 1px;
    width: 1px;
    overflow: hidden;
  }

• All inputs and textareas must have lables.
• Icon fonts (social icons for example) should have fallback text for screen readers.
• Use [ARIA landmark] (https://make.wordpress.org/themes/handbook/review/accessibility/required/#aria-landmark-roles) roles.
• Use <strong> and <em> instead of <bold> and <i> (even if screen readers sees them the same - [source] (http://webaim.org/techniques/semanticstructure/)).

Navigation Accessibility

• Add role="navigation" and aria-label="<?php _e( 'Name of the Menu', 'textdomain' ); ?>" on <nav>.
• Add role="menubar" only on the first ul if ul is horizontal.
• Add role="menuitem" on all li element or role="presentation" (if there is still bug in validator).
• Add role="menu" on al uls width sub-menu.
• Add aria-haspopup="true" on li with sub-menu.
• Add aria-expanded="false" on all li elements with sub-menu on default. Change to aria-expanded="true" if sub-menu is open.

Directory tree structure

TODO

Of a theme

Of a plugin

WP Customizer

• List of tutorials about customizer - some might be out of date though.
• Improvements in WP 4.0: panels, new controls (supporting all HTML5 input types), contextual controls.
• Improvements in WP 4.1: registering control types, sending PHP control data to JS, JS/Underscore templating.

Git

• Stick to this guide on How to Write a Git Commit Message.
• This is a guide how the commits history should look like.
• Version names follow Semantic Versioning.

Git hooks

We use git hooks in order to check the code quality and run some automatic tests. When you make a commit in our projects, the committed PHP files are checked against WordPress standards. By doing so we ensure that the code quality is of the highest standard.

Installation

In order for the git hooks to run smoothly you will need to install and configure some dependencies:

• Install WordPress Coding Standards for PHP_CodeSniffer. Follow the instructions on the page and make sure to include the library to the PATH variable of your OS (so the phpcs command will be available globally).
• In your project folder run the command grunt githooks. This will configure/apply the git hooks.

Other tools

Bower

All 3rd party frontend dependencies should be included via Bower, so the repo stays clean and it is easy to update to future versions from comfort of terminal.

In rare occasions the backend dependencides can be included via bower as well, if they don't support Composer packages.

Composer

All backend dependencies should be inluded via Composer, the same resons as for Bower.

Grunt

---

TODO

• TOC
• Add EditorConfig file
• https://www.npmjs.com/package/tinypng-cli and image optimization (somewhere)

Created and maintained by @primozcigler.