Code

We’re not just about looks. We take great care in the design of our code structure and naming conventions.

This section has all the nuts n’ bolts for getting the site setup on your system, where to find things, and how stick with our code standards.

Setup


Running locally

Louder Than Ten is built with Craft CMS, which requires a basic PHP & MySQL server. We use Mamp Pro to host locally with little fuss, but you can use any PHP/MySQL setup as long as it meets Craft’s requirements.

If you want to make any code updates, you’ll want to setup the full site on your local machine:

Front-end setup

If you want to update the CSS or Javascript, you’re also going to need to setup a few front-end libraries.

Project structure


Here’s how the Louder Than Ten site is organized:

/public_html

This is where all compiled static assets live. Find images and font files here, as well as all compiled and minified CSS and JavaScript. Don’t edit these CSS and JS files. Your changes will be overwritten by the preprocessor.

/source

This contains all of the pre-compiled Sass and Javascript files. This is where you will write your CSS and JavaScript.

/craft

The Craft CMS folder.

/craft/templates

Where the Twig-based Craft templates reside. These are the templates that make the website.

/craft/plugins

Where all Craft plugins get installed.

Version control


We use Git to manage our version control. It keeps track of all our code changes and stores them in a central Github repository.

We make heavy use of branches and version numbers to help track of progress and allow feature development without interfering with our Master production branch.

Here’s a quick breakdown of our versioning and branching philosophy:

Branching

We loosely follow Vincent Driessen’s approach to Git versioning. Here’s our quick n’ dirty overview:

master

The master branch should always be bug free (yeah right) and ready to deploy to the production server. We never make direct changes in this branch and only merge features and updates into it after they’ve been thoroughly tested.

dev

The dev branch is where we merge our features into for testing and previewing and gets deployed to our dev server. No work should ever be done on this branch.

feature-branches

Feature branches are copied from the dev branch. These should be named after the feature we are developing. This is where the work gets done. Commit often, push to origin, and regularly pull updates from the dev branch to ensure you’re working with the latest code. When a feature is finished and ready for testing, we merge it back into dev. These should be named lowercase with hyphens separating the words and prefixed with feature/.

hotfixes

These are quick bug fixes and updates that need to be immediately pushed live. A hot fix branch name should be prefixed with hotfix/ and copied directly from master. Once the change is complete, it should be merged back into master as well as dev to make sure the entire project gets the fix.

Version numbers

We loosely follow the Semantic Versioning approach to our releases.

Major version (x.)

In our case, the major version gets changed with major site overhauls or redesigns.

Minor version (1.x)

We regularly make a list of all the features we want to implement in the next release. We bump this when these features are complete, implemented, and merged into master.

Patch version (1.1.x)

We update this everytime we push something to master that isn’t part of the planned feature release. This might include bug fixes, or unplanned changes or adjustments (aka hotfixes).

Markup


We use standard HTML5 for markup with a simplified version of BEM syntax to name classes. This sets an easy standard for others to adopt and keeps the library tight, modular, and free of specificity issues.

Here’s the basic syntax:

.block {} /* A component or module */
.block__element {} /* A descendent of that module */
.block--modifier {} /* A modified or alternate version of the module */

Read more about BEM syntax.

CSS


All of the styles are written using Sass. All source files can be found in /source/scss/.

We use a highly modular approach when authoring our SASS and break all of our pieces into files. This helps keep things organized and easy to modify.

Every element group, component, and module should have it’s own file where we define everything except colour.

Sass folders

/source/scss/ This folder contains all of the SCSS styles in the project. The guide and Craft templates both share the same CSS. What this means is that whenever you make changes to your styles, they will be reflected in the manual as well as the site.

We’ve structured our scss folder based on Harry Robert’s ITCSS methodology.

app.scss

This generates the main CSS file. It has two includes:

_includes — base.scss

Imports the base scss variables and utilites that every SCSS file requires.

1_settings/_includes

Pulls in all the elements, components, and modules you want to include in your projects.

1_settings/_includes — async

Pulls in only the critical elements, components, and modules you want to include in your projects. We separate this from the above include so you can choose asyncronously load CSS that appears outside the viewport for quicker loading. More info on the technique at Filament Group.

/app/_scss/1_settings/ Contains the project variables, font includes and a few other things that set the stage.

_variables.scss Set most global variables in here. You can set things like base typographic settings, default corner radius, breakpoint widths, and grid units. _colors.scss We keep our colour variables separate so we can easily experiement with multiple colour schemes. _includes — base.scss Imports the base scss variables and utilites that every SCSS file requires. _includes.scss Use this to include or exclude the sections you want in your project. We made everything modular, so you can use as much or as little as you like. _livewires.scss Blanks out text inside of any element with a .content class in your HTML. Include this when presenting wireframes to clients or your team to focus their attention on layout and flow, rather than textual content. But hark the broken record: get your content in before you get into design. _font-faces.scss Add any font or icon @font-face includes to this file. /app/_scss/2_tools/ Contains our handy logic-based SCSS tools like Mixins and Functions.

_mixins.scss & _functions.scss These include powerful enhacements to help save time. Have a browse to see what’s available and how they work. /app/_scss/3_generic/ Contains third party styles like normalize as well as any plugin css that needs to be overridden.

/app/_scss/4_elements/ Naked default HTML elements are styled here. Avoid styling with clases. e.g. paragraphs, headings, form fields

/app/_scss/5_components/ The reusable pieces that consist of groups of elements. Start styling with classes here. e.g. callouts, pagination, code blocks

/app/_scss/6_modules/ Major chunks that make up the main sections of a template. They often contain components and global elements, and are often used once per page. e.g. headers, footers, layout modules

/app/_scss/7_theme/ This contains all colour-related styles. We’ve kept all the color assignments separate from structural styles to make theming easier, faster, and less prone to errors. Optional.

/app/_scss/8_pages/ Page-specific styles. We recommend keeping larger files in this section out of the main stylesheet and only calling them on their respective pages.

/app/_scss/9_overrides/ Anything that needs to sit at the bottom of the CSS. Put your important overrides in here.