tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Documentation tidy for Requirements.php

Browse Source 
Documentation-only changes, except where a couple of methods have been moved to live next to other related functions.
This commit is contained in:
Nik Rolls 2015-04-29 20:17:08 +12:00
parent e393a30d0f
commit 8727f27f2a
1 changed files with 416 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

698
view/Requirements.php
View File

@ -1,8 +1,7 @@
<?php <?php
/** /**
* Requirements tracker, for javascript and css. * Requirements tracker for JavaScript and CSS.
* @todo Document the requirements tracker, and discuss it with the others.
* *
* @package framework * @package framework
* @subpackage view * @subpackage view
@ -10,7 +9,7 @@
class Requirements implements Flushable { class Requirements implements Flushable {
/** /**
* Triggered early in the request when someone requests a flush. * Triggered early in the request when a flush is requested
*/ */
public static function flush() { public static function flush() {
self::delete_all_combined_files(); self::delete_all_combined_files();
@ -18,7 +17,8 @@ class Requirements implements Flushable {
/** /**
* Enable combining of css/javascript files. * Enable combining of css/javascript files.
* @param boolean $enable *
* @param bool $enable
*/ */
public static function set_combined_files_enabled($enable) { public static function set_combined_files_enabled($enable) {
self::backend()->set_combined_files_enabled($enable); self::backend()->set_combined_files_enabled($enable);
@ -26,14 +26,16 @@ class Requirements implements Flushable {
/** /**
* Checks whether combining of css/javascript files is enabled. * Checks whether combining of css/javascript files is enabled.
* @return boolean *
* @return bool
*/ */
public static function get_combined_files_enabled() { public static function get_combined_files_enabled() {
return self::backend()->get_combined_files_enabled(); return self::backend()->get_combined_files_enabled();
} }
/** /**
* Set the relative folder e.g. "assets" for where to store combined files * Set the relative folder e.g. 'assets' for where to store combined files
*
* @param string $folder Path to folder * @param string $folder Path to folder
*/ */
public static function set_combined_files_folder($folder) { public static function set_combined_files_folder($folder) {
@ -41,8 +43,10 @@ class Requirements implements Flushable {
} }
/** /**
* Set whether we want to suffix requirements with the time / * Set whether to add caching query params to the requests for file-based requirements.
* location on to the 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.
* *
* @param bool * @param bool
*/ */
@ -51,7 +55,7 @@ class Requirements implements Flushable {
} }
/** /**
* Return whether we want to suffix requirements * Check whether we want to suffix requirements
* *
* @return bool * @return bool
*/ */
@ -60,9 +64,10 @@ class Requirements implements Flushable {
} }
/** /**
* Instance of requirements for storage * Instance of the requirements for storage. You can create your own backend to change the
* default JS and CSS inclusion behaviour.
* *
* @var Requirements * @var Requirements_Backend
*/ */
private static $backend = null; private static $backend = null;
@ -76,74 +81,78 @@ class Requirements implements Flushable {
/** /**
* Setter method for changing the Requirements backend * Setter method for changing the Requirements backend
* *
* @param Requirements $backend * @param Requirements_Backend $backend
*/ */
public static function set_backend(Requirements_Backend $backend) { public static function set_backend(Requirements_Backend $backend) {
self::$backend = $backend; self::$backend = $backend;
} }
/** /**
* Register the given javascript file as required. * Register the given JavaScript file as required.
*
* See {@link Requirements_Backend::javascript()} for more info
* *
* @param string $file Relative to docroot
*/ */
public static function javascript($file) { public static function javascript($file) {
self::backend()->javascript($file); self::backend()->javascript($file);
} }
/** /**
* Add the javascript code to the header of the page * Register the given JavaScript code into the list of requirements
* *
* See {@link Requirements_Backend::customScript()} for more info * @param string $script The script content as a string (without enclosing <script> tag)
* @param script The script content * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
* @param uniquenessID Use this to ensure that pieces of code only get added once.
*/ */
public static function customScript($script, $uniquenessID = null) { public static function customScript($script, $uniquenessID = null) {
self::backend()->customScript($script, $uniquenessID); self::backend()->customScript($script, $uniquenessID);
} }
/** /**
* Include custom CSS styling to the header of the page. * Return all registered custom scripts
* *
* See {@link Requirements_Backend::customCSS()} * @return array
*/
public static function get_custom_scripts() {
return self::backend()->get_custom_scripts();
}
/**
* Register the given CSS styles into the list of requirements
* *
* @param string $script CSS selectors as a string (without <style> tag enclosing selectors). * @param string $script CSS selectors as a string (without enclosing <style> tag)
* @param int $uniquenessID Group CSS by a unique ID as to avoid duplicate custom CSS in header * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public static function customCSS($script, $uniquenessID = null) { public static function customCSS($script, $uniquenessID = null) {
self::backend()->customCSS($script, $uniquenessID); self::backend()->customCSS($script, $uniquenessID);
} }
/** /**
* Add the following custom code to the <head> section of the page. * Add the following custom HTML code to the <head> section of the page
* See {@link Requirements_Backend::insertHeadTags()}
* *
* @param string $html * @param string $html Custom HTML code
* @param string $uniquenessID * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public static function insertHeadTags($html, $uniquenessID = null) { public static function insertHeadTags($html, $uniquenessID = null) {
self::backend()->insertHeadTags($html, $uniquenessID); self::backend()->insertHeadTags($html, $uniquenessID);
} }
/** /**
* Load the given javascript template with the page. * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
* See {@link Requirements_Backend::javascriptTemplate()} * variables will be interpolated with values from $vars similar to a .ss template.
* *
* @param file The template file to load. * @param string $file The template file to load, relative to docroot
* @param vars The array of variables to load. These variables are loaded via string search & replace. * @param string[]|int[] $vars The array of variables to interpolate.
* @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public static function javascriptTemplate($file, $vars, $uniquenessID = null) { public static function javascriptTemplate($file, $vars, $uniquenessID = null) {
self::backend()->javascriptTemplate($file, $vars, $uniquenessID); self::backend()->javascriptTemplate($file, $vars, $uniquenessID);
} }
/** /**
* Register the given stylesheet file as required. * Register the given stylesheet into the list of requirements.
* See {@link Requirements_Backend::css()}
* *
* @param $file String Filenames should be relative to the base, eg, 'framework/javascript/tree/tree.css' * @param string $file The CSS file to load, relative to site root
* @param $media String Comma-separated list of media-types (e.g. "screen,projector") * @param string $media Comma-separated list of media types to use in the link tag
* @see http://www.w3.org/TR/REC-CSS2/media.html * (e.g. 'screen,projector')
*/ */
public static function css($file, $media = null) { public static function css($file, $media = null) {
self::backend()->css($file, $media); self::backend()->css($file, $media);
@ -152,116 +161,166 @@ class Requirements implements Flushable {
/** /**
* Registers the given themeable stylesheet as required. * Registers the given themeable stylesheet as required.
* *
* A CSS file in the current theme path name "themename/css/$name.css" is * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for,
* first searched for, and it that doesn't exist and the module parameter is * and it that doesn't exist and the module parameter is set then a CSS file with that name in
* set then a CSS file with that name in the module is used. * the module is used.
* *
* NOTE: This API is experimental and may change in the future. * @param string $name The name of the file - eg '/css/File.css' would have the name 'File'
* * @param string $module The module to fall back to if the css file does not exist in the
* @param string $name The name of the file - e.g. "/css/File.css" would have * current theme.
* the name "File". * @param string $media Comma-separated list of media types to use in the link tag
* @param string $module The module to fall back to if the css file does not * (e.g. 'screen,projector')
* exist in the current theme.
* @param string $media The CSS media attribute.
*/ */
public static function themedCSS($name, $module = null, $media = null) { public static function themedCSS($name, $module = null, $media = null) {
return self::backend()->themedCSS($name, $module, $media); return self::backend()->themedCSS($name, $module, $media);
} }
/** /**
* Clear either a single or all requirements. * Clear either a single or all requirements
* Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}.
* *
* See {@link Requirements_Backend::clear()} * Caution: Clearing single rules added via customCSS and customScript only works if you
* originally specified a $uniquenessID.
* *
* @param $file String * @param string|int $fileOrID
*/ */
public static function clear($fileOrID = null) { public static function clear($fileOrID = null) {
self::backend()->clear($fileOrID); self::backend()->clear($fileOrID);
} }
/**
* Blocks inclusion of a specific file
* See {@link Requirements_Backend::block()}
*
* @param unknown_type $fileOrID
*/
public static function block($fileOrID) {
self::backend()->block($fileOrID);
}
/**
* Removes an item from the blocking-list.
* See {@link Requirements_Backend::unblock()}
*
* @param string $fileOrID
*/
public static function unblock($fileOrID) {
self::backend()->unblock($fileOrID);
}
/**
* Removes all items from the blocking-list.
* See {@link Requirements_Backend::unblock_all()}
*/
public static function unblock_all() {
self::backend()->unblock_all();
}
/** /**
* Restore requirements cleared by call to Requirements::clear * Restore requirements cleared by call to Requirements::clear
* See {@link Requirements_Backend::restore()}
*/ */
public static function restore() { public static function restore() {
self::backend()->restore(); self::backend()->restore();
} }
/** /**
* Update the given HTML content with the appropriate include tags for the registered * Block inclusion of a specific file
* requirements.
* See {@link Requirements_Backend::includeInHTML()} for more information.
* *
* @param string $templateFilePath Absolute path for the *.ss template file * The difference between this and {@link clear} is that the calling order does not matter;
* @param string $content HTML content that has already been parsed from the $templateFilePath * {@link clear} must be called after the initial registration, whereas {@link block} can be
* through {@link SSViewer}. * used in advance. This is useful, for example, to block scripts included by a superclass
* @return string HTML content thats augumented with the requirements before the closing <head> tag. * 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.
*
* @param string|int $fileOrID
*/
public static function block($fileOrID) {
self::backend()->block($fileOrID);
}
/**
* Remove an item from the block list
*
* @param string|int $fileOrID
*/
public static function unblock($fileOrID) {
self::backend()->unblock($fileOrID);
}
/**
* Removes all items from the block list
*/
public static function unblock_all() {
self::backend()->unblock_all();
}
/**
* 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.
*
* @param string $templateFile No longer used, only retained for compatibility
* @param string $content HTML content that has already been parsed from the $templateFile
* through {@link SSViewer}
* @return string HTML content augmented with the requirements tags
*/ */
public static function includeInHTML($templateFile, $content) { public static function includeInHTML($templateFile, $content) {
return self::backend()->includeInHTML($templateFile, $content); return self::backend()->includeInHTML($templateFile, $content);
} }
/**
* Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given
* HTTP Response
*
* @param SS_HTTPResponse $response
*/
public static function include_in_response(SS_HTTPResponse $response) { public static function include_in_response(SS_HTTPResponse $response) {
return self::backend()->include_in_response($response); return self::backend()->include_in_response($response);
} }
/** /**
* Add i18n files from the given javascript directory. * 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.
* *
* @param String * @param string $langDir The JavaScript lang directory, relative to the site root, e.g.,
* @param Boolean * 'framework/javascript/lang'
* @param Boolean * @param bool $return Return all relative file paths rather than including them in
* requirements
* @param bool $langOnly Only include language files, not the base libraries
* *
* See {@link Requirements_Backend::add_i18n_javascript()} for more information. * @return array
*/ */
public static function add_i18n_javascript($langDir, $return = false, $langOnly = false) { public static function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
return self::backend()->add_i18n_javascript($langDir, $return, $langOnly); return self::backend()->add_i18n_javascript($langDir, $return, $langOnly);
} }
/** /**
* Concatenate several css or javascript files into a single dynamically generated file. * Concatenate several css or javascript files into a single dynamically generated file. This
* See {@link Requirements_Backend::combine_files()} for more info. * increases performance by fewer HTTP requests.
* *
* @param string $combinedFileName * The combined file is regenerated based on every file modification time. Optionally a
* @param array $files * rebuild can be triggered by appending ?flush=1 to the URL. If all files to be combined are
* @param string $media * JavaScript, we use the external JSMin library to minify the JavaScript.
*
* All combined files will have a comment on the start of each concatenated file denoting their
* original position. For easier debugging, we only minify JavaScript if not in development
* mode ({@link 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 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:
* <code>
* Requirements::combine_files(
* 'foobar.js',
* array(
* 'mysite/javascript/foo.js',
* 'mysite/javascript/bar.js',
* )
* );
* </code>
*
* Example for combined CSS:
* <code>
* Requirements::combine_files(
* 'foobar.css',
* array(
* 'mysite/javascript/foo.css',
* 'mysite/javascript/bar.css',
* )
* );
* </code>
*
* @param string $combinedFileName Filename of the combined file relative to docroot
* @param array $files Array of filenames relative to docroot
*
* @return bool|void
*/ */
public static function combine_files($combinedFileName, $files, $media = null) { public static function combine_files($combinedFileName, $files) {
self::backend()->combine_files($combinedFileName, $files, $media); self::backend()->combine_files($combinedFileName, $files);
} }
/** /**
* Returns all combined files. * Return all combined files; keys are the combined file names, values are lists of
* See {@link Requirements_Backend::get_combine_files()} * files being combined.
* *
* @return array * @return array
*/ */
@ -270,8 +329,7 @@ class Requirements implements Flushable {
} }
/** /**
* Deletes all dynamically generated combined files from the filesystem. * Delete all dynamically generated combined files from the filesystem
* See {@link Requirements_Backend::delete_combine_files()}
* *
* @param string $combinedFileName If left blank, all combined files are deleted. * @param string $combinedFileName If left blank, all combined files are deleted.
*/ */
@ -281,7 +339,7 @@ class Requirements implements Flushable {
/** /**
* Deletes all generated combined files in the configured combined files directory, * Deletes all generated combined files in the configured combined files directory,
* but doesn't delete the directory itself. * but doesn't delete the directory itself
*/ */
public static function delete_all_combined_files() { public static function delete_all_combined_files() {
return self::backend()->delete_all_combined_files(); return self::backend()->delete_all_combined_files();
@ -295,44 +353,36 @@ class Requirements implements Flushable {
} }
/** /**
* See {@link combine_files()}. * Do the heavy lifting involved in combining (and, in the case of JavaScript minifying) the
* combined files.
*/ */
public static function process_combined_files() { public static function process_combined_files() {
return self::backend()->process_combined_files(); return self::backend()->process_combined_files();
} }
/** /**
* Returns all custom scripts * Set whether you want to write the JS to the body of the page rather than at the end of the
* See {@link Requirements_Backend::get_custom_scripts()} * head tag.
* *
* @return array * @param bool
*/
public static function get_custom_scripts() {
return self::backend()->get_custom_scripts();
}
/**
* Set whether you want to write the JS to the body of the page or
* in the head section
*
* @see Requirements_Backend::set_write_js_to_body()
* @param boolean
*/ */
public static function set_write_js_to_body($var) { public static function set_write_js_to_body($var) {
self::backend()->set_write_js_to_body($var); self::backend()->set_write_js_to_body($var);
} }
/** /**
* Set the javascript to be forced to end of the HTML, or use the default. * Set whether to force the JavaScript to end of the body. Useful if you use inline script tags
* Useful if you use inline <script> tags, that don't need the javascripts * that don't rely on scripts included via {@link Requirements::javascript()).
* included via Requirements::require();
* *
* @param boolean $var If true, force the javascripts to be included at the bottom. * @param boolean $var If true, force the JavaScript to be included at the bottom of the page
*/ */
public static function set_force_js_to_bottom($var) { public static function set_force_js_to_bottom($var) {
self::backend()->set_force_js_to_bottom($var); self::backend()->set_force_js_to_bottom($var);
} }
/**
* Output debugging information
*/
public static function debug() { public static function debug() {
return self::backend()->debug(); return self::backend()->debug();
} }
@ -346,72 +396,70 @@ class Requirements implements Flushable {
class Requirements_Backend { class Requirements_Backend {
/** /**
* Do we want requirements to suffix onto the requirement link * Whether to add caching query params to the requests for file-based requirements.
* tags for caching or is it disabled. Getter / Setter available * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
* through {@link Requirements::set_suffix_requirements()} * 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.
* *
* @var bool * @var bool
*/ */
protected $suffix_requirements = true; protected $suffix_requirements = true;
/** /**
* Enable combining of css/javascript files. * Whether to combine CSS and JavaScript files
* *
* @var boolean * @var bool
*/ */
protected $combined_files_enabled = true; protected $combined_files_enabled = true;
/** /**
* Paths to all required .js files relative to the webroot. * Paths to all required JavaScript files relative to docroot
* *
* @var array $javascript * @var array $javascript
*/ */
protected $javascript = array(); protected $javascript = array();
/** /**
* Paths to all required .css files relative to the webroot. * Paths to all required CSS files relative to the docroot.
* *
* @var array $css * @var array $css
*/ */
protected $css = array(); protected $css = array();
/** /**
* All custom javascript code that is inserted * All custom javascript code that is inserted into the page's HTML
* directly at the bottom of the HTML <head> tag.
* *
* @var array $customScript * @var array $customScript
*/ */
protected $customScript = array(); protected $customScript = array();
/** /**
* All custom CSS rules which are inserted * All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag
* directly at the bottom of the HTML <head> tag.
* *
* @var array $customCSS * @var array $customCSS
*/ */
protected $customCSS = array(); protected $customCSS = array();
/** /**
* All custom HTML markup which is added before * All custom HTML markup which is added before the closing <head> tag, e.g. additional
* the closing <head> tag, e.g. additional metatags. * metatags.
* This is preferred to entering tags directly into
*/ */
protected $customHeadTags = array(); protected $customHeadTags = array();
/** /**
* Remembers the filepaths of all cleared Requirements * Remembers the file paths or uniquenessIDs of all Requirements cleared through
* through {@link clear()}. * {@link clear()}, so that they can be restored later.
* *
* @var array $disabled * @var array $disabled
*/ */
protected $disabled = array(); protected $disabled = array();
/** /**
* The filepaths (relative to webroot) or * The file paths (relative to docroot) or uniquenessIDs of any included requirements which
* uniquenessIDs of any included requirements * should be blocked when executing {@link inlcudeInHTML()}. This is useful, for example,
* which should be blocked when executing {@link inlcudeInHTML()}. * to block scripts included by a superclass without having to override entire functions and
* This is useful to e.g. prevent core classes to modifying * duplicate a lot of code.
* Requirements without subclassing the entire functionality. *
* Use {@link unblock()} or {@link unblock_all()} to revert changes. * Use {@link unblock()} or {@link unblock_all()} to revert changes.
* *
* @var array $blocked * @var array $blocked
@ -419,82 +467,93 @@ class Requirements_Backend {
protected $blocked = array(); protected $blocked = array();
/** /**
* See {@link combine_files()}. * A list of combined files registered via {@link combine_files()}. Keys are the output file
* names, values are lists of input files.
* *
* @var array $combine_files * @var array $combine_files
*/ */
public $combine_files = array(); public $combine_files = array();
/** /**
* Using the JSMin library to minify any * Use the JSMin library to minify any javascript file passed to {@link combine_files()}.
* javascript file passed to {@link combine_files()}.
* *
* @var boolean * @var bool
*/ */
public $combine_js_with_jsmin = true; public $combine_js_with_jsmin = true;
/** /**
* Setting for whether or not a file header should be written when * Whether or not file headers should be written when combining files
* combining files.
* *
* @var boolean * @var boolean
*/ */
public $write_header_comment = true; public $write_header_comment = true;
/** /**
* @var string By default, combined files are stored in assets/_combinedfiles. * Where to save combined files. By default they're placed in assets/_combinedfiles, however
* Set this by calling Requirements::set_combined_files_folder() * this may be an issue depending on your setup, especially for CSS files which often contain
* relative paths.
*
* @var string
*/ */
protected $combinedFilesFolder = null; protected $combinedFilesFolder = null;
/** /**
* Put all javascript includes at the bottom of the template * Put all JavaScript includes at the bottom of the template before the closing <body> tag,
* before the closing <body> tag instead of the <head> tag. * rather than the default behaviour of placing them at the end of the <head> tag. This means
* This means script downloads won't block other HTTP-requests, * script downloads won't block other HTTP requests, which can be a performance improvement.
* 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 * @var bool
*
* @var boolean
*/ */
public $write_js_to_body = true; public $write_js_to_body = true;
/** /**
* Force the javascripts to the bottom of the page, even if there's a * Force the JavaScript to the bottom of the page, even if there's a script tag in the body already
* <script> tag in the body already
* *
* @var boolean * @var boolean
*/ */
protected $force_js_to_bottom = false; protected $force_js_to_bottom = false;
/**
* Enable or disable the combination of CSS and JavaScript files
*
* @param $enable
*/
public function set_combined_files_enabled($enable) { public function set_combined_files_enabled($enable) {
$this->combined_files_enabled = (bool) $enable; $this->combined_files_enabled = (bool) $enable;
} }
/**
* Check whether file combination is enabled.
*
* @return bool
*/
public function get_combined_files_enabled() { public function get_combined_files_enabled() {
return $this->combined_files_enabled; return $this->combined_files_enabled;
} }
/** /**
* @param String $folder * Set the folder to save combined files in. 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.
*
* @param string $folder
*/ */
public function setCombinedFilesFolder($folder) { public function setCombinedFilesFolder($folder) {
$this->combinedFilesFolder = $folder; $this->combinedFilesFolder = $folder;
} }
/** /**
* @return String Folder relative to the webroot * @return string Folder relative to the webroot
*/ */
public function getCombinedFilesFolder() { public function getCombinedFilesFolder() {
return ($this->combinedFilesFolder) ? $this->combinedFilesFolder : ASSETS_DIR . '/_combinedfiles'; return ($this->combinedFilesFolder) ? $this->combinedFilesFolder : ASSETS_DIR . '/_combinedfiles';
} }
/** /**
* Set whether we want to suffix requirements with the time / * Set whether to add caching query params to the requests for file-based requirements.
* location on to the 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.
* *
* @param bool * @param bool
*/ */
@ -503,7 +562,7 @@ class Requirements_Backend {
} }
/** /**
* Return whether we want to suffix requirements * Check whether we want to suffix requirements
* *
* @return bool * @return bool
*/ */
@ -512,33 +571,35 @@ class Requirements_Backend {
} }
/** /**
* Set whether you want the files written to the head or the body. It * Set whether you want to write the JS to the body of the page rather than at the end of the
* writes to the body by default which can break some scripts * head tag.
* *
* @param boolean * @param bool
*/ */
public function set_write_js_to_body($var) { public function set_write_js_to_body($var) {
$this->write_js_to_body = $var; $this->write_js_to_body = $var;
} }
/** /**
* Forces the javascript to the end of the body, just before the closing body-tag. * Forces the JavaScript requirements to the end of the body, right before the closing tag
* *
* @param boolean * @param bool
*/ */
public function set_force_js_to_bottom($var) { public function set_force_js_to_bottom($var) {
$this->force_js_to_bottom = $var; $this->force_js_to_bottom = $var;
} }
/**
* Register the given javascript file as required.
* Filenames should be relative to the base, eg, 'framework/javascript/loader.js'
*/
/**
* Register the given JavaScript file as required.
*
* @param string $file Relative to docroot
*/
public function javascript($file) { public function javascript($file) {
$this->javascript[$file] = true; $this->javascript[$file] = true;
} }
/** /**
* Returns an array of all included javascript * Returns an array of all required JavaScript
* *
* @return array * @return array
*/ */
@ -547,10 +608,10 @@ class Requirements_Backend {
} }
/** /**
* Add the javascript code to the header of the page * Register the given JavaScript code into the list of requirements
* @todo Make Requirements automatically put this into a separate file :-) *
* @param script The script content * @param string $script The script content as a string (without enclosing <script> tag)
* @param uniquenessID Use this to ensure that pieces of code only get added once. * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public function customScript($script, $uniquenessID = null) { public function customScript($script, $uniquenessID = null) {
if($uniquenessID) $this->customScript[$uniquenessID] = $script; if($uniquenessID) $this->customScript[$uniquenessID] = $script;
@ -560,10 +621,27 @@ class Requirements_Backend {
} }
/** /**
* Include custom CSS styling to the header of the page. * Return all registered custom scripts
* *
* @param string $script CSS selectors as a string (without <style> tag enclosing selectors). * @return array
* @param int $uniquenessID Group CSS by a unique ID as to avoid duplicate custom CSS in header */
public function get_custom_scripts() {
$requirements = "";
if($this->customScript) {
foreach($this->customScript as $script) {
$requirements .= "$script\n";
}
}
return $requirements;
}
/**
* Register the given CSS styles into the list of requirements
*
* @param string $script CSS selectors as a string (without enclosing <style> tag)
* @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public function customCSS($script, $uniquenessID = null) { public function customCSS($script, $uniquenessID = null) {
if($uniquenessID) $this->customCSS[$uniquenessID] = $script; if($uniquenessID) $this->customCSS[$uniquenessID] = $script;
@ -571,10 +649,10 @@ class Requirements_Backend {
} }
/** /**
* Add the following custom code to the <head> section of the page. * Add the following custom HTML code to the <head> section of the page
* *
* @param string $html * @param string $html Custom HTML code
* @param string $uniquenessID * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public function insertHeadTags($html, $uniquenessID = null) { public function insertHeadTags($html, $uniquenessID = null) {
if($uniquenessID) $this->customHeadTags[$uniquenessID] = $html; if($uniquenessID) $this->customHeadTags[$uniquenessID] = $html;
@ -582,9 +660,12 @@ class Requirements_Backend {
} }
/** /**
* Load the given javascript template with the page. * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
* @param file The template file to load. * variables will be interpolated with values from $vars similar to a .ss template.
* @param vars The array of variables to load. These variables are loaded via string search & replace. *
* @param string $file The template file to load, relative to docroot
* @param string[]|int[] $vars The array of variables to interpolate.
* @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
*/ */
public function javascriptTemplate($file, $vars, $uniquenessID = null) { public function javascriptTemplate($file, $vars, $uniquenessID = null) {
$script = file_get_contents(Director::getAbsFile($file)); $script = file_get_contents(Director::getAbsFile($file));
@ -601,11 +682,11 @@ class Requirements_Backend {
} }
/** /**
* Register the given stylesheet file as required. * Register the given stylesheet into the list of requirements.
* *
* @param $file String Filenames should be relative to the base, eg, 'framework/javascript/tree/tree.css' * @param string $file The CSS file to load, relative to site root
* @param $media String Comma-separated list of media-types (e.g. "screen,projector") * @param string $media Comma-separated list of media types to use in the link tag
* @see http://www.w3.org/TR/REC-CSS2/media.html * (e.g. 'screen,projector')
*/ */
public function css($file, $media = null) { public function css($file, $media = null) {
$this->css[$file] = array( $this->css[$file] = array(
@ -613,28 +694,22 @@ class Requirements_Backend {
); );
} }
/**
* Get the list of registered CSS file requirements, excluding blocked files
*
* @return array
*/
public function get_css() { public function get_css() {
return array_diff_key($this->css, $this->blocked); return array_diff_key($this->css, $this->blocked);
} }
/** /**
* Needed to actively prevent the inclusion of a file, * Clear either a single or all requirements
* e.g. when using your own jQuery version.
* 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().
* *
* @param string $fileOrID * Caution: Clearing single rules added via customCSS and customScript only works if you
*/ * originally specified a $uniquenessID.
public function block($fileOrID) {
$this->blocked[$fileOrID] = $fileOrID;
}
/**
* Clear either a single or all requirements.
* Caution: Clearing single rules works only with customCSS and customScript if you specified a {@uniquenessID}.
* *
* @param $file String * @param string|int $fileOrID
*/ */
public function clear($fileOrID = null) { public function clear($fileOrID = null) {
if($fileOrID) { if($fileOrID) {
@ -659,21 +734,6 @@ class Requirements_Backend {
} }
} }
/**
* Removes an item from the blocking-list.
* CAUTION: Does not "re-add" any previously blocked elements.
* @param string $fileOrID
*/
public function unblock($fileOrID) {
if(isset($this->blocked[$fileOrID])) unset($this->blocked[$fileOrID]);
}
/**
* Removes all items from the blocking-list.
*/
public function unblock_all() {
$this->blocked = array();
}
/** /**
* Restore requirements cleared by call to Requirements::clear * Restore requirements cleared by call to Requirements::clear
*/ */
@ -684,18 +744,48 @@ class Requirements_Backend {
$this->customCSS = $this->disabled['customCSS']; $this->customCSS = $this->disabled['customCSS'];
$this->customHeadTags = $this->disabled['customHeadTags']; $this->customHeadTags = $this->disabled['customHeadTags'];
} }
/**
* 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.
*
* @param string|int $fileOrID
*/
public function block($fileOrID) {
$this->blocked[$fileOrID] = $fileOrID;
}
/**
* Remove an item from the block list
*
* @param string|int $fileOrID
*/
public function unblock($fileOrID) {
if(isset($this->blocked[$fileOrID])) unset($this->blocked[$fileOrID]);
}
/**
* Removes all items from the block list
*/
public function unblock_all() {
$this->blocked = array();
}
/** /**
* Update the given HTML content with the appropriate include tags for the registered * 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, * 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. * including a head and body tag.
* *
* @todo Calculate $prefix properly * @param string $templateFile No longer used, only retained for compatibility
* * @param string $content HTML content that has already been parsed from the $templateFile
* @param string $templateFilePath Absolute path for the *.ss template file * through {@link SSViewer}
* @param string $content HTML content that has already been parsed from the $templateFilePath * @return string HTML content augmented with the requirements tags
* through {@link SSViewer}.
* @return string HTML content thats augumented with the requirements before the closing <head> tag.
*/ */
public function includeInHTML($templateFile, $content) { public function includeInHTML($templateFile, $content) {
if( if(
@ -715,8 +805,7 @@ class Requirements_Backend {
} }
} }
// add all inline javascript *after* including external files which // Add all inline JavaScript *after* including external files they might rely on
// they might rely on
if($this->customScript) { if($this->customScript) {
foreach(array_diff_key($this->customScript,$this->blocked) as $script) { foreach(array_diff_key($this->customScript,$this->blocked) as $script) {
$jsRequirements .= "<script type=\"text/javascript\">\n//<![CDATA[\n"; $jsRequirements .= "<script type=\"text/javascript\">\n//<![CDATA[\n";
@ -746,9 +835,8 @@ class Requirements_Backend {
// Remove all newlines from code to preserve layout // Remove all newlines from code to preserve layout
$jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements); $jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements);
// We put script tags into the body, for performance. // Forcefully put the scripts at the bottom of the body instead of before the first
// We forcefully put it at the bottom instead of before // script tag.
// the first script-tag occurence
$content = preg_replace("/(<\/body[^>]*>)/i", $jsRequirements . "\\1", $content); $content = preg_replace("/(<\/body[^>]*>)/i", $jsRequirements . "\\1", $content);
// Put CSS at the bottom of the head // Put CSS at the bottom of the head
@ -757,7 +845,6 @@ class Requirements_Backend {
// Remove all newlines from code to preserve layout // Remove all newlines from code to preserve layout
$jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements); $jsRequirements = preg_replace('/>\n*/', '>', $jsRequirements);
// We put script tags into the body, for performance.
// If your template already has script tags in the body, then we try to put our script // If your template already has script tags in the body, then we try to put our script
// tags just before those. Otherwise, we put it at the bottom. // tags just before those. Otherwise, we put it at the bottom.
$p2 = stripos($content, '<body'); $p2 = stripos($content, '<body');
@ -766,7 +853,7 @@ class Requirements_Backend {
$commentTags = array(); $commentTags = array();
$canWriteToBody = ($p1 !== false) $canWriteToBody = ($p1 !== false)
&& &&
//check that the script tag is not inside a html comment tag // Check that the script tag is not inside a html comment tag
!( !(
preg_match('/.*(?|(<!--)|(-->))/U', $content, $commentTags, 0, $p1) preg_match('/.*(?|(<!--)|(-->))/U', $content, $commentTags, 0, $p1)
&& &&
@ -791,7 +878,10 @@ class Requirements_Backend {
} }
/** /**
* 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 given
* HTTP Response
*
* @param SS_HTTPResponse $response
*/ */
public function include_in_response(SS_HTTPResponse $response) { public function include_in_response(SS_HTTPResponse $response) {
$this->process_combined_files(); $this->process_combined_files();
@ -819,12 +909,17 @@ class Requirements_Backend {
} }
/** /**
* Add i18n files from the given javascript directory. SilverStripe expects that the given directory * Add i18n files from the given javascript directory. SilverStripe expects that the given
* will contain a number of java script files named by language: en_US.js, de_DE.js, etc. * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js,
* etc.
* *
* @param String The javascript lang directory, relative to the site root, e.g., 'framework/javascript/lang' * @param string $langDir The JavaScript lang directory, relative to the site root, e.g.,
* @param Boolean Return all relative file paths rather than including them in requirements * 'framework/javascript/lang'
* @param Boolean Only include language files, not the base libraries * @param bool $return Return all relative file paths rather than including them in
* requirements
* @param bool $langOnly Only include language files, not the base libraries
*
* @return array
*/ */
public function add_i18n_javascript($langDir, $return = false, $langOnly = false) { public function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
$files = array(); $files = array();
@ -863,10 +958,10 @@ class Requirements_Backend {
} }
/** /**
* Finds the path for specified file. * Finds the path for specified file
* *
* @param string $fileOrUrl * @param string $fileOrUrl
* @return string|boolean * @return string|bool
*/ */
protected function path_for_file($fileOrUrl) { protected function path_for_file($fileOrUrl) {
if(preg_match('{^//|http[s]?}', $fileOrUrl)) { if(preg_match('{^//|http[s]?}', $fileOrUrl)) {
@ -896,27 +991,22 @@ class Requirements_Backend {
} }
/** /**
* Concatenate several css or javascript files into a single dynamically generated * Concatenate several css or javascript files into a single dynamically generated file. This
* file (stored in {@link Director::baseFolder()}). This increases performance * increases performance by fewer HTTP requests.
* by fewer HTTP requests.
* *
* The combined file is regenerated * The combined file is regenerated based on every file modification time. Optionally a
* based on every file modification time. Optionally a rebuild can be triggered * rebuild can be triggered by appending ?flush=1 to the URL. If all files to be combined are
* by appending ?flush=1 to the URL. * JavaScript, we use the external JSMin library to minify the JavaScript. This can be
* If all files to be combined are javascript, we use the external JSMin library * controlled using {@link $combine_js_with_jsmin}.
* to minify the javascript. This can be controlled by {@link $combine_js_with_jsmin}.
* *
* All combined files will have a comment on the start of each concatenated file * All combined files will have a comment on the start of each concatenated file denoting their
* denoting their original position. For easier debugging, we recommend to only * original position. For easier debugging, we only minify JavaScript if not in development
* minify javascript if not in development mode ({@link Director::isDev()}). * mode ({@link Director::isDev()}).
* *
* CAUTION: You're responsible for ensuring that the load order for combined files * CAUTION: You're responsible for ensuring that the load order for combined files is
* is retained - otherwise combining javascript files can lead to functional errors * retained - otherwise combining JavaScript files can lead to functional errors in the
* in the javascript logic, and combining css can lead to wrong styling inheritance. * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also
* Depending on the javascript logic, you also have to ensure that files are not included * only include each file once across all includes and combinations in a single page load.
* 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. * CAUTION: Combining CSS Files discards any "media" information.
* *
@ -942,15 +1032,10 @@ class Requirements_Backend {
* ); * );
* </code> * </code>
* *
* @see http://code.google.com/p/jsmin-php/ * @param string $combinedFileName Filename of the combined file relative to docroot
* @param array $files Array of filenames relative to docroot
* *
* @todo Should we enforce unique inclusion of files, or leave it to the developer? Can auto-detection cause * @return bool|void
* breaks?
*
* @param string $combinedFileName Filename of the combined file (will be stored in {@link Director::baseFolder()}
* by default)
* @param array $files Array of filenames relative to the webroot
* @param string $media Comma-separated list of media-types (e.g. "screen,projector").
*/ */
public function combine_files($combinedFileName, $files, $media = null) { public function combine_files($combinedFileName, $files, $media = null) {
// duplicate check // duplicate check
@ -1005,7 +1090,9 @@ class Requirements_Backend {
} }
/** /**
* Returns all combined files. * Return all combined files; keys are the combined file names, values are lists of
* files being combined.
*
* @return array * @return array
*/ */
public function get_combine_files() { public function get_combine_files() {
@ -1013,7 +1100,7 @@ class Requirements_Backend {
} }
/** /**
* Deletes all dynamically generated combined files from the filesystem. * Delete all dynamically generated combined files from the filesystem
* *
* @param string $combinedFileName If left blank, all combined files are deleted. * @param string $combinedFileName If left blank, all combined files are deleted.
*/ */
@ -1043,16 +1130,19 @@ class Requirements_Backend {
} }
} }
/**
* Clear all registered CSS and JavaScript file combinations
*/
public function clear_combined_files() { public function clear_combined_files() {
$this->combine_files = array(); $this->combine_files = array();
} }
/** /**
* See {@link combine_files()} * Do the heavy lifting involved in combining (and, in the case of JavaScript minifying) the
* * combined files.
*/ */
public function process_combined_files() { public function process_combined_files() {
// The class_exists call prevents us from loading SapphireTest.php (slow) just to know that // The class_exists call prevents us loading SapphireTest.php (slow) just to know that
// SapphireTest isn't running :-) // SapphireTest isn't running :-)
if(class_exists('SapphireTest', false)) $runningTest = SapphireTest::is_running_test(); if(class_exists('SapphireTest', false)) $runningTest = SapphireTest::is_running_test();
else $runningTest = false; else $runningTest = false;
@ -1077,7 +1167,7 @@ class Requirements_Backend {
// Work out the relative URL for the combined files from the base folder // Work out the relative URL for the combined files from the base folder
$combinedFilesFolder = ($this->getCombinedFilesFolder()) ? ($this->getCombinedFilesFolder() . '/') : ''; $combinedFilesFolder = ($this->getCombinedFilesFolder()) ? ($this->getCombinedFilesFolder() . '/') : '';
// Figure out which ones apply to this pageview // Figure out which ones apply to this request
$combinedFiles = array(); $combinedFiles = array();
$newJSRequirements = array(); $newJSRequirements = array();
$newCSSRequirements = array(); $newCSSRequirements = array();
@ -1112,8 +1202,9 @@ class Requirements_Backend {
Filesystem::makeFolder(dirname($combinedFilePath)); Filesystem::makeFolder(dirname($combinedFilePath));
} }
// If the file isn't writeable, don't even bother trying to make the combined file and return (falls back // If the file isn't writeable, don't even bother trying to make the combined file and return. The
// to uncombined). Complex test because is_writable fails if the file doesn't exist yet. // files will be included individually instead. This is a complex test because is_writable fails
// if the file doesn't exist yet.
if((file_exists($combinedFilePath) && !is_writable($combinedFilePath)) if((file_exists($combinedFilePath) && !is_writable($combinedFilePath))
|| (!file_exists($combinedFilePath) && !is_writable(dirname($combinedFilePath))) || (!file_exists($combinedFilePath) && !is_writable(dirname($combinedFilePath)))
) { ) {
@ -1133,7 +1224,7 @@ class Requirements_Backend {
} }
$refresh = $srcLastMod > filemtime($combinedFilePath); $refresh = $srcLastMod > filemtime($combinedFilePath);
} else { } else {
// file doesn't exist, or refresh was explicitly required // File doesn't exist, or refresh was explicitly required
$refresh = true; $refresh = true;
} }
@ -1151,8 +1242,7 @@ class Requirements_Backend {
} }
if ($this->write_header_comment) { if ($this->write_header_comment) {
// write a header comment for each file for easier identification and debugging // Write a header comment for each file for easier identification and debugging. The semicolon between each file is required for jQuery to be combined properly and protects against unterminated statements.
// also the semicolon between each file is required for jQuery to be combinable properly
$combinedData .= "/****** FILE: $file *****/\n"; $combinedData .= "/****** FILE: $file *****/\n";
} }
@ -1168,7 +1258,7 @@ class Requirements_Backend {
} }
if($failedToMinify){ if($failedToMinify){
// Failed to minify, use unminified. This warning is raised at the end to allow code execution // Failed to minify, use unminified files instead. This warning is raised at the end to allow code execution
// to complete in case this warning is caught inside a try-catch block. // to complete in case this warning is caught inside a try-catch block.
user_error('Failed to minify '.$file.', exception: '.$e->getMessage(), E_USER_WARNING); user_error('Failed to minify '.$file.', exception: '.$e->getMessage(), E_USER_WARNING);
} }
@ -1181,12 +1271,19 @@ class Requirements_Backend {
} }
} }
// @todo Alters the original information, which means you can't call this // Note: Alters the original information, which means you can't call this method repeatedly - it will behave
// method repeatedly - it will behave different on the second call! // differently on the subsequent calls
$this->javascript = $newJSRequirements; $this->javascript = $newJSRequirements;
$this->css = $newCSSRequirements; $this->css = $newCSSRequirements;
} }
/**
* Minify the given $content according to the file type indicated in $filename
*
* @param string $filename
* @param string $content
* @return string
*/
protected function minifyFile($filename, $content) { protected function minifyFile($filename, $content) {
// if we have a javascript file and jsmin is enabled, minify the content // if we have a javascript file and jsmin is enabled, minify the content
$isJS = stripos($filename, '.js'); $isJS = stripos($filename, '.js');
@ -1200,20 +1297,18 @@ class Requirements_Backend {
return $content; return $content;
} }
public function get_custom_scripts() {
$requirements = "";
if($this->customScript) {
foreach($this->customScript as $script) {
$requirements .= "$script\n";
}
}
return $requirements;
}
/** /**
* @see Requirements::themedCSS() * 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.
*
* @param string $name The name of the file - eg '/css/File.css' would have the name 'File'
* @param string $module The module to fall back to if the css file does not exist in the
* current theme.
* @param string $media Comma-separated list of media types to use in the link tag
* (e.g. 'screen,projector')
*/ */
public function themedCSS($name, $module = null, $media = null) { public function themedCSS($name, $module = null, $media = null) {
$theme = SSViewer::get_theme_folder(); $theme = SSViewer::get_theme_folder();
@ -1234,6 +1329,9 @@ class Requirements_Backend {
} }
} }
/**
* Output debugging information.
*/
public function debug() { public function debug() {
Debug::show($this->javascript); Debug::show($this->javascript);
Debug::show($this->css); Debug::show($this->css);