`
* `Requirements_Backend.default_combined_files_folder` - This defaults to `_combinedfiles`, and is the folder
within the configured asset backend that combined files will be stored in. If using a backend shared with
other systems, it is usually necessary to distinguish combined files from other assets.
* `Requirements_Backend.combine_in_dev` - By default combined files will not be combined except in test
or live environments. Turning this on will allow for pre-combining of files in development mode.
In some cases it may be necessary to create a new storage backend for combined files, if the default location
is not appropriate. Normally a single backend is used for all site assets, so a number of objects must be
replaced. For instance, the below will set a new set of dependencies to write to `mysite/javascript/combined`
:::yaml
---
Name: myrequirements
---
SilverStripe\View\Requirements:
disable_flush_combined: true
SilverStripe\View\Requirements_Backend:
combine_in_dev: true
combine_hash_querystring: true
default_combined_files_folder: 'combined'
SilverStripe\Core\Injector\Injector:
MySiteAdapter:
class: 'SilverStripe\Filesystem\Flysystem\AssetAdapter'
constructor:
Root: ./mysite/javascript
# Define the default filesystem
MySiteBackend:
class: 'League\Flysystem\Filesystem'
constructor:
Adapter: '%$MySiteAdapter'
calls:
PublicURLPlugin: [ addPlugin, [ %$FlysystemUrlPlugin ] ]
# Requirements config
MySiteAssetHandler:
class: SilverStripe\Filesystem\Storage\FlysystemGeneratedAssetHandler
properties:
Filesystem: '%$MySiteBackend'
SilverStripe\View\Requirements_Backend:
properties:
AssetHandler: '%$MySiteAssetHandler'
In the above configuration, automatic expiry of generated files has been disabled, and it is necessary for
the developer to maintain these files manually. This may be useful in environments where assets must
be pre-cached, where scripts must be served alongside static files, or where no framework php request is
guaranteed. Alternatively, files may be served from instances other than the one which generated the
page response, and file synchronisation might not occur fast enough to propagate combined files to
mirrored filesystems.
In any case, care should be taken to determine the mechanism appropriate for your development
and production environments.
### Combined CSS Files
You can also combine CSS files into a media-specific stylesheets as you would with the `Requirements::css` call - use
the third paramter of the `combine_files` function:
```php
$loader = ThemeResourceLoader::instance();
$themes = SSViewer::get_themes();
$printStylesheets = array(
$loader->findThemedCSS('print_HomePage.css', $themes),
$loader->findThemedCSS('print_Page.css', $themes)
);
Requirements::combine_files('print.css', $printStylesheets, 'print');
```
By default, all requirements files are flushed (deleted) when ?flush querystring parameter is set.
This can be disabled by setting the `Requirements.disable_flush_combined` config to `true`.
When combining CSS files, take care of relative urls, as these will not be re-written to match
the destination location of the resulting combined CSS.
### Combined JS Files
You can also add the 'async' and/or 'defer' attributes to combined Javascript files as you would with the
`Requirements::javascript` call - use the third paramter of the `combine_files` function:
```php
$loader = ThemeResourceLoader::instance();
$themes = SSViewer::get_themes();
$scripts = array(
$loader->findThemedJavascript('some_script.js', $themes),
$loader->findThemedJavascript('some_other_script.js', $themes)
);
Requirements::combine_files('scripts.js', $scripts, array('async' => true, 'defer' => true));
```
### Minification of CSS and JS files
You can minify combined Javascript and CSS files at runtime using an implementation of the
`SilverStripe\View\Requirements_Minifier` interface.
```php
namespace MyProject;
use SilverStripe\View\Requirements_Minifier;
class MyMinifier implements Requirements_Minifier
{
/**
* Minify the given content
*
* @param string $content
* @param string $type Either js or css
* @param string $filename Name of file to display in case of error
* @return string minified content
*/
public function minify ($content, $type, $fileName)
{
// Minify $content;
return $minifiedContent;
}
}
```
Then, inject this service in `Requirements_Backend`.
```yaml
SilverStripe\Core\Injector\Injector:
SilverStripe\View\Requirements_Backend:
properties:
Minifier: %$MyProject\MyMinifier
```
While the framework does afford you the option of minification at runtime, we recommend using one of many frontend build
tools to do this for you, e.g. [Webpack](https://webpack.github.io/), [Gulp](http://gulpjs.com/), or [Grunt](https://gruntjs.com/).
## Clearing assets
:::php
Requirements::clear();
Clears all defined requirements. You can also clear specific requirements.
:::php
Requirements::clear(THIRDPARTY_DIR.'/prototype.js');
Depending on where you call this command, a Requirement might be *re-included* afterwards.
## Blocking
Requirements can also be explicitly blocked from inclusion, which is useful to avoid conflicting JavaScript logic or
CSS rules. These blocking rules are independent of where the `block()` call is made. It applies both for already
included requirements, and ones included after the `block()` call.
One common example is to block the core `jquery.js` added by various form fields and core controllers, and use a newer
version in a custom location. This assumes you have tested your application with the newer version.
:::php
Requirements::block(ADMIN_THIRDPARTY_DIR . '/jquery/jquery.js');
The CMS also uses the `Requirements` system, and its operation can be affected by `block()` calls. Avoid this by
limiting the scope of your blocking operations, e.g. in `init()` of your controller.
## Inclusion Order
Requirements acts like a stack, where everything is rendered sequentially in the order it was included. There is no way
to change inclusion-order, other than using *Requirements::clear* and rebuilding the whole set of requirements.
Inclusion order is both relevant for CSS and Javascript files in terms of dependencies, inheritance and overlays - be
careful when messing with the order of requirements.
## Javascript placement
By default, SilverStripe includes all Javascript files at the bottom of the page body, unless there's another script
already loaded, then, it's inserted before the first `