Requirements
class Requirements implements Flushable (View source)
Requirements tracker for JavaScript and CSS.
Properties
| static private bool | $disable_flush_combined | Flag whether combined files should be deleted on flush. |
Methods
Triggered early in the request when a flush is requested
Enable combining of css/javascript files.
Checks whether combining of css/javascript files is enabled.
Set the relative folder e.g. 'assets' for where to store combined files
Set whether to add caching query params to the requests for file-based requirements.
Check whether we want to suffix requirements
No description
Register the given JavaScript file as required.
Register the given JavaScript code into the list of requirements
Return all registered custom scripts
Register the given CSS styles into the list of requirements
Add the following custom HTML code to the <head> section of the page
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.
Register the given stylesheet into the list of requirements.
Registers the given themeable stylesheet as required.
Registers the given themeable javascript as required.
Clear either a single or all requirements
Restore requirements cleared by call to Requirements::clear
Block inclusion of a specific file
Remove an item from the block list
Removes all items from the block list
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.
Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given HTTP Response
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.
Concatenate several css or javascript files into a single dynamically generated file. This increases performance by fewer HTTP requests.
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.
Deletes all generated combined files in the configured combined files directory, but doesn't delete the directory itself
Re-sets the combined files definition. See {@link Requirements_Backend::clear_combined_files()}
Do the heavy lifting involved in combining the combined files.
Set whether you want to write the JS to the body of the page rather than at the end of the head tag.
Set whether you want to write the JS to the body of the page rather than at the end of the head tag.
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()).
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()).
Check if JS minification is enabled
Enable or disable js minification
Check if header comments are written
Flag whether header comments should be written for each combined file
Output debugging information
Details
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($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.
static bool
get_suffix_requirements()
Check whether we want to suffix requirements
static Requirements_Backend
backend()
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.
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.
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.
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.
static
restore()
Restore requirements cleared by call to Requirements::clear
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.
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.
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',
)
);
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($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