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/).
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 also includes a dynamic grid system called the Fluid Grid: http://akikoo.github.com/Fluid-Grid/. Sass/Compass is used by default, both in One Web Boilerplate and the Fluid Grid.
-
/build contains Ant build script and all the tools you need to make your frontend build. Common build properties are defined in /build/config/project.properties. There's also a folder called masterpage, which is used as a blueprint for creating new pages.
-
/webroot contains two subdirectories: /assets and /html.
-
/webroot/assets contains all the Sass and LESS files, stylesheets, JavaScript files and theme images.
-
/webroot/html contains all the HTML files, generated by Apache Server Side Includes. HTML properties are defined in /webroot/config.shtml.
Dev files are in /webroot/assets and /webroot/html. Optimised files are in /build/publish/assets and /build/publish/html.
- Java Development Kit (JDK) (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
- Ant (http://ant.apache.org/)
- Ant-Contrib Tasks (http://ant-contrib.sourceforge.net/)
- YUI Compressor (http://developer.yahoo.com/yui/compressor/)
- Rhino (http://www.mozilla.org/rhino/)
- JSLint (http://www.jslint.com/)
- JSHint (http://www.jshint.com/)
- CSSLint (http://csslint.net/)
- HTML Compressor (http://code.google.com/p/htmlcompressor/)
- JSDoc Toolkit (http://code.google.com/p/jsdoc-toolkit/)
- JsDoc Toolkit Ant Task (http://code.google.com/p/jsdoc-toolkit-ant-task/)
- Closure Compiler (https://developers.google.com/closure/compiler/)
- r.js optimizer (http://requirejs.org/docs/download.html#rjs)
- less-rhino (https://github.com/cloudhead/less.js/blob/master/dist/less-rhino-1.1.5.js)
- JRuby (http://www.jruby.org/download)
- OptiPNG http://optipng.sourceforge.net/
- jpegtran http://www.ijg.org/
-
Whether you're on Windows or Mac, you'll need the Java Development Kit (JDK) (at least version 1.4). You can download it here: http://www.oracle.com/technetwork/java/javase/downloads/index.html. If you're not sure which version of the JDK you have, run the command java -version in the terminal.
-
Download Apache Ant here (on Mac OSX it's usually already installed): http://ant.apache.org/bindownload.cgi. On Windows, it's probably best to extract the contents of the zip to C:\ant.
-
See this article for how to finish the installation on your platform: http://net.tutsplus.com/tutorials/other/automate-your-projects-with-apache-ant/ (see section Windows- and Mac-Specific Install Bits.)
To permit SSI on your server, see this article: http://httpd.apache.org/docs/2.2/howto/ssi.html
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.
After Apache Ant, SSI, Ruby, Sass and Compass setup, you need to do two more things to configure the build:
- In /build/config/project.properties, look for 'web.home' in line number 124. Change the path to your local directory.
- 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.
-
A CSS preprocessor, either Sass (http://sass-lang.com/), default option with Compass (http://compass-style.org/), or LESS (http://lesscss.org/) is used to compile the stylesheets. If you don't want to use a preprocessor, you can of course work with the CSS files directly. By default, it's assumed that you compile Sass or LESS files on your local machine, and let the build process do the CSSLint check on your generated CSS files. (There are tasks for Sass and LESS processing in /build/build.xml, namely <css.compile.sass /> and <css.compile.less /> macrodef calls, but they are commented out.) To compile CSS files on your local machine, type one of the following commands in the terminal (replace the '{pathtoworkingcopy}' with your local path):
a) using Sass: sass --watch /{pathtoworkingcopy}/webroot/assets/scss:/{pathtoworkingcopy}/webroot/assets/css
b) using Compass with Sass: compass watch /{pathtoworkingcopy}/webroot/assets
For more info, see Sass and Compass documentation.
-
Media Queries are based on 16px default font size and defined in ems. The framework is designed to be modular so you should split the rules into logical modules, and place the styles in /webroot/assets/scss/components/modules. For more info on how to categorize your CSS, see SMACSS: http://smacss.com/.
-
JavaScript should not be relied on for layout. That's why I've adopted a bulletproof solution from Nicholas Zakas and Tantek Çelik: http://www.nczonline.net/blog/2011/03/22/using-html5-semantic-elements-today/ and http://tantek.com/presentations/2010/11/html5-now/.
-
Don't use IDs in CSS selectors. Use classes, or ARIA landmark roles instead (referenced with CSS attribute selectors). See also http://oli.jp/2011/ids/.
- Each page has a controller in /webroot/html/pages/pagename/index.shtml. In that file, we include the config file and set variables, define the view, and template file that we need to include, to render that particular page. For more information, see project main index file: https://github.com/akikoo/one-web-boilerplate/blob/master/webroot/html/index.shtml.
CSS - A number of stylesheets by default, compiled and imported by Sass, included in the following order:
- /webroot/assets/css/common/normalize.css (third-party reset styles)
- /webroot/assets/scss/common/elements.scss (global, mobile first styles, containing only common colour and typographic rules for basic experience to all users)
- /webroot/assets/scss/common/utilities.scss (helper styles from HTML5 Boilerplate and HTML5 Mobile Boilerplate)
- /webroot/assets/scss/common/base.scss (base stylesheet that imports the above mentioned three stylesheets)
- /webroot/assets/scss/components/layout.scss (page layout rules)
- /webroot/assets/scss/components/module.scss (module base stylesheet that imports all the modules)
- /webroot/assets/scss/components/state.scss (state rules for layout and modules)
- /webroot/assets/scss/components/theme.scss (theme styles)
- /webroot/assets/scss/main.scss (layout with Media Queries for responsive, enhanced design for smartphones, tablets and larger screens)
- /webroot/assets/scss/main-ie.scss (layout without Media Queries for legacy IE 6/7/8 browsers).
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.
- Third-party plugins are included in /webroot/assets/js/lib. Custom scripts are in /webroot/assets/js/modules. Dependancies are managed by RequireJS (http://requirejs.org/), a script loader that supports AMD (Asynchronous Module Definition) API. Script paths and their dependencies are defined in /webroot/assets/js/config.js. Scripts are imported in /webroot/assets/js/main.js. In the optimized script bundle, almond.js (https://github.com/jrburke/almond) is used in place of require.js, to package everything in just one script file.
This assumes you've set up the build, as explained in Build configuration.
- Open terminal and go to /path_to_your_project/build
- Run ant -buildfile build.xml
- Old build directory called /publish is deleted
- /publish directory is recreated, and build timestamps are added as text files
- HTML header and footer files are edited, to include minified and concatenated assets, created during the build
- SHTML snippets are called to generate full HTML web pages
- SHTML snippets are called to generate HTML modules
- 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
- Component, module, page and template lists are generated, to be included in the project root index page
- HTML header and footer files are reverted, to include separate assets again (we'll continue developing!)
- CSSLint tool is run against all CSS files (however excluding third-party stylesheets)
- JSHint tool is run against JavaScript code (excluding third-party scripts)
- JSDoc documentation is created and placed in build/publish/docs/jsdocs
- 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.
- 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.
- Unoptimised images are copied to /build/publish/assets/img
- Temporary directory that was used during the build is deleted
- That's it!
Congratulations! You now have a brand new /build/publish directory that has the following four directories:
- HTML files (/build/publish/html),
- Compressed HTML files (/build/publish/html-compressed),
- Minified and concatenated CSS and JS files (/build/publish/assets), and
- JSDoc documentation (/build/publish/docs/jsdocs).
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.
- Small tweaks here and there...
Thanks and good luck!
- http://html5boilerplate.com
- http://html5boilerplate.com/mobile
- https://github.com/malarkey/320andup/
- http://foundation.zurb.com/
- http://twitter.github.com/bootstrap/
- Big thanks to Will Howat (@willhowat: http://twitter.com/willhowat) and Andrew Massey (@wearymadness: http://twitter.com/wearymadness) for the inspiration, code, and fresh ideas. Great work on the Archetype framework!
- Thanks to Dennis Green-Lieber (@dennislieber: http://twitter.com/dennislieber) for promoting the use of the framework and for great suggestions and ideas for making it better.
- http://forabeautifulweb.com/blog/about/hardboiled_css3_media_queries/
- http://stuffandnonsense.co.uk/blog/about/proportional_leading_with_css3_media_queries/
- http://www.blog.highub.com/mobile-2/revisit-hardboiled-css3-media-queries/
- http://css-tricks.com/6731-css-media-queries/
- http://www.quirksmode.org/blog/archives/2010/08/combining_media.html
- http://www.slideshare.net/bryanrieger/rethinking-the-mobile-web-by-yiibu
- http://www.cloudfour.com/css-media-query-for-mobile-is-fools-gold/
- http://www.broken-links.com/2011/02/21/using-media-queries-in-the-real-world/
- http://nicolasgallagher.com/mobile-first-css-sass-and-ie/
- http://www.abookapart.com/products/responsive-web-design
- http://easy-readers.net/
- http://www.alistapart.com/articles/responsive-web-design/
- http://www.lukew.com/ff/entry.asp?933
- http://adactio.com/journal/1716/
- http://adactio.com/journal/4780/
- http://adactio.com/journal/1700/
- http://www.456bereastreet.com/archive/201103/html5_sectioning_elements_headings_and_document_outlines/
- http://www.456bereastreet.com/archive/201104/html5_document_outline_revisited/
- http://mezzoblue.com/archives/2011/01/31/boilerplate/
- http://www.nczonline.net/blog/2011/03/22/using-html5-semantic-elements-today/
- http://tantek.com/presentations/2010/11/html5-now/
- http://microformats.org/wiki/hatom
- http://unstoppablerobotninja.com/entry/fluid-images/
- http://blog.cloudfour.com/responsive-imgs/
- http://www.cloudfour.com/responsive-imgs-part-2/
- http://blog.cloudfour.com/responsive-imgs-part-3-future-of-the-img-tag/
- http://smacss.com/
- http://oocss.org/
- http://sass-lang.com/
- https://github.com/davidrapson/scss-toolkit
- http://jakearchibald.github.com/sass-ie/
- http://lesscss.org/
- http://oli.jp/2011/ids/
- http://code.google.com/p/universal-ie6-css/
- https://github.com/necolas/normalize.css
- http://requirejs.org/
- https://github.com/jrburke/almond
- https://github.com/tbranyen/backbone-boilerplate
- https://github.com/ryanfitzer/Example-RequireJS-jQuery-Project
There's no mobile, everything's mobile.