1. class
  2. SilverStripe
  3. \
  4. View
  5. \
  6. Requirements

Requirements

class Requirements implements Flushable

Requirements tracker for JavaScript and CSS.

Config options

disable_flush_combined bool Flag whether combined files should be deleted on flush.

Methods

static 
flush()

Triggered early in the request when a flush is requested

static 
set_combined_files_enabled(bool $enable)

Enable combining of css/javascript files.

static bool
get_combined_files_enabled()

Checks whether combining of css/javascript files is enabled.

static 
set_combined_files_folder(string $folder)

Set the relative folder e.g. 'assets' for where to store combined files

static 
set_suffix_requirements(bool $var)

Set whether to add caching query params to the requests for file-based requirements.

static bool
get_suffix_requirements()

Check whether we want to suffix requirements

static Requirements_Backend
backend()

No description

static 
set_backend(Requirements_Backend $backend)

Setter method for changing the Requirements backend

static 
javascript(string $file, array $options = array())

Register the given JavaScript file as required.

static 
customScript(string $script, string|int $uniquenessID = null)

Register the given JavaScript code into the list of requirements

static array
get_custom_scripts()

Return all registered custom scripts

static 
customCSS(string $script, string|int $uniquenessID = null)

Register the given CSS styles into the list of requirements

static 
insertHeadTags(string $html, string|int $uniquenessID = null)

Add the following custom HTML code to the <head> section of the page

static 
javascriptTemplate(string $file, string[]|int[] $vars, string|int $uniquenessID = null)

Include the content of the given JavaScript file in the list of requirements. Dollar-sign variables will be interpolated with values from $vars similar to a .ss template.

static 
css(string $file, string $media = null, array $options = [])

Register the given stylesheet into the list of requirements.

static 
themedCSS(string $name, string $media = null)

Registers the given themeable stylesheet as required.

static 
themedJavascript(string $name, string $type = null)

Registers the given themeable javascript as required.

static 
clear(string|int $fileOrID = null)

Clear either a single or all requirements

static 
restore()

Restore requirements cleared by call to Requirements::clear

static 
block(string|int $fileOrID)

Block inclusion of a specific file

static 
unblock(string|int $fileOrID)

Remove an item from the block list

static 
unblock_all()

Removes all items from the block list

static string
includeInHTML(string $content)

Update the given HTML content with the appropriate include tags for the registered requirements. Needs to receive a valid HTML/XHTML template in the $content parameter, including a head and body tag.

static 
include_in_response(HTTPResponse $response)

Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given HTTP Response

static array
add_i18n_javascript(string $langDir, bool $return = false, bool $langOnly = false)

Add i18n files from the given javascript directory. SilverStripe expects that the given directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js, etc.

static 
combine_files(string $combinedFileName, array $files, array $options = array())

Concatenate several css or javascript files into a single dynamically generated file. This increases performance by fewer HTTP requests.

static array
get_combine_files()

Return all combined files; keys are the combined file names, values are lists of associative arrays with 'files', 'type', and 'media' keys for details about this combined file.

static 
delete_all_combined_files()

Deletes all generated combined files in the configured combined files directory, but doesn't delete the directory itself

static 
clear_combined_files()

Re-sets the combined files definition. See {@link Requirements_Backend::clear_combined_files()}

static 
process_combined_files()

Do the heavy lifting involved in combining the combined files.

static bool
get_write_js_to_body()

Set whether you want to write the JS to the body of the page rather than at the end of the head tag.

static 
set_write_js_to_body(bool $var)

Set whether you want to write the JS to the body of the page rather than at the end of the head tag.

static bool
get_force_js_to_bottom()

Get whether to force the JavaScript to end of the body. Useful if you use inline script tags that don't rely on scripts included via {@link Requirements::javascript()).

static 
set_force_js_to_bottom(bool $var)

Set whether to force the JavaScript to end of the body. Useful if you use inline script tags that don't rely on scripts included via {@link Requirements::javascript()).

static bool
get_minify_combined_js_files()

Check if JS minification is enabled

static 
set_minify_combined_js_files(bool $minify)

Enable or disable js minification

static bool
get_write_header_comments()

Check if header comments are written

set_write_header_comments(bool $write)

Flag whether header comments should be written for each combined file

static 
debug()

Output debugging information

Details

at line 31
static flush()

Triggered early in the request when a flush is requested

at line 44
static set_combined_files_enabled(bool $enable)

Enable combining of css/javascript files.

Parameters

bool $enable

at line 54
static bool get_combined_files_enabled()

Checks whether combining of css/javascript files is enabled.

Return Value

bool

at line 64
static set_combined_files_folder(string $folder)

Set the relative folder e.g. 'assets' for where to store combined files

Parameters

string $folder Path to folder

at line 77
static set_suffix_requirements(bool $var)

Set whether to add caching query params to the requests for file-based requirements.

Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by filemtime. This has the benefit of allowing the browser to cache the URL infinitely, while automatically busting this cache every time the file is changed.

Parameters

bool $var

at line 87
static bool get_suffix_requirements()

Check whether we want to suffix requirements

Return Value

bool

at line 103
static Requirements_Backend backend()

Return Value

Requirements_Backend

at line 116
static set_backend(Requirements_Backend $backend)

Setter method for changing the Requirements backend

Parameters

Requirements_Backend $backend

at line 130
static javascript(string $file, array $options = array())

Register the given JavaScript file as required.

Parameters

string $file Relative to docroot
array $options List of options. Available options include: - 'provides' : List of scripts files included in this file - 'async' : Boolean value to set async attribute to script tag - 'defer' : Boolean value to set defer attribute to script tag

at line 141
static customScript(string $script, string|int $uniquenessID = null)

Register the given JavaScript code into the list of requirements

Parameters

string $script The script content as a string (without enclosing <script> tag)
string|int $uniquenessID A unique ID that ensures a piece of code is only added once

at line 151
static array get_custom_scripts()

Return all registered custom scripts

Return Value

array

at line 162
static customCSS(string $script, string|int $uniquenessID = null)

Register the given CSS styles into the list of requirements

Parameters

string $script CSS selectors as a string (without enclosing <style> tag)
string|int $uniquenessID A unique ID that ensures a piece of code is only added once

at line 173
static insertHeadTags(string $html, string|int $uniquenessID = null)

Add the following custom HTML code to the <head> section of the page

Parameters

string $html Custom HTML code
string|int $uniquenessID A unique ID that ensures a piece of code is only added once

at line 186
static javascriptTemplate(string $file, string[]|int[] $vars, string|int $uniquenessID = null)

Include the content of the given JavaScript file in the list of requirements. Dollar-sign variables will be interpolated with values from $vars similar to a .ss template.

Parameters

string $file The template file to load, relative to docroot
string[]|int[] $vars The array of variables to interpolate.
string|int $uniquenessID A unique ID that ensures a piece of code is only added once

at line 201
static css(string $file, string $media = null, array $options = [])

Register the given stylesheet into the list of requirements.

Parameters

string $file The CSS file to load, relative to site root
string $media Comma-separated list of media types to use in the link tag (e.g. 'screen,projector')
array $options List of options. Available options include: - 'integrity' : SubResource Integrity hash - 'crossorigin' : Cross-origin policy for the resource

at line 217
static themedCSS(string $name, string $media = null)

Registers the given themeable stylesheet as required.

A CSS file in the current theme path name 'themename/css/$name.css' is first searched for, and it that doesn't exist and the module parameter is set then a CSS file with that name in the module is used.

Parameters

string $name The name of the file - eg '/css/File.css' would have the name 'File'
string $media Comma-separated list of media types to use in the link tag (e.g. 'screen,projector')

at line 233
static themedJavascript(string $name, string $type = null)

Registers the given themeable javascript as required.

A javascript file in the current theme path name 'themename/javascript/$name.js' is first searched for, and it that doesn't exist and the module parameter is set then a javascript file with that name in the module is used.

Parameters

string $name The name of the file - eg '/javascript/File.js' would have the name 'File'
string $type Comma-separated list of types to use in the script tag (e.g. 'text/javascript,text/ecmascript')

at line 246
static clear(string|int $fileOrID = null)

Clear either a single or all requirements

Caution: Clearing single rules added via customCSS and customScript only works if you originally specified a $uniquenessID.

Parameters

string|int $fileOrID

at line 254
static restore()

Restore requirements cleared by call to Requirements::clear

at line 272
static block(string|int $fileOrID)

Block inclusion of a specific file

The difference between this and {@link clear} is that the calling order does not matter; {@link clear} must be called after the initial registration, whereas {@link block} can be used in advance. This is useful, for example, to block scripts included by a superclass without having to override entire functions and duplicate a lot of code.

Note that blocking should be used sparingly because it's hard to trace where an file is being blocked from.

Parameters

string|int $fileOrID

at line 282
static unblock(string|int $fileOrID)

Remove an item from the block list

Parameters

string|int $fileOrID

at line 290
static unblock_all()

Removes all items from the block list

at line 304
static string includeInHTML(string $content)

Update the given HTML content with the appropriate include tags for the registered requirements. Needs to receive a valid HTML/XHTML template in the $content parameter, including a head and body tag.

Parameters

string $content HTML content that has already been parsed from the $templateFile through {@link SSViewer}

Return Value

string HTML content augmented with the requirements tags

at line 323
static include_in_response(HTTPResponse $response)

Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given HTTP Response

Parameters

HTTPResponse $response

at line 341
static array add_i18n_javascript(string $langDir, bool $return = false, bool $langOnly = false)

Add i18n files from the given javascript directory. SilverStripe expects that the given directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js, etc.

Parameters

string $langDir The JavaScript lang directory, relative to the site root, e.g., 'framework/javascript/lang'
bool $return Return all relative file paths rather than including them in requirements
bool $langOnly @deprecated 4.1.0:5.0.0 as i18n.js should be included manually in your project

Return Value

array

at line 392
static combine_files(string $combinedFileName, array $files, array $options = array())

Concatenate several css or javascript files into a single dynamically generated file. This increases performance by fewer HTTP requests.

The combined file is regenerated based on every file modification time. Optionally a rebuild can be triggered by appending ?flush=1 to the URL.

All combined files will have a comment on the start of each concatenated file denoting their original position.

CAUTION: You're responsible for ensuring that the load order for combined files is retained - otherwise combining JavaScript files can lead to functional errors in the JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also only include each file once across all includes and comibinations in a single page load.

CAUTION: Combining CSS Files discards any "media" information.

Example for combined JavaScript: Requirements::combine_files( 'foobar.js', array( 'mysite/javascript/foo.js', 'mysite/javascript/bar.js', ) );

Example for combined CSS: Requirements::combine_files( 'foobar.css', array( 'mysite/javascript/foo.css', 'mysite/javascript/bar.css', ) );

Parameters

string $combinedFileName Filename of the combined file relative to docroot
array $files Array of filenames relative to docroot
array $options Array of options for combining files. Available options are: - 'media' : If including CSS Files, you can specify a media type - 'async' : If including JavaScript Files, boolean value to set async attribute to script tag - 'defer' : If including JavaScript Files, boolean value to set defer attribute to script tag

at line 407
static array get_combine_files()

Return all combined files; keys are the combined file names, values are lists of associative arrays with 'files', 'type', and 'media' keys for details about this combined file.

Return Value

array

at line 416
static delete_all_combined_files()

Deletes all generated combined files in the configured combined files directory, but doesn't delete the directory itself

at line 424
static clear_combined_files()

Re-sets the combined files definition. See {@link Requirements_Backend::clear_combined_files()}

at line 432
static process_combined_files()

Do the heavy lifting involved in combining the combined files.

at line 443
static bool get_write_js_to_body()

Set whether you want to write the JS to the body of the page rather than at the end of the head tag.

Return Value

bool

at line 454
static set_write_js_to_body(bool $var)

Set whether you want to write the JS to the body of the page rather than at the end of the head tag.

Parameters

bool $var

at line 465
static bool get_force_js_to_bottom()

Get whether to force the JavaScript to end of the body. Useful if you use inline script tags that don't rely on scripts included via {@link Requirements::javascript()).

Return Value

bool

at line 476
static set_force_js_to_bottom(bool $var)

Set whether to force the JavaScript to end of the body. Useful if you use inline script tags that don't rely on scripts included via {@link Requirements::javascript()).

Parameters

bool $var If true, force the JavaScript to be included at the bottom of the page

at line 486
static bool get_minify_combined_js_files()

Check if JS minification is enabled

Return Value

bool

at line 496
static set_minify_combined_js_files(bool $minify)

Enable or disable js minification

Parameters

bool $minify

at line 506
static bool get_write_header_comments()

Check if header comments are written

Return Value

bool

at line 516
set_write_header_comments(bool $write)

Flag whether header comments should be written for each combined file

Parameters

bool $write

at line 525
static debug()

Output debugging information