Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 952 lines (725 sloc) 38.089 kb
1e4f5d2 @canton7 Add readme
canton7 authored
1 Casset
2 ======
3
4 Casset is an alternative to fuelphp's Asset class.
1d79dbe @canton7 Add a little to the readme introduction.
canton7 authored
5 Casset supports minifying and combining scripts, in order to reduce the number and size of http requests need to load a given page. Grouping syntax has been made cleaner, and the ability to render all groups, and enable/disable specific groups, added.
6 There are are some other changes too, please read on!
1e4f5d2 @canton7 Add readme
canton7 authored
7
8 Thanks to Stephen Clay (and Douglas Crockford) for writing the minification libraries, stolen from http://code.google.com/p/minify/.
9
7d5512b @canton7 Talk about forum thread in readme
canton7 authored
10 If you have any comments/queries, either send me a message on github, post to the fuelphp [forum thread](http://fuelphp.com/forums/topics/view/2187), catch me on #fuelphp, or open an issue.
11
3753234 @canton7 Add link to quickref from readme
canton7 authored
12 If you're just after a quick reference, or a reminder of the API, see the the file `quickref.md`.
13
1e4f5d2 @canton7 Add readme
canton7 authored
14 Installation
15 ------------
16
c3755f2 @canton7 Remove the readme comment about oil installs on windows
canton7 authored
17 ### Using oil
20b0179 @canton7 Add instructions to install casset using oil
canton7 authored
18 1. cd to your fuel project's root
19 2. Run `php oil package install casset`
20 3. Optionally edit fuel/packages/casset/config/casset.php (the defaults are sensible)
21 4. Create public/assets/cache
22 5. Add 'casset' to the 'always_load/packages' array in app/config/config.php (or call `Fuel::add_package('casset')` whenever you want to use it).
23 6. Enjoy :)
24
72d296f @canton7 Add comment to readme saying that my repo is likely to be more up-to-…
canton7 authored
25 ### Manual (may be more up-to-date)
20b0179 @canton7 Add instructions to install casset using oil
canton7 authored
26 1. Clone (`git clone git://github.com/canton7/fuelphp-casset`) / [download](https://github.com/canton7/fuelphp-casset/zipball/master)
c0294ec @canton7 Change installation instructions to take account of the fact that Cas…
canton7 authored
27 2. Stick in fuel/packages/
28 3. Optionally edit fuel/packages/casset/config/casset.php (the defaults are sensible)
1e4f5d2 @canton7 Add readme
canton7 authored
29 4. Create public/assets/cache
cbb6e6e @canton7 Add instrunctions on how to load casset to the readme.
canton7 authored
30 5. Add 'casset' to the 'always_load/packages' array in app/config/config.php (or call `Fuel::add_package('casset')` whenever you want to use it).
31 6. Enjoy :)
1e4f5d2 @canton7 Add readme
canton7 authored
32
741312a @canton7 Add a note to the readme talkign about using a custom config file.
canton7 authored
33 If you don't want to change the config file in `fuel/packages/casset/config/casset.php`, you can create your own config file in `fuel/app/config/casset.php`.
34 You can either copy the entirely of the original config file, or just override the keys as you like.
35 The magic of Fuel's `Config` class takes care of the rest.
36
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
37 Introduction
38 ------------
39
40 Casset is an easy-to-use asset management library. It boasts the following features:
41
42 - Speficy which assets to use for a particular page in your view/controller, and print them in your template.
43 - Collect your assets into groups, either pre-defined or on-the-fly.
44 - Enable/disable specific groups from your view/controller.
45 - Minify your groups and combine into single files to reduce browser requests and loading times.
46 - Define JS/CSS in your view/controller to be included in your template.
47 - Namespace your assets.
48
1e4f5d2 @canton7 Add readme
canton7 authored
49 Basic usage
50 -----------
51
52 JS and CSS files are handled the same way, so we'll just consider JS. Just substitude 'js' with 'css' for css-related functions.
53
54 Javascript files can be added using the following, where "myfile.js" and "myfile2.js" are the javascript files you want to include,
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
55 and are located at public/assets/js/myfile.js and public/assets/js/myfile2.js (configurable).
1e4f5d2 @canton7 Add readme
canton7 authored
56
57 ```php
58 Casset::js('myfile.js');
59 Casset::js('myfile2.js');
60 ```
61
738d154 @canton7 Readme example in basic usage of what will happen if minification is
canton7 authored
62 By default, Casset will minify both of these files and combine them into a single file (which is written to public/assets/cache/\<md5 hash\>.js).
1e4f5d2 @canton7 Add readme
canton7 authored
63 To include this file in your page, use the following:
64
65 ```php
66 echo Casset::render_js();
67 /*
68 Returns something like
69 <script type="text/javascript" src="http://localhost/site/assets/cache/d148a723c710760bc62ca3ecc8c50206.js?1307384477"></script>
70 */
71 ```
72
738d154 @canton7 Readme example in basic usage of what will happen if minification is
canton7 authored
73 If you've got minification turned off (see the section at the bottom of this readme), you'll instead get:
74
75 ```php
76 <script type="text/javascript" src="http://localhost/site/assets/js/myfile.js"></script>
77 <script type="text/javascript" src="http://localhost/site/assets/js/myfile2.js"></script>
78 ```
79
1e4f5d2 @canton7 Add readme
canton7 authored
80 If you have a specific file ("myfile.min.js") which you want Casset to use, rather than generating its own minified version, you
81 can pass this as the second argument, eg:
82
83 ```php
84 Casset::js('myfile.js', 'myfile.min.js');
85 ```
86
7846187 @canton7 Document render() function in readme
canton7 authored
87 Some folks like css and js tags to be together. `Casset::render()` is a shortcut which calls `Casset::render_css()` then `Casset::render_js()`.
88
1e4f5d2 @canton7 Add readme
canton7 authored
89 Images
90 ------
91
383968e @canton7 Fix another typo in the readme.
canton7 authored
92 Although the original Asset library provided groups, etc, for dealing with images, I couldn't see the point.
1e4f5d2 @canton7 Add readme
canton7 authored
93
bcdb8dc @canton7 Update ther readme to reflect the changes to img().
canton7 authored
94 Therefore image handling is somewhat simpler, and can be summed up by the following line, where the third argument is an optional array of attributes:
1e4f5d2 @canton7 Add readme
canton7 authored
95
96 ```php
bcdb8dc @canton7 Update ther readme to reflect the changes to img().
canton7 authored
97 echo Casset::img('test.jpg', 'alt text', array('width' => 200));
1e4f5d2 @canton7 Add readme
canton7 authored
98 ```
99
100 You can also pass an array of images (which will all have to same attributes applied to them), eg:
101
102 ```php
bcdb8dc @canton7 Update ther readme to reflect the changes to img().
canton7 authored
103 echo Casset::img(array('test.jpg', 'test2.jpg'), 'Some thumbnails');
1e4f5d2 @canton7 Add readme
canton7 authored
104 ```
105
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
106 This function has more power when you consider namespacing, detailed later.
107
1e4f5d2 @canton7 Add readme
canton7 authored
108 Groups
109 ------
110
111 Groups are collections of js/css files.
112 A group can be defined in the config file, or on-the-fly. They can be enabled and disabled invidually, and rendered individually.
113
114 CSS and JS have their own group namespaces, so feel free to overlap.
115
116 To define a group in the config file, use the 'groups' key, eg:
117
118 ```php
119 'groups' => array(
120 'js' => array(
121 'group_name' => array(
122 'files' => array(
123 array('file1.js', 'file1.min.js'),
124 'file2.js'
125 ),
cb3032f @canton7 Document combining in the readme
canton7 authored
126 'combine' => false,
ce9463b @canton7 Add documentation of new per-group minification strategy to the readme
canton7 authored
127 'min' => false,
ad4059e @canton7 Document the changes in the readme
canton7 authored
128 'inline' => true
1e4f5d2 @canton7 Add readme
canton7 authored
129 ),
130 'group_name_2' => array(.....),
131 ),
132 'css' => array(
133 'group_name' => array(
134 'files' => array(
135 array('file1.css', 'file1.min.css'),
136 'file2.css',
137 ),
ad4059e @canton7 Document the changes in the readme
canton7 authored
138 'enabled' => false,
139 'attr' => array('media' => 'print'),
b1554b0 @canton7 Document the dependencies
canton7 authored
140 'deps' => array('some_group'),
1e4f5d2 @canton7 Add readme
canton7 authored
141 ),
142 'group_name_3' => array(.....),
143 ),
144 ),
145 ```
146
147 As you can see, the javascript and css groups are entirely separate.
148 Each group consists of the following parts:
149 **files**: a list of files present in the group. Each file definition can either be a string or a 2-element array.
150 If you're using minification, but have a pre-minified copy of your file (jquery is an example), you can pass this as the second
151 array element.
5242819 @canton7 Fix whitespace problems in the readme
canton7 authored
152 **enabled**: Optional, specifies whether a group is enabled. A group will only be rendered when it is enabled. Default true.
153 **combine**: This optional key allows you to override the 'combine' config key on a per-group bases.
c571e8e @canton7 Document new inline behaviour in the readme
canton7 authored
154 **min**: This optional key allows you to override the 'min' config key on a per-group basis.
ad4059e @canton7 Document the changes in the readme
canton7 authored
155 **inline**: Optional, allows you to render the group 'inline' -- that is, show the CSS directly in the file, rather than including a separate .css file. See the section on inling below.
b1554b0 @canton7 Document the dependencies
canton7 authored
156 **attr**: Optional, allows you to specify extra attributes to be added to the script/css/link tag generated. See the section on attributes below.
157 **deps**: (Optional) Specifies other groups to be rendered whenever this group is rendered, see the section below.
1e4f5d2 @canton7 Add readme
canton7 authored
158
cc70747 @canton7 Any non-string asset names will be ignored
canton7 authored
159 Aside: You can specify any non-string value for the asset name, and it will be ignored.
160 This can be handy if you're doing something like `'files' => array(($var == $val) ? false : 'file.js')`.
161
1e4f5d2 @canton7 Add readme
canton7 authored
162 Groups can be enabled using `Casset::enable_js('group_name')`, and disabled using `Casset::disable_js('group_name')`. CSS equivalents also exist.
7812c87 @canton7 Minor typo-fixes and reformatting of readme
canton7 authored
163 The shortcuts `Casset::enable('group_name')` and `Casset::disable('group_name')` also exist, which will enable/disable both the js and css groups of the given name, if they are defined.
78ffcd2 @canton7 Document change to enable()/disable() in readme.
canton7 authored
164 You can also pass an array of groups to enable/disable.
1e4f5d2 @canton7 Add readme
canton7 authored
165
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
166 Specific groups can be rendered using eg `Casset::render_js('group_name')`. If no group name is passed, *all* groups will be rendered.
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
167 Note that when a group is rendered, it is disabled. See the "Extra attributes" section for an application of this behaviour.
1e4f5d2 @canton7 Add readme
canton7 authored
168
169 Files can be added to a group by passing the group name as the third argument to `Casset::js` / `Casset::css`, eg:
170
171 ```php
172 Casset::js('myfile.js', 'myfile.min.js', 'group_name');
173 Casset::css('myfile.css', false, 'group_name');
174 ```
175
b951dc1 @canton7 Document the ability to pass any non-x (bool, array) value for some
canton7 authored
176 (As an aside, you can pass any non-string value instead of 'false' in the second example, and Casset will behave the same: generate your minified file for you.)
177
e80440c @canton7 Remote add_group documentation from the readme
canton7 authored
178 If the group name doesn't exist, the group is created, and enabled.
1e4f5d2 @canton7 Add readme
canton7 authored
179
c241bee @canton7 Document changes in the readme
canton7 authored
180 You can also add groups on-the-fly using `Casset::add_group($group_type, $group_name, $files, $options)`, where `$options`is an array with *any* of the following keys:
181
182 ```php
183 $options = array(
184 'enabled' => true/false,
185 'min' => true/false,
186 'combine' => true/false,
ad4059e @canton7 Document the changes in the readme
canton7 authored
187 'inline' => true/false,
188 'attr' => array(),
aad2689 @canton7 Make add_group_base accept a single string dep, and document this
canton7 authored
189 'deps' => array(),
c241bee @canton7 Document changes in the readme
canton7 authored
190 );
191 ```
192
193 The arguments are the same as for the config key -- if `'enabled'`, `'combine'` or `'min'` are omitted, the value specified in the config file are used. Eg:
70f60dd @canton7 Document re-implemented add_group function
canton7 authored
194
195 ```php
196 Casset::add_group('test_group', array(
197 array('file1.js', 'file1.min.js'),
198 'file2.js',
199 ));
200 ```
201
202 This method is provided merely for convenience when adding lots of files to a group at once.
203 You don't have to create a group before adding files to it -- the group will be created it it doesn't exist.
204
9d37cd1 @canton7 Fix typos in readme
canton7 authored
205 You can change any of these options on-the-fly using `Casset::set_group_option($type, $group, $key, $value)`, or the CSS- and JS- specific versions, `Casset::set_js_option($group, $key, $value)` and `Casset::set_css_option($group, $key, $value)`.
c93416e @canton7 Document the new functions
canton7 authored
206 `$group` has some special values: an empty string is a shortcut to the 'global' group (to which files are added if a group is not specified), and '*' is a shortcut to all groups.
207 Multiple group names can also be specified, using an array.
208
209 Examples:
210
211 ```php
212 // Add a dep to the my_plugin group
213 Casset::set_js_option('my_plugin', 'deps', 'jquery');
214
215 // Make all files added to the current page using Casset::add_css() display inline:
216 Casset::set_css_option('', 'inline', true);
217
218 // Turn off minification for all groups, regardless of per-group settings, for the current page:
7897913 @chrismeller Fix a typo in the readme's example code.
chrismeller authored
219 Casset::set_js_option('*', 'min', false);
c93416e @canton7 Document the new functions
canton7 authored
220 ```
221
51a41f4 @canton7 Document order in which files and groups are rendered, and the
canton7 authored
222 When you call `Casset::render()` (or the js- and css-specific varients), the order that groups are rendered is determined by the order in which they were created, with groups present in the config file appearing first.
223 Similarly (for JS files only), the order in which files appear is determined by the order in which they were added.
c241bee @canton7 Document changes in the readme
canton7 authored
224 This allows you a degree of control over what order your files are included in your page, which may be necessary when satisfying dependencies.
51a41f4 @canton7 Document order in which files and groups are rendered, and the
canton7 authored
225 If this isn't working for you, or you want something a bit more explicit, try this: If file A depends on B, add B to its own group and explicitely render it first.
226
1e4f5d2 @canton7 Add readme
canton7 authored
227 NOTE: Calling ``Casset::js('file.js')`` will add that file to the "global" group. Use / abuse as you need!
228
c241bee @canton7 Document changes in the readme
canton7 authored
229 NOTE: The arguments for `Casset::add_group` used to be different. Backwards compatibilty is maintained (for now), but you are encouranged to more to the new syntax.
230
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
231 Paths and namespacing
232 ---------------------
233
234 The Asset library searches through all of the items in the 'paths' config key until it finds the first matching file.
235 However, this approach was undesirable, as it means that if you had the directory structure below, and tried to include 'index.js', the file that was included would be determined by the order of the
236 entries in the paths array.
237
238 ```
239 assets/
240 css/
241 js/
242 index.js
243 img/
244 admin/
245 css/
246 js/
247 index.js
248 img/
249 ```
250
251 Casset brings decent namespacing to the rescue!
252 For the above example, you can specify the following in your config file:
253
254 ```
255 'paths' => array(
256 'core' => 'assets/',
257 'admin' => 'assets/admin/',
258 ),
259 ```
260
6d94499 @canton7 Fix small readme typo
canton7 authored
261 You can also add paths on-the-fly using `Casset::add_path($key, $path)`, eg.
6e2fbae @canton7 Add documentation on add_path (just noticed it wasn't present already)
canton7 authored
262
263 ```php
264 Casset::add_path('admin', 'assets/admin/');
265 ```
266
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
267 Which path to use is then decided by prefixing the asset filename with the key of the path to use. Note that if you omit the path key, the current default path key (initially 'core') is used.
268
269 ```php
270 Casset::js('index.js');
271 // Or
272 Casset::js('core::index.js');
273 // Will add assets/js/index.js
274
275 Casset::js('admin::index.js');
276 // Will add assets/admin/js/index.js
277
278 echo Casset::img('test.png', 'An image');
279 // <img src="...assets/img/test.png" alt="An image" />
280
281 echo Casset::img('admin::test.png', 'An image');
282 // <img src="...assets/admin/img/test.png" alt="An image" />
283 ```
284
285 If you wish, you can change the current default path key using `Casset::set_path('path_key')`. This can be useful if you know that all of the assets in a given file will be from a given path. For example:
286
287 ```php
288 Casset::set_path('admin);
289 Casset::js('index.js');
290 // Will add assets/admin/js/index.js
291 ```
292
7812c87 @canton7 Minor typo-fixes and reformatting of readme
canton7 authored
293 The "core" path can be restored by calling `Casset::set_path()` with no arguments (or calling `Casset::set_path('core')`).
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
294
295 You can also namespace the files listed in the config file's 'groups' section, in the same manner.
296 Note that these are loaded before the namespace is changed from 'core', so any files not in the core namespace will have to by explicitely prepended with the namespace name.
297
bc17320 @canton7 Update the readme to include information on overriding dirs in paths.
canton7 authored
298 In addition, you can override the config options 'js_path', 'css_path' and 'img_path' on a per-path basis. In this case, the element of the 'paths' config array takes the following form,
299 where each of 'js_path', 'css_path' and 'img_path' are optional. If they are not specified, the defaults will be used.
300
301 ```php
302 array (
303 'some_key' => array(
304 'path' => 'more_assets/',
cadc1b8 @canton7 Misc whitespace and formatting changes to the readme
canton7 authored
305 'js_dir' => 'javascript/',
1809165 @canton7 Typo correcting in the readme
canton7 authored
306 'css_dir' => 'styles/',
cadc1b8 @canton7 Misc whitespace and formatting changes to the readme
canton7 authored
307 'img_dir' => 'images/',
bc17320 @canton7 Update the readme to include information on overriding dirs in paths.
canton7 authored
308 ),
309 ),
310 ```
311
312 This can be particularly useful when you're using some third-party code, and don't have control over where the assets are located.
313
6e2fbae @canton7 Add documentation on add_path (just noticed it wasn't present already)
canton7 authored
314 Note also that you can add an asset which uses a path which isn't yet defined.
315 Casset only requires that the path is defined by the time the file is rendered.
316
1d17191 @canton7 Document new feature in readme
canton7 authored
317 If you add an asset whose path starts with a leading slash, the folder specified by 'js_dir', 'css_dir', etc (either in the config or in the namespace), is ignored.
318 This can be handy if you have a third-party module which, for example, puts css inside the js/ folder.
319 For example:
320
321 ```php
322 Casset::js('some_key::file.js')
323 // Adds more_assets/javascript/file.js
324 Casset::js('some_key::/file.js')
325 // Adds more_assets/file.js
326 ```
327
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
328 Globbing
329 --------
330
1809165 @canton7 Typo correcting in the readme
canton7 authored
331 As well as filenames, you can specify [glob patterns](http://php.net/glob). This will act exactly the same as if each file which the glob matches had been added individually.
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
332 For example:
333
334 ```php
335 Casset::css('*.css');
336 // Runs glob('assets/css/*.css') and adds all matches.
337
338 Casset::css('admin::admin_*.css');
339 // (Assuming the paths configuration in the "Paths and namespacing" section)
340 // Executes glob('adders/admin/css/admin_*.css') and adds all matches
341
342 Casset::js('*.js', '*.js');
1809165 @canton7 Typo correcting in the readme
canton7 authored
343 // Adds all js files in assets/js, ensuring that none of them are pre-minified.
27e9c62 @canton7 Move paths and namespacing and globbing above inlining and extra
canton7 authored
344 ```
345
346 An exception is thrown when no files can be matched.
1e4f5d2 @canton7 Add readme
canton7 authored
347
b1554b0 @canton7 Document the dependencies
canton7 authored
348 Dependencies
349 ------------
350
351 Casset allows you to specify dependancies between groups, which are automatically resolved.
352 This means that you can, say, define a group for your jQuery plugin, and have jQuery automatically included every time that plugin is included.
353
354 Note that dependancies can only be entire groups -- groups can not depend on individual files.
355 This has to do with how files are put into cache files, email me if you're interested.
356
357 A JS group can only depend on other JS groups, while a CSS group can only depend on other CSS groups.
358
359 Casset is pretty intelligent, and will only include a file once, before the file that requires it.
360 After a file has been required as a dependency, it will be disabled.
361 Casset will also bail after following the dependency chain through a certain number of steps, to avoid cycling dependancies.
362 This value is given by the config key 'deps_max_depth'.
363
364 The easiest way of specifying dependancies is through the config file:
365
366 ```php
367 'groups' => array(
368 'js' => array(
369 'jquery' => array(
370 'files' => array(
371 array('jquery.js', 'jquery.min.js'),
372 ),
373 ),
374
375 'my_plugin' => array(
376 'files' => array(
377 'jquery.my_plugin.js',
378 ),
379 'deps' => array(
380 'jquery',
381 ),
382 ),
383 ),
384 ),
385 ```
386
387 Dependencies can be either a string (for a single dependency), or an array (for multiple ones).
388
389 You can also define dependencies when you call `Casset::add_group()`, by using the `'deps'` key in `$options`.
aad2689 @canton7 Make add_group_base accept a single string dep, and document this
canton7 authored
390
b1554b0 @canton7 Document the dependencies
canton7 authored
391 Eg:
392
393 ```php
9d37cd1 @canton7 Fix typos in readme
canton7 authored
394 Casset::add_group('js', 'my_plugin', array('jquery.my_plugin.js'), array(
b1554b0 @canton7 Document the dependencies
canton7 authored
395 'deps' => 'jquery',
396 ));
397 ```
398
399 In addition, the functions `Casset::add_js_deps()` and `Casset::add_css_deps()` exist, which can be used like:
400
401 ```php
402 Casset::add_js_deps('group_name', array('this', 'groups', 'deps'));
403 ```
404
405 As usual, there's another base function, `Casset::add_deps()`, which takes 'js' or 'css' as its first argument, but is otherwise identical.
406
407 If you have a JS group A, which depends on both the JS group B and CSS group B, a useful trick is to create a CSS group A with no files, that depends on the CSS group B.
408 Therefore whenever group A is rendered, both the JS group B and CSS group B will be rendered.
409
1e4f5d2 @canton7 Add readme
canton7 authored
410 Inlining
411 --------
412
c571e8e @canton7 Document new inline behaviour in the readme
canton7 authored
413 If you want Casset to display a group inline, instead of linking to a cache file, you can mark the group as 'inline' when you create it.
1e4f5d2 @canton7 Add readme
canton7 authored
414
415 ```php
c571e8e @canton7 Document new inline behaviour in the readme
canton7 authored
416 // In your config (see add_group also)
417 'groups' => array(
418 'js' => array(
9a3f48c @canton7 Correct example syntax for inlining
canton7 authored
419 'my_inline_group' => array(
420 'files' => array('file.css'),
421 'inline' => true,
422 ),
c571e8e @canton7 Document new inline behaviour in the readme
canton7 authored
423 ),
424 ),
1e4f5d2 @canton7 Add readme
canton7 authored
425 ```
426
c571e8e @canton7 Document new inline behaviour in the readme
canton7 authored
427 NOTE: You could previously pass an argument to `Casset::render()` to tell it to render the group inline.
428 This behaviour has been deprecated, although it still works.
429 You are encouraged to move away from this technique if you are using it.
430
1e4f5d2 @canton7 Add readme
canton7 authored
431 Occasionally it can be useful to declare a bit of javascript in your view, but have it included in your template. Casset allows for this, although it doesn't support groups and minification
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
432 (as I don't see a need for those features in this context -- give me a shout if you find an application for them, and I'll enhance).
1e4f5d2 @canton7 Add readme
canton7 authored
433
434 In your view:
435
436 ```php
437 $bar = 'baz';
438 $js = <<<EOF
439 var foo = "$bar";
440 EOF;
441 Casset::js_inline($js);
442 ```
443
444 In your template:
445
446 ```php
447 echo Casset::render_js_inline();
448 /*
449 Will output:
450 <script type="text/javascript">
451 var foo = "baz";
452 </script>
453 */
454 ```
455
456 Similarly, `Casset::css_inline()` and `Casset::render_css_inline()` exist.
457
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
458 Extra attributes
459 ----------------
460
ad4059e @canton7 Document the changes in the readme
canton7 authored
461 If you want to apply extra attributes to the script/link tag, you can add them to the group config, using the key 'attr'.
462 For example:
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
463
464 ```php
ad4059e @canton7 Document the changes in the readme
canton7 authored
465 // In your config
466 'groups' => array(
467 'css' => array(
cbcb794 @canton7 Another readme typo
canton7 authored
468 'my_print' => array(
ad4059e @canton7 Document the changes in the readme
canton7 authored
469 'files' => array('file.css'),
470 'attr' => array('media' => 'print'),
471 ),
472 ),
473 ),
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
474
ad4059e @canton7 Document the changes in the readme
canton7 authored
475 // Render the 'my_print' group, along with the others
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
476 echo Casset::render_css();
ad4059e @canton7 Document the changes in the readme
canton7 authored
477 // <link rel="stylesheet" type="text/css" href="http://...somefile.css" media="print" />
625abba @canton7 Update readme to document usage of attr argument to render_css and re…
canton7 authored
478 ```
479
2a1f92f @canton7 Add note about using with add_group() in 'Extra Attributes'
canton7 authored
480 You can also pass them in the `$options` argument to `Casset::add_group()`, for example:
481
482 ```php
483 Casset::add_group('js', 'my_deferred_js', array(
484 'file.js',
485 ), array(
486 'attr' => array(
487 'defer' => 'defer',
488 ),
489 );
490
491 echo Casset::render_js();
492 // <script type="text/javascript" src="http://...somefile.js" defer="defer"></script>
493 ```
494
ad4059e @canton7 Document the changes in the readme
canton7 authored
495 NOTE: You used to be able to pass an `$attr` argument to `Casset::render()`.
496 This behaviour has been deprecated, although it still works.
497 Please move to the new system.
498
cb3032f @canton7 Document combining in the readme
canton7 authored
499 Minification and combining
500 --------------------------
1e4f5d2 @canton7 Add readme
canton7 authored
501
502 Minification uses libraries from Stephen Clay's [Minify library](http://code.google.com/p/minify/).
503
cb3032f @canton7 Document combining in the readme
canton7 authored
504 The 'min' and 'combine' config file keys work together to control exactly how Casset operates:
505
cadc1b8 @canton7 Misc whitespace and formatting changes to the readme
canton7 authored
506 **Combine and minify:**
cb3032f @canton7 Document combining in the readme
canton7 authored
507 When an enabled group is rendered, the files in that group are minified (or the minified version used, if given, see the second parameter of eg `Casset::js()`),
508 and combined into a single cache file in public/assets/cache (configurable).
509
cadc1b8 @canton7 Misc whitespace and formatting changes to the readme
canton7 authored
510 **Combine and not minify:**
cb3032f @canton7 Document combining in the readme
canton7 authored
511 When an enabled group is rendered, the files in that group are combined into a a single cache file in public/assets/cache (configurable). The files are not minified.
512
cadc1b8 @canton7 Misc whitespace and formatting changes to the readme
canton7 authored
513 **Not combine and minify:**
cb3032f @canton7 Document combining in the readme
canton7 authored
514 When an enabled group is rendered, a separate `<script>` or `<link>` tag is created for each file.
515 If a minified version of a file has been given, it will be linked to. Otherwise, the non-minified version is linked to.
516 NOTE THAT THIS MIGHT BE UNEXPECTED BEHAVIOUR. It is useful, however, when linking to remote assets. See the section on remote assets.
517
518 **Not combine and not minify**
519 When an enabled group is rendered, a separate `<script>` or `<link>` tag is created for each file.
520 The non-minified version of the file is used in each case.
1e4f5d2 @canton7 Add readme
canton7 authored
521
522 You can choose to include a comment above each `<script>` and `<link>` tag saying which group is contained with that file by setting the "show_files" key to true in the config file.
523 Similarly, you can choose to put comments inside each minified file, saying which origin file has ended up where -- set "show_files_inline" to true.
524
cb3032f @canton7 Document combining in the readme
canton7 authored
525 You can control whether Casset minifies or combines individual groups, see the groups section.
b951dc1 @canton7 Document the ability to pass any non-x (bool, array) value for some
canton7 authored
526
926610e @canton7 Changes to the minifications and examples sections of the readme, for
canton7 authored
527 When minifying CSS files, urls are rewritten to take account of the fact that your css file has effectively moved into `public/assets/cache`.
528
cb3032f @canton7 Document combining in the readme
canton7 authored
529 With both CSS and JS files, when a cache file is used, changing the order in which files were added to the group will re-generate the cache file, with the files in their new positions.
71234d8 @canton7 Document change in behaviour wrt not ordering css files
canton7 authored
530 This is because the order of files can be important, as dependancies may need to be satisfied.
9a1c938 @canton7 Document file order stuff in the readme.
canton7 authored
531 Bear this in mind when adding files to groups dynamically -- if you're changing the order of files in an otherwise identical group, you're not allowing
532 the browser to properly use its cache.
533
cb3032f @canton7 Document combining in the readme
canton7 authored
534 NOTE: If you change the contents of a group, and a cache file is used, a new cache file will be generated. However the old one will not be removed (groups are mutable,
535 so Casset doesn't know whether a page still uses the old cache file).
536 Therefore an occasional clearout of `public/assets/cache/` is recommended. See the section below on clearing the cache.
609129d @canton7 Document cache-clearing in the readme.
canton7 authored
537
fff1e59 @canton7 Add remote files section to the config file
canton7 authored
538 Remote files
539 ------------
540
541 Casset supports handing files on remote machines, as well as the local one.
542 This is done by creating a new namespace, and specifying a url instead of a relative path.
543 All files using that namespace will then be fetched from the given url.
544
9951243 @canton7 Fix markdown formatting in Readme
canton7 authored
545 However, there are a couple of caveats:
546 - It is possible for Casset to fetch, combine and minify remote assets. However, it can obviously only write the cache file locally.
fff1e59 @canton7 Add remote files section to the config file
canton7 authored
547 - Casset doesn't bother to check the modification times on remote files when deciding whether the cache is out of date (as this would cause lots of http requests from your server, and entirely defeat
548 the point of caching in the first place). Therefore if the remote file changes, Casset's cache will not be updated, and you'll have to remove it manually, or with the cache-clearing functions.
549
550 For this reason, recommended practice is to either turn off combining files entirely if using remote assets (possibly undesirable),
551 or create one or more groups dedicated to remote files, in which combination is disabled.
552
553 Note that when combining files is disabled, but minification enabled, each file in the group will have its own `<script>` or `<link>` tag, but the minified version of the file will be linked to, if supplied.
554 If no minified version of the file is supplied, the non-minified version will be linked to.
555 This behaviour was designed for use when using remote assets, where the desired behaviour is to avoid caching the file locally, instead leaving it on the remote server.
556
557 Here is an example, using the Google API libraries:
558
559 ```php
560 // In config/casset.php
561 'paths' => array(
562 'core' => 'assets/',
563 'google_api' => array(
564 'path' => 'http://ajax.googleapis.com/ajax/libs/',
565 'js_dir' => '',
566 ),
567 ),
568
569 'groups' => array(
570 'js' => array(
571 'jquery' => array(
572 'files' => array(
573 array('google_api::jquery/1.6.2/jquery.js', 'google_api::jquery/1.6.2/jquery.min.js'),
574 ),
575 'enabled' => true,
576 'combine' => false,
577 ),
578 ),
579 ),
580
581 // Then you can also do....
582 Casset::js('google_api::jqueryui/1.8.14/jquery-ui.js', 'google_api::jqueryui/1.8.14/jquery-ui.min.js', 'jquery');
583
584
585 echo Casset::render();
586
587 // If minification is disabled:
588 // <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.js"></script>
589 // <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.9.14/jquery-ui.js"></script>
590
591 // If minification is enabled:
592 // <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
593 // <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.9.14/jquery-ui.min.js"></script>
594 ```
595
fd39ba2 @canton7 Document new functions
canton7 authored
596 Getting asset paths / urls
597 --------------------------
598
599 Thanks to [Peter](http://fuelphp.com/forums/posts/view_reply/3097) for this one. You can ask Casset for the path / url to a specific file.
600 Files are specified in exactly the same way as with eg `Casset::js()`, with the same rules to do with namespacing, `Casset::set_path()`, etc.
601
602 The functions in question are `Casset::get_filepath_js()`, `Casset::get_filepath_css()`, and `Casset::get_filepath_img()`.
603
604 They're all used in the same way:
605
606 ```php
607 echo Casset::get_filepath_js('file.js');
608 // assets/js/file.js
609 ```
610
611 Note that fuel executes in the `/public` directory, so the paths returned are relative to the current working dir.
612 If you'd prefer urls to be returned, pass `true` as the second parameter.
613 Note that a url will not be added if you're referencing a remote file.
614
615 ```php
616 echo Casset::get_filepath_js('file.js', true);
617 // eg http://localhost/site/public/assets/js/file.js
618 ```
619
620 Complexities start arising when you specify globs.
621 By default, an array will be returned if more than one file is found, otherwise a string is returned.
622 To override this behaviour, and return an array even if only one file is found, pass `true` as the third parameter.
623
624 ```php
625 print_r(Casset::get_filepath_js('file.js', false, true));
626 // Array( [0] => 'assets/js/file.js' )
627
628 print_r(Casset::get_filepath_js('file*.js'));
629 // Array( [0] => 'assets/js/file1.js', [1] => 'assets/js/file2.js' )
630 ```
631
632 There also exists `Casset::get_filepath()`, which takes the form
633
634 ```php
635 Casset::get_filepath($name, $type, $add_url = false, $force_array = false);
636 ```
637
638 `$name`, `$add_url` and `$force_array` are the same as for `Casset::get_filepath_js()`, while the `$type` argument is one of 'js', 'css', or 'img'.
639 In the future there are plans to let you specify your own types, hence why this is exposed :)
640
3cbb37b @canton7 Document new gen_tags option
canton7 authored
641 Controlling whether tags are generated
642 --------------------------------------
643
644 Thanks to antitoxic for motivating this feature.
645
646 The `get_filepath_*` functions are useful if you want to link directly to an asset.
647 However, this doesn't cover the case where you want to, for whatever reason, generate your own `<script>` or `<link>` tags, while still keeping Casset's minification/combining functionality.
648
649 The solution to this is to passed `array('gen_tags' => false)` as the second argument of `render_css()`/`render_js()`.
650 This will make `render_*` return an array of filenames / file contents (depending on whether you've turned on inlining for that group), rather then a string of tags (and maybe content).
651
652 For example:
653
654 ```php
655 Casset::js('test_file.js');
656 Casset::render_js(false);
657 // Returns <script type="text/javascript" src="http://....test_file.js"></script>
658 Casset::render_js(false, array('gen_tags' => false));
659 // Returns Array (
660 // [0] => "http://....test_file.js"
661 // )
662
663 Casset::set_group_option('js', 'global', 'inline', true);
664 Casset::render_js(false);
9d37cd1 @canton7 Fix typos in readme
canton7 authored
665 // Returns <script type="text/javascript">Some javascript file content</script>
3cbb37b @canton7 Document new gen_tags option
canton7 authored
666 Casset::render_js(false, array('gen_tags' => false));
667 // Returns Array (
668 // [0] => "Some javascript file content"
669 // )
670 ```
671
672 If more than one `<script>`/`<link>` tag would normally be generated, the array return will contain more than one element.
673
609129d @canton7 Document cache-clearing in the readme.
canton7 authored
674 Clearing the cache
675 ------------------
7812c87 @canton7 Minor typo-fixes and reformatting of readme
canton7 authored
676 Since cache files are not automatically removed (Casset has no way of knowing whether a cache file might be needed again), a few methods have been provided to remove cache files.
609129d @canton7 Document cache-clearing in the readme.
canton7 authored
677
13b57e8 @canton7 Minor changes to the readme.
canton7 authored
678 `Casset::clear_cache()` will clear all cache files, while `Casset::clear_js_cache()` and `Casset::clear_css_cache()` will remove just JS and CSS files respectively.
609129d @canton7 Document cache-clearing in the readme.
canton7 authored
679 All of the above functions optionally accept an argument allowing you to only delete cache files last modified before a certain time. This time is specified as a
7812c87 @canton7 Minor typo-fixes and reformatting of readme
canton7 authored
680 [strtotime](http://php.net/strtotime)-formatted string, for example "2 hours ago", "last Tuesday", or "20110609".
681 For example:
609129d @canton7 Document cache-clearing in the readme.
canton7 authored
682
683 ```php
684 Casset::clear_js_cache('2 hours ago');
685 // Removes all js cache files last modified more than 2 hours ago
686
687 Casset::clear_cache('yesterday');
688 // Removes all cache files last modified yesterday
689 ```
1e4f5d2 @canton7 Add readme
canton7 authored
690
6316893 @canton7 Document callbacks.
canton7 authored
691 Callbacks
692 ---------
693
996d6cf @canton7 Document new callback in the readme
canton7 authored
694 ### post_load_callback
6316893 @canton7 Document callbacks.
canton7 authored
695
996d6cf @canton7 Document new callback in the readme
canton7 authored
696 Quick thanks to [ShonM](https://github.com/shonm) for pushing so hard to get this feature implemented :)
6316893 @canton7 Document callbacks.
canton7 authored
697
996d6cf @canton7 Document new callback in the readme
canton7 authored
698 The post_load callback allows you the flexibility to do you own processing on the files that Casset loads.
6316893 @canton7 Document callbacks.
canton7 authored
699 This means that you can use SASS, CoffeeScript, etc, then configure Casset to call the appropriate compiler when it loads the asset.
700
701 Note that the `post_load` is *only* called when the 'combine' config key is set to true.
702 If 'combine' is false, Casset doesn't generate a cache file and instead links to the asset directly.
703 No cache file = no processing of the file by Casset = no callback.
704 If you really need this changed, send me a message and I'll start hacking :)
705
706 Processing files (beyond minification) is not really what Casset is about, and this reflects in the callback design.
707 There is a single callback, which is called for all files, regardless of group, type, extension, etc.
708 The callback is passed the name of the file, the type (js or css) and the group to which it belongs,as well as the file content of course.
709 It is then up to you to decide how, if at all, you want to process this content, based on the other parameters passed.
710
45bad4a @canton7 Document changes in the way fuel handles closures in config.
canton7 authored
711 You can either define your callback using `Casset::set_post_load_callback()`, or you can pass the name of a function to call to the config key `post_load_callback`.
712 `Casset::set_post_load_callback()` expects an anonymous function (closure), although I daresay you could bind it straight to some other library's method.
713 Unfortunately, fuel doesn't allow you to define closues in your config (it tries to evaluate them to get a value to assign to the config key).
6316893 @canton7 Document callbacks.
canton7 authored
714
715 The callback itself has the following prototype, although you can miss out the latter arguments if you want: PHP won't complain.
716
717 ```php
718 function($content, $filename, $type, $group_name) { ... }
719 ```
720
721 Where:
722 `$content`: The content of the file which Casset has read, and is passing to you.
723 `$filename`: The name of the file which Casset has read.
724 `$type`: 'js' or 'css', depending on whether the file is js or css.
725 `$group_name`: The group which is currently being rendered, and to which the file belongs.
726
727 Obviously, the callback is only called when a cache file is generated.
728 When testing, therefore, it is recommended that you stick a `Casset::clear_cache()` above your testing code.
729
730 Time for a few examples:
731
732 ```php
733 // In a controller somewhere
734 Casset::set_post_load_callback(function($content, $filename) {
735 $ext = pathinfo($filename, PATHINFO_EXTENSION);
736 if ($ext != 'sass')
737 return $content;
738 return SomeSassLibrary::some_method($content);
739 });
45bad4a @canton7 Document changes in the way fuel handles closures in config.
canton7 authored
740
741 // In the config file:
742 'post_load_callback' => 'my_callback_name',
6316893 @canton7 Document callbacks.
canton7 authored
743 ```
744
745 Note that Casset is pretty lazy, so the callback won't be called under you call `Casset::render()` (or one of its variants).
746 Therefore feel free to define your callback after telling Casset to include the files you want the callback to process.
747
996d6cf @canton7 Document new callback in the readme
canton7 authored
748 ### filepath_callback
749
750 Thanks to [leekudos](https://github.com/leekudos) for pushing for this one, and for numerous suggestions and comments.
751
752 This callback was implenented to solve one particular problem. However, it has been generalised in case you manage to find another use.
753
754 The original problem was this: There are some very large images on the server, so have been cached for a very long time.
755 This means that the url of the image has to be changed every time the image changes.
756 Now what if we could get Casset to do this url changing for us....
757
758 The filepath callback is called, basically, whenever Casset has generated a URL, but has not yet committed to using it.
759 This allows you to modify that URL.
760
761 More specifically:
762
763 - `img()` calls it just before writing the <img> tag.
764 - `render_css()` and `render_js()` call it just before writing a \<script src=".."\> or \<link href="..."\> tag to the page.
765
766 The callback itself has the following prototype:
767
768 ```php
769 function($filepath, $type, $remote) { ... }
770 ```
771
772 Where:
773 `$filepath`: The path to the asset. Doesn't include the part of the URL specified by the 'url' config key, although will be a full URL if the asset is located on another server.
774 `$type`: The type of asset: 'js', 'css' or 'img' currently.
775 `$remote`: True if the asset is located on another server, false otherwise.
776
777 As with the post_local callback, this callback can either be specified directly using `Casset::set_filepath_callback()`, or the name of a function to call can be specified in the config, under the 'filepath_callback' key.
778
779 A trivial example:
780
781 ```php
782 // Adds the string '?query=hello' to the end of all local js urls
783 Casset::set_filepath_callback(function($filepath, $type, $remote) {
784 if ($remote || $type != 'js')
785 return $filepath;
786 return $filepath.'?query=hello';
787 });
788 ```
789
790 Back to addressing the original problem (large cached images).
791 Appending the last modified time of the file to the end of the URL is one option, but this doesn't necessarily work in all browsers.
792 However, inserting the mtime into the middle of the filename will certainly work.
793 This needs some .htaccess magic, but that's OK.
794
795 Somewhere in your project:
796
797 ```php
798 // Rewrite e.g. assets/img/file.jpeg to assets/img/file.1298892196.jpg
799 Casset::set_filepath_callback($filepath, $type, $remote) {
800 if ($remote || $type != 'img')
801 return $filepath;
802
803 $pathinfo = pathinfo($filepath);
804 $mtime = filemtime(DOCROOT.$filepath);
805 return $pathinfo['dirname'].$pathinfo['basename'].'.'.$mtime.'.'.$pathinfo['extension'];
806 });
807 ```
808
809 In your .htaccess:
810
811 ```
812 # Rewrite e.g. http://example.com/assets/img/test.1298892196.jpg to http://example.com/assets/img/test.jpg
813 # Needs to be ABOVE the lines for removing index.php, if they exist.
814 RewriteRule ^(.*)\/(.+)\.([0-9]+)\.(js|css|jpg|jpeg|gif|png)$ $1/$2.$4 [L]
815 ```
6316893 @canton7 Document callbacks.
canton7 authored
816
f9cc28c @canton7 Add twig documentation
canton7 authored
817 Addons
818 ------
819
95bc8f4 @canton7 Fix typos in readme
canton7 authored
820 Casset also ships with the following addons, to ease integration with third-party frameworks.
f9cc28c @canton7 Add twig documentation
canton7 authored
821 For more details, see `classes/casset/addons/readme.md`.
822
823 - **Twig** - Adds the `render`, `render_js`, `render_css`, and `img` functions to Twig.
824
f7ba31d @canton7 Add "Comparison to Assetic" section to the readme.
canton7 authored
825 Comparison to Assetic
826 ---------------------
827
828 A frequent question is how Casset differs from kriswallsmith's [Assetic](https://github.com/fuel-packages/fuel-assetic). InCasset and Assetic have completely different goals.
829
830 * Assetic is a very powerful asset mangement framework. It allows you to perform minification, compression and compilation on your assets, although learning it will take time.
831 * Casset is designed to make assets very easy to handle. You call `Casset::js()` then `Casset::render_js()`, and everything is taken care of.
832
833 If you're a developer tasked with fully optimising your site's page load time, for example, go with Assetic. If you want a very easy way to manage your assets, with some minification
834 thrown in for free, (and have no need for Assetic's complex features), go with Casset.
835
1e4f5d2 @canton7 Add readme
canton7 authored
836 Examples
837 --------
838
839 Let's say we have a site which uses jquery on every page, jquery-ui on some pages, and then various other odds and sods.
840
841 In the config file:
842
843 ```php
844 'groups' => array(
845 'js' => array(
846 'jquery' => array(
847 'files' => array(
848 array('jquery.js', 'jquery.min.js'),
849 ),
850 'enabled' => true,
851 ),
852 'jquery-ui' => array(
853 'files' => array(
854 array('jquery-ui.js', 'jquery-ui.min.js'),
855 ),
856 'enabled' => false,
857 ),
858 ),
859 'css' => array(
860 'jquery-ui' => array(
861 'files' => array(
862 'jquery-ui.css',
863 ),
77002c1 @canton7 Fix typo in readme
canton7 authored
864 'enabled' => false,
1e4f5d2 @canton7 Add readme
canton7 authored
865 ),
866 ),
867 ),
868 ```
869
870 In our template file:
871
872 ```html
873 ...
874 <head>
875 <?php echo Casset::render_css() ?>
876 </head>
877 ...
878 <body>
879 ...
880 <?php
881 echo Casset::render_js();
882 echo Casset::render_js_inline();
883 ?>
926610e @canton7 Changes to the minifications and examples sections of the readme, for
canton7 authored
884 </body>
1e4f5d2 @canton7 Add readme
canton7 authored
885 ```
886
887 We can then turn the jquery-ui group on as we please.
888
889 file_1.php: (doesn't use jquery-ui)
890
891 ```php
892 ...
893 Casset::js('file_1.js');
894 Casset::css('file_1.css');
895 ...
896 ```
897
898 file_2.php: (does use jquery-ui)
899
900 ```php
901 ...
902 Casset::js('file_2.js');
903 Casset::css('file_2.css');
904 Casset::enable('jquery-ui');
905 ...
f36f399 @canton7 Add contributing section to readme
canton7 authored
906 ```
907
96385c7 @canton7 Add 'Thanks' section to readme
canton7 authored
908 Thanks
909 ------
910
911 The following people have helped Casset become what it is, so thank you!
912
913 - [Peter Wigger](http://fuelphp.com/user/383)
914 - [ShonM](https://github.com/shonm)
915 - [Lee Overy](https://github.com/leekudos)
916 - [Chris Meller](https://github.com/chrismeller)
917 - [monsonis](https://github.com/monsonis)
918 - [Anton Stoychev](https://github.com/antitoxic)
8d880ac @canton7 Add reporter (gnodeb) to contributers
canton7 authored
919 - [gnodeb](https://github.com/gnodeb)
1e64a02 @canton7 Add dmyers to the contributers list
canton7 authored
920 - [Derek Myers](https://github.com/dmyers)
fe93aec @canton7 Add iturgeon to the contributers
canton7 authored
921 - [Ian Turgeon](https://github.com/iturgeon)
49ad8f5 @canton7 Add Peter Wiggers to contributers
canton7 authored
922 - [Peter Wiggers](https://github.com/pwwebdev)
96385c7 @canton7 Add 'Thanks' section to readme
canton7 authored
923
f36f399 @canton7 Add contributing section to readme
canton7 authored
924 Contributing
925 ------------
926
926610e @canton7 Changes to the minifications and examples sections of the readme, for
canton7 authored
927 If you've got any issues/complaints/suggestions, please tell me and I'll do my best!
f36f399 @canton7 Add contributing section to readme
canton7 authored
928
926610e @canton7 Changes to the minifications and examples sections of the readme, for
canton7 authored
929 Pull requests are also gladly accepted. This project uses [git flow](http://nvie.com/posts/a-successful-git-branching-model/), so please base your work on the tip of the `develop` branch, and rebase onto `develop` again before submitting the pull request.
31bef83 @canton7 Detail exactly how to contribute in readme
canton7 authored
930 For example:
931
932 ```bash
933 # Fork canton7/fuelphp-casset on github
934 # Clone your new repo
935 $ git clone git@github.com:your_user/fuelphp-casset.git
12b370d @canton7 Correct 'contributing' instructions in readme
canton7 authored
936 # Add my repo as a remote, so you can pull in new changes, then fetch from it
31bef83 @canton7 Detail exactly how to contribute in readme
canton7 authored
937 $ git remote add upstream git://github.com/canton7/fuelphp-casset.git
12b370d @canton7 Correct 'contributing' instructions in readme
canton7 authored
938 $ git fetch upstream
31bef83 @canton7 Detail exactly how to contribute in readme
canton7 authored
939 # Create a new feature branch based off my develop branch
940 $ git checkout -b feature/my_feature_name upstream/develop
941 # Push this branch to origin
942 $ git push -u origin feature/my_feature_name
943 # Work work work... Git add, commit, etc, as normal
944 # Update your copy of my develop branch
945 $ git fetch upstream
946 # Rebase your feature branch back on top of my develop branch
947 $ git rebase upstream/develop
948 # Force-push just this up to origin (as the rebase will have rewritten it)
949 $ git push -f origin feature/my_feature_branch
950 # Submit the pull request to github!
9d37cd1 @canton7 Fix typos in readme
canton7 authored
951 ```
Something went wrong with that request. Please try again.