diff --git a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md index f07cceaef..fbb0d9e19 100644 --- a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md +++ b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md @@ -13,6 +13,10 @@ coding any references in the `` tag of your template, as it enables a more **mysite/templates/Page.ss** +``` +<% require css("cms/css/TreeSelector.css") %> +<% require themedCSS("TreeSelector") %> +<% require javascript("cms/javascript/LeftAndMain.js") %> ``` [alert] @@ -24,24 +28,48 @@ Requiring assets from the template is restricted compared to the PHP API. It is common practice to include most Requirements either in the *init()*-method of your [controller](../controllers/), or as close to rendering as possible (e.g. in [api:FormField]). +```php +` element, so you can define 'screen' or 'print' for example. +```php +Requirements::css("cms/css/TreeSelector.css", "screen,projection"); ``` ### Javascript Files +```php +Requirements::javascript($path); ``` A variant on the inclusion of custom javascript is the inclusion of *templated* javascript. Here, you keep your JavaScript in a separate file and instead load, via search and replace, several PHP-generated variables into that code. +```php +$vars = array( + "EditorCSS" => "cms/css/editor.css", +); + +Requirements::javascriptTemplate("cms/javascript/editor.template.js", $vars); ``` In this example, `editor.template.js` is expected to contain a replaceable variable expressed as `$EditorCSS`. @@ -53,6 +81,18 @@ of 'configuration' from the database in a raw format. You'll need to use the `h 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(<< If SilverStripe doesn't have permissions on your server to write these files it will default back to including them individually. SilverStripe **will not** rewrite your paths within the file. -[/info] + 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'); ``` By default, all requirements files are flushed (deleted) when ?flush querystring parameter is set. @@ -89,10 +147,14 @@ This can be disabled by setting the `Requirements.disable_flush_combined` config ## Clearing assets +```php +Requirements::clear(); ``` Clears all defined requirements. You can also clear specific requirements. +```php +Requirements::clear(THIRDPARTY_DIR.'/prototype.js'); ``` [alert] @@ -108,6 +170,8 @@ 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(THIRDPARTY_DIR . '/jquery/jquery.js'); ``` [alert] @@ -130,6 +194,8 @@ careful when messing with the order of requirements. 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 `