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

Philipp Nowinski's avatar
Philipp Nowinski committed
3
# sgalinski command line interface
Philipp Nowinski's avatar
Philipp Nowinski committed
4

Philipp Nowinski's avatar
Philipp Nowinski committed
5 6
> **Please note:**
> The sgc currently only supports Linux and OSX operating systems. The CLI is intended to be used with bash or zsh.
Philipp Nowinski's avatar
Philipp Nowinski committed
7

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

10
Move the 'sgc-core' folder inside your project root and execute the install script.
Philipp Nowinski's avatar
Philipp Nowinski committed
11 12

```bash
13 14 15 16 17 18 19 20 21
./sgc-core/install.sh
```

### Local Installation

If you don't want to install the sgc command globally (e.g. in a server environment), just pass the --local flag to the install script.

```bash
./sgc-core/install.sh --local
Philipp Nowinski's avatar
Philipp Nowinski committed
22 23 24 25
```

## Configuration

26 27 28 29 30 31
To configure the frontend build process to your needs, you will have to modify the .sgc-config.json that the installer
will put into your projects root-directory.

> **Heads up**
> Prior to SGC 1.2.0, the config file was named config.json and lived inside the sgc-core/gulp folder. If this file is
> still present, sgc will use it instead of the .sgc-config.json. It is highly advised to use .sgc-config.json instead!
Philipp Nowinski's avatar
Philipp Nowinski committed
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

### 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
Philipp Nowinski's avatar
Philipp Nowinski committed
64
sgc css --ext project_base
Philipp Nowinski's avatar
Philipp Nowinski committed
65 66 67 68 69 70 71
```

There are a few available tasks you need to remember:

### default/watch task

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
72
sgc
Philipp Nowinski's avatar
Philipp Nowinski committed
73 74 75 76 77 78 79 80 81
```
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
82
sgc css:sprites --ext [extensions name]
Philipp Nowinski's avatar
Philipp Nowinski committed
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
```

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 {
Philipp Nowinski's avatar
Philipp Nowinski committed
100
	@include sprite ($box);
Philipp Nowinski's avatar
Philipp Nowinski committed
101 102 103 104
}
```

The @sprite mixin already contains width and height. If you need these values for something else, use the @sprite-width
Philipp Nowinski's avatar
Philipp Nowinski committed
105
and @sprite-height functions.
Philipp Nowinski's avatar
Philipp Nowinski committed
106 107 108 109

### css task

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
110
sgc css --ext [extension name]
Philipp Nowinski's avatar
Philipp Nowinski committed
111 112 113 114 115 116 117 118 119 120 121 122
```

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
Philipp Nowinski's avatar
Philipp Nowinski committed
123
sgc images --ext [extension name]
Philipp Nowinski's avatar
Philipp Nowinski committed
124 125 126 127 128 129 130 131 132 133 134
```

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
Philipp Nowinski's avatar
Philipp Nowinski committed
135
sgc images:uploaded
Philipp Nowinski's avatar
Philipp Nowinski committed
136 137
```

Philipp Nowinski's avatar
Philipp Nowinski committed
138
This tasks optimizes all images (png, jpg, gif, svg) inside the folders you specified in the sgc-config.json file. You might want to
Philipp Nowinski's avatar
Philipp Nowinski committed
139 140
run this task on a regular basis to compress user uploaded media.

Philipp Nowinski's avatar
Philipp Nowinski committed
141 142
# Extending the sgc with your own modules

143
You can easily extend the sgc functionality by writing your own modules. Simply create a sgc-scripts folder next to sgc-core
Philipp Nowinski's avatar
Philipp Nowinski committed
144 145 146 147 148
and put your custom scripts in there. Right now only shell-scripts with are supported, other languages might follow in the future.

Execute your custom scripts by calling sgc <scriptName>

```
149 150
+ sgc-core
+ sgc-scripts
Philipp Nowinski's avatar
Philipp Nowinski committed
151 152 153 154 155 156 157 158 159
    - updateInstance.sh
    - updateDeployData.sh
```


```bash
sgc updateInstance
```

Philipp Nowinski's avatar
Philipp Nowinski committed
160 161
# Troubleshooting

Philipp Nowinski's avatar
Philipp Nowinski committed
162 163 164 165 166
## Timeouts of the registry while installing the toolchain

Please try to remove the npm-shrinkgwrap.json file and execute the following commands:

```bash
167
cd sgc-core
Philipp Nowinski's avatar
Philipp Nowinski committed
168 169 170 171
rm -rf node_modules
npm set registry http://registry.npmjs.org/
npm install
```