One Web Boilerplate

A One Web Boilerplate for all your Responsive Web needs. Powered by Apache SSI, SMACSS, Sass and RequireJS. Also includes Ant build script with several useful tools, as well as an SSI-based fork of adactio's Pattern-Primer (https://github.com/akikoo/Pattern-Primer).

View the Project on GitHub akikoo/one-web-boilerplate

One Web/Mobile First Responsive Boilerplate

What is it?

The One Web Front-end Boilerplate is a modular framework for building responsive websites with Apache Server Side Includes (http://httpd.apache.org/docs/2.2/howto/ssi.html), SMACSS (Scalable and Modular Architecture for CSS, http://smacss.com/), Sass preprocessor (http://sass-lang.com/), and RequireJS (http://requirejs.org/).

Demo: Optimized Styleguide Page: http://akikoo.github.com/one-web-boilerplate/publish/html-compressed/pages/styleguide/index.html.

This boilerplate draws code from many other projects, combining various solutions into a custom, modular, and responsive front-end build framework. It's packed with goodies, building on many of the industry best practices found in the resources listed under Credits. The project also includes Ant build script that runs code quality tools against JavaScript and CSS files, minifying and concatenating them at the end of the process.

The One Web Boilerplate works well for me which is why I'm publishing it here for you to use and improve. It basically extends popular boilerplates, including 320 and Up (https://github.com/malarkey/320andup/), HTML5 Boilerplate (http://html5boilerplate.com/), Mobile Boilerplate (http://html5boilerplate.com/mobile/), ZURB Foundation (http://foundation.zurb.com/), Twitter Bootstrap (http://twitter.github.com/bootstrap/), and many others, with Server Side Includes. The framework can easily be plugged into Continuous Integration solutions, such as Jenkins: http://jenkins-ci.org.

This framework doesn't include any grid. You decide how you build your site. However, if you need a grid, have a look at the Fluid Grid that supports both Sass (SCSS) and LESS CSS: http://akikoo.github.com/Fluid-Grid/. Sass/Compass is used by default, both in One Web Boilerplate and the Fluid Grid.

File structure

There are two main directories: /build and /webroot.

Dev files are in /webroot/assets and /webroot/html. Optimised files are in /build/publish/assets and /build/publish/html.

Build tools

Environment setup

Apache Ant

Apache SSI

To permit SSI on your server, see this article: http://httpd.apache.org/docs/2.2/howto/ssi.html

Ruby (you need this if you use Sass/Compass)

On OS X, you'll already have Ruby installed. On Windows, see http://rubyinstaller.org/downloads/. For installing Sass, see http://sass-lang.com/tutorial.html. For installing Compass, see http://compass-style.org/install/. You should use it, it's awesome.

All the other tools needed in the local build are in the tools folder.

Build configuration

After Apache Ant, SSI, Ruby, Sass and Compass setup, you need to do two more things to configure the build:

  1. In /build/config/project.properties, look for 'web.home' in line number 124. Change the path to your local directory.
  2. In that same file, look for 'web.url' in line number 126. Create an Apache virtualhost that points to the location you defined for 'web.home' above.

If you get the "java.lang.OutOfMemoryError: PermGen space" error during the build on OS X (I did), try running this in your terminal: export ANT_OPTS=-XX:MaxPermSize=256m

You should now be up and running with both the environment and the local build.

Things you need to know

Logic

HTML

CSS - A number of stylesheets by default, compiled and imported by Sass, included in the following order:

Scalable and Modular Architecture for CSS (SMACSS, http://smacss.com/) is used by default. main.scss and main-ie.scss are the main stylesheets that @import all the common styles. Note that styles are @import-ed only for development. For production, the build script inlines and minifies styles in the same order that you @import-ed them. Nice, eh? But keep in mind that you have to @import the core styles (see above) before anything else.

Remember that if you work with Sass, you should only do changes in /webroot/assets/scss/ directory, as the files in /webroot/assets/css/ will obviously be the generated ones, rewritten on each save.

New stylesheets you create should be placed in /webroot/assets/scss/components/modules. Remember to add @import rules for any new styles. After the base styles, the order in which the module stylesheets are included should't matter (you write your styles carefully, right?) The idea is that module styles inherit only from base rules, not from other modules.

config.rb file in /assets is used for passing compile options to Compass. By default you don't need to touch that file. If you want to edit it, see Compass documentation.

JavaScript

Ant build process

To build your project, do the following

This assumes you've set up the build, as explained in Build configuration.

  1. Open terminal and go to /path_to_your_project/build
  2. Run ant -buildfile build.xml

The sequence of events is then as follows:

  1. Old build directory called /publish is deleted
  2. /publish directory is recreated, and build timestamps are added as text files
  3. HTML header and footer files are edited, to include minified and concatenated assets, created during the build
  4. SHTML snippets are called to generate full HTML web pages
  5. SHTML snippets are called to generate HTML modules
  6. SHTML file extensions are changed to HTML and all pages are copied to build/publish/html. Compressed HTML versions are copied to build/publish/html-compressed
  7. Component, module, page and template lists are generated, to be included in the project root index page
  8. HTML header and footer files are reverted, to include separate assets again (we'll continue developing!)
  9. CSSLint tool is run against all CSS files (however excluding third-party stylesheets)
  10. JSHint tool is run against JavaScript code (excluding third-party scripts)
  11. JSDoc documentation is created and placed in build/publish/docs/jsdocs
  12. CSS files are concatenated by inlining all @import-ed styles, producing two files: main.css and main-ie.css (one with and one without Media Queries). This way, we can keep the CSS rules separate from the actual Media Queries. Both files are then minified and placed in build/publish/assets/css.
  13. JavaScript files are minified and concatenated and placed in /build/publish/assets/js/lib (currently only Modernizr and require.js.) Note that compiled require.js contains the original require.js and all the modules, loaded with almond require/define shim.
  14. Unoptimised images are copied to /build/publish/assets/img
  15. Temporary directory that was used during the build is deleted
  16. That's it!

Congratulations! You now have a brand new /build/publish directory that has the following four directories:

You can now deploy the site using your favourite Continuous Integration server. It could be Jenkins (http://jenkins-ci.org) or Bamboo (http://www.atlassian.com/software/bamboo/). You decide.

Please note that the earlier version of this framework that uses the Yahoo YUI compressor is tagged here: https://github.com/akikoo/one-web-boilerplate/tags. Nowadays I prefer this framework to use RequireJS with an optimizer that manages dependencies in a much easier way.

Another note: I prefer Sass preprocessor nowadays because it's more powerful (especially with Compass) and because it's actively maintained and developed. This means that I'm not anymore actively maintaining the LESS files in this framework. Just wanted to let you know. However do let me know if you have any LESS issues so I can try to fix them (I'd be more up for it if I knew someone out there was still using LESS with this framework...).

One more thing: you should obviously exclude /build/publish directory from version control because that directory is cleaned up and recreated on each build. No need to track changes to that.

To-Do:

Thanks and good luck!

Credits

Boilerplates:

Generic build/deploy process optimization:

Solutions:

Media queries:

Inspiration:

Markup:

Images:

CSS:

JavaScript:

There's no mobile, everything's mobile.