# Requirements ## Introduction The requirements class takes care of including CSS and JavaScript into your applications. This is preferred to hardcoding any references in the ``-tag of your template, as it enables a more flexible handling. ## Including inside PHP Code It is common practice to include most Requirements either in the *init()*-method of your [controller](/topics/controller), or as close to rendering as possible (e.g. in `[api:FormField]` :::php Requirements::javascript("cms/javascript/LeftAndMain.js"); Requirements::css("cms/css/TreeSelector.css"); If you're using the CSS method a second argument can be used. This argument defines the 'media' attribute of the `` element, so you can define 'screen' or 'print' for example. Requirements::css("cms/css/TreeSelector.css", "screen,projection"); ## Including inside Template files If you do not want to touch the PHP (for example you are constructing a generic theme) then you can include a file via the templates <% require css("cms/css/TreeSelector.css") %> <% require themedCSS("TreeSelector") %> <% require javascript("cms/javascript/LeftAndMain.js") %> ## Combining Files You can concatenate several CSS or javascript files into a single dynamically generated file. This increases performance reducing HTTP requests. Note that for debugging purposes combined files is disabled in devmode. :::php // supports CSS + JS Requirements::combine_files( 'foobar.js', array( 'mysite/javascript/foo.js', 'mysite/javascript/bar.js', ) ); By default it stores the generated file in the assets/ folder but you can configure this by pointing the `Requirements.combined_files_folder` configuration setting to a specific folder. If SilverStripe doesn't have permissions on your server to write these files it will default back to including them individually . 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 $printStylesheets = array( "$themeDir/css/print_HomePage.css", "$themeDir/css/print_Page.css", ); Requirements::combine_files('print.css', $printStylesheets, 'print'); ## Custom Inline Scripts You can also quote custom script directly. This may seem a bit ugly, but is useful when you need to transfer some kind of 'configuration' from the database to the javascript/css. You'll need to use the "heredoc" syntax to quote JS and CSS, this is generally speaking the best way to do these things - it clearly marks the copy as belonging to a different language. :::php Requirements::customScript(<< "mot/css/editor.css", ); Requirements::javascriptTemplate("cms/javascript/editor.template.js", $vars); ## Clearing You may want to clear all of the requirements mentioned thus far. I've used this when you've put an iframe generator as an action on the controller that uses it. The iframe has a completely different set of scripting and styling requirements, and it's easiest to flush all the default stuff and start again. :::php Requirements::clear(); You can also clear specific Requirements: :::php Requirements::clear('jsparty/prototype.js'); Caution: 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` include added by various form fields and core controllers, and use a newer version in a custom location. :::php Requirements::block(THIRDPARTY_DIR . '/jquery/jquery.js'); Caution: 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 (=guessing) the whole set of requirements. Caution: Inclusion order is both relevant for CSS and Javascript files in terms of dependencies, inheritance and overlays - please 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 `