|
Perforce Chronicle 2012.2/486814
API Documentation
|
Themes and modules are 'packages'. More...
Public Member Functions | |
| getBaseUrl () | |
| Get the url to this package folder. | |
| getDescription () | |
| Get the description of this package from the package info file. | |
| getDojoModules () | |
| Get all dojo modules that are defined by this module. | |
| getDojoOnLoads () | |
| Get dojo 'addOnLoad' entries for this package. | |
| getHtmlMeta () | |
| Get meta listed in the package file in a format suitable for passing to Zend's headMeta helper. | |
| getIconUrl () | |
| Get the URI to the package icon file. | |
| getId () | |
| Return the name of this package as the id. | |
| getLabel () | |
| Get a friendly label for this package. | |
| getMaintainerInfo ($field=null) | |
| Get information about the maintainer of this package if available. | |
| getMenus () | |
| Get any menus configured for this module. | |
| getName () | |
| Get the name of this package. | |
| getPackageInfo ($key=null) | |
| Get the package configuration by parsing the package file. | |
| getPath () | |
| Get the path to this package. | |
| getScripts () | |
| Get scripts listed in the package file in a format suitable for passing to the headScript helper. | |
| getStylesheets () | |
| Get stylesheets listed in the package file in a format suitable for passing to Zend's headLink helper. | |
| getTags () | |
| Get tags listed in the package file. | |
| getVersion () | |
| Get the version of this package from the package info file. | |
| getWidgetConfig () | |
| Get the widget configuration defined by the package (grouped by region). | |
| hasIcon () | |
| Determine if there is an icon for this package. | |
| populate () | |
| Read in relevant data for this package. | |
| setPath ($path) | |
| Set the full path to the package folder. | |
Static Public Member Functions | |
| static | addPackagesPath ($path) |
| Add a path to the set of paths from which packages (of this class type) can be sourced. | |
| static | clearCache () |
| Clear the cached list of packages. | |
| static | clearPackagesPaths () |
| Clear the set of paths from which packages can be sourced. | |
| static | exists ($name) |
| Determine if a package with the given name exists. | |
| static | fetch ($name) |
| Fetch a single package by name from the set of packages. | |
| static | fetchAll () |
| Get all packages (of this class type) available to the system. | |
| static | getDocumentRoot () |
| Get the file-system path to the document root. | |
| static | getPackagesPaths () |
| Get the set of paths from which packages (of this class type) can be sourced. | |
| static | getView () |
| Get current view object from the view renderer. | |
| static | getViewRenderer () |
| Get the P4CMS (theme-aware) view renderer - load it if necessary. | |
| static | setDocumentRoot ($path) |
| Set the file-system path to the document root. | |
| static | setPackagesPaths ($paths) |
| Set the set of paths from which packages (of this class type) can be sourced. | |
Public Attributes | |
| const | PACKAGE_FILENAME = 'package.ini' |
Protected Member Functions | |
| _loadDojo () | |
| Takes care of the 'dojo' section of package config including requires, provides and onLoad. | |
| _loadHtmlMeta () | |
| Load the meta tags in this package into the view headMeta helper. | |
| _loadScripts () | |
| Load the scripts in this package into the view headScript helper. | |
| _loadStylesheets () | |
| Load the stylesheets in this package into the view headLink helper. | |
| _passesAcl ($acl) | |
| Checks whether a dojo module should be loaded based on the resource privileges If any resource or privilege matches, the user needs this dojo module. | |
Static Protected Member Functions | |
| static | _getCacheId () |
| Get cache id for this class constructed from the called class name and a serialized set of packages source paths. | |
Protected Attributes | |
| $_dojoModules = null | |
| $_packageInfo = null | |
| $_path = null | |
Static Protected Attributes | |
| static | $_documentRoot = null |
| static | $_packagesPaths = array() |
Themes and modules are 'packages'.
Themes and modules have some shared functionality and this class exists to avoid duplicating code.
| static P4Cms_PackageAbstract::_getCacheId | ( | ) | [static, protected] |
Get cache id for this class constructed from the called class name and a serialized set of packages source paths.
We also include the user's roles as the applicable dojo modules depend on the user's permissions.
{
$packagesPaths = array_unique(static::getPackagesPaths());
sort($packagesPaths);
$roles = P4Cms_User::hasActive()
? P4Cms_User::fetchActive()->getRoles()->invoke('getId')
: array();
return get_called_class() . md5(serialize(array($packagesPaths, $roles)));
}
| P4Cms_PackageAbstract::_loadDojo | ( | ) | [protected] |
Takes care of the 'dojo' section of package config including requires, provides and onLoad.
{
// enable dojo view helper.
$view = $this->getView();
Zend_Dojo::enableView($view);
// load defined dojo modules
$dojoModules = $this->getDojoModules();
foreach ($dojoModules as $module) {
// always register every module path
$view->dojo()->registerModulePath($module['namespace'], $module['path']);
// require modules that pass acl
if ($module['allowed']) {
$view->dojo()->requireModule($module['namespace']);
}
}
// deal with addOnLoad
foreach ($this->getDojoOnLoads() as $onLoad) {
$view->dojo()->addOnLoad($onLoad);
}
}
| P4Cms_PackageAbstract::_loadHtmlMeta | ( | ) | [protected] |
Load the meta tags in this package into the view headMeta helper.
{
$view = $this->getView();
foreach ($this->getHtmlMeta() as $meta) {
switch ($meta['type']) {
case 'httpEquiv':
$view->headMeta()->setHttpEquiv($meta['field'], $meta['content']);
break;
case 'name':
$view->headMeta()->setName($meta['field'], $meta['content']);
break;
}
}
}
| P4Cms_PackageAbstract::_loadScripts | ( | ) | [protected] |
Load the scripts in this package into the view headScript helper.
{
$view = $this->getView();
foreach ($this->getScripts() as $script) {
$view->headScript()->appendFile($script['src'], $script['type'], $script['attrs']);
}
}
| P4Cms_PackageAbstract::_loadStylesheets | ( | ) | [protected] |
Load the stylesheets in this package into the view headLink helper.
{
$view = $this->getView();
foreach ($this->getStylesheets() as $stylesheet) {
$view->headLink()->appendStylesheet(
$stylesheet['href'],
$stylesheet['media'],
$stylesheet['conditional'],
array('buildGroup' => 'packages')
);
}
}
| P4Cms_PackageAbstract::_passesAcl | ( | $ | acl | ) | [protected] |
Checks whether a dojo module should be loaded based on the resource privileges If any resource or privilege matches, the user needs this dojo module.
| array | $acl | list of resources as keys with privileges as values |
{
// if item has no acl resource, nothing to check.
if (empty($acl)) {
return true;
}
// if no active user, can't check acl - assume the worst.
if (!P4Cms_User::hasActive()) {
return false;
}
// match any of the resource privileges
foreach ($acl as $resource => $privileges) {
foreach ($privileges as $privilege) {
if (P4Cms_User::fetchActive()->isAllowed($resource, $privilege)) {
return true;
}
}
}
return false;
}
| static P4Cms_PackageAbstract::addPackagesPath | ( | $ | path | ) | [static] |
Add a path to the set of paths from which packages (of this class type) can be sourced.
The order that packages paths are added is significant. If a package exists in two paths, the path that was added last wins.
| string | $path | a path that can contain packages. |
{
if (!in_array($path, static::$_packagesPaths)) {
static::$_packagesPaths[] = $path;
}
}
| static P4Cms_PackageAbstract::clearCache | ( | ) | [static] |
Clear the cached list of packages.
{
return P4Cms_Cache::remove(static::_getCacheId());
}
| static P4Cms_PackageAbstract::clearPackagesPaths | ( | ) | [static] |
Clear the set of paths from which packages can be sourced.
{
static::$_packagesPaths = array();
}
| static P4Cms_PackageAbstract::exists | ( | $ | name | ) | [static] |
Determine if a package with the given name exists.
| string | $name | the name of the package to look for. |
{
$packages = static::fetchAll();
if (!isset($packages[strtolower($name)]) || empty($name)) {
return false;
} else {
return true;
}
}
| static P4Cms_PackageAbstract::fetch | ( | $ | name | ) | [static] |
Fetch a single package by name from the set of packages.
| string | $name | the name of the package to fetch. |
| P4Cms_Model_NotFoundException | if the requested package can't be found. |
{
// throw exception if no name given.
if (!is_string($name) || !$name) {
throw new InvalidArgumentException(
"Can't fetch package. No package name given."
);
}
// validate package name - package must exist.
if (!static::exists($name)) {
throw new P4Cms_Model_NotFoundException(
"Invalid package name: '" . $name . "'."
);
}
// return requested package model.
$packages = static::fetchAll();
return $packages[strtolower($name)];
}
| static P4Cms_PackageAbstract::fetchAll | ( | ) | [static] |
Get all packages (of this class type) available to the system.
Looks for packages under the paths that have been registered via addPackagesPath().
{
$cacheId = static::_getCacheId();
$cached = P4Cms_Cache::load($cacheId);
if ($cached !== false) {
return $cached;
}
// collect all packages.
$packages = new P4Cms_Model_Iterator;
foreach (static::getPackagesPaths() as $packagesPath) {
if (is_dir($packagesPath)) {
$directory = new DirectoryIterator($packagesPath);
foreach ($directory as $entry) {
if ($entry->isDir()
&& !$entry->isDot()
&& is_file($entry->getPathname() . '/' . static::PACKAGE_FILENAME)
) {
$package = new static;
$package->setPath($entry->getPathname());
// force a populate now if we are caching, to avoid
// repeated lazy loading when reading from cache.
if (P4Cms_Cache::canCache()) {
$package->populate();
}
$packages[strtolower($package->getName())] = $package;
}
}
}
}
// put packages in sorted order.
$packages->sortBy('name', array(P4Cms_Model_Iterator::SORT_ALPHA));
// cache packages.
P4Cms_Cache::save($packages, $cacheId);
return $packages;
}
| P4Cms_PackageAbstract::getBaseUrl | ( | ) |
Get the url to this package folder.
Reimplemented in P4Cms_Module.
{
// can't produce base url if the package is not under the public path.
if (strpos($this->getPath(), static::getDocumentRoot()) !== 0) {
throw new P4Cms_Package_Exception(
"Cannot get package base url. Package is not under the public path."
);
}
$request = Zend_Controller_Front::getInstance()->getRequest();
if ($request instanceof Zend_Controller_Request_Http) {
$baseUrl = $request->getBaseUrl();
} else {
$baseUrl = null;
}
$baseUrl = $baseUrl . "/" . str_replace(
static::getDocumentRoot() . '/',
'',
$this->getPath()
);
// On Windows, getPath() returns a path containing backslashes.
// Replace backslashes with the forward slashes.
return str_replace('\\', '/', $baseUrl);
}
| P4Cms_PackageAbstract::getDescription | ( | ) |
Get the description of this package from the package info file.
{
$info = $this->getPackageInfo();
return isset($info['description']) ? (string) $info['description'] : null;
}
| static P4Cms_PackageAbstract::getDocumentRoot | ( | ) | [static] |
Get the file-system path to the document root.
| P4Cms_Package_Exception | if the doc root has not been set. |
{
if (!strlen(static::$_documentRoot)) {
throw new P4Cms_Package_Exception(
"Cannot get document root. The document root has not been set."
);
}
return static::$_documentRoot;
}
| P4Cms_PackageAbstract::getDojoModules | ( | ) |
Get all dojo modules that are defined by this module.
{
$info = $this->getPackageInfo();
if (!isset($info['dojo']) || !is_array($info['dojo'])) {
return array();
}
// if we already have a cached set return it.
// note: we cache mainly for the acl checks.
if ($this->_dojoModules) {
return $this->_dojoModules;
}
$modules = array();
$groups = $info['dojo'];
foreach ($groups as $name => $group) {
if ($name === 'addOnLoad') {
continue;
}
// path must be string with length.
if (!isset($group['path']) || !is_string($group['path']) || !strlen($group['path'])) {
continue;
}
// make path relative to package baseUrl.
$path = $group['path'];
if (P4Cms_Uri::isRelativeUri($path)) {
$path = $this->getBaseUrl() . '/' . $path;
}
// dojo modules can be limited by acl. this is intended to avoid
// loading modules for features that the user can't access anyway.
// acl limits be must declared as a list of resources with each
// resource having a list of privileges (may be comma delimited).
$acl = array();
if (isset($group['acl']) && is_array($group['acl'])) {
foreach ($group['acl'] as $resource => $privileges) {
$privileges = is_array($privileges)
? $privileges
: explode(",", $privileges);
$acl[$resource] = array_filter($privileges, 'trim');
}
}
$module = array(
'namespace' => $group['namespace'],
'path' => $path,
'allowed' => $this->_passesAcl($acl)
);
$modules[] = $module;
}
$this->_dojoModules = $modules;
return $modules;
}
| P4Cms_PackageAbstract::getDojoOnLoads | ( | ) |
Get dojo 'addOnLoad' entries for this package.
{
$info = $this->getPackageInfo();
if (!isset($info['dojo']['addOnLoad'])
|| !is_array($info['dojo']['addOnLoad'])
) {
return array();
}
return $info['dojo']['addOnLoad'];
}
| P4Cms_PackageAbstract::getHtmlMeta | ( | ) |
Get meta listed in the package file in a format suitable for passing to Zend's headMeta helper.
Only supports arrays that include a key, so charset[] is not supported
{
// ensure metas is an array
$info = $this->getPackageInfo();
if (!isset($info['meta']) || !is_array($info['meta'])) {
return array();
}
// build set of valid meta fields
$meta = array();
$types = $info['meta'];
foreach ($types as $type => $fields) {
foreach ($fields as $field => $content) {
// content must be string with length.
if (!is_string($content) || !strlen($content)) {
continue;
}
$meta[] = array(
'type' => $type,
'field' => $field,
'content' => $content
);
}
}
return $meta;
}
| P4Cms_PackageAbstract::getIconUrl | ( | ) |
Get the URI to the package icon file.
| P4Cms_Package_Exception | if there is no icon. |
{
if (!$this->hasIcon()) {
throw new P4Cms_Package_Exception(
"Cannot get icon URI. This package has no icon."
);
}
$info = $this->getPackageInfo();
$uri = $info['icon'];
return (P4Cms_Uri::isRelativeUri($uri)) ? $this->getBaseUrl() . '/' . $uri : $uri;
}
| P4Cms_PackageAbstract::getId | ( | ) |
Return the name of this package as the id.
Needed to satisfy model config parent class.
Reimplemented from P4Cms_Model.
{
return $this->getName();
}
| P4Cms_PackageAbstract::getLabel | ( | ) |
Get a friendly label for this package.
The value is taken from the 'label' field of the package falling back to 'title' as an alternate storage location and lastly running a 'ucfirst' on name.
{
$info = $this->getPackageInfo() + array('label' => '', 'title' => '');
$label = $info['label'] ?: $info['title'];
return $label ?: ucfirst($this->getName());
}
| P4Cms_PackageAbstract::getMaintainerInfo | ( | $ | field = null | ) |
Get information about the maintainer of this package if available.
For example: name, email and url.
| string | $field | optional - the name of a specific maintainer field to get (e.g. name, email, url). |
{
$info = $this->getPackageInfo();
if ($field) {
return isset($info['maintainer'][$field]) ? $info['maintainer'][$field] : null;
} else {
return isset($info['maintainer']) && is_array($info['maintainer'])
? $info['maintainer'] : null;
}
}
| P4Cms_PackageAbstract::getMenus | ( | ) |
Get any menus configured for this module.
{
$info = $this->getPackageInfo();
return isset($info['menus']) && is_array($info['menus']) ? $info['menus'] : array();
}
| P4Cms_PackageAbstract::getName | ( | ) |
Get the name of this package.
The name is dervied from the basename of the path.
Reimplemented in P4Cms_Module.
{
return basename($this->getPath());
}
| P4Cms_PackageAbstract::getPackageInfo | ( | $ | key = null | ) |
Get the package configuration by parsing the package file.
| string | $key | optional - the name of a specific value to get, null if no such key exists. |
{
// parse package info file into array - if we haven't already
$info = $this->_packageInfo;
if ($info === null) {
$packageFile = $this->getPath() . '/' . static::PACKAGE_FILENAME;
if (is_readable($packageFile)) {
try {
$config = new Zend_Config_Ini($packageFile);
$info = $config->toArray();
} catch (Zend_Config_Exception $e) {
P4Cms_Log::logException("Unable to read package information.", $e);
}
}
$this->_packageInfo = isset($info) ? $info : array();
}
// if caller gave a key, return value at key, or null if no such key.
if ($key) {
return isset($info[$key]) ? $info[$key] : null;
}
return $info;
}
| static P4Cms_PackageAbstract::getPackagesPaths | ( | ) | [static] |
Get the set of paths from which packages (of this class type) can be sourced.
Reimplemented in P4Cms_Module.
{
return static::$_packagesPaths;
}
| P4Cms_PackageAbstract::getPath | ( | ) |
Get the path to this package.
| P4Cms_PackageException | if the path has not been set. |
{
if ($this->_path === null) {
throw new P4Cms_Package_Exception("Cannot get path. Path has not been set.");
}
return $this->_path;
}
| P4Cms_PackageAbstract::getScripts | ( | ) |
Get scripts listed in the package file in a format suitable for passing to the headScript helper.
The package file groups scripts by type for aesthetic reasons. Here we flatten the list to make it easier to work with.
{
// ensure scripts is an array.
$info = $this->getPackageInfo();
if (!isset($info['scripts']) || !is_array($info['scripts'])) {
return array();
}
// build set of valid scripts.
$scripts = array();
$types = $info['scripts'];
foreach ($types as $type => $urls) {
foreach ($urls as $url) {
// url must be string with length.
if (!is_string($url) || !strlen($url)) {
continue;
}
// make url relative to package baseUrl.
if (P4Cms_Uri::isRelativeUri($url)) {
$url = $this->getBaseUrl() . '/' . $url;
}
// add to scripts list.
$script = array(
'src' => $url,
'type' => "text/" . $type,
'attrs' => array()
);
$scripts[] = $script;
}
}
return $scripts;
}
| P4Cms_PackageAbstract::getStylesheets | ( | ) |
Get stylesheets listed in the package file in a format suitable for passing to Zend's headLink helper.
The package file groups stylesheets by media type for aesthetic reasons. Here we flatten the list to make it easier to work with.
{
// ensure stylesheets is an array.
$info = $this->getPackageInfo();
if (!isset($info['stylesheets']) || !is_array($info['stylesheets'])) {
return array();
}
// build set of valid stylesheets.
$styles = array();
$groups = $info['stylesheets'];
foreach ($groups as $name => $group) {
// set media to 'all' if it's not provided or empty
if (isset($group['media'])) {
$media = implode(', ', (array) $group['media']);
}
if (!isset($media) || !trim($media)) {
$media = 'all';
}
// conditional stylesheet
$conditional = isset($group['condition']) && is_string($group['condition'])
? $group['condition'] : '';
// skip the stylesheet if no url set
if (!isset($group['href'])) {
continue;
}
// nomalize the hrefs to an array
foreach ((array) $group['href'] as $url) {
// url must be string with length.
if (!is_string($url) || !strlen($url)) {
continue;
}
// make url relative to package baseUrl.
if (P4Cms_Uri::isRelativeUri($url)) {
$url = $this->getBaseUrl() . '/' . $url;
}
// add to styles list.
$style = array(
'href' => $url,
'media' => $media,
'conditional' => $conditional
);
$styles[] = $style;
}
}
return $styles;
}
| P4Cms_PackageAbstract::getTags | ( | ) |
Get tags listed in the package file.
{
$info = $this->getPackageInfo();
$tags = isset($info['tags']) ? preg_split('/,|\s/', $info['tags']) : array();
$tags = array_filter(array_map('trim', $tags));
return $tags;
}
| P4Cms_PackageAbstract::getVersion | ( | ) |
Get the version of this package from the package info file.
{
$info = $this->getPackageInfo();
return isset($info['version']) ? (string) $info['version'] : null;
}
| static P4Cms_PackageAbstract::getView | ( | ) | [static] |
Get current view object from the view renderer.
{
$renderer = static::getViewRenderer();
if (!$renderer->view) {
$renderer->initView();
}
return $renderer->view;
}
| static P4Cms_PackageAbstract::getViewRenderer | ( | ) | [static] |
Get the P4CMS (theme-aware) view renderer - load it if necessary.
{
$renderer = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
if (!$renderer instanceof P4Cms_Controller_Action_Helper_ViewRenderer) {
$renderer = new P4Cms_Controller_Action_Helper_ViewRenderer;
Zend_Controller_Action_HelperBroker::addHelper($renderer);
}
return $renderer;
}
| P4Cms_PackageAbstract::getWidgetConfig | ( | ) |
Get the widget configuration defined by the package (grouped by region).
{
$info = $this->getPackageInfo();
$widgets = array();
if (isset($info['regions']) && is_array($info['regions'])) {
$widgets = $info['regions'];
}
return $widgets;
}
| P4Cms_PackageAbstract::hasIcon | ( | ) |
Determine if there is an icon for this package.
{
$info = $this->getPackageInfo();
return isset($info['icon']) && is_string($info['icon']);
}
| P4Cms_PackageAbstract::populate | ( | ) |
Read in relevant data for this package.
Useful when caching packages as it ensures the cached copies are primed with the information we care about.
{
$this->getPackageInfo();
// get dojo modules to determine which modules the user
// has access to. we want this cached to avoid querying
// acl every request, we are able to cache it because we
// incorporate the user's roles into the cache key.
$this->getDojoModules();
}
| static P4Cms_PackageAbstract::setDocumentRoot | ( | $ | path | ) | [static] |
Set the file-system path to the document root.
| string | $path | the location of the public folder. |
{
static::$_documentRoot = rtrim($path, '/');
}
| static P4Cms_PackageAbstract::setPackagesPaths | ( | $ | paths | ) | [static] |
Set the set of paths from which packages (of this class type) can be sourced.
| array | $paths | the list of paths that can contain packages. |
{
// don't do anything if $paths is not an array
if (!is_array($paths)) {
return;
}
static::$_packagesPaths = $paths;
}
| P4Cms_PackageAbstract::setPath | ( | $ | path | ) |
Set the full path to the package folder.
| string | $path | the full path to the package folder. |
Reimplemented in P4Cms_Module.
{
// ensure given path is a string.
if (!is_string($path) || !$path) {
throw new InvalidArgumentException("Cannot set path. Path is not a string.");
}
// ensure path exists.
if (!is_dir($path)) {
throw new P4Cms_Package_Exception(
"Cannot set package path. Path does not exist."
);
}
// set the path in the instance.
$this->_path = rtrim($path, '/');
return $this;
}
P4Cms_PackageAbstract::$_documentRoot = null [static, protected] |
P4Cms_PackageAbstract::$_dojoModules = null [protected] |
P4Cms_PackageAbstract::$_packageInfo = null [protected] |
P4Cms_PackageAbstract::$_packagesPaths = array() [static, protected] |
Reimplemented in P4Cms_Module, and P4Cms_Theme.
P4Cms_PackageAbstract::$_path = null [protected] |
| const P4Cms_PackageAbstract::PACKAGE_FILENAME = 'package.ini' |
Reimplemented in P4Cms_Module, and P4Cms_Theme.