README.md
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