sminnee /
silverstripe-framework
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like Requirements_Backend often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use Requirements_Backend, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 19 | class Requirements_Backend |
||
| 20 | { |
||
| 21 | use Injectable; |
||
| 22 | |||
| 23 | /** |
||
| 24 | * Whether to add caching query params to the requests for file-based requirements. |
||
| 25 | * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by |
||
| 26 | * filemtime. This has the benefit of allowing the browser to cache the URL infinitely, |
||
| 27 | * while automatically busting this cache every time the file is changed. |
||
| 28 | * |
||
| 29 | * @var bool |
||
| 30 | */ |
||
| 31 | protected $suffixRequirements = true; |
||
| 32 | |||
| 33 | /** |
||
| 34 | * Whether to combine CSS and JavaScript files |
||
| 35 | * |
||
| 36 | * @var bool |
||
| 37 | */ |
||
| 38 | protected $combinedFilesEnabled = true; |
||
| 39 | |||
| 40 | /** |
||
| 41 | * Determine if files should be combined automatically on dev mode. |
||
| 42 | * |
||
| 43 | * By default combined files will not be combined except in test or |
||
| 44 | * live environments. Turning this on will allow for pre-combining of files in development mode. |
||
| 45 | * |
||
| 46 | * @config |
||
| 47 | * @var bool |
||
| 48 | */ |
||
| 49 | private static $combine_in_dev = false; |
||
| 50 | |||
| 51 | /** |
||
| 52 | * Paths to all required JavaScript files relative to docroot |
||
| 53 | * |
||
| 54 | * @var array |
||
| 55 | */ |
||
| 56 | protected $javascript = array(); |
||
| 57 | |||
| 58 | /** |
||
| 59 | * Map of included scripts to array of contained files. |
||
| 60 | * To be used alongside front-end combination mechanisms. |
||
| 61 | * |
||
| 62 | * @var array Map of providing filepath => array(provided filepaths) |
||
| 63 | */ |
||
| 64 | protected $providedJavascript = array(); |
||
| 65 | |||
| 66 | /** |
||
| 67 | * Paths to all required CSS files relative to the docroot. |
||
| 68 | * |
||
| 69 | * @var array |
||
| 70 | */ |
||
| 71 | protected $css = array(); |
||
| 72 | |||
| 73 | /** |
||
| 74 | * All custom javascript code that is inserted into the page's HTML |
||
| 75 | * |
||
| 76 | * @var array |
||
| 77 | */ |
||
| 78 | protected $customScript = array(); |
||
| 79 | |||
| 80 | /** |
||
| 81 | * All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag |
||
| 82 | * |
||
| 83 | * @var array |
||
| 84 | */ |
||
| 85 | protected $customCSS = array(); |
||
| 86 | |||
| 87 | /** |
||
| 88 | * All custom HTML markup which is added before the closing <head> tag, e.g. additional |
||
| 89 | * metatags. |
||
| 90 | * |
||
| 91 | * @var array |
||
| 92 | */ |
||
| 93 | protected $customHeadTags = array(); |
||
| 94 | |||
| 95 | /** |
||
| 96 | * Remembers the file paths or uniquenessIDs of all Requirements cleared through |
||
| 97 | * {@link clear()}, so that they can be restored later. |
||
| 98 | * |
||
| 99 | * @var array |
||
| 100 | */ |
||
| 101 | protected $disabled = array(); |
||
| 102 | |||
| 103 | /** |
||
| 104 | * The file paths (relative to docroot) or uniquenessIDs of any included requirements which |
||
| 105 | * should be blocked when executing {@link inlcudeInHTML()}. This is useful, for example, |
||
| 106 | * to block scripts included by a superclass without having to override entire functions and |
||
| 107 | * duplicate a lot of code. |
||
| 108 | * |
||
| 109 | * Use {@link unblock()} or {@link unblock_all()} to revert changes. |
||
| 110 | * |
||
| 111 | * @var array |
||
| 112 | */ |
||
| 113 | protected $blocked = array(); |
||
| 114 | |||
| 115 | /** |
||
| 116 | * A list of combined files registered via {@link combine_files()}. Keys are the output file |
||
| 117 | * names, values are lists of input files. |
||
| 118 | * |
||
| 119 | * @var array |
||
| 120 | */ |
||
| 121 | protected $combinedFiles = array(); |
||
| 122 | |||
| 123 | /** |
||
| 124 | * Use the JSMin library to minify any javascript file passed to {@link combine_files()}. |
||
| 125 | * |
||
| 126 | * @var bool |
||
| 127 | */ |
||
| 128 | protected $minifyCombinedJSFiles = true; |
||
| 129 | |||
| 130 | /** |
||
| 131 | * Whether or not file headers should be written when combining files |
||
| 132 | * |
||
| 133 | * @var boolean |
||
| 134 | */ |
||
| 135 | protected $writeHeaderComment = true; |
||
| 136 | |||
| 137 | /** |
||
| 138 | * Where to save combined files. By default they're placed in assets/_combinedfiles, however |
||
| 139 | * this may be an issue depending on your setup, especially for CSS files which often contain |
||
| 140 | * relative paths. |
||
| 141 | * |
||
| 142 | * @var string |
||
| 143 | */ |
||
| 144 | protected $combinedFilesFolder = null; |
||
| 145 | |||
| 146 | /** |
||
| 147 | * Put all JavaScript includes at the bottom of the template before the closing <body> tag, |
||
| 148 | * rather than the default behaviour of placing them at the end of the <head> tag. This means |
||
| 149 | * script downloads won't block other HTTP requests, which can be a performance improvement. |
||
| 150 | * |
||
| 151 | * @var bool |
||
| 152 | */ |
||
| 153 | public $writeJavascriptToBody = true; |
||
| 154 | |||
| 155 | /** |
||
| 156 | * Force the JavaScript to the bottom of the page, even if there's a script tag in the body already |
||
| 157 | * |
||
| 158 | * @var boolean |
||
| 159 | */ |
||
| 160 | protected $forceJSToBottom = false; |
||
| 161 | |||
| 162 | /** |
||
| 163 | * Configures the default prefix for combined files. |
||
| 164 | * |
||
| 165 | * This defaults to `_combinedfiles`, and is the folder within the configured asset backend that |
||
| 166 | * combined files will be stored in. If using a backend shared with other systems, it is usually |
||
| 167 | * necessary to distinguish combined files from other assets. |
||
| 168 | * |
||
| 169 | * @config |
||
| 170 | * @var string |
||
| 171 | */ |
||
| 172 | private static $default_combined_files_folder = '_combinedfiles'; |
||
| 173 | |||
| 174 | /** |
||
| 175 | * Flag to include the hash in the querystring instead of the filename for combined files. |
||
| 176 | * |
||
| 177 | * By default the `<hash>` of the source files is appended to the end of the combined file |
||
| 178 | * (prior to the file extension). If combined files are versioned in source control or running |
||
| 179 | * in a distributed environment (such as one where the newest version of a file may not always be |
||
| 180 | * immediately available) then it may sometimes be necessary to disable this. When this is set to true, |
||
| 181 | * the hash will instead be appended via a querystring parameter to enable cache busting, but not in |
||
| 182 | * the filename itself. I.e. `assets/_combinedfiles/name.js?m=<hash>` |
||
| 183 | * |
||
| 184 | * @config |
||
| 185 | * @var bool |
||
| 186 | */ |
||
| 187 | private static $combine_hash_querystring = false; |
||
| 188 | |||
| 189 | /** |
||
| 190 | * @var GeneratedAssetHandler |
||
| 191 | */ |
||
| 192 | protected $assetHandler = null; |
||
| 193 | |||
| 194 | /** |
||
| 195 | * Gets the backend storage for generated files |
||
| 196 | * |
||
| 197 | * @return GeneratedAssetHandler |
||
| 198 | */ |
||
| 199 | public function getAssetHandler() |
||
| 203 | |||
| 204 | /** |
||
| 205 | * Set a new asset handler for this backend |
||
| 206 | * |
||
| 207 | * @param GeneratedAssetHandler $handler |
||
| 208 | */ |
||
| 209 | public function setAssetHandler(GeneratedAssetHandler $handler) |
||
| 213 | |||
| 214 | /** |
||
| 215 | * Enable or disable the combination of CSS and JavaScript files |
||
| 216 | * |
||
| 217 | * @param bool $enable |
||
| 218 | */ |
||
| 219 | public function setCombinedFilesEnabled($enable) |
||
| 223 | |||
| 224 | /** |
||
| 225 | * Check if header comments are written |
||
| 226 | * |
||
| 227 | * @return bool |
||
| 228 | */ |
||
| 229 | public function getWriteHeaderComment() |
||
| 233 | |||
| 234 | /** |
||
| 235 | * Flag whether header comments should be written for each combined file |
||
| 236 | * |
||
| 237 | * @param bool $write |
||
| 238 | * @return $this |
||
| 239 | */ |
||
| 240 | public function setWriteHeaderComment($write) |
||
| 245 | |||
| 246 | /** |
||
| 247 | * Set the folder to save combined files in. By default they're placed in _combinedfiles, |
||
| 248 | * however this may be an issue depending on your setup, especially for CSS files which often |
||
| 249 | * contain relative paths. |
||
| 250 | * |
||
| 251 | * This must not include any 'assets' prefix |
||
| 252 | * |
||
| 253 | * @param string $folder |
||
| 254 | */ |
||
| 255 | public function setCombinedFilesFolder($folder) |
||
| 259 | |||
| 260 | /** |
||
| 261 | * Retrieve the combined files folder prefix |
||
| 262 | * |
||
| 263 | * @return string |
||
| 264 | */ |
||
| 265 | public function getCombinedFilesFolder() |
||
| 272 | |||
| 273 | /** |
||
| 274 | * Set whether to add caching query params to the requests for file-based requirements. |
||
| 275 | * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by |
||
| 276 | * filemtime. This has the benefit of allowing the browser to cache the URL infinitely, |
||
| 277 | * while automatically busting this cache every time the file is changed. |
||
| 278 | * |
||
| 279 | * @param bool |
||
| 280 | */ |
||
| 281 | public function setSuffixRequirements($var) |
||
| 285 | |||
| 286 | /** |
||
| 287 | * Check whether we want to suffix requirements |
||
| 288 | * |
||
| 289 | * @return bool |
||
| 290 | */ |
||
| 291 | public function getSuffixRequirements() |
||
| 295 | |||
| 296 | /** |
||
| 297 | * Set whether you want to write the JS to the body of the page rather than at the end of the |
||
| 298 | * head tag. |
||
| 299 | * |
||
| 300 | * @param bool |
||
| 301 | * @return $this |
||
| 302 | */ |
||
| 303 | public function setWriteJavascriptToBody($var) |
||
| 308 | |||
| 309 | /** |
||
| 310 | * Check whether you want to write the JS to the body of the page rather than at the end of the |
||
| 311 | * head tag. |
||
| 312 | * |
||
| 313 | * @return bool |
||
| 314 | */ |
||
| 315 | public function getWriteJavascriptToBody() |
||
| 319 | |||
| 320 | /** |
||
| 321 | * Forces the JavaScript requirements to the end of the body, right before the closing tag |
||
| 322 | * |
||
| 323 | * @param bool |
||
| 324 | * @return $this |
||
| 325 | */ |
||
| 326 | public function setForceJSToBottom($var) |
||
| 331 | |||
| 332 | /** |
||
| 333 | * Check if the JavaScript requirements are written to the end of the body, right before the closing tag |
||
| 334 | * |
||
| 335 | * @return bool |
||
| 336 | */ |
||
| 337 | public function getForceJSToBottom() |
||
| 341 | |||
| 342 | /** |
||
| 343 | * Check if minify js files should be combined |
||
| 344 | * |
||
| 345 | * @return bool |
||
| 346 | */ |
||
| 347 | public function getMinifyCombinedJSFiles() |
||
| 351 | |||
| 352 | /** |
||
| 353 | * Set if combined js files should be minified |
||
| 354 | * |
||
| 355 | * @param bool $minify |
||
| 356 | * @return $this |
||
| 357 | */ |
||
| 358 | public function setMinifyCombinedJSFiles($minify) |
||
| 363 | |||
| 364 | /** |
||
| 365 | * Register the given JavaScript file as required. |
||
| 366 | * |
||
| 367 | * @param string $file Relative to docroot |
||
| 368 | * @param array $options List of options. Available options include: |
||
| 369 | * - 'provides' : List of scripts files included in this file |
||
| 370 | * - 'async' : Boolean value to set async attribute to script tag |
||
| 371 | * - 'defer' : Boolean value to set defer attribute to script tag |
||
| 372 | * - 'type' : Override script type= value. |
||
| 373 | */ |
||
| 374 | public function javascript($file, $options = array()) |
||
| 414 | |||
| 415 | /** |
||
| 416 | * Remove a javascript requirement |
||
| 417 | * |
||
| 418 | * @param string $file |
||
| 419 | */ |
||
| 420 | protected function unsetJavascript($file) |
||
| 424 | |||
| 425 | /** |
||
| 426 | * Gets all scripts that are already provided by prior scripts. |
||
| 427 | * This follows these rules: |
||
| 428 | * - Files will not be considered provided if they are separately |
||
| 429 | * included prior to the providing file. |
||
| 430 | * - Providing files can be blocked, and don't provide anything |
||
| 431 | * - Provided files can't be blocked (you need to block the provider) |
||
| 432 | * - If a combined file includes files that are provided by prior |
||
| 433 | * scripts, then these should be excluded from the combined file. |
||
| 434 | * - If a combined file includes files that are provided by later |
||
| 435 | * scripts, then these files should be included in the combined |
||
| 436 | * file, but we can't block the later script either (possible double |
||
| 437 | * up of file). |
||
| 438 | * |
||
| 439 | * @return array Array of provided files (map of $path => $path) |
||
| 440 | */ |
||
| 441 | public function getProvidedScripts() |
||
| 465 | |||
| 466 | /** |
||
| 467 | * Returns an array of required JavaScript, excluding blocked |
||
| 468 | * and duplicates of provided files. |
||
| 469 | * |
||
| 470 | * @return array |
||
| 471 | */ |
||
| 472 | public function getJavascript() |
||
| 480 | |||
| 481 | /** |
||
| 482 | * Gets all javascript, including blocked files. Unwraps the array into a non-associative list |
||
| 483 | * |
||
| 484 | * @return array Indexed array of javascript files |
||
| 485 | */ |
||
| 486 | protected function getAllJavascript() |
||
| 490 | |||
| 491 | /** |
||
| 492 | * Register the given JavaScript code into the list of requirements |
||
| 493 | * |
||
| 494 | * @param string $script The script content as a string (without enclosing <script> tag) |
||
| 495 | * @param string $uniquenessID A unique ID that ensures a piece of code is only added once |
||
| 496 | */ |
||
| 497 | public function customScript($script, $uniquenessID = null) |
||
| 505 | |||
| 506 | /** |
||
| 507 | * Return all registered custom scripts |
||
| 508 | * |
||
| 509 | * @return array |
||
| 510 | */ |
||
| 511 | public function getCustomScripts() |
||
| 515 | |||
| 516 | /** |
||
| 517 | * Register the given CSS styles into the list of requirements |
||
| 518 | * |
||
| 519 | * @param string $script CSS selectors as a string (without enclosing <style> tag) |
||
| 520 | * @param string $uniquenessID A unique ID that ensures a piece of code is only added once |
||
| 521 | */ |
||
| 522 | public function customCSS($script, $uniquenessID = null) |
||
| 530 | |||
| 531 | /** |
||
| 532 | * Return all registered custom CSS |
||
| 533 | * |
||
| 534 | * @return array |
||
| 535 | */ |
||
| 536 | public function getCustomCSS() |
||
| 540 | |||
| 541 | /** |
||
| 542 | * Add the following custom HTML code to the <head> section of the page |
||
| 543 | * |
||
| 544 | * @param string $html Custom HTML code |
||
| 545 | * @param string $uniquenessID A unique ID that ensures a piece of code is only added once |
||
| 546 | */ |
||
| 547 | public function insertHeadTags($html, $uniquenessID = null) |
||
| 555 | |||
| 556 | /** |
||
| 557 | * Return all custom head tags |
||
| 558 | * |
||
| 559 | * @return array |
||
| 560 | */ |
||
| 561 | public function getCustomHeadTags() |
||
| 565 | |||
| 566 | /** |
||
| 567 | * Include the content of the given JavaScript file in the list of requirements. Dollar-sign |
||
| 568 | * variables will be interpolated with values from $vars similar to a .ss template. |
||
| 569 | * |
||
| 570 | * @param string $file The template file to load, relative to docroot |
||
| 571 | * @param string[] $vars The array of variables to interpolate. |
||
| 572 | * @param string $uniquenessID A unique ID that ensures a piece of code is only added once |
||
| 573 | */ |
||
| 574 | public function javascriptTemplate($file, $vars, $uniquenessID = null) |
||
| 590 | |||
| 591 | /** |
||
| 592 | * Register the given stylesheet into the list of requirements. |
||
| 593 | * |
||
| 594 | * @param string $file The CSS file to load, relative to site root |
||
| 595 | * @param string $media Comma-separated list of media types to use in the link tag |
||
| 596 | * (e.g. 'screen,projector') |
||
| 597 | */ |
||
| 598 | public function css($file, $media = null) |
||
| 604 | |||
| 605 | /** |
||
| 606 | * Remove a css requirement |
||
| 607 | * |
||
| 608 | * @param string $file |
||
| 609 | */ |
||
| 610 | protected function unsetCSS($file) |
||
| 614 | |||
| 615 | /** |
||
| 616 | * Get the list of registered CSS file requirements, excluding blocked files |
||
| 617 | * |
||
| 618 | * @return array Associative array of file to spec |
||
| 619 | */ |
||
| 620 | public function getCSS() |
||
| 624 | |||
| 625 | /** |
||
| 626 | * Gets all CSS files requirements, including blocked |
||
| 627 | * |
||
| 628 | * @return array Associative array of file to spec |
||
| 629 | */ |
||
| 630 | protected function getAllCSS() |
||
| 634 | |||
| 635 | /** |
||
| 636 | * Gets the list of all blocked files |
||
| 637 | * |
||
| 638 | * @return array |
||
| 639 | */ |
||
| 640 | public function getBlocked() |
||
| 644 | |||
| 645 | /** |
||
| 646 | * Clear either a single or all requirements |
||
| 647 | * |
||
| 648 | * Caution: Clearing single rules added via customCSS and customScript only works if you |
||
| 649 | * originally specified a $uniquenessID. |
||
| 650 | * |
||
| 651 | * @param string|int $fileOrID |
||
| 652 | */ |
||
| 653 | public function clear($fileOrID = null) |
||
| 676 | |||
| 677 | /** |
||
| 678 | * Restore requirements cleared by call to Requirements::clear |
||
| 679 | */ |
||
| 680 | public function restore() |
||
| 688 | |||
| 689 | /** |
||
| 690 | * Block inclusion of a specific file |
||
| 691 | * |
||
| 692 | * The difference between this and {@link clear} is that the calling order does not matter; |
||
| 693 | * {@link clear} must be called after the initial registration, whereas {@link block} can be |
||
| 694 | * used in advance. This is useful, for example, to block scripts included by a superclass |
||
| 695 | * without having to override entire functions and duplicate a lot of code. |
||
| 696 | * |
||
| 697 | * Note that blocking should be used sparingly because it's hard to trace where an file is |
||
| 698 | * being blocked from. |
||
| 699 | * |
||
| 700 | * @param string|int $fileOrID |
||
| 701 | */ |
||
| 702 | public function block($fileOrID) |
||
| 706 | |||
| 707 | /** |
||
| 708 | * Remove an item from the block list |
||
| 709 | * |
||
| 710 | * @param string|int $fileOrID |
||
| 711 | */ |
||
| 712 | public function unblock($fileOrID) |
||
| 716 | |||
| 717 | /** |
||
| 718 | * Removes all items from the block list |
||
| 719 | */ |
||
| 720 | public function unblockAll() |
||
| 724 | |||
| 725 | /** |
||
| 726 | * Update the given HTML content with the appropriate include tags for the registered |
||
| 727 | * requirements. Needs to receive a valid HTML/XHTML template in the $content parameter, |
||
| 728 | * including a head and body tag. |
||
| 729 | * |
||
| 730 | * @param string $content HTML content that has already been parsed from the $templateFile |
||
| 731 | * through {@link SSViewer} |
||
| 732 | * @return string HTML content augmented with the requirements tags |
||
| 733 | */ |
||
| 734 | public function includeInHTML($content) |
||
| 803 | |||
| 804 | /** |
||
| 805 | * Given a block of HTML, insert the given scripts at the bottom before |
||
| 806 | * the closing </body> tag |
||
| 807 | * |
||
| 808 | * @param string $jsRequirements String containing one or more javascript <script /> tags |
||
| 809 | * @param string $content HTML body |
||
| 810 | * @return string Merged HTML |
||
| 811 | */ |
||
| 812 | protected function insertScriptsAtBottom($jsRequirements, $content) |
||
| 823 | |||
| 824 | /** |
||
| 825 | * Given a block of HTML, insert the given scripts inside the <body></body> |
||
| 826 | * |
||
| 827 | * @param string $jsRequirements String containing one or more javascript <script /> tags |
||
| 828 | * @param string $content HTML body |
||
| 829 | * @return string Merged HTML |
||
| 830 | */ |
||
| 831 | protected function insertScriptsIntoBody($jsRequirements, $content) |
||
| 860 | |||
| 861 | /** |
||
| 862 | * Given a block of HTML, insert the given code inside the <head></head> block |
||
| 863 | * |
||
| 864 | * @param string $jsRequirements String containing one or more html tags |
||
| 865 | * @param string $content HTML body |
||
| 866 | * @return string Merged HTML |
||
| 867 | */ |
||
| 868 | protected function insertTagsIntoHead($jsRequirements, $content) |
||
| 877 | |||
| 878 | /** |
||
| 879 | * Safely escape a literal string for use in preg_replace replacement |
||
| 880 | * |
||
| 881 | * @param string $replacement |
||
| 882 | * @return string |
||
| 883 | */ |
||
| 884 | protected function escapeReplacement($replacement) |
||
| 888 | |||
| 889 | /** |
||
| 890 | * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given |
||
| 891 | * HTTP Response |
||
| 892 | * |
||
| 893 | * @param HTTPResponse $response |
||
| 894 | */ |
||
| 895 | public function includeInResponse(HTTPResponse $response) |
||
| 924 | |||
| 925 | /** |
||
| 926 | * Add i18n files from the given javascript directory. SilverStripe expects that the given |
||
| 927 | * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js, |
||
| 928 | * etc. |
||
| 929 | * |
||
| 930 | * @param string $langDir The JavaScript lang directory, relative to the site root, e.g., |
||
| 931 | * 'framework/javascript/lang' |
||
| 932 | * @param bool $return Return all relative file paths rather than including them in |
||
| 933 | * requirements |
||
| 934 | * |
||
| 935 | * @return array|null All relative files if $return is true, or null otherwise |
||
| 936 | */ |
||
| 937 | public function add_i18n_javascript($langDir, $return = false) |
||
| 969 | |||
| 970 | /** |
||
| 971 | * Finds the path for specified file |
||
| 972 | * |
||
| 973 | * @param string $fileOrUrl |
||
| 974 | * @return string|bool |
||
| 975 | */ |
||
| 976 | protected function pathForFile($fileOrUrl) |
||
| 1004 | |||
| 1005 | /** |
||
| 1006 | * Concatenate several css or javascript files into a single dynamically generated file. This |
||
| 1007 | * increases performance by fewer HTTP requests. |
||
| 1008 | * |
||
| 1009 | * The combined file is regenerated based on every file modification time. Optionally a |
||
| 1010 | * rebuild can be triggered by appending ?flush=1 to the URL. |
||
| 1011 | * |
||
| 1012 | * All combined files will have a comment on the start of each concatenated file denoting their |
||
| 1013 | * original position. |
||
| 1014 | * |
||
| 1015 | * CAUTION: You're responsible for ensuring that the load order for combined files is |
||
| 1016 | * retained - otherwise combining JavaScript files can lead to functional errors in the |
||
| 1017 | * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also |
||
| 1018 | * only include each file once across all includes and combinations in a single page load. |
||
| 1019 | * |
||
| 1020 | * CAUTION: Combining CSS Files discards any "media" information. |
||
| 1021 | * |
||
| 1022 | * Example for combined JavaScript: |
||
| 1023 | * <code> |
||
| 1024 | * Requirements::combine_files( |
||
| 1025 | * 'foobar.js', |
||
| 1026 | * array( |
||
| 1027 | * 'mysite/javascript/foo.js', |
||
| 1028 | * 'mysite/javascript/bar.js', |
||
| 1029 | * ), |
||
| 1030 | * array( |
||
| 1031 | * 'async' => true, |
||
| 1032 | * 'defer' => true, |
||
| 1033 | * ) |
||
| 1034 | * ); |
||
| 1035 | * </code> |
||
| 1036 | * |
||
| 1037 | * Example for combined CSS: |
||
| 1038 | * <code> |
||
| 1039 | * Requirements::combine_files( |
||
| 1040 | * 'foobar.css', |
||
| 1041 | * array( |
||
| 1042 | * 'mysite/javascript/foo.css', |
||
| 1043 | * 'mysite/javascript/bar.css', |
||
| 1044 | * ), |
||
| 1045 | * array( |
||
| 1046 | * 'media' => 'print', |
||
| 1047 | * ) |
||
| 1048 | * ); |
||
| 1049 | * </code> |
||
| 1050 | * |
||
| 1051 | * @param string $combinedFileName Filename of the combined file relative to docroot |
||
| 1052 | * @param array $files Array of filenames relative to docroot |
||
| 1053 | * @param array $options Array of options for combining files. Available options are: |
||
| 1054 | * - 'media' : If including CSS Files, you can specify a media type |
||
| 1055 | * - 'async' : If including JavaScript Files, boolean value to set async attribute to script tag |
||
| 1056 | * - 'defer' : If including JavaScript Files, boolean value to set defer attribute to script tag |
||
| 1057 | */ |
||
| 1058 | public function combineFiles($combinedFileName, $files, $options = array()) |
||
| 1116 | |||
| 1117 | /** |
||
| 1118 | * Return path and type of given combined file |
||
| 1119 | * |
||
| 1120 | * @param string|array $file Either a file path, or an array spec |
||
| 1121 | * @return array array with two elements, path and type of file |
||
| 1122 | */ |
||
| 1123 | protected function parseCombinedFile($file) |
||
| 1147 | |||
| 1148 | /** |
||
| 1149 | * Return all combined files; keys are the combined file names, values are lists of |
||
| 1150 | * associative arrays with 'files', 'type', and 'media' keys for details about this |
||
| 1151 | * combined file. |
||
| 1152 | * |
||
| 1153 | * @return array |
||
| 1154 | */ |
||
| 1155 | public function getCombinedFiles() |
||
| 1159 | |||
| 1160 | /** |
||
| 1161 | * Includes all combined files, including blocked ones |
||
| 1162 | * |
||
| 1163 | * @return array |
||
| 1164 | */ |
||
| 1165 | protected function getAllCombinedFiles() |
||
| 1169 | |||
| 1170 | /** |
||
| 1171 | * Clears all combined files |
||
| 1172 | */ |
||
| 1173 | public function deleteAllCombinedFiles() |
||
| 1180 | |||
| 1181 | /** |
||
| 1182 | * Clear all registered CSS and JavaScript file combinations |
||
| 1183 | */ |
||
| 1184 | public function clearCombinedFiles() |
||
| 1188 | |||
| 1189 | /** |
||
| 1190 | * Do the heavy lifting involved in combining the combined files. |
||
| 1191 | */ |
||
| 1192 | public function processCombinedFiles() |
||
| 1258 | |||
| 1259 | /** |
||
| 1260 | * Given a set of files, combine them (as necessary) and return the url |
||
| 1261 | * |
||
| 1262 | * @param string $combinedFile Filename for this combined file |
||
| 1263 | * @param array $fileList List of files to combine |
||
| 1264 | * @param string $type Either 'js' or 'css' |
||
| 1265 | * @return string|null URL to this resource, if there are files to combine |
||
| 1266 | */ |
||
| 1267 | protected function getCombinedFileURL($combinedFile, $fileList, $type) |
||
| 1319 | |||
| 1320 | /** |
||
| 1321 | * Given a filename and list of files, generate a new filename unique to these files |
||
| 1322 | * |
||
| 1323 | * @param string $combinedFile |
||
| 1324 | * @param array $fileList |
||
| 1325 | * @return string |
||
| 1326 | */ |
||
| 1327 | protected function hashedCombinedFilename($combinedFile, $fileList) |
||
| 1334 | |||
| 1335 | /** |
||
| 1336 | * Check if combined files are enabled |
||
| 1337 | * |
||
| 1338 | * @return bool |
||
| 1339 | */ |
||
| 1340 | public function getCombinedFilesEnabled() |
||
| 1364 | |||
| 1365 | /** |
||
| 1366 | * For a given filelist, determine some discriminating value to determine if |
||
| 1367 | * any of these files have changed. |
||
| 1368 | * |
||
| 1369 | * @param array $fileList List of files |
||
| 1370 | * @return string SHA1 bashed file hash |
||
| 1371 | */ |
||
| 1372 | protected function hashOfFiles($fileList) |
||
| 1386 | |||
| 1387 | /** |
||
| 1388 | * Registers the given themeable stylesheet as required. |
||
| 1389 | * |
||
| 1390 | * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for, |
||
| 1391 | * and it that doesn't exist and the module parameter is set then a CSS file with that name in |
||
| 1392 | * the module is used. |
||
| 1393 | * |
||
| 1394 | * @param string $name The name of the file - eg '/css/File.css' would have the name 'File' |
||
| 1395 | * @param string $media Comma-separated list of media types to use in the link tag |
||
| 1396 | * (e.g. 'screen,projector') |
||
| 1397 | */ |
||
| 1398 | public function themedCSS($name, $media = null) |
||
| 1410 | |||
| 1411 | /** |
||
| 1412 | * Registers the given themeable javascript as required. |
||
| 1413 | * |
||
| 1414 | * A javascript file in the current theme path name 'themename/javascript/$name.js' is first searched for, |
||
| 1415 | * and it that doesn't exist and the module parameter is set then a javascript file with that name in |
||
| 1416 | * the module is used. |
||
| 1417 | * |
||
| 1418 | * @param string $name The name of the file - eg '/js/File.js' would have the name 'File' |
||
| 1419 | * @param string $type Comma-separated list of types to use in the script tag |
||
| 1420 | * (e.g. 'text/javascript,text/ecmascript') |
||
| 1421 | */ |
||
| 1422 | public function themedJavascript($name, $type = null) |
||
| 1438 | |||
| 1439 | /** |
||
| 1440 | * Output debugging information. |
||
| 1441 | */ |
||
| 1442 | public function debug() |
||
| 1451 | |||
| 1452 | } |
||
| 1453 |
Loading history...
When comparing two booleans, it is generally considered safer to use the strict comparison operator.