Requirements_Backend
class Requirements_Backend (View source)
Traits
A class that can be instantiated or replaced via DI
Properties
| protected | bool | $suffixRequirements | Whether to add caching query params to the requests for file-based requirements. |
|
| protected | bool|null | $combinedFilesEnabled | Whether to combine CSS and JavaScript files |
|
| protected | array | $javascript | Paths to all required JavaScript files relative to docroot |
|
| protected | array | $providedJavascript | Map of included scripts to array of contained files. |
|
| protected | array | $css | Paths to all required CSS files relative to the docroot. |
|
| protected | array | $customScript | All custom javascript code that is inserted into the page's HTML |
|
| protected | array | $customCSS | All custom CSS rules which are inserted directly at the bottom of the HTML |
|
| protected | array | $customHeadTags | All custom HTML markup which is added before the closing |
|
| protected | array | $disabled | Remembers the file paths or uniquenessIDs of all Requirements cleared through clear(), so that they can be restored later. |
|
| protected | array | $blocked | The file paths (relative to docroot) or uniquenessIDs of any included requirements which should be blocked when executing inlcudeInHTML(). This is useful, for example, to block scripts included by a superclass without having to override entire functions and duplicate a lot of code. |
|
| protected | array | $combinedFiles | A list of combined files registered via combine_files(). Keys are the output file names, values are lists of input files. |
|
| protected | bool | $writeHeaderComment | Whether or not file headers should be written when combining files |
|
| protected | string | $combinedFilesFolder | Where to save combined files. By default they're placed in assets/_combinedfiles, however this may be an issue depending on your setup, especially for CSS files which often contain relative paths. |
|
| public | bool | $writeJavascriptToBody | Put all JavaScript includes at the bottom of the template before the closing |
|
| protected | bool | $forceJSToBottom | Force the JavaScript to the bottom of the page, even if there's a script tag in the body already |
|
| protected | GeneratedAssetHandler | $assetHandler |
Methods
An implementation of the factory method, allows you to create an instance of a class
Creates a class instance by the "singleton" design pattern.
Enable or disable the combination of CSS and JavaScript files
Flag whether header comments should be written for each combined file
Set the folder to save combined files in. By default they're placed in _combinedfiles, however this may be an issue depending on your setup, especially for CSS files which often contain relative paths.
Set whether to add caching query params to the requests for file-based requirements.
Set whether you want to write the JS to the body of the page rather than at the end of the head tag.
Check whether you want to write the JS to the body of the page rather than at the end of the head tag.
Forces the JavaScript requirements to the end of the body, right before the closing tag
Check if the JavaScript requirements are written to the end of the body, right before the closing tag
Register the given JavaScript file as required.
Returns an array of required JavaScript, excluding blocked and duplicates of provided files.
Gets all javascript, including blocked files. Unwraps the array into a non-associative list
Register the given JavaScript code into the list of requirements
Register the given Javascript code into the list of requirements with optional tag attributes.
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.
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.
Given a block of HTML, insert the given scripts at the bottom before
the closing </body> tag
Given a block of HTML, insert the given scripts inside the <body></body>
Given a block of HTML, insert the given code inside the <head></head> block
Safely escape a literal string for use in preg_replace replacement
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.
Given a set of files, combine them (as necessary) and return the url
Resolves relative paths in CSS files which are lost when combining them
Given a filename and list of files, generate a new filename unique to these files
For a given filelist, determine some discriminating value to determine if any of these files have changed.
Registers the given themeable stylesheet as required.
Registers the given themeable javascript as required.
Details
static Injectable
create(mixed ...$args)
An implementation of the factory method, allows you to create an instance of a class
This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.
This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();
static Injectable
singleton(string $class = null)
Creates a class instance by the "singleton" design pattern.
It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).
GeneratedAssetHandler
getAssetHandler()
Gets the backend storage for generated files
setAssetHandler(GeneratedAssetHandler $handler)
Set a new asset handler for this backend
setCombinedFilesEnabled(bool $enable)
Enable or disable the combination of CSS and JavaScript files
bool
getWriteHeaderComment()
Check if header comments are written
$this
setWriteHeaderComment(bool $write)
Flag whether header comments should be written for each combined file
setCombinedFilesFolder(string $folder)
Set the folder to save combined files in. By default they're placed in _combinedfiles, however this may be an issue depending on your setup, especially for CSS files which often contain relative paths.
This must not include any 'assets' prefix
string
getCombinedFilesFolder()
Retrieve the combined files folder prefix
setSuffixRequirements(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.
bool
getSuffixRequirements()
Check whether we want to suffix requirements
$this
setWriteJavascriptToBody(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.
bool
getWriteJavascriptToBody()
Check whether you want to write the JS to the body of the page rather than at the end of the head tag.
$this
setForceJSToBottom(bool $var)
Forces the JavaScript requirements to the end of the body, right before the closing tag
bool
getForceJSToBottom()
Check if the JavaScript requirements are written to the end of the body, right before the closing tag
javascript(string $file, array $options = [])
Register the given JavaScript file as required.
protected
unsetJavascript(string $file)
Remove a javascript requirement
array
getProvidedScripts()
Gets all scripts that are already provided by prior scripts.
This follows these rules:
- Files will not be considered provided if they are separately included prior to the providing file.
- Providing files can be blocked, and don't provide anything
- Provided files can't be blocked (you need to block the provider)
- If a combined file includes files that are provided by prior scripts, then these should be excluded from the combined file.
- If a combined file includes files that are provided by later scripts, then these files should be included in the combined file, but we can't block the later script either (possible double up of file).
array
getJavascript()
Returns an array of required JavaScript, excluding blocked and duplicates of provided files.
protected array
getAllJavascript()
Gets all javascript, including blocked files. Unwraps the array into a non-associative list
customScript(string $script, string $uniquenessID = null)
Register the given JavaScript code into the list of requirements
customScriptWithAttributes(string $script, array $attributes = [], string|int|null $uniquenessID = null)
Register the given Javascript code into the list of requirements with optional tag attributes.
array
getCustomScripts()
Return all registered custom scripts
customCSS(string $script, string $uniquenessID = null)
Register the given CSS styles into the list of requirements
array
getCustomCSS()
Return all registered custom CSS
insertHeadTags(string $html, string $uniquenessID = null)
Add the following custom HTML code to the <head> section of the page
array
getCustomHeadTags()
Return all custom head tags
javascriptTemplate(string $file, string[] $vars, string $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.
css(string $file, string $media = null, array $options = [])
Register the given stylesheet into the list of requirements.
protected
unsetCSS(string $file)
Remove a css requirement
array
getCSS()
Get the list of registered CSS file requirements, excluding blocked files
protected array
getAllCSS()
Gets all CSS files requirements, including blocked
array
getBlocked()
Gets the list of all blocked files
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.
restore()
Restore requirements cleared by call to Requirements::clear
block(string|int $fileOrID)
Block inclusion of a specific file
The difference between this and clear is that the calling order does not matter; 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.
unblock(string|int $fileOrID)
Remove an item from the block list
unblockAll()
Removes all items from the block list
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.
protected string
insertScriptsAtBottom(string $jsRequirements, string $content)
Given a block of HTML, insert the given scripts at the bottom before
the closing </body> tag
protected string
insertScriptsIntoBody(string $jsRequirements, string $content)
Given a block of HTML, insert the given scripts inside the <body></body>
protected string
insertTagsIntoHead(string $jsRequirements, string $content)
Given a block of HTML, insert the given code inside the <head></head> block
protected string
escapeReplacement(string $replacement)
Safely escape a literal string for use in preg_replace replacement
includeInResponse(HTTPResponse $response)
Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given HTTP Response
array|null
add_i18n_javascript(string $langDir, bool $return = 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.
protected string|bool
pathForFile(string $fileOrUrl)
Finds the path for specified file
combineFiles(string $combinedFileName, array $files, array $options = [])
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 combinations 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',
),
array(
'async' => true,
'defer' => true,
)
);Example for combined CSS:
Requirements::combine_files(
'foobar.css',
array(
'mysite/javascript/foo.css',
'mysite/javascript/bar.css',
),
array(
'media' => 'print',
)
);
protected array
parseCombinedFile(string|array $file)
Return path and type of given combined file
array
getCombinedFiles()
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.
protected array
getAllCombinedFiles()
Includes all combined files, including blocked ones
deleteAllCombinedFiles()
Clears all combined files
clearCombinedFiles()
Clear all registered CSS and JavaScript file combinations
processCombinedFiles()
Do the heavy lifting involved in combining the combined files.
protected string|null
getCombinedFileURL(string $combinedFile, array $fileList, string $type)
Given a set of files, combine them (as necessary) and return the url
protected string
resolveCSSReferences(string $content, string $filePath)
Resolves relative paths in CSS files which are lost when combining them
protected string
hashedCombinedFilename(string $combinedFile, array $fileList)
Given a filename and list of files, generate a new filename unique to these files
bool
getCombinedFilesEnabled()
Check if combined files are enabled
protected string
hashOfFiles(array $fileList)
For a given filelist, determine some discriminating value to determine if any of these files have changed.
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.
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.
debug()
Output debugging information.