Commit 0e159321 authored by Philipp Nowinski's avatar Philipp Nowinski
Browse files

[TASK] add documentation

parent 4826d4a4
......@@ -29,6 +29,90 @@ To run the generator, navigate to the directory you want to create your project
yo gulp-sgalinski
```
### Standalone vs. TYPO3 project
The first question the generator will ask you, is what kind of a project you want to build. Basically, there are two
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,
we mainly use this for building prototypes.
#### TYPO3 projects
The main function of this generator is to scaffold a frontend setup for TYPO3 projects with Extbase Extensions. This
setup is separated into two components. In your project root (next to the typo3conf directory), you need to generate
the 'TYPO3 Frontend Setup'. This will install the gulp tasks to your project root. You'll then need to generate the
'TYPO3 Extbase Extension' setup inside every extensions folder you want to use the gulp setup on. This will generate
some config files inside the extensions folder, so that gulp knows where to put things when you run tasks.
### 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.
E.g. if you want to run the image optimizer for an extension called 'acme_base', run 'gulp images --ext acme_base'.
#### 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.
* css
* [command: 'gulp css']
* The css task will compile your sass files and run all configured post-processors on them.
* 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
generating the setup, it will also minify them.
* images
* [command: 'gulp images']
* The images task will optimize (lossless) all images inside you images directory. This is not part of the watch
task, so you have to start it manually.
* browser-sync
* [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:
* .editorconfig
* [Editorconfig](http://editorconfig.org/) is a great common way to synchronize editor settings across projects and
IDEs/Editors. You can simply remove it, if you don't want to use it.
* .jshintrc
* This is where you can define all rules JsHint will apply to your code. If you delete this file, JsHint will use
the standard settings. This file should also work for instances of JsHint that are built into your Editor.
* gulp/settings.js
* This is where all gulp tasks read the paths to you assets from. It will be configured according to your answers
to the generators questions.
* asset-paths.json [only for Extbase Extensions]
* If you're working on a TYPO3 project, your gulp tasks (including settings.js) will live in your project root.
Since different extensions can store their assets to different paths, gulp needs to be aware of the paths for the
extension you want to work on. This is a simple JSON file, that lives inside every extensions folder and defines
the paths for its assets.
* bower.json [optional]
* This file is where all clientside dependencies can be defined if you want to use Bower. See
[http://bower.io](http://bower.io) for more information on what Bower can do for you.
* package.json [mandatory]
* The package.json file is the manifest for every node.js module. Since gulp is written in node, you will need this
file. This is where all used node modules (e.g. every gulp task is a node module) are defined as dependencies. They
will get installed from the NPM registry when you run 'npm install' inside your project root (the generator will run
'npm install' and 'bower install' automatically for you as its last step).
#### What to check in?
There are different opinions on which files should be under version control. We recommend to put the following files
on your ignorelist (.gitignore, .svnignore, etc.):
* node_modules
* This folder can be quite heavy and its contents can differ depending on you Operating System. The recommended way
is to check in the package.json and run 'npm install' on every new checkout.
* bower_components
* If you decide to use Bower, this is where all clientside dependencies will be stored
((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:
......@@ -50,13 +134,12 @@ The gulp-sgalinski generator comes packed with the following:
* 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
* 2015-01-14   v1.0.4   bugfix for paths in image and js task
* 2015-01-13   v1.0.3   bugfix for paths in html boilerplate
* 2015-01-13   v1.0.2   bugfix for jshint paths
* 2015-01-13   v1.0.1   bugfix for minified js path
* 2015-01-19   v1.1.0   major changes to the scaffolded gulp tasks + massive README
* 2015-01-13   v1.0.0   add livereload as browsersync alternative [first stable version]
* 2015-01-12   v0.1.0   release
......
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