README.md 7.1 KB
Newer Older
Philipp Nowinski's avatar
Philipp Nowinski committed
1
2
3
4
[![sgalinski Internet Services](http://www.sgalinski.de/_Resources/Static/Packages/SGalinski.SgalinskiDe/Images/logo.png  "sgalinski Internet Services")](http://www.sgalinski.de/)

# generator-gulp-sgalinski

Philipp Nowinski's avatar
Philipp Nowinski committed
5
> **NOTE:**
6
> This project is deprecated and will not be developed any further. The gulp-toolchain is now integrated into sgc [(sgalinski cli)](https://www.sgalinski.de/typo3-produkte-webentwicklung/gulp-frontend-toolchain/).
Philipp Nowinski's avatar
Philipp Nowinski committed
7

Philipp Nowinski's avatar
Philipp Nowinski committed
8
9
10
## Installation

To use the sgalinski-generator you need to have node and npm installed. Furthermore, you should have
11
yeoman and gulp installed globally. To do so, simply run
Philipp Nowinski's avatar
Philipp Nowinski committed
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

```bash
npm install -g yo
npm install -g gulp
```

Finally, to install the generator, run

```bash
npm install -g generator-gulp-sgalinski
```

## Usage

To run the generator, navigate to the directory you want to create your project in and run

```bash
yo gulp-sgalinski
```

This will generate all the files you need to run the toolchain, including a config.json file which you will have to adapt to your needs.

Here is what you get in detail:

* gulp | this folder contains the gulp tasks, split into several files, as well as the config.json
* gulpfile.js | The entry point for gulp
* package.json | The package file that contains all needed Node dependencies
* npm-shrinkwrap.json | This file contains all required dependencies, locked down to a specific version number ([learn more](https://docs.npmjs.com/cli/shrinkwrap))
* install.sh | you can execute this file to ensure a proper installation of the toolchain. It will set up the correct version of Node, Gulp and the toolchain.
* .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 | The configuration file for jshint
* .scss-lint.yml | The configuration file for Scss-Linters

45
46
47
48
49
50
51
52
53
### The install script

Since version 4.0.0, the toolchain comes with an installation shell-script. The purpose of this script is to easily set
up the correct version of Node and gulp and to install the toolchains dependencies in one single step.

While this might not seem important during the initial creation of a project, it is rather handy when setting up the 
development environment at another machine. After checking out the repository of your project, your fellow co-workers
will simply have to execute the install.sh in order to get the toolchain up and running.

Philipp Nowinski's avatar
Philipp Nowinski committed
54
55
56
57
58
59
60
61
62
63
64
### Useful tasks

#### Updating / Installing the toolchains dependencies

> This task will also be executed by the install.sh script

In order for the toolchain to work, you need to install all its dependencies. To do so, you can simply run the update task
(this will also work for the initial installation). Please note that you need to go to the website root
(e.g. web/website-base.dev/) in order to execute this command.

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
65
npm run toolchain:update
Philipp Nowinski's avatar
Philipp Nowinski committed
66
67
68
69
70
71
72
73
74
75
76
77
```

This task will delete all previously installed dependencies and pull in the new ones.

#### Upgrading the toolchain

> **Caution!**
> This task is only meant for finishing up a new release of the toolchain itself.

To upgrade all dependencies and rewrite the npm-shrinkwrap, run the following command:

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
78
npm run toolchain:upgrade
Philipp Nowinski's avatar
Philipp Nowinski committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
```

The upgrade task will delete all dependencies, remove the current shrinkwrap and then install the new dependencies (as stated in package.json) and create a new shrinkwrap.

If you run this task, make sure that you know what you're doing, as updating dependencies can break stuff if not propperly tested!

## Configuration

To adjust the toolchain to a certain project, there is a [config.json](app/templates/gulp/config.json) file where the following options can be configured:

### directories

Holds the paths to the css, sass, javascript, images, sprites and inline-svgs, relative to the extensions root.

### abovethefold

Configuration for the critical path css.

* template: *path to the src template*
* dest: *path to the destination*

### js

* libraryPaths: *additional locations that should be searched when resolving CommonJS requires*
* excludeFromQa: *glob patterns with locations that hold JavaScript that does not need to be linted (vendor stuff)

### images

* optimize: *locations of user uploaded images that should be optimized*

### extensions

A list of extensions that should be included in the watch task. Please note, that the very first extension in this list is expected to be your project_theme.

## Usage
You can run a specific task on a specific component, or start a watcher that will fire up BrowserSync and run tasks when
source files change. Extensions that will be watched are defined in [config.json](gulp/config.json).

If you run a specific task, you need to specify the extension you want the task to run on with the --ext parameter.

```bash
gulp css --ext project_base
```

There are a few available tasks you need to remember:

### default/watch task

```bash
gulp
```
Starts a project wide watcher that will trigger the css/javascript task when you change any .scss, or .js-file and opens
the website in your browser, as a browsersync session (changed js and css will automatically get injected when recompiled).

*Hint:* If you already have a browsersync instance open in your browser, you can pass the argument -s to restart the session without opening a browser.

### sprite task

```bash
gulp sprites --ext [extensions name]
```

Triggers sprite generation inside the given directory.

Assumptions:

* all sprite images are inside images/sprites, relative to the given path.
* all sprite images are PNGs.
* there is a sass directory, next to the images folder.

This task will generate a png inside the images folder, containing all the sprites and a .scss file inside the sass
folder, which will provide the necessary mixins. To use the sprites inside your SASS code, import the _sprite.scss file.
You can then use the following mixins:

```scss
// will output css for a sprite image 'box.png'
.element {
	@sprite ($box);
}
```

The @sprite mixin already contains width and height. If you need these values for something else, use the @sprite-width
and @sprite-height mixins.

### css task

```bash
gulp css --ext [extension name]
```

Triggers css compilation inside the given directory. Note, that this task will also run the sprite task before it starts.

Assumptions:

* all scss files are inside the sass directory, relative to the given path.
* all css files go into the stylesheets directory, relative to the given path.

### images task

```bash
gulp images --ext [extension name]
```

Optimizes all images for the given path.

Assumptions:

* all images are inside the image directory, relative to the given path.

### optimize images in fileadmin and uploads

```bash
gulp images:uploaded
```

This task optimizes all images (png, jpg, gif) inside the folders you specified in the config.json file. You might want to
run this task on a regular basis to compress user uploaded media.

# Troubleshooting

## Strange errors during npm install
200
If you get strange errors during npm install, it might help to clear the npm cache. To do so, run 'npm cache clean', oder simply delete the .npm directory inside your home folder.