search

xfiveco / generator-xh

A Yeoman generator for scaffolding web projects.
MIT License
55 stars 5 forks source link

readme

XH Generator Build Status NPM version NPM dependiencies

XH Generator is a Yeoman generator for scaffolding web projects.

NPM

XH Generator is not maintained anymore, please use Chisel generator instead.

XH is suitable for client work when you deliver a completed project to your client for further review and development.

XH Generator creates a project structure, files and Grunt tasks which support modern workflows like CSS preprocessors. Built HTML, CSS and JS files are prettified and fully editable so clients can work directly with them if they wish.

Project index

Table of contents

Features

Getting Started

The following software needs to be installed if you want to use 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).

4) Yeoman

XH Generator is a Yeoman generator, so obviously it depends on it. You can easily install Yeoman with the following command:

npm install -g yo

5) XH Generator

Finally install the XH Generator:

npm install -g generator-xh

Congratulations, you are now ready to use XH Generator!

Usage

1) Project scaffolding

To create a project with XH Generator, create a new folder, open a command line in it and type:

yo xh

You will be presented with a welcome screen and project scaffolding options. Answer the generator questions according your project needs.

Project scaffolding

Once done, the generator will create the required files and folders and install all npm and Bower dependencies for you:

NPM & Bower installation

XH Generator allows you to generate projects based on provided configuration. If the yo-rc.json file is present in project root folder, you will be prompted to type new name for the project and the rest will be scaffolded automatically.

Use --config option to provide a path to your custom configuration file (if you're storing the file in your home directory, use non-default name for it, ie. .yo-config.json - otherwise Yeoman will change the project directory to your home dir):

yo xh --config ~/.yo-config.json

Example of valid configuration file:

{
  "generator-xh": {
    "config": {
      "projectName": "Default Project Name",
      "useBranding": true,
      "reloader": "BrowserSync",
      "devServer": true,
      "cssPreprocessor": "scss",
      "ignoreDist": true,
      "isWP": false,
      "features": [
        "useJquery",
        "useOptim",
        "useBootstrap",
        "useModernizr",
        "useSprites"
      ]
    }
  }
}

2) Project structure

The generated project structure will look like this:

Project structure

The meaning of files and folders are as follows:

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.

3) Adding pages to the project

Once you have basic project structure generated, you should add pages you will be working on. XH Generator comes with a subgenerator for adding new pages to the project.

From the command line type:

yo xh:page "Page Name"

for example

yo xh:page "Home"

You can also create multiple pages at once by separating page names with space:

yo xh:page "Home" "About Us" "Contact Us" "News"

The command will do the following:

  1. creates a HTML file for your page in src folder from the template file src/template.html. If you want you can update the template file as needed, so the generated files look accordingly.
  2. adds a page name and link to it to the project index
  3. runs grunt build command to generate the page

Page added

When running the command, you will asked if index.html should be overridden:

Project index overwrite

If you wonder what Yanxdh means in the above screenshot, it is:

Confirm overwriting the file with Y or with a at once.

Generating multiple pages at once

You can also list the pages that you want to create directly in the .yo-rc.json file:

{
  "generator-xh": {
    "config": {...},
    "pages": [
      "Home",
      "About Us",
      "Contact Us",
      "News"
    ]
  }
}

Then, from the command line you can type:

yo xh:page

After you run the command, please proceed with the flow described above.

4) Development

When you have the basic setup done and your first page added, you can start development. Run the grunt build command to generate preview files in the dist folder:

grunt build

grunt command

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

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. If relevant options were selected during project setup, development server may be started and/or BrowserSync (or LiveReload) scripts injected.

grunt watch command

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

grunt build

To validate HTML files, use the following task:

grunt validate

To detach X-Precise from pages, rebuild the project, validate HTML files and check JavaScript files with JS Hint, use the following task

grunt qa

5) WordPress Development

XH Generator supports WordPress development. When setting up the project using yo xh, answer Yes to the question Is this a WordPress project?. The generator prepares directory structure for WP installation and connects the front-end files to the project theme.

Use the WordPress subgenerator to set up a WordPress project any time in the project life cycle:

yo xh:wp

Several options are available:

Once you run the subgenerator, it does the following:

When running Grunt tasks the front-end dist files are automatically copied to your theme folder, so you can continue working on the front-end like usually and all updates will be applied to the WordPress site as well.

6) Collaborating

If you are joining an existing project which was set up using XH Generator, remember that the project was already generated with yo xh command so you don't have to generate it again. 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 we have a project called Robot Magic here at the Xfive GitHub account. First, we will clone it locally:

git clone git@github.com:xfiveco/robot-magic.git

Now change the directory to your newly cloned project:

cd robot-magic

First, install Bower depedencies:

bower install

Then install npm dependencies:

npm install

Now the project is set up and you can continue like described in the Development section. If there are no pages in the project yet, first you need to add some pages to it.

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. However, once you hand over the project to your client, they can work directly with plain HTML and CSS files if they wish.

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

Writing styles

XH Generator supports Sass or Less. Sass syntax is not recommended. The following source files are generated in src/scss or src/less folders:

The following approach is recommended when creating styles:

  1. Use main.scss or main.less only for importing other stylesheets. Do not write styles directly to these files!
  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. If you want to avoid using preprocessors for certain reason (eg. your project is very simple), you can still use SCSS or Less files to write only regular CSS.
  7. 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

  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="https://github.com/xfiveco/generator-xh/raw/master/bower_components/jquery/dist/jquery.min.js"></script>
<script src="https://github.com/xfiveco/generator-xh/raw/master/bower_components/jquery-colorbox/jquery.colorbox-min.js"></script>
<!-- endbuild -->
<script src="https://github.com/xfiveco/generator-xh/raw/master/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|less} - 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|less} files if you need to check them.

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.

Working with Files Other than *.html

During project setup there is an option to specify default pages extension. It will automatically configure some tasks like watch or usemin to work with files other than *.html (like *.php or *.jade). However, it will disable development server - it is assumed that when you need other file types it also means you need to configure something that will be responsible for processing them, be it local server (like Apache or Nginx) or some template processing engine.

This setting will be remembered in the project configuration, so when you run yo xh:page it will create files with correct extension.

Live Reloading Tips

Disable Index Page Auto-opening

For BrowserSync

In grunt/browser-sync.js file find options section and add open: false.

For LiveReload

In grunt/contrib-connect.js file find options section and either remove open: true or change it to false.

BrowserSync Proxy

During setup, when you choose not to run development server (or are unable to run it), you will be asked about URL of the page you will work with. By default this is localhost, but you can change it to something like project.dev or anything you like. When running development (default) grunt task, BrowserSync will then set up proxy server (by default on port 3000), that will allow you to use live reloading while for example simultaneously serving pages via Apache (and using PHP).

Browserify

With version 0.7 comes support for Browserify module bundler (available as an option from additional features), so feel free to require('module') in your JS code. Example usage is provided in main.js. Also be sure to check out browserify-shim in case you need compatibility with some non-AMD, non-CommonJS packages (e.g. from bower) or with some jQuery plugins. Always use npm packages where possible.

Changelog

Check Releases

Contributing

If you want to contribute to the XH Generator development, watch the project repository so you are notified about the new issues and related discussion.

Each fix or new idea needs be added as an issue so they can be referred later and reviewed and discussed if necessary.

The following labels are used to mark the issues and ensure predictable generator API and usage:

Please also follow the GitHub guides for contributing and reporting issues to the project:

Credits

XH Generator is inspired by Yeogurt Generator.

License

XH Generator is licensed under MIT License.