Commit aab0345b authored by Philipp Nowinski's avatar Philipp Nowinski
Browse files

[TASK] update documentation

parent ee50732a
![sgalinski Internet Services](http://www.sgalinski.de/_Resources/Static/Packages/SGalinski.SgalinskiDe/Images/logo.png "sgalinski Internet Services")
# generator-gulp-sgalinski
> [Yeoman](http://yeoman.io) generator
......@@ -34,7 +36,7 @@ The first question the generator will ask you, is what kind of a project you wan
different kinds of projects: Standalone and TYPO3 projects.
#### Standalone
The standalone option is meant for scaffolding projects that do not require a backend. At Sgalinski Internet Services,
The standalone option is meant for scaffolding projects that do not require a backend. At [sgalinski Internet Services](http://www.sgalinski.de/),
we mainly use this for building prototypes.
#### TYPO3 projects
......@@ -46,24 +48,53 @@ some config files inside the extensions folder, so that gulp knows where to put
### Firing up gulp
To invoke a gulp task, you simply run 'gulp', followed by the name of the task you want to run. E.g. if you want to run
the CSS task, you'd run 'gulp css'. Below, you'll find a list of commands that come bundled with this generator. Please
note, that you will always have to run the command inside the directory in where your gulpfile lives. If you are working
on a TYPO3 project, you will also need to specify the extension you want to work on with the '--ext' parameter.
the CSS task, you'd run 'gulp css'. Below, you'll find a list of commands that come bundled with this generator.
#### Work with extensions
If you are working on a TYPO3 project, there are two different ways of running tasks. You can either run a specific task for a specific extension, or you can run the default task, which will start a dev environment with BrowserSync and a couple of watchers.
##### Running a specific task
If you just want to run a specific task for a specific extension, run
```bash
gulp [taskname] --ext [extensionname]
```
E.g. if you want to run the CSS task for an extension called 'acme_base', run
```bash
gulp css --ext acme_base
```
You must specify the extension name here, to tell gulp which SASS files you want to compile.
##### Watching the whole project
By running
```bash
gulp
```
you will get a development environment with BrowserSync and some watchers that will automatically trigger tasks when you change sourcefiles. If you are not familliar with [BrowserSync](http://www.browsersync.io/), you should definitely check it out.
BrowserSync will basically start up a server and provide you with a URL which points to your project. If you are running a standalone project, BrowserSync will simply serve files from your project root. If you are running a TYPO3 project, BrowserSync will be set up with a proxy that tunnels request to your development URL. You can change this URL inside gulp/browser-sync.js. Apart from the livereload functionallity, BrowserSync offers some other cool features like syncing Mouse- and Keyboardevents. Since version 2.0.0, there is also a UI with a lot more to discover. You should read about this on the BrowserSync website.
E.g. if you want to run the image optimizer for an extension called 'acme_base', run 'gulp images --ext acme_base'.
Once the default tasks started and BrowserSync is ready to serve your files, all changes you make to you CSS and JavaScript files will automatically injected into the browser, without reloading the site. Gulp will automatically figure out the extension you made changes to and pass the information to the corresponding task.
#### Available gulp tasks
* default
* [command: 'gulp']
* The default task will be triggered by just calling 'gulp' without a specific task name. It will trigger the css
and the javascript task and then start browser-sync/livereload and all watchers.
* The default task will be triggered by just calling 'gulp' without a specific task name. It will start BrowserSync and watchers for your CSS and JavaScript.
* css
* [command: 'gulp css']
* The css task will compile your sass files and run all configured post-processors on them.
* The css task will compile your sass files to css and run a bunch of additional processes on them.
* It will run the included sprite-engine ([learn how to use it](docs/SPRITE-ENGINE.md)).
* It will resolve css-width and css-height functions ([learn how to use them](https://www.npmjs.com/package/gulp-css-image-dimensions)).
* It will autoprefix your css.
* It will resolve css @import-statements to avoid additional requests.
* It will generate sourcempas for your css files.
* It will minify your css if you enabled this option during project generation.
* javascript
*[command: 'gulp javascript']
* The javascript task runs jshint on your JS files. Depending on your configuration, it also runs
(http://browserify.org/)[browserify] on them, or concatenates them into on file. If you chose this option when
[browserify](http://browserify.org/) on them, or concatenates them into one file. If you chose this option when
generating the setup, it will also minify them.
* images
* [command: 'gulp images']
......@@ -73,7 +104,6 @@ E.g. if you want to run the image optimizer for an extension called 'acme_base',
* [command: 'gulp browser-sync']
* BrowserSync starts a webserver with built-in code sync and action sync. Refer to
[the BrowserSync website](http://www.browsersync.io/) to learn more about it.
* If you're not using BrowserSync, you have the option to include [Livereload](http://livereload.com/) instead.
#### config files
The gulp-sgalinski generator will generate the following config files:
......@@ -113,29 +143,6 @@ on your ignorelist (.gitignore, .svnignore, etc.):
((http://bower.io/docs/config/)[you can change the name if you want to]). You might consider to handle them the
same way as node dependencies and just check in the bower.json file.
## What's in there?
The gulp-sgalinski generator comes packed with the following:
* Gulp tasks for
* CSS
* Compiling SASS
* You can choose to either use Compass (which will use ruby-sass), or libsass as a compiler.
* cssImport: Parses css files and insert file contents instead of @import directives.
* autoprefixer: Parse CSS and add vendor prefixes to rules by Can I Use.
* minification [optional]
* JavaScript
* JsHint
* Modular JS with Browserify [optional]
* Conatenation [optional]
* Imageoptimization
* Browsersync / Livereload
* You can choose between Browsersync and Livereload to automatically reload the website when source files change.
* Bower [optional]
* Clientside Dependency Management
* Editorconfig
* To establish a common JS code style for the project.
* HTML5 Boilerplate
* If you build a standalone project, you will get a ready-to-go index.html, filled with HTML5 Boilerplate.
## Changelog
......
......@@ -7,25 +7,15 @@ NVM (Node Verison Manager).
> First you'll need to make sure your system has a c++ compiler. For OSX, XCode will work, for Ubuntu, the build-essential and libssl-dev packages work.
To install NVM, execute on of the following commands:
To install nvm, clone this repo to get the latest version:
use curl:
git clone https://github.com/creationix/nvm.git ~/.nvm && cd ~/.nvm && git checkout `git describe --abbrev=0 --tags`
```bash
$ curl https://raw.githubusercontent.com/creationix/nvm/v0.12.1/install.sh | bash
```
or wget:
```bash
$ wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.12.1/install.sh | bash
```
To activate nvm, you need to source it from your shell:
Once the installation process finished, run the following command:
source ~/.nvm/nvm.sh
```bash
$ source ~/.profile
```
You should add this line to your .bashrc file. Remember to reopen your terminal after you modified .bashrc.
To install a specific version of Node, you can run 'nvm install [node-version]'. To install the latest stable version, run:
......
# Included sprite-engine
This generator comes bundled with the [css-sprite](https://www.npmjs.com/package/css-sprite) engine.
## How it's set up
All your sprite images have to live inside a 'sprites' folder inside your images folder. The sprite engine will generate a spritesheet inside your images folder and a _sprite.scss file inside your sass folder. To use the sprites inside your sass files, you will need to include _sprites.scss. This will provide you with a sprite-mixin and sprite-width and sprite-height functions.
```scss
@import "sprite";
.icon {
position: absolute;
@include sprite($icon-blue);
left: 50%;
margin-left: sprite-width($icon-blue)/-2;
}
```
The example above defines an .icon-class, which includes the icon-blue sprite (the original image source would be 'sprites/icon-blue.png' in this case) and makes use of the sprite-width function to center the element.
## Configuration
The _sprite.scss file is generated, based on a mustache template. You can find this template inside your gulp folder (gulp/sprite-scss-template.mustache).
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment