Paul Docs

• Node.js
• Grunt
• Bower
• SASS
• SASS-Globbing Plugin

I won't expose how to install these libraries and extensions. Please have a look at the contributors documentation.

This steps assumes you have successfully installed the required libraries and extensions (s. above).

1. Clone the git repo $ git clone https://github.com/olafgleba/paul.git or download the zip and extract it on your machine.
2. 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 the build-bower-components.command file, which will install the prepared bower plugins (Both currently only executable on OS X).
3. 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 section¹.

At this point we are set to a project section named example (don't worry, we'll deal with that later).

¹) 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.

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 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/

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.

|-- 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.

|-- 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 named minified/ 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. The htaccess file is a modified copy of the HB5 htaccess file. All files these contains variable declarations which are substituted dynamically.

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 the scss/ folder which will be the only one's to be compiled to be referenced in you HTML.

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.

1. If applicable, stop grunt execution
2. 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]/
           ...

3. 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]/
           ...

4. Open package.json in your editor
5. Within the activeSection directive replace the value of the name attribute with your new project section name (line 4)

   {
     ...
     "activeSection": {
       "name": "[name-of-new-project-section]",
       ...
   }

6. Start Paul by enter $ grunt on the console. You're done.

Switching between sections is as simply as changing the name attribute in our package.json file and restarting Grunt.

1. If applicable, stop grunt execution
2. Change the project section name

   {
     ...
     "activeSection": {
       "name": "[your-project-section-name]"
       ...
   }

3. Start Paul by enter $ grunt on the console. You're done.

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>"
    ]
    ...
}

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.

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"
  }
  ...
}

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.

1. Open the Gruntfile.js and go to the $INC-LIBRARY comment block.

2. Change the value of the library variable from:

   library: grunt.file.readJSON('bower_components/jquery/bower.json')

   to

   library: ""

3. Delete all references within you HTML files

Back to index page