1# Component Installer for [Composer](http://getcomposer.org) [![Build Status](https://secure.travis-ci.org/RobLoach/component-installer.png?branch=master)](http://travis-ci.org/RobLoach/component-installer)
2
3Allows installation of Components via [Composer](http://getcomposer.org).
4
5## Install
6
7```
8composer require robloach/component-installer
9```
10
11``` json
12{
13    "require": {
14        "robloach/component-installer": "*"
15    }
16}
17```
18
19## Usage
20
21To install a Component with Composer, add the Component to your *composer.json*
22`require` key. The following will install [jQuery](http://jquery.com) and
23[normalize.css](https://github.com/necolas/normalize.css):
24
25```
26composer require components/jquery
27composer require components/normalize.css
28```
29
30``` json
31{
32    "require": {
33        "components/jquery": "2.*",
34        "components/normalize.css": "3.*",
35        "robloach/component-installer": "*"
36    }
37}
38```
39
40### Using the Component
41
42The easiest approach is to use the Component statically. Just reference the
43Components manually using a `script` or `link` tag:
44
45``` html
46<script src="components/jquery/jquery.js"></script>
47<link href="components/normalize/normalize.css" rel="stylesheet">
48```
49
50For complex projects, a [RequireJS](http://requirejs.org) configuration is
51available, which allows autoloading scripts only when needed. A *require.css*
52file is also compiled, including all Component stylesheets:
53
54``` html
55<!DOCTYPE html>
56<html>
57    <head>
58        <link href="components/require.css" rel="stylesheet" type="text/css">
59        <script src="components/require.js"></script>
60    </head>
61    <body>
62        <h1>jQuery+RequireJS Component Installer Sample Page</h1>
63        <script>
64          require(['jquery'], function($) {
65            $('body').css('background-color', 'green');
66          });
67        </script>
68    </body>
69</html>
70```
71
72## Configuration
73
74There are a number of ways to alter how Components are installed and used.
75
76### Installation Directory
77
78It is possible to switch where Components are installed by changing the
79`component-dir` option in your root *composer.json*'s `config`. The following
80will install jQuery to *public/jquery* rather than *components/jquery*:
81
82``` json
83{
84    "require": {
85        "components/jquery": "*"
86    },
87    "config": {
88        "component-dir": "public"
89    }
90}
91```
92
93Defaults to `components`.
94
95### Base URL
96
97While `component-dir` depicts where the Components will be installed,
98`component-baseurl` tells RequireJS the base path that will use when attempting
99to load the scripts in the web browser. It is important to make sure the
100`component-baseurl` points to the `component-dir` when loaded externally. See
101more about [`baseUrl`](http://requirejs.org/docs/api.html#config-baseUrl) in the
102RequireJS documentation.
103
104``` json
105{
106    "require": {
107        "components/jquery": "*"
108    },
109    "config": {
110        "component-dir": "public/assets",
111        "component-baseurl": "/assets"
112    }
113}
114```
115
116Defaults to `components`.
117
118### Assetic filters
119
120``` json
121{
122    "require": {
123        "components/jquery": "*"
124    },
125    "config": {
126        "component-dir": "public/assets",
127        "component-baseurl": "/assets",
128        "component-scriptFilters": {
129            "\\Assetic\\Filter\\GoogleClosure\\CompilerApiFilter": []
130        },
131        "component-styleFilters": {
132            "\\Assetic\\Filter\\CssImportFilter": []
133        }
134    }
135}
136```
137
138## Creating a Component
139
140To set up a Component to be installed with Component Installer, have it
141`require` the package *robloach/component-installer* and set the `type` to
142*component*, but it is not necessary:
143
144``` json
145{
146    "name": "components/bootstrap",
147    "type": "component",
148    "require": {
149        "robloach/component-installer": "*"
150    },
151    "extra": {
152        "component": {
153            "scripts": [
154                "js/bootstrap.js"
155            ],
156            "styles": [
157                "css/bootstrap.css"
158            ],
159            "files": [
160                "img/*.png",
161                "js/bootstrap.min.js",
162                "css/bootstrap.min.css"
163            ]
164        }
165    }
166}
167```
168
169* `scripts` - List of all the JavaScript files that will be concatenated
170together and processed when loading the Component.
171* `styles` - List of all the CSS files that should be concatenated together
172into the final *require.css* file.
173* `files` - Any additional file assets that should be copied into the Component
174directory.
175
176### Component Name
177
178Components can provide their own Component name. The following will install
179jQuery to *components/myownjquery* rather than *components/jquery*:
180
181``` json
182{
183    "name": "components/jquery",
184    "type": "component",
185    "extra": {
186        "component": {
187            "name": "myownjquery"
188        }
189    }
190}
191```
192
193Defaults to the package name, without the vendor.
194
195### RequireJS Configuration
196
197Components can alter how [RequireJS](http://requirejs.org) registers and
198interacts with them by changing some of the [configuration
199options](http://www.requirejs.org/docs/api.html#config):
200
201``` json
202{
203    "name": "components/backbone",
204    "type": "component",
205    "require": {
206        "components/underscore": "*"
207    },
208    "extra": {
209        "component": {
210            "shim": {
211                "deps": ["underscore", "jquery"],
212                "exports": "Backbone"
213            },
214            "config": {
215                "color": "blue"
216            }
217        }
218    },
219    "config": {
220        "component": {
221            "waitSeconds": 5
222        }
223    }
224}
225```
226
227Current available RequireJS options for individual packages include:
228* [`shim`](http://www.requirejs.org/docs/api.html#config-shim)
229* [`config`](http://www.requirejs.org/docs/api.html#config-moduleconfig)
230* Anything that's passed through `config.component` is sent to Require.js
231
232### Packages Without Composer Support
233
234Using [`repositories`](http://getcomposer.org/doc/05-repositories.md#repositories)
235in *composer.json* allows use of Component Installer in packages that don't
236explicitly provide their own *composer.json*. In the following example, we
237define use of [html5shiv](https://github.com/aFarkas/html5shiv):
238
239``` json
240{
241    "require": {
242        "afarkas/html5shiv": "3.6.*"
243    },
244    "repositories": [
245        {
246            "type": "package",
247            "package": {
248                "name": "afarkas/html5shiv",
249                "type": "component",
250                "version": "3.6.2",
251                "dist": {
252                    "url": "https://github.com/aFarkas/html5shiv/archive/3.6.2.zip",
253                    "type": "zip"
254                },
255                "source": {
256                    "url": "https://github.com/aFarkas/html5shiv.git",
257                    "type": "git",
258                    "reference": "3.6.2"
259                },
260                "extra": {
261                    "component": {
262                        "scripts": [
263                            "dist/html5shiv.js"
264                        ]
265                    }
266                },
267                "require": {
268                    "robloach/component-installer": "*"
269                }
270            }
271        }
272    ]
273}
274```
275
276### Packages Without Component Support In *composer.json*
277
278Using [`extra`](https://getcomposer.org/doc/04-schema.md#extra)
279in *composer.json* allows use of Component Installer in packages that don't
280explicitly provide support for component, but do ship with their own *composer.json*.
281Using `extra` with packages that ship with Component Installer, will override component's settings for that package.
282
283``` json
284{
285    "require": {
286        "datatables/datatables": "~1.10"
287    },
288    "extra": {
289        "component": {
290            "datatables/datatables": {
291                "scripts": [
292                    "media/js/jquery.dataTables.js"
293                ],
294                "styles": [
295                    "media/css/jquery.dataTables.css"
296                ],
297                "files": [
298                    "media/js/jquery.dataTables.min.js",
299                    "media/css/jquery.dataTables.min.css",
300                    "media/images/*.png"
301                ]
302            }
303        }
304    }
305}
306```
307
308## Not Invented Here
309
310There are many other amazing projects from which Component Installer was
311inspired. It is encouraged to take a look at some of the [other great package
312management systems](http://github.com/wilmoore/frontend-packagers):
313* [npm](http://npmjs.org)
314* [bower](http://twitter.github.com/bower/)
315* [component](http://github.com/component/component)
316* [Jam](http://jamjs.org)
317* [volo](http://volojs.org)
318* [Ender](http://ender.jit.su)
319* etc
320
321## License
322
323Component Installer is licensed under the MIT License - see LICENSE.md for
324details.
325