Skip to content
This repository

Roundarch Isobar Interface Development's front-end coding standards. Memorize them BY HEART.

Merge pull request #76 from isobar-idev/update-isobar-branding

Update Branding
latest commit b583f4003f
Evan Davis authored January 10, 2014
Octocat-spinner-32 _layouts updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 css updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 img updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 js further improving readme, adding generated styles to repo as gh-pages… August 14, 2013
Octocat-spinner-32 scss updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 sections updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 .gitignore further improving readme, adding generated styles to repo as gh-pages… August 14, 2013
Octocat-spinner-32 .nojekyll Removing jekyll. November 08, 2013
Octocat-spinner-32 Gemfile further improving readme, adding generated styles to repo as gh-pages… August 14, 2013
Octocat-spinner-32 Gemfile.lock further improving readme, adding generated styles to repo as gh-pages… August 14, 2013
Octocat-spinner-32 Gruntfile.js Removing jekyll. November 08, 2013
Octocat-spinner-32 README.md Changes to make readme.md instructions for Windows more user friendly… November 20, 2013
Octocat-spinner-32 config.rb Moving css to scss files May 24, 2013
Octocat-spinner-32 en.html updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 es.html updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 favicon.ico Merged files from the public live master branch. i don't think this b… January 27, 2013
Octocat-spinner-32 humans.txt This is a manual merge of the files in the outstanding commits, pulle… September 17, 2012
Octocat-spinner-32 index.html updated branding with new Isobar URLs, new logo SVG, and removed all … January 10, 2014
Octocat-spinner-32 package.json Updated Assemble to the current 0.4.33; This fixes path errors December 30, 2013
Octocat-spinner-32 robots.txt This is a manual merge of the files in the outstanding commits, pulle… September 17, 2012
README.md

Roundarch Isobar Front-end Development Standards and Guidelines

License:

All content licensed under Creative Commons Attribution 3.0 Unported License

Summary:

This document contains guidelines for web applications built by the Front-end development practice of Roundarch Isobar (previously Isobar & Molecular). It is to be readily available to anyone who wishes to check or contribute to the iterative progress of our discipline's best practices.

This document's primary motivation is two- fold:

  1. code consistency and
  2. best practices.

By maintaining consistency in coding styles and conventions, we can ease the burden of legacy code maintenance, and mitigate risk of breakage in the future. By adhering to best practices, we ensure optimized page loading, performance and maintainable code.

We hope to encourage other developers to think about how to best standardize their approaches to development, to propose their own ideas for debate and for inclusion in our version of the document, and to adapt our standards for their own unique development practices. What better way of achieving consensus on how best to develop in our discipline than through feedback from members of that discipline themselves?

Intent for Build and Content

We hope to seperate the structure of the document from the content contained in the standards themselves. Effectively, our goal is to be able to easily update the content without having to worry about the structure.

This also enables pull requests to focus on content and forks to the content to be easily re-branded.

Viewing the Document

To view the latest, you can just clone locally:

git clone git://github.com/isobar-idev/code-standards.git

To make changes using the process in place, please use the build process. The next few sections describe this build process.

Building the Document

Requirements

The build system uses Grunt.js via Node.js and SASS via Compass.

First, install Node.js from their Web site.

Then, prior to running the build commands, make sure you have ruby 1.9.3 installed, ideally using RVM (Mac OS X and Linux) or RubyInstaller (Windows).

Build Details

We are using Grunt to run the Assemble task to parse, populate variables, and combine files for the HTML, Markdown, and Handlebars templates.

Note: Assemble is an exceptionally active and flexible framework for building static HTML pages. It allows the usage of Handlebars, Markdown, and HTML files so we can gradually migrate to Markdown content files over time.

We suggest you check out Assemble as well.

The Gruntfile (grunt.js) includes the build for the multi-lingual copies of the document. There is a variable for standards.defaultLanguage which will determine what language the default index.html is rendered in.

To start with a clean slate, the Gruntfile has a cleanup task which will remove the previously generated index.html and associated language files.

There is also a watch task if you like to work that way.

Execute the Build

Run 'npm install' from the command line of the project directory to install all the node dependencies. You may need to occasionally re-run this command as new dependencies are added.

Windows: You may need to manually run npm install -g grunt and npm install -g grunt-cli to correctly set the path variables required to run grunt from the command line.

Run 'grunt' from the command line of the project directory to run the build process.

Structure of Page Content

The *.html files in the root are generated via grunt and should not be edited directly. There is one file per language, by language code.

./en.html
./es.html
./ru.html
...

Finally, the standards.defaultLanguage setting determines which *.html file will be copied to the index.html file.

Note: In the near future the layout and templates will be updated to include the i18l language menus.

Content

./sections/[lang]/*.html
./sections/[lang]/*.md

Each of the .html files (and soon .md - Markdown) contained within these directories is a portion of the final output file. We have separated the different sections that make up the page into individual files so that it is easier to edit.

Including A Content File

The content files are included as partials and the data and order is defined in the following folder and files:

./sections/[lang]/build/[lang].hbs
./sections/[lang]/build/data.json

The data.json file has special significance to Assemble, do not rename this file.

Page Layout (Presentation)

The main layout is a Handlebars file that the content is injected into and language specific attributes are updated.

The file is ./_layouts/main.hbs.

Structure of CSS

The CSS files are generated via Compass from the SCSS files located in the SCSS folder, which is run as part of the Grunt task.

Deploy

Because github pages only serve static content, you must push your generated files to the gh-pages branch for updates to appear online.

Something went wrong with that request. Please try again.