summaryrefslogtreecommitdiff
path: root/app
diff options
context:
space:
mode:
authoremkael <emkael@tlen.pl>2016-05-03 21:05:07 +0200
committeremkael <emkael@tlen.pl>2016-05-03 21:05:07 +0200
commit663467b7dea1f068984b0863bd3eeaf3c54ca862 (patch)
tree156ad0a96232599ad204f451caaf2e9c389d8ef7 /app
parent2a2ec96ee56eec935301a9b2430e41bc2f6ef035 (diff)
* client script manager documentation
Diffstat (limited to 'app')
-rw-r--r--app/php/web/ClientScriptManager.php119
1 files changed, 87 insertions, 32 deletions
diff --git a/app/php/web/ClientScriptManager.php b/app/php/web/ClientScriptManager.php
index 1ebd8c3..64cfa76 100644
--- a/app/php/web/ClientScriptManager.php
+++ b/app/php/web/ClientScriptManager.php
@@ -10,10 +10,12 @@ class ClientScriptManager extends TClientScriptManager {
parent::__construct($page);
}
+ // Base path of the entire application
private function _getBasePath() {
return Prado::getPathOfNamespace('Web');
}
+ // Translate URLs to filesystem paths, index return array by URLs
private function _getBasePaths($urls) {
$basePath = $this->_getBasePath();
return array_combine(
@@ -27,6 +29,7 @@ class ClientScriptManager extends TClientScriptManager {
);
}
+ // Base cache path, suffixed with subdirectory, create on demand
private function _getCachePath($subdir = 'assets') {
$cachePath = $this->Application->RuntimePath
. DIRECTORY_SEPARATOR
@@ -46,12 +49,14 @@ class ClientScriptManager extends TClientScriptManager {
return $cachePath;
}
+ // Cache path for a file of specified type
private function _getCacheFilePath($path, $type) {
return $this->_getCachePath($type)
. DIRECTORY_SEPARATOR
. $path;
}
+ // Cache key for specific file set, including current theme
private function _getFileCollectionCacheKey($files) {
sort($files);
if ($this->_page->Theme) {
@@ -60,10 +65,13 @@ class ClientScriptManager extends TClientScriptManager {
return md5(implode(PHP_EOL, $files));
}
+ // Last modification time of a file set
private function _getFileCollectionMTime($files) {
return max(array_map('filemtime', $files));
}
+ // Storage (application cache) key for list of rendered assets of specified type
+ // Rendered[ASSET_TYPE].[VIEW_ID] (VIEW_ID as rendered in Layout hidden field)
private function _getRenderedAssetsStoreKey($type) {
$template = $this->_page->Master;
if (!$template instanceof Layout) {
@@ -74,14 +82,17 @@ class ClientScriptManager extends TClientScriptManager {
return sprintf('Rendered%s.%s', $type, $template->generateViewID());
}
+ // Shorthand for JS assets cache key
private function _getRenderedScriptsStoreKey() {
return $this->_getRenderedAssetsStoreKey('Scripts');
}
+ // Shorthand for CSS assets cache key
private function _getRenderedSheetsStoreKey() {
return $this->_getRenderedAssetsStoreKey('Sheets');
}
+ // Application (primary) cache module, required to keep track of assets rendered on current page
private function _getCache() {
$cache = $this->Application->Cache;
if (!$cache) {
@@ -92,26 +103,31 @@ class ClientScriptManager extends TClientScriptManager {
return $cache;
}
+ // Check cache file validity, comparing to source file set
private function _isCacheValid($cacheFile, $paths) {
return file_exists($cacheFile)
&& (filemtime($cacheFile) >= $this->_getFileCollectionMTime($paths));
}
+ // Determine whether specific URL points to a local asset (i.e. existing on the filesystem)
private function _isFileLocal($file) {
$basePath = $this->_getBasePath();
return file_exists($basePath . DIRECTORY_SEPARATOR . $file);
}
+ // Filter URL set to leave only local assets
private function _determineLocalFiles($files) {
return array_filter(
$files, [$this, '_isFileLocal']
);
}
- // Scripts
+ // Scripts - internal methods
private $_renderedScriptsInitialized = FALSE;
+ // Retrieve scripts already rendered on current page from application cache,
+ // maintaining the state over callbacks
private function _getRenderedScripts() {
$sessionKey = $this->_getRenderedScriptsStoreKey();
if ($this->_page->IsCallBack || $this->_renderedScriptsInitialized) {
@@ -123,6 +139,7 @@ class ClientScriptManager extends TClientScriptManager {
}
}
+ // Store information on rendered scripts in application cache
private function _appendRenderedScripts(array $newScripts, $compiledFileKey) {
$scripts = $this->_getRenderedScripts();
if (!isset($scripts[$compiledFileKey])) {
@@ -140,12 +157,14 @@ class ClientScriptManager extends TClientScriptManager {
);
}
+ // Compress JS file and return its content
private function _getCompressedScript($path) {
return trim(TJavaScript::JSMin(
file_get_contents($path)
));
}
+ // Join multiple script files into single asset, mark all of them as rendered in parent
private function _compileScriptFiles($files) {
foreach ($files as $file) {
$this->markScriptFileAsRendered($file);
@@ -169,6 +188,7 @@ class ClientScriptManager extends TClientScriptManager {
return $this->Application->AssetManager->publishFilePath($cacheFile);
}
+ // Write output tag for a single, compiled JS asset, consisting of multiple local assets
private function _renderLocalScriptFiles($writer, $localFiles) {
if ($localFiles) {
$assetPath = $this->_compileScriptFiles($localFiles);
@@ -176,6 +196,7 @@ class ClientScriptManager extends TClientScriptManager {
}
}
+ // Keep track of external JS scripts rendered on the page
private function _renderExternalScriptFiles($writer, $externalFiles) {
if ($externalFiles) {
foreach ($externalFiles as $file) {
@@ -186,19 +207,8 @@ class ClientScriptManager extends TClientScriptManager {
}
}
- public function renderScriptFiles($writer, Array $files) {
- if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
- if ($files) {
- $localFiles = $this->_determineLocalFiles($files);
- $this->_renderLocalScriptFiles($writer, $localFiles);
- $externalFiles = array_diff($files, $localFiles);
- $this->_renderExternalScriptFiles($writer, $externalFiles);
- }
- } else {
- parent::renderScriptFiles($writer, $files);
- }
- }
-
+ // Determine actual asset URL that a source JS file was rendered as (after compilation/compression)
+ // FALSE means script wasn't rendered at all (i.e. was just registered in current callback)
private function _getRenderedScriptUrl($registeredScript) {
$renderedScripts = $this->_getRenderedScripts();
foreach ($renderedScripts as $compiledFile => $scripts) {
@@ -215,6 +225,25 @@ class ClientScriptManager extends TClientScriptManager {
return FALSE;
}
+ // Scripts - public interface overrides
+
+ // In application modes "higher" than Debug, compile JS assets to as few files as possible
+ public function renderScriptFiles($writer, Array $files) {
+ if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
+ if ($files) {
+ $localFiles = $this->_determineLocalFiles($files);
+ $this->_renderLocalScriptFiles($writer, $localFiles);
+ $externalFiles = array_diff($files, $localFiles);
+ $this->_renderExternalScriptFiles($writer, $externalFiles);
+ }
+ } else {
+ parent::renderScriptFiles($writer, $files);
+ }
+ }
+
+ // When above compilation occurs, list of JS URLs a callback requires
+ // significantly deviates from parent implementation.
+ // Also, new scripts that have been registered in current callback may need compiling, too.
public function getScriptUrls() {
if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
$registeredScripts = array_unique(
@@ -250,20 +279,24 @@ class ClientScriptManager extends TClientScriptManager {
private $_scripts = [];
private $_headScripts = [];
+ // Keep track of what we're registering
public function registerScriptFile($key, $file) {
$this->_scripts[$key] = $file;
return parent::registerScriptFile($key, $file);
}
+ // Keep track of what we're registering
public function registerHeadScriptFile($key, $file) {
$this->_headScripts[$key] = $file;
return parent::registerHeadScriptFile($key, $file);
}
- // Stylesheets
+ // Stylesheets - internal methods
private $_renderedSheetsInitialized = FALSE;
+ // Retrieve stylesheets already rendered on current page from application cache,
+ // maintaining the state over callbacks
private function _getRenderedSheets() {
$sessionKey = $this->_getRenderedSheetsStoreKey();
if ($this->_page->IsCallBack || $this->_renderedSheetsInitialized) {
@@ -275,6 +308,7 @@ class ClientScriptManager extends TClientScriptManager {
}
}
+ // Store information on rendered stylesheets in application cache
private function _appendRenderedSheets(array $newSheets, $compiledFileKey) {
$sheets = $this->_getRenderedSheets();
if (!isset($sheets[$compiledFileKey])) {
@@ -309,6 +343,7 @@ class ClientScriptManager extends TClientScriptManager {
);
}
+ // Compress CSS file and return its content
private function _getCompressedSheet($origPath, $path) {
Prado::using('Lib.cssmin.CssMin');
return trim(CssMin::minify(
@@ -319,10 +354,12 @@ class ClientScriptManager extends TClientScriptManager {
));
}
+ // Join multiple stylesheet files into single asset
private function _compileSheetFiles($files) {
$paths = $this->_getBasePaths(
array_map('reset', $files)
);
+ // determine if file was registered as a themed sheet
$correctedPaths = [];
foreach ($paths as $url => $path) {
$correctedPaths[
@@ -348,6 +385,7 @@ class ClientScriptManager extends TClientScriptManager {
return $this->Application->AssetManager->publishFilePath($cacheFile);
}
+ // Filter only local stylesheet file entries
private function _determineLocalSheetFiles($files) {
$basePath = $this->_getBasePath();
return array_filter(
@@ -358,6 +396,7 @@ class ClientScriptManager extends TClientScriptManager {
);
}
+ // Write HTML markup for CSS stylesheet
private function _renderSheetFileTag(THtmlWriter $writer, $href, $media) {
$writer->addAttribute('rel', 'stylesheet');
$writer->addAttribute('type', 'text/css');
@@ -367,6 +406,7 @@ class ClientScriptManager extends TClientScriptManager {
$writer->write(PHP_EOL);
}
+ // Group registered local CSS assets by media query string and render markup for compiled sheets
private function _renderLocalSheetFiles(THtmlWriter $writer, $localFiles) {
if ($localFiles) {
$fileTypes = [];
@@ -384,6 +424,7 @@ class ClientScriptManager extends TClientScriptManager {
}
}
+ // Render markup for external stylesheets
private function _renderExternalSheetFiles(THtmlWriter $writer, $externalFiles) {
if ($externalFiles) {
foreach ($externalFiles as $file) {
@@ -393,20 +434,9 @@ class ClientScriptManager extends TClientScriptManager {
}
}
- public function renderStyleSheetFiles($writer) {
- if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
- $files = $this->_styles;
- if ($files) {
- $localFiles = $this->_determineLocalSheetFiles($files);
- $this->_renderLocalSheetFiles($writer, $localFiles);
- $externalFiles = array_diff_key($files, $localFiles);
- $this->_renderExternalSheetFiles($writer, $externalFiles);
- }
- } else {
- parent::renderStyleSheetFiles($writer);
- }
- }
-
+ // Determine actual asset URL that a source CSS file was rendered as (after compilation/compression)
+ // FALSE means sheet wasn't rendered at all (i.e. was just registered in current callback)
+ // Media query types can easily be ignored in a callback request, only URLs matter
private function _getRenderedSheetUrl($registeredSheet) {
$renderedSheets = $this->_getRenderedSheets();
foreach ($renderedSheets as $compiledFile => $sheets) {
@@ -425,6 +455,26 @@ class ClientScriptManager extends TClientScriptManager {
return FALSE;
}
+ // Stylesheets - public interface overrides
+
+ // In application modes "higher" than Debug, compile CSS assets to as few files as possible
+ public function renderStyleSheetFiles($writer) {
+ if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
+ $files = $this->_styles;
+ if ($files) {
+ $localFiles = $this->_determineLocalSheetFiles($files);
+ $this->_renderLocalSheetFiles($writer, $localFiles);
+ $externalFiles = array_diff_key($files, $localFiles);
+ $this->_renderExternalSheetFiles($writer, $externalFiles);
+ }
+ } else {
+ parent::renderStyleSheetFiles($writer);
+ }
+ }
+
+ // When above compilation occurs, list of CSS URLs a callback requires
+ // significantly deviates from parent implementation.
+ // New stylesheets may need compiling, as well.
public function getStyleSheetUrls() {
if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
$registeredSheets = $this->_styles;
@@ -457,9 +507,9 @@ class ClientScriptManager extends TClientScriptManager {
);
return $sheetUrls;
}
- // in Debug mode, theme sheets before fixing paths
+ // And even in Debug mode, theme sheets before fixing paths
// might also have been published via assets manager,
- // so we have to discard these from parent list
+ // so we have to discard these from parent list.
return array_diff(
parent::getStyleSheetUrls(),
$this->_fixedStyleFiles
@@ -467,15 +517,20 @@ class ClientScriptManager extends TClientScriptManager {
}
private $_styles = [];
- private $_themeStyles = [];
+ // Keep track of what we're registering
public function registerStyleSheetFile($key, $file, $media = '') {
$this->_styles[$key] = [$file, $media];
return parent::registerStyleSheetFile($key, $file, $media ?: 'all');
}
+ private $_themeStyles = [];
private $_fixedStyleFiles = [];
+ // New method, automatically corrects URLs within stylesheet to current page theme
+ // when sheets are not compiled (when they are, it's done on compilation anyways).
+ // Such files are rewritten (not in place, though) and registered so that they don't show up
+ // within published assets returned from asset manager, as they don't end up in the markup.
public function registerThemeStyleSheetFile($key, $file, $media = '') {
if ($this->getApplication()->getMode() !== TApplicationMode::Debug) {
$this->_themeStyles[$key] = $file;