npm install.We follow the the principles of BEM ( Block-Element-Modifier ) in our front-end development. BEM is advantageous for a number of reasons:
If you’re unfamiliar with BEM, go to http://getbem.com/introduction/ for a rundown on using it.
Here’s a brief example of how we implement BEM to build a simple navigation:
HTML :
menu is considered the Block, menu__item is the Element, and menu__item--active is an example of a modifier. The js-menu-toggle class is used purely for targeting the element with javascript.
<nav class="menu">
<a href="https://github.com/ObjectiveSubject/ccl/blob/master/about" class="menu__item">About</a>
<a href="https://github.com/ObjectiveSubject/ccl/blob/master/products" class="menu__item menu__item--active">Products</a>
<a href="https://github.com/ObjectiveSubject/ccl/blob/master/contact" class="menu__item">Contact</a>
<a href="#" class="menu__toggle js-menu-toggle">Menu Toggle</a>
</nav>CSS :
Structure remains as flat as possible. By looking at this CSS you immediately know how the elements are structured in the markup. .menu is a block in which .menu__item elements are children and .menu__item--active is a modifier class used on .menu__item elements to turn their color red.
.menu {
width: 100%;
}
.menu__item {
display: none;
color: blue;
.menu--open & {
display: block;
}
}
.menu__item--active {
color: red;
}
.menu__toggle {
display: block;
}JavaScript :
Unique 'js-' prefixed classes should always be used for targeting elements in javascript. These class names should be independent of ones used for any styling purposes. This keeps styling classes from getting muddled with javascript and makes it easy to look at the html and see what elements javascript is working with.
$('.js-menu-toggle').click(function(e){
e.preventDefault();
$('.menu').toggleClass('menu--open');
});SCSS should be used to build stylesheets.
SCSS files should be organized in the following way:
Bourbon is a mixin library that helps you quickly write sass and not have to worry about vendor prefixes, among other things. Neat is a mixin library for implementing a grid system.
Variables are located in the /assets/css/sass/shared directory. Two important variables to take note of are $max-width and $grid-columns. These are used by Neat's grid column functions and mixins. You can adjust them according to your design and Neat's mixins will adjust accordingly.
Mixins are located in the /assets/css/sass/shared directory. Currently, the only mixin that comes out of the box is for writing media queries. Feel free to add more.
In addition to modifier classes, state classes should be used to suggest, as the name implies, an element's state. State classes are always prefixed with is- or has-.
Here's an example of a dropdown in its "open" state:
<ul class="dropdown is-open">
...
</ul>.dropdown {
height: 0;
&.is-open { height: 100px; }
}Utility classes are helpful, single (or limited) purpose, classes usually created for the styles you apply the most. Utility classes are always prefixed with u-. For example, centering an element is a very common practice and instead of having to write styles for every element that should be centered, we can write utility classes and include it in our markup:
.u-centered {
max-width: 800px;
margin: 0 auto;
}<article class="u-centered">
...
</article>Whenever size is being determined for something (font-size, width, height, margins, etc), rem and em units should almost always be used. This definitely goes for typography and in most cases can be applied to other elements. Using rem and em allows the site to be easily scaled by simple adjusting the font size of the root element (<html>) or the element from which a size is being inherited.
JS files should be created inside a source folder and then compiled into 1 main file for loading on the page. Each piece of the user interface should have it's own source file. Vendor libraries should be loaded in a vendor directory.
Grunt or Gulp are both acceptable tools for compiling CSS and JS.
The following is a list of frameworks often used in our development. Please strongly consider whether additional libraries are necessary. The slimmer the better.
CSS
NOTE: Please DO NOT use Bootstrap or any other framework which comes with a stylesheet of its own. Bourbon and Neat are mixin and function libraries and therefore do not get compiled. Exceptions are vendor stylesheets which may be necessary for some javascript libraries. If possible, please designate them to their own .scss file inside the css/sass/shared/ folder.
Javascript
Icomoon.io should be used to create icon fonts for the UI of the site. This includes things like arrows, social media icons, search icons, etc. Icomoon will let you export .ttf, .woff, and .svg versions of your icon fonts. Icon fonts as well as regular fonts for the site as a whole, if self-hosted, should be stored in a /fonts directory inside the theme.
Icon markup should use <span> tags with the appropriate attributes. Important: Use aria-hidden to hide from screen readers.
<a href="https://github.com/ObjectiveSubject/ccl/blob/master/"><span class="icon icon-arrow-left" aria-hidden="true"></span> Back to the home page</a>We use the extended-cpts library to easily create and manage custom post types.
We use the extended-taxos library to easily create and manage custom taxonomies.
We use the CMB2 library to create and manage custom fields in the backend. Refer to the CMB2 wiki for documentation.
In addition to the functions.php file, the theme should have an includes folder which holds all necessary backend functions. It should look something like this: