P4Cms_Widget Class Reference

Widgets are configurations of a widget-controller in a region. More...

Inheritance diagram for P4Cms_Widget:

List of all members.

Public Member Functions
	getError ()
	Get the error message if an error occurred during run.
	getException ()
	Get the exception if one occurred.
	getType ()
	Get the type of this widget.
	hasError ()
	Determine if this widget suffered an error during run.
	hasException ()
	Determine if an exception occurred during run.
	isAsynchronous ()
	Whether or not to load this widget asynchronously.
	run ($throwExceptions=false)
	Run this widget and return the output.
	save ($description=null)
	Save this widget.
	setType ($type)
	Set the type of this widget.
Static Public Member Functions
static	factory ($type, array $values=null, P4Cms_Record_Adapter $adapter=null)
	Create a new instance of a widget by specifying a widget type.
static	fetchByRegion ($id, $query=null, P4Cms_Record_Adapter $adapter=null)
	Get the widgets contained in a given region.
static	installDefaults (P4Cms_Record_Adapter $adapter=null)
	Collect all default widgets and install any that are missing.
static	installPackageDefaults (P4Cms_PackageAbstract $package, P4Cms_Record_Adapter $adapter=null, $restoreDelete=false)
	Collect all default widgets from a package and install any that are missing.
static	removePackageDefaults (P4Cms_PackageAbstract $package, P4Cms_Record_Adapter $adapter=null)
	Remove widgets provided by a package.
Protected Attributes
	$_error = null
	$_exception = null
Static Protected Attributes
static	$_fields
	Specifies the array of fields that the current Record class wishes to use.
static	$_idField = 'id'
	All records should have an id field.
static	$_storageSubPath = 'widgets'
	Specifies the sub-path to use for storage of records.

---

Detailed Description

Widgets are configurations of a widget-controller in a region.

The widget model provides read/write access to an individual widget's configuration information.

Each widget has an id that is unique within it's region. The id is is determined by the order that that the widget was defined in.

Copyright:

2011-2012 Perforce Software. All rights reserved

License:

Please see LICENSE.txt in top-level folder of this distribution.

Version:

2012.2/486814

---

Member Function Documentation

static P4Cms_Widget::factory	(	$	type,
		array $	values = null,
		P4Cms_Record_Adapter $	adapter = null
	)		[static]

Create a new instance of a widget by specifying a widget type.

The type can be a type instance or a type id.

If caller provides values, they will be merged with the widget type defaults (given values win).

Parameters:

string | P4Cms_Widget_Type	$type	the type of widget to create.
array	$values	optional - widget values to use
P4Cms_Record_Adapter	$adapter	optional - storage adapter to use.

Returns:

P4Cms_Widget a newly created widget instance.

Exceptions:

P4Cms_Widget_Exception

if the specified type is invalid.

    {
        // lookup type model if id given.
        if (is_string($type) && P4Cms_Widget_Type::exists($type)) {
            $type = P4Cms_Widget_Type::fetch($type);
        }

        // validate type.
        if (!$type instanceof P4Cms_Widget_Type || !$type->isValid()) {
            throw new P4Cms_Widget_Exception(
                "Cannot create widget. The given widget type is invalid."
            );
        }

        // merge caller provided values with type defaults.
        $values = $values ?: array();
        $values = array_merge(
            array(
                'title'     => $type->label,
                'config'    => $type->getDefaults()
            ),
            $values
        );

        // instantiate widget setting type and defaults.
        return static::create($values, $adapter)->setType($type);
    }

static P4Cms_Widget::fetchByRegion	(	$	id,
		$	query = null,
		P4Cms_Record_Adapter $	adapter = null
	)		[static]

Get the widgets contained in a given region.

Widgets have a 'region' attribute which we utilize to locate them.

Parameters:

string	$id	the id of the region
P4Cms_Record_Query | array | null	$query	optional - query options to augment result.
P4Cms_Record_Adapter	$adapter	optional - storage adapter to use.

Returns:

P4Cms_Record the requested widget(s)

    {
        if (empty($id)) {
            throw new InvalidArgumentException(
                'Cannot fetch by region. Region id must be specified.'
            );
        }

        $query = static::_normalizeQuery($query);
        $query->addFilter(P4Cms_Record_Filter::create()->add('region', $id));

        $widgets = new P4Cms_Model_Iterator;
        foreach (static::fetchAll($query, $adapter) as $widget) {
            $type = $widget->getValue('type');
            if (P4Cms_Widget_Type::exists($type) && P4Cms_Widget_Type::fetch($type)->isValid()) {
                $widgets[$widget->getId()] = $widget;
            }
        }

        // put widgets in order. we do this client side as the server lacks
        // a purely numeric sort (negative order for example would be a problem)
        $widgets->sortBy(
            array(
                'order'   => array(P4Cms_Model_Iterator::SORT_NUMERIC),
                'addTime' => array(P4Cms_Model_Iterator::SORT_NUMERIC)
            )
        );

        return $widgets;
    }

P4Cms_Widget::getError

(

)

Get the error message if an error occurred during run.

Returns:

string the error message.

Exceptions:

P4Cms_Widget_Exception

if no error occured.

    {
        if (!$this->hasError()) {
            throw new P4Cms_Widget_Exception(
                "Cannot get error. No error occurred."
            );
        }

        return $this->_error;
    }

P4Cms_Widget::getException

(

)

Get the exception if one occurred.

Returns:

Exception the exception that occurred.

Exceptions:

P4Cms_Widget_Exception

if no exception occurred.

    {
        if (!$this->hasException()) {
            throw new P4Cms_Widget_Exception(
                "Cannot get exception. No exception occurred."
            );
        }

        return $this->_exception;
    }

P4Cms_Widget::getType

(

)

Get the type of this widget.

Returns:

P4Cms_Widget_Type an instance of this widget's type.

Exceptions:

P4Cms_Widget_Exception

if no valid type is set.

    {
        $type = $this->_getValue('type');

        // ensure type id is set.
        if (!is_string($type) || !strlen($type)) {
            throw new P4Cms_Widget_Exception(
                "Cannot get widget type. The type has not been set."
            );
        }

        return P4Cms_Widget_Type::fetch($type);
    }

P4Cms_Widget::hasError

(

)

Determine if this widget suffered an error during run.

Returns:

bool true if an error occurred.

    {
        return is_string($this->_error) && strlen($this->_error);
    }

P4Cms_Widget::hasException

(

)

Determine if an exception occurred during run.

Returns:

bool true if an exception occurred.

    {
        return $this->_exception instanceof Exception;
    }

static P4Cms_Widget::installDefaults

(

P4Cms_Record_Adapter $

adapter = null

)

[static]

Collect all default widgets and install any that are missing.

Parameters:

P4Cms_Record_Adapter

$adapter

optional - storage adapter to use.

    {
        // clear the module/theme cache
        P4Cms_Module::clearCache();
        P4Cms_Theme::clearCache();

        $packages = P4Cms_Module::fetchAllEnabled();

        // add the active theme to the packages list
        if (P4Cms_Theme::hasActive()) {
            $packages[] = P4Cms_Theme::fetchActive();
        }

        // install default widgets for each package
        foreach ($packages as $package) {
            static::installPackageDefaults($package, $adapter);
        }
    }

static P4Cms_Widget::installPackageDefaults	(	P4Cms_PackageAbstract $	package,
		P4Cms_Record_Adapter $	adapter = null,
		$	restoreDelete = false
	)		[static]

Collect all default widgets from a package and install any that are missing.

Parameters:

P4Cms_PackageAbstract	$package	the package whose widgets are to be installed.
P4Cms_Record_Adapter	$adapter	optional - storage adapter to use.
boolean	$restoreDelete	optional - restore the deleted widget.

    {
        // if no adapter given, use default.
        $adapter = $adapter ?: static::getDefaultAdapter();

        // collect default widgets that have not been configured,
        // and instantiate the defined widgets
        $regionWidgetConfig = $package->getWidgetConfig();

        foreach ($regionWidgetConfig as $regionId => $widgetConfigs) {
            $widgets = array();
            foreach ($widgetConfigs as $id => $widgetConfig) {
                // create predictable uuid formatted id from package name, region id and the given id.
                $widgetId = $package->getName() . '-' . $regionId . '-' . $id;
                $widgetId = P4Cms_Uuid::fromMd5(md5($widgetId))->get();

                // skip existing widgets
                if (P4Cms_Widget::exists($widgetId, null, $adapter)) {
                    continue;
                }

                // Restore the widget if it has been deleted and $restoreDelete is set
                if ($restoreDelete &&
                    P4Cms_Widget::exists($widgetId, array('includeDeleted' => true), $adapter)
                ) {
                    $widget = P4Cms_Widget::fetch($widgetId, array('includeDeleted' => true), $adapter);
                    $widget->save();
                } else {
                    // try to create and save the widget.
                    try {
                        $type   = isset($widgetConfig['type']) ? $widgetConfig['type'] : null;
                        $widget = P4Cms_Widget::factory($type, $widgetConfig, $adapter);
                        $widget->setId($widgetId)
                               ->setValue('region', $regionId)
                               ->save();
                    } catch (P4Cms_Widget_Exception $e) {
                        continue;
                    }
                }
            }
        }
    }

P4Cms_Widget::isAsynchronous

(

)

Whether or not to load this widget asynchronously.

If true, widget should not be run during initial page rendering process, but rather via a subsequent http request.

Returns:

bool true if widget should be loaded asynchronously.

    {
        return (bool) $this->asynchronous;
    }

static P4Cms_Widget::removePackageDefaults	(	P4Cms_PackageAbstract $	package,
		P4Cms_Record_Adapter $	adapter = null
	)		[static]

Remove widgets provided by a package.

Parameters:

P4Cms_PackageAbstract	$package	the package whose widgets to be removed
P4Cms_Record_Adapter	$adapter	optional - storage adapter to use.

    {
        // if no adapter given, use default.
        $adapter = $adapter ?: static::getDefaultAdapter();

        // collect default regions from the package
        $regionWidgetConfig = $package->getWidgetConfig();

        foreach ($regionWidgetConfig as $regionId => $widgetConfigs) {
            foreach ($widgetConfigs as $id => $widgetConfig) {
                // create predictable uuid formatted id from package name, region id and the given id.
                $widgetId = $package->getName() . '-' . $regionId . '-' . $id;
                $widgetId = P4Cms_Uuid::fromMd5(md5($widgetId))->get();

                // delete the widget
                try {
                    P4Cms_Widget::remove($widgetId, $adapter);
                } catch (Exception $e) {
                    // we can't do much if the delete fails.
                    continue;
                }
            }
        }
    }

P4Cms_Widget::run

(

$

throwExceptions = false

)

Run this widget and return the output.

Parameters:

bool

$throwExceptions

optional - defaults to false to prevent widgets from halting execution - if you want to permit exceptions pass true for this argument.

Returns:

string the output produced by the widget.

    {
        // try to run the widget controller.
        // suppress exceptions unless throw exceptions is true.
        $output = '';
        try {
            $view   = Zend_Layout::getMvcInstance()->getView();
            $type   = $this->getType();
            $params = $type->getRouteParams();
            
            // when an action parameter is included in a page request (e.g. ?action=foo),
            // the action will be retrieved by dispatcher->getActionMethod() because
            // $params['action'] is null -- it's not defined in the module.ini file.  
            // we provide a default 'index' action here to avoid the problem.
            $output = $view->action(
                $params['action'] ?: 'index',
                $params['controller'],
                $params['module'],
                array('widget' => $this)
            );
        } catch (Exception $e) {
            P4Cms_Log::logException("Failed to run widget.", $e);

            $this->_exception = $e;
            $this->_error     = $e->getMessage();

            if ($throwExceptions) {
                throw $e;
            }
        }

        return $output;
    }

P4Cms_Widget::save

(

$

description = null

)

Save this widget.

Extends parent to keep record of the time that the widget is added.

Parameters:

string

$description

optional - a description of the change.

Returns:

P4Cms_Record provides a fluent interface

Reimplemented from P4Cms_Record_Config.

    {
        if (!$this->getValue('addTime')) {
            $this->setValue('addTime', microtime(true));
        }

        return parent::save($description);
    }

P4Cms_Widget::setType

(

$

type

)

Set the type of this widget.

Parameters:

null | string | P4Cms_Widget_Type

$type

the type of widget (either id or instance).

    {
        // normalize type instance to id string.
        if ($type instanceof P4Cms_Widget_Type) {
            $type = $type->getId();
        }

        if (!is_string($type) && $type !== null) {
            throw new InvalidArgumentException(
                "Widget type must be a string, a widget type instance or null."
            );
        }

        return $this->_setValue('type', $type);
    }

---

Member Data Documentation

P4Cms_Widget::$_error = null [protected]

P4Cms_Widget::$_exception = null [protected]

P4Cms_Widget::$_fields [static, protected]

Initial value:

 array(
        'id',
        'region',
        'type',
        'title',
        'showTitle',
        'order'         => array(
            'default'   => 0
        ),
        'class',
        'asynchronous'  => array(
            'default'   => false
        ),
        'config',
        'addTime'
    )

Specifies the array of fields that the current Record class wishes to use.

The implementing class MUST set this property.

Reimplemented from P4Cms_Record_Config.

P4Cms_Widget::$_idField = 'id' [static, protected]

All records should have an id field.

Reimplemented from P4Cms_Record.

P4Cms_Widget::$_storageSubPath = 'widgets' [static, protected]

Specifies the sub-path to use for storage of records.

This is used in combination with the records path (provided by the storage adapter) to construct the full storage path. The implementing class MUST set this property.

Reimplemented from P4Cms_Record.

---

The documentation for this class was generated from the following file:

• library/P4Cms/Widget.php