Version: current

# Class Requirements_Backend

Package: sapphire\view
Located at sapphire/core/Requirements.php

## Methods summary

`public` | # `set_combined_files_enabled( mixed $enable )`
`public` | # `get_combined_files_enabled( )`
`public` | # `setCombinedFilesFolder( mixed $folder )`
`public` | # `set_suffix_requirements( boolean $var )` Set whether we want to suffix requirements with the time / location on to the requirements Set whether we want to suffix requirements with the time / location on to the requirements #### Parameters $var bool
`public boolean` | # `get_suffix_requirements( )` Return whether we want to suffix requirements Return whether we want to suffix requirements #### Returns `boolean` bool
`public` | # `set_write_js_to_body( boolean $var )` Set whether you want the files written to the head or the body. It writes to the body by default which can break some scripts Set whether you want the files written to the head or the body. It writes to the body by default which can break some scripts #### Parameters $var boolean
`public` | # `javascript( mixed $file )` Register the given javascript file as required. Filenames should be relative to the base, eg, 'sapphire/javascript/loader.js' Register the given javascript file as required. Filenames should be relative to the base, eg, 'sapphire/javascript/loader.js'
`public array` | # `get_javascript( )` Returns an array of all included javascript Returns an array of all included javascript #### Returns `array` array
`public` | # `customScript( script $script, uniquenessID $uniquenessID = null )` Add the javascript code to the header of the page Add the javascript code to the header of the page #### Parameters $script script The script content $uniquenessID uniquenessID Use this to ensure that pieces of code only get added once.
`public` | # `customCSS( string $script, integer $uniquenessID = null )` Include custom CSS styling to the header of the page. Include custom CSS styling to the header of the page. #### Parameters $script string $script CSS selectors as a string (without <style> tag enclosing selectors). $uniquenessID int $uniquenessID Group CSS by a unique ID as to avoid duplicate custom CSS in header
`public` | # `insertHeadTags( string $html, string $uniquenessID = null )` Add the following custom code to the <head> section of the page. Add the following custom code to the <head> section of the page. #### Parameters $html string $html $uniquenessID string $uniquenessID
`public` | # `javascriptTemplate( file $file, vars $vars, mixed $uniquenessID = null )` Load the given javascript template with the page. Load the given javascript template with the page. #### Parameters $file file The template file to load. $vars vars The array of variables to load. These variables are loaded via string search & replace. $uniquenessID
`public` | # `css( mixed $file, mixed $media = null )` Register the given stylesheet file as required. Register the given stylesheet file as required. #### Parameters $file $file String Filenames should be relative to the base, eg, 'sapphire/javascript/tree/tree.css' $media $media String Comma-separated list of media-types (e.g. "screen,projector") #### See http://www.w3.org/TR/REC-CSS2/media.html
`public` | # `get_css( )`
`public` | # `block( string $fileOrID )` Needed to actively prevent the inclusion of a file, e.g. when using your own prototype.js. Blocking should only be used as an exception, because it is hard to trace back. You can just block items with an ID, so make sure you add an unique identifier to customCSS() and customScript(). Needed to actively prevent the inclusion of a file, e.g. when using your own prototype.js. Blocking should only be used as an exception, because it is hard to trace back. You can just block items with an ID, so make sure you add an unique identifier to customCSS() and customScript(). #### Parameters $fileOrID string $fileOrID
`public` | # `clear( mixed $fileOrID = null )` Clear either a single or all requirements. Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}. Clear either a single or all requirements. Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}. #### Parameters $fileOrID $file String
`public` | # `unblock( string $fileOrID )` Removes an item from the blocking-list. CAUTION: Does not "re-add" any previously blocked elements. Removes an item from the blocking-list. CAUTION: Does not "re-add" any previously blocked elements. #### Parameters $fileOrID string $fileOrID
`public` | # `unblock_all( )` Removes all items from the blocking-list. Removes all items from the blocking-list.
`public` | # `restore( )` Restore requirements cleared by call to Requirements::clear Restore requirements cleared by call to Requirements::clear
`public string` | # `includeInHTML( string $templateFile, 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> tag. The requirements will insert before the closing <head> tag automatically. 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> tag. The requirements will insert before the closing <head> tag automatically. #### Parameters $templateFile string $templateFilePath Absolute path for the *.ss template file $content string $content HTML content that has already been parsed from the $templateFilePath through `SSViewer`. #### Returns `string` HTML content thats augumented with the requirements before the closing <head> tag.
`public` | # `include_in_response( `SS_HTTPResponse` $response )` Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the HTTP response Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the HTTP response
`public` | # `add_i18n_javascript( mixed $langDir )` Add i18n files from the given javascript directory. Sapphire expects that the given directory will contain a number of java script files named by language: en_US.js, de_DE.js, etc. Add i18n files from the given javascript directory. Sapphire expects that the given directory will contain a number of java script files named by language: en_US.js, de_DE.js, etc. #### Parameters $langDir $langDir The javascript lang directory, relative to the site root, e.g., 'sapphire/javascript/lang'
`protected string|boolean` | # `path_for_file( string $fileOrUrl )` Finds the path for specified file. Finds the path for specified file. #### Parameters $fileOrUrl string $fileOrUrl #### Returns `string|boolean` string|boolean
`public` | # `combine_files( string $combinedFileName, array $files )` Concatenate several css or javascript files into a single dynamically generated file (stored in `Director::baseFolder()`). This increases performance by fewer HTTP requests. Concatenate several css or javascript files into a single dynamically generated file (stored in `Director::baseFolder()`). 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. If all files to be combined are javascript, we use the external JSMin library to minify the javascript. This can be controlled by `Requirements_Backend::$combine_js_with_jsmin`. All combined files will have a comment on the start of each concatenated file denoting their original position. For easier debugging, we recommend to only minify javascript if not in development mode (`Director::isDev()`). 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 wrong styling inheritance. Depending on the javascript logic, you also have to ensure that files are not included in more than one combine_files() call. Best practice is to include every javascript file in exactly one combine_files() directive to avoid the issues mentioned above - this is enforced by this function. 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 $combinedFileName string $combinedFileName Filename of the combined file (will be stored in `Director::baseFolder()` by default) $files array $files Array of filenames relative to the webroot #### See http://code.google.com/p/jsmin-php/
`public array` | # `get_combine_files( )` Returns all combined files. Returns all combined files. #### Returns `array` array
`public` | # `delete_combined_files( string $combinedFileName = null )` Deletes all dynamically generated combined files from the filesystem. Deletes all dynamically generated combined files from the filesystem. #### Parameters $combinedFileName string $combinedFileName If left blank, all combined files are deleted.
`public` | # `clear_combined_files( )`
`public` | # `process_combined_files( )` See `Requirements_Backend::combine_files()` See `Requirements_Backend::combine_files()`
`public` | # `get_custom_scripts( )`
`public` | # `themedCSS( mixed $name, mixed $media = null )` Register the given "themeable stylesheet" as required. Themeable stylesheets have globally unique names, just like templates and PHP files. Because of this, they can be replaced by similarly named CSS files in the theme directory. Register the given "themeable stylesheet" as required. Themeable stylesheets have globally unique names, just like templates and PHP files. Because of this, they can be replaced by similarly named CSS files in the theme directory. #### Parameters $name $name String The identifier of the file. For example, css/MyFile.css would have the identifier "MyFile" $media $media String Comma-separated list of media-types (e.g. "screen,projector")
`public` | # `debug( )`

### Magic methods summary

## Properties summary

`protected boolean` | $suffix_requirements | # Do we want requirements to suffix onto the requirement link tags for caching or is it disabled. Getter / Setter available through `Requirements::set_suffix_requirements()` Do we want requirements to suffix onto the requirement link tags for caching or is it disabled. Getter / Setter available through `Requirements::set_suffix_requirements()`
`protected boolean` | $combined_files_enabled | # Enable combining of css/javascript files. Enable combining of css/javascript files.
`protected array` | $javascript | # Paths to all required .js files relative to the webroot. Paths to all required .js files relative to the webroot.
`protected array` | $css | # Paths to all required .css files relative to the webroot. Paths to all required .css files relative to the webroot.
`protected array` | $customScript | # All custom javascript code that is inserted directly at the bottom of the HTML <head> tag. All custom javascript code that is inserted directly at the bottom of the HTML <head> tag.
`protected array` | $customCSS | # All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag. All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag.
`protected array` | $customHeadTags | # All custom HTML markup which is added before the closing <head> tag, e.g. additional metatags. This is preferred to entering tags directly into All custom HTML markup which is added before the closing <head> tag, e.g. additional metatags. This is preferred to entering tags directly into
`protected array` | $disabled | # Remembers the filepaths of all cleared Requirements through `Requirements_Backend::clear()`. Remembers the filepaths of all cleared Requirements through `Requirements_Backend::clear()`.
`protected array` | $blocked | # The filepaths (relative to webroot) or uniquenessIDs of any included requirements which should be blocked when executing inlcudeInHTML(). This is useful to e.g. prevent core classes to modifying Requirements without subclassing the entire functionality. Use `Requirements_Backend::unblock()` or `Requirements_Backend::unblock_all()` to revert changes. The filepaths (relative to webroot) or uniquenessIDs of any included requirements which should be blocked when executing inlcudeInHTML(). This is useful to e.g. prevent core classes to modifying Requirements without subclassing the entire functionality. Use `Requirements_Backend::unblock()` or `Requirements_Backend::unblock_all()` to revert changes.
`public array` | $combine_files | # See `Requirements_Backend::combine_files()`. See `Requirements_Backend::combine_files()`.
`public boolean` | $combine_js_with_jsmin | # Using the JSMin library to minify any javascript file passed to `Requirements_Backend::combine_files()`. Using the JSMin library to minify any javascript file passed to `Requirements_Backend::combine_files()`.
`protected string` | $combinedFilesFolder | # By default, combined files are stored in assets/_combinedfiles. Set this by calling Requirements::set_combined_files_folder() By default, combined files are stored in assets/_combinedfiles. Set this by calling Requirements::set_combined_files_folder()
`public boolean` | $write_js_to_body | # Put all javascript includes at the bottom of the template before the closing <body> tag instead of the <head> tag. This means script downloads won't block other HTTP-requests, which can be a performance improvement. Caution: Doesn't work when modifying the DOM from those external scripts without listening to window.onload/document.ready (e.g. toplevel document.write() calls). Put all javascript includes at the bottom of the template before the closing <body> tag instead of the <head> tag. This means script downloads won't block other HTTP-requests, which can be a performance improvement. Caution: Doesn't work when modifying the DOM from those external scripts without listening to window.onload/document.ready (e.g. toplevel document.write() calls). #### See http://developer.yahoo.com/performance/rules.html#js_bottom

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -