Front End start template and short guideby Anton Yatsenyuk

Before you start:

You need to have NodeJS and NPM installed. See this tutorial for help.

Start new project:

Every new project will start from common basic template and file structure.What includes:

- /index.html - start html template. Use it for all *.html files- /styles/sass [or less]/ - directory for css-preprocessor sources- /styles/css/ - directory for main.css output. Compiled main.scss or main.less will be saved there for later

processing.- /assets/ - folder for loaded assets that you cannot install with bower. Save files for it in this folder and

include them in your *.html from /assets folder.- gulp - build system: compiles sass/less, concatenates many files into one, runs local server and other

stuff…- bower - package manager. Use it to install needed dependencies (bootstrap, jquery, jquery-ui… if it

exists in bower library).- gulpfile.js - gulp configuration file. All information about how to use it you can find below or in file

comments.- package.json - npm configuration file. Stores dependencies and short info about project.- bower.json - bower configuration file. Stores bower installed dependencies.

Step 1:

Download ZIP and paste content from it into your “new_awesome-project” directory.Install dependencies:*depends on your OS you should run commands with root access (sudo ...)

$> npm install

After successful installation run:

$> bower install or$> sudo bower install --allow-root

… if first command returns error.

Step 2:

Choose your CSS preprocessor and create main.scss[less] file in the /styles/sass[less] directory. You already have /styles/sass folder.If you want to use LESS instead of SASS just rename that folder to ‘less’ and create main.less file inside it.IMPORTANT: main styles file should have name “main.*” and nothing else.

Step 3:

Open gulpfile.js in your editor and depend on you CSS preprocessor choice you need to configure gulp.On 10-th line you can find VAR block, there are 2 variables:

useSASS = falseuseLESS = false

Change false value to true only on variable that equals with your CSS preprocessor choice. Save and close gulpfile.js.

Congratulations :)>>>

Bower:

Use search to find libraries that you need. To install some, open terminal in project folder and run:

bower install $libNameHere --save

You don’t need to include JavaScript libraries from bower_components/ all libs will be concatinate in one file - vendor.js and this file is already included in the template.vendor.js file will update automatically after installing new bower dependency, when you start gulp.

Gulp:

To run gulp, open terminal in project folder and run: (more info is in gulpfile.js)

gulp watch // run web server and compile all assets

gulp build // just compile assets

File Structure Style:

- Group files into folders based on their logic.- All project files should be named based on their logical presentation.- Don’t use spaces in the filename.- Use dash for a word separator.- Use lowercase filenames.

Good:navbar.htmlmessages-list.scssauth-service.js

Avoid:mainTopHeader.htmltopNavButtons.scssmainMessagesController.js

Big project structure:

If project is large and you created a lots of files try to group them in folders, for example:

SASS/LESS code style:

Use indentation with 4 spaces. Setup your editor with this setting and use it always.Keep CSS properties in alphabetical order.

Avoid BetterExample:

SASS/LESS code style:

In /styles folder you will have a main.scss or main.less file. DO NOT write any styles inside it. This file contains all your modules. Use @import to include created modules to the main file.

First module should be “variables”.In this module describe all colors that are in the project and default colors like:$white: #fff;$black: #000;After colors variables create fonts variables for each font family in project.Variables naming style is the same as for files (lowercase, separate words with dash...).Create modules for every new instance. For example you should have separate modules for header, footer, aside, custom buttons, forms, and other GUI elements.

If you need any helper classes like: .no-padding, .no-margin etc. Create one module called “helpers” and describe all your helpers there.

Classes naming:

We will use simplified BEM-like class naming style in our code, based on suffix. Try to keep blocks independent from their parent blocks, if it is not necessary.

Classes naming:

On this image you can find many blocks inside main parent “Head block”. We need to provide styles for each of them so that we can just copy some child block from “Head block” and paste in other place in our html page and it will looks the same as in “Head” or with minimal difference.

Classes naming:

Let’s do short example with “Head block” and “auth block”.HTML looks like this:

Classes naming:

And auth-block.scss module by our guide:

Variables are from our variables.scss module.

We used *-suffix in our styles instead of child classes. Why and what it gives to us?

Classes naming:

Let’s look in our compiled but not minified yet CSS output (/styles/css/main.css):

Let’s compare our source styles (left tab) and compiled styles (right tab).In our working SASS we’re having logical cascade that is only for developers to understand what is going on there, but on the output CSS file we have no cascade and that is the best and fastest for page rendering result.There will be situations when you’ll need nested-class inheritance and it’s OK and it’s not prohibited. Just try to use this way rarely.

Classes naming:

But what should we do if in “Aside block” we need “Auth block” with different button background?So there is a way to do this:In our aside-block styles module we can use .auth-block(and children) as nested block and make styling for it.

So with this structure we can use HTML-code of our “Auth block” anywhere in project and it won’t ruin itself.

Conclusion:

Use these simple instructions and practices in you projects and your life and life of your teammates will be much easier.If you have any proposals or questions you know where to find me :)

Sincerely yours, Anton Yatseniuk