Test Proj

Test Proj is a Front-end project created with XH Generator, a Yeoman generator for scaffolding web projects.

Table of contents

• Prerequisites
  • Node.js
  • Grunt
  • Bower
• Usage
  • Project Structure
  • Getting Started
  • Development
  • WordPress Development
• Tips & Tricks
  • Working with Files in the dist Folder
  • Writing Syles
  • LibSass Notices
  • Adding 3rd-party Dependency via Bower
  • Using Sprites
  • Automatic SVG Fallbacks

Prerequisites

The following software needs to be installed if you want to use develop & build project created with XH Generator. These installations need to be done just once so you can skip this section if you have the software already installed.

(Note: As a command line replacement at Windows we recommend ConEmu.)

1) Node.js

Install Node.js so you can work with npm, Node package manager.

2) Grunt

Then install Grunt's command line interface (CLI) globally:

npm install -g grunt-cli

3) Bower

For managing certain dependencies like Bootstrap, you will need Bower, another package manager. Install it from the command line too:

npm install -g bower

Also make sure that git is installed as some bower packages require it to be fetched and installed. On Windows ensure that Git is installed in your PATH by selecting Run Git from the Windows Command Prompt option during installation (check this screenshot).

Usage

1) Project Structure

The meaning of files and folders in generated project structure are as follows:

• dist - production / preview files are automatically generated here, this is where you check your work in a browser.
• node_modules - Node.js modules for various Grunt tasks, usually you don’t have to do anything about this folder
• src - source files, development is done here
  • bower_components - 3rd party libraries managed via Bower
  • grunt - atomic grunt tasks configuration
  • includes - HTML partials like head.html, scripts.html, etc.
  • scss - Sass files
    • main.scss - main file where other stylesheets are imported
    • common - common styles for most of pages
    • components - styles for page modules/components; this is where most of your styles will go
    • setup - various configurations and preprocesor helpers
    • vendor - styles overwriting/replacing library ones
  • js
    • main.js is a main JS file in project
  • home.html, etc. - HTML files composed from HTML partials
• index.html - project index with project pages listed
• Gruntfile.js - Grunt file with various automation tasks defined in it
• bower.json - Bower dependencies in the project
• package.json - npm packages dependencies
• .yo-rc.json - Yeoman generator configuration file
• .bowerrc - configuration file for Bower
• .editorconfig - EditorConfig configuration file to achieve consistent coding style
• .gitattributes - Git configuration file to force Unix line ending in all text files
• .gitignore - default Git ignore files and folders
• .jshitrc - JSHint configuration

On a typical project, you will work in src folder and check your work in dist folder so you don’t have to touch other files. For more info about working with styles structure go to Writing styles section.

2) Getting Started

If you are joining an existing project which was set up using XH Generator (assuming that you have all prerequisites installed), all you need to do is to clone the existing repository and install Bower and npm dependencies.

Let's imagine you have cloned/unpacked Test Proj project into test-proj directory.

First, change the directory to your cloned project:

cd test-proj

After that install Bower depedencies:

bower install

Then install npm dependencies:

npm install

Finally, (re)generate preview files in the dist folders:

grunt build

If everything went ok, the preview files will be generated and you will be able to check your work in the dist folder.

Now the project is set up and you can continue like described in the Development section.

3) Development

When you have the basic setup done, you can start development. To re-compile HTML / scss file in real time you can use default task. Type

grunt

and this will start a task that will watch for changes in files and recompile them as needed. Additionaly, development server will be started and BrowserSync scripts injected.

To rebuild the whole project, use the grunt build task again

grunt build

To validate HTML, use the following task

grunt validate

Tips & Tricks

Working with Files in the dist Folder

In general, it’s not recommended that you work directly with files in the dist. The files in dist folder are automatically generated from the source files in src folder and by default dist folder is ignored in version control system.

HTML and CSS files are prettified for consistent formatting and a table of contents from imported Sass stylesheets is generated at the beginning of main.css for better overview.

Writing Styles

The following source files are generated in src/scss folders:

• main.scss - main file where other stylesheets are imported
• common - common styles for most of pages
  • base.scss - normalized base styles
  • layout.scss - main page structure
  • utilities.scss - utility classes (image replacement, hide, etc.)
• components - styles for page modules/components; this is where most of your styles will go
• setup - various configurations and preprocesor helpers
  • variables.scss - variables file
  • mixins.scss - mixins file
  • sprites.scss - sprite mixin
  • sprites.scss.mustache - template file for generating actual sprites code
• vendor - styles overwriting/replacing library ones

The following approach is recommended when creating styles:

1. Use main.scss only for importing other stylesheets. Do not write styles directly in this file!
2. Use variables and mixins files to store your variables and mixins.
3. Depending on your preferences for styles organization, you can organize them according modules & components (recommended, use components folder), or pages. A good practice is to name file the same as main class used for that component, for example if you create a component representing an article with .article as a main CSS class followed by .article-title, .article-meta, etc. and with .article--featured variant that will have slightly different color scheme, you will do everyone a favour by placing it in scss/components/_article.scss file instead of scss/components/_text.scss.
4. If you find yourself overwriting/replacing default library styles, put them into vendor folder. A good examples of that are replacing library custom select or lightbox styles with your own or overwriting some Bootstrap styles that were not configurable.
5. Comment main sections and subsections appropriately.
6. By default autoprefixer is enabled in project, which mean that you don't need to write prefixes for the standard CSS3 properties. It uses Can I Use database. However, please note that some popular properties (like -webkit-appearance or -webkit-font-smoothing are not a part of standard and need to be written with prefixes by you).

Adding 3rd-party Dependency via Bower

Let’s say you want to add Colorbox to your project. The following example shows how you can add it as a Bower package and merge its JS file into common plugins.min.js file.

1. First, install it via Bower

   bower install jquery-colorbox --save-dev
   

2. Then link it in src/includes/scripts.html. This will ensure that the library will be added to plugins.min.js file

   <!-- build:js js/plugins.min.js -->
   <script src="bower_components/jquery/dist/jquery.min.js"></script>
   <script src="bower_components/jquery-colorbox/jquery.colorbox-min.js"></script>
   <!-- endbuild -->
   <script src="js/main.js"></script>

3. Go to src/bower_components/jquery-colorbox and copy images from example1/images folder to src/img/colorbox folder.

4. Get example1/colorbox.css from the same dir, rename it to _colorbox.scss, store it in src/scss/vendor folder and adjust to your needs if needed.

5. Import _colorbox.scss in main.scss

   @import "vendor/colorbox";

6. Replace all instances of images/ in _colorbox.scss with ../img/colorbox/

7. Run the grunt build task or grunt task

8. Now you can use Colorbox in your HTML files and initiate it from src/js/main.js

Using Sprites

When relevant option is selected during setup, tasks for automatic sprite generation are added. Out-of-the-box only PNG files are supported, however if for some reason other source files are needed (like JPGs and GIFs) it is possible to add them (it will require installing some additional dependencies tough).

Sprites generation is accomplished using grunt-spritesmith. Detailed documentation regarding available options and generation engines is described there.

In the XH Generator default configuration you are expected to put yor files in src/img/sprites/1x/ directory for normal-density screens and src/img/sprites/2x/ for retina & similar ones. Filename of the image should be the same - let's say home.png. When task finishes running (it may take some time, which is why sprite generation is optional feature), you will be able to use sprite helper mixins in your code. The one you're most interested in can be found in src/scss/setup/_sprites.scss - sprite-retina mixin. It takes two arguments (for now, we're planning to further simplify that) - variable that holds normal sprite data & variable that holds retina sprite data. Those variables were generated for you when task ran. To make it clearer, using scss for our example home icon you would do:

.my-home-icon {
    @include sprite-retina($sprite-1x-home, $sprite-2x-home);
}

The exact variable names can be found in src/scss/setup/sprites@N.scss

Important! Currently you need to provide both files (nomal & retina). If you do not, the output sprite images will differ and as a result generated background-position values will be incorrect.

Automatic SVG Fallbacks

Vector graphics is increasingly more popular in web development due to its prefect look no matter the scale. As such you will probably find yourself using SVG files or icon fonts more and more often. However, not all browsers support SVGs out of the box, so fallbacks are needed. Currently XH Generator supports automatic optimization of SVG files (along with various other raster image formats) and PNG fallbacks creation. The caveat for correct automatic fallbacks is that SVG viewport needs to have proper size (PNG file will have the same dimensions). Also, if something seems off you can play with optimization settings in grunt/contrib-imagemin.js task.