Requirements
I won't expose how to install these libraries and extensions. Please have a look at the contributors documentation.
Setup
This steps assumes you have successfully installed the required libraries and extensions (s. above).
- Clone the git repo
$ git clone https://github.com/olafgleba/paul.git
or download the zip and extract it on your machine. - Navigate to the
build-node-modules.command
file, double-click it. A terminal window opens and installs Paul's node modules dependencies. Do the same with thebuild-bower-components.command
file, which will install the prepared bower plugins (Both currently only executable on OS X). - Afterwards run
$ grunt
on the console now. The webserver and livereload server will start, get through all development tasks and opens a browser window with the index page of the project section1.
At this point we are set to a project section named example (don't worry, we'll deal with that later).
1) If the $ grunt
task stops with the warning: Unable to find application named 'Google Chrome Canary', open the Grundfile.js
, go to the comment section $BROWSER and set your prefered browser for development. Restart the grunt task.
The 'single direction' approach
Paul's workflow is based on a single direction approach. That means we have one main app/
output folder for both, development and deployment. The app/
folder may never be touched directly. Regardless what grunt task is running,- the content of this folder will change continiously.
Separation between output (app/
) and building (source/
) is very handy to let grunt do a lot of cumbersome work for us. It enables variable substitution to automate the inclusion of javascript, css paths, setting project meta data and more.
So, where do we put the real stuff to work with? Let's dig in the source/
folder...
The source/
folder
The source/
folder contains two main branches: scss/
and sections/
. While the scss/
folder contains the (S)CSS structure for any project section, within the sections/
we organize our project sections itself (with one folder each).
|-- source/
|-- scss/
|-- sections/
Right, but what are project sections?
Consider a client project, which contains several sections for a public website to introduce the company, a admin panel for customer downloads, and a microsite the client wants to have for marketing reasons.
To get the lightest possible footprint for every section and respect different designs, segmenting these sections is rather useful to avoid loading CSS or/and javascript and other assets that are unused in a particular section.
Possibly project sections:|-- source/
|-- scss/
|-- sections/
|-- website/
|-- admin/
|-- microsite/
...
- Line 4-6: Based on the example scenario above, we have a website, admin and a microsite project section.
A project section folder is the only folder that contain editable content! All HTML, images and all other assets must be placed here (except any CSS, s. The scss/ folder). Paul comes with one example project section. Let's have a look on the folder structure and some particular files.
Expanded "example" project section:|-- source/
...
|-- sections/
|-- example/
|-- assets/ <- fonts, downloads etc.
|-- html/
-- index.html
|-- icons/
-- *.icon files / favicon
|-- img/
|-- source/
-- README.md
|-- libs/
-- base.js
|-- vendor/
-- README.md
|-- meta/
-- htaccess
-- humans.txt
-- robots.txt
- Line 4: The project section folder itself.
- Line 7: In the index.html you will notice some
@@
data. These are placeholders for variables that will substituted through grunt tasks. - Line 11: All original images must be placed within the
img/source
folder. This is usefull because on$ grunt deploy
a new folder namedminified/
will dynamically added to the structure, which contains the compiled versions of our images. - Line 14: The
base.js
is our main javascript file, where we handle calls on document.ready. No plugin code lives here! - Line 18-20: The
meta/
folder contains some file templates you might want to use. Thehtaccess
file is a modified copy of the HB5 htaccess file. All files these contains variable declarations which are substituted dynamically.
The scss/
folder
The scss/
folder contains my opinionated (S)CSS structure to build projects. To obtain a identical code base for all project sections, all CSS declaring and compiling is strictly separated from the design of a project section. To keep the focus i won't get into explaining the particular folder and file structure here. We need to add a _[name-of-the-project-section]-configuration.scss
configuration file and a analogous subfolder within scss/sections/
for every project section at least.
|-- source/
|-- scss/
-- _bootstrap.scss
-- _example-configuration.scss
|-- abstracts/
|-- base/
-- _examples.scss
|-- extensions/
-- _ext_example.scss
|-- compile/
-- dated.scss
-- styles.scss
|-- sections/
|-- example/
-- _example.scss
|-- queries/
-- _md.scss
|-- vendor/
|-- overrides/
-- _overrides.scss
|-- utilities/
-- _functions.scss
-- _mixins.scss
- Line 4, 14-20: A project section (here with the name: example) comprised this files at least.
- Line 10: The
compile/
folder contains the two stylesheets to compile. They handle with variable substitution and will produce real SCSS templates in the root of thescss/
folder which will be the only one's to be compiled to be referenced in you HTML.
The Gruntfile.js
file
Here most of the magic happens. But instead of walk through every single task i encourage you to have a look at the extensive annotions within this file. The comments will probably gives you a rather comprehensive overview how Paul works.
Common Workflows:
Add a new project section
- If applicable, stop grunt execution
- Dig into the
source/sections
folder and add a new project section folder (with a subfolder structure equivalent to the example folder). Hint: Just copy the example folder and rename it. In this case you got all prepared HTML a.s.o. at one go.|-- source/ |-- scss/ |-- sections/ |-- example/ |-- [name-of-new-project-section]/ ...
- Go to the
source/scss
folder and:- Add a new configuration file (line 5) with the same naming scheme
- Add a new section folder (Line 9) containing the same subfolders as the example folder.
|-- source/ |-- scss/ ... -- _example-configuration.scss -- _[name-of-new-project-section]-configuration.scss ... |-- sections/ |-- example/ |-- [name-of-new-project-section]/ ...
- Open
package.json
in your editor - Within the
activeSection
directive replace the value of thename
attribute with your new project section name (line 4){ ... "activeSection": { "name": "[name-of-new-project-section]", ... }
- Start Paul by enter
$ grunt
on the console. You're done.
Switching between project sections
Switching between sections is as simply as changing the name attribute in our package.json
file and restarting Grunt.
- If applicable, stop grunt execution
- Change the project section name
{ ... "activeSection": { "name": "[your-project-section-name]" ... }
- Start Paul by enter
$ grunt
on the console. You're done.
Add/remove a Bower plugin
You'll probably want to add/remove plugins to fit your project. After installing the desired plugin with bower ($ bower install <package> --save
), just pick up the path to the main plugin file, open the package.json
file and append it to the plugins hash (Line 9) of the activeSection directive.
You even don't have to stop/start the grunt task, as the package.json file is recognized by the Grunt watch task on document save. The plugins.js
file, which concatenate all plugins automatically, will be rebuild immediately.
To eliminate a bower plugin from concatenation, simply delete the path reference within the plugins directive within the package.json
.
{
...
"activeSection": {
...
},
"plugins": [
"bower_components/fastclick/lib/fastclick.js",
"bower_components/jquery.easing/js/jquery.easing.js",
"bower_components/<path>/<to>/<the>/<new>/<plugin>"
]
...
}
Add a vendor stylesheet/javascript file
Arbitary stylesheets and javascript files are included on project section level. Vendor stylesheets get into the vendor folder within the corresponding section:
|-- source/
|-- scss/
...
|-- sections/
|-- [name-of-new-project-section]/
...
|-- vendor/
-- [your-vendor-stylesheet]
...
Line 7: To make SASS aware of the vendor stylesheet, it's necessary to change the suffix of these files from .css
to .scss
.
Just place vendor javascript files in the correspoding folder as well:
|-- source/
|-- sections/
|-- [name-of-new-project-section]/
...
|-- libs/
|-- vendor/
-- [your-vendor-javascript-file]
Line 7: All files placed within the vendor folder will be concatenated to the dynamically created plugins.js
file automatically.
Change project credits and metadata
Appropriate files contains dynamically inserted banners with some project credits and other meta information. We can change this on one spot within the package.json
file.
Initially it's filled with Paul's meta data:
{
"name": "Paul",
"description": "Frontend development with Grunt, Sass, Bower and inuit.css",
"version": "1.0.0",
"homepage": "http://github.com/olafgleba.github.io/paul",
"author": {
"name": "Olaf Gleba",
"email": "og@olafgleba.de"
}
...
}
Remove javascript library inclusion
Sometimes there is no need for having a (relative) heavy javascript library such as jQuery. So, whenever it's not necessary, we should prohibit the inclusion.
- Open the
Gruntfile.js
and go to the$INC-LIBRARY
comment block. Change the value of the library variable from:
library: grunt.file.readJSON('bower_components/jquery/bower.json')
to
library: ""
- Delete all references within you HTML files