|
Perforce Chronicle 2012.2/486814
API Documentation
|
View helper that displays a content list. More...
Public Member Functions | |
| __toString () | |
| A magic method which calls through to render; see render method for details. | |
| closeList () | |
| Returns the end of the html list. | |
| contentList ($query, array $options=array()) | |
| Default method called for this view helper. | |
| getDecorators ($fieldName, $type) | |
| Get the decorator instances for a given field. | |
| getDisplayValue ($fieldIndex, $entry) | |
| Gets a rendered (decorated and filtered) field value. | |
| getFields () | |
| Get list of fields configured for display including any options for those fields such as filters and decorators. | |
| getFilters ($fieldName, $type) | |
| Get the filter instances for a given field. | |
| getTemplate () | |
| Accessor for the optional template path. | |
| openList () | |
| Returns the start of the html list. | |
| render () | |
| Render method for this view helper. | |
Protected Member Functions | |
| _getElement () | |
| Returns a form element for the purpose of loading filters/decorators. | |
| _normalizeOptions (array $options) | |
| Normalizes options to ensure that it is in a consistent format. | |
Protected Attributes | |
| $_defaultOptions | |
| $_element = null | |
| $_options = array() | |
| $_query = null | |
View helper that displays a content list.
| Content_View_Helper_ContentList::__toString | ( | ) |
A magic method which calls through to render; see render method for details.
{
try {
return $this->render();
} catch (Exception $e) {
return "";
}
}
| Content_View_Helper_ContentList::_getElement | ( | ) | [protected] |
Returns a form element for the purpose of loading filters/decorators.
return Zend_Form_Element a form element for loading filters/decorators.
{
if ($this->_element instanceof Zend_Form_Element) {
return $this->_element;
}
$form = new P4Cms_Form;
$form->addElement('text', 'loader');
$this->_element = $form->getElement('loader');
return $this->_element;
}
| Content_View_Helper_ContentList::_normalizeOptions | ( | array $ | options | ) | [protected] |
Normalizes options to ensure that it is in a consistent format.
| array | $options | The un-normalized fields array. |
{
$normalized = $options + $this->_defaultOptions;
// ensure fields is an array.
if (isset($options['fields']) && is_array($options['fields'])) {
$normalized['fields'] = array();
} else {
$options['fields'] = $this->_defaultOptions['fields'];
}
// normalize fields to name/options w. filters and decorators.
$defaults = array('filters' => array(), 'decorators' => array());
foreach ($options['fields'] as $name => $value) {
if (is_numeric($name) && is_string($value)) {
$name = $value;
$value = $defaults;
}
// skip invalid field declarations.
if (!is_string($name) || !is_array($value)) {
continue;
}
// ensure field options has filter/decorator entries.
$value += $defaults;
// set field name value
if (!array_key_exists('field', $value)) {
$value['field'] = $name;
}
// ensure that the filters and decorators options are both arrays
foreach (array('filters', 'decorators') as $option) {
if (!is_array($value[$option])) {
$value[$option] = array();
}
}
$normalized['fields'][$name] = $value;
}
return $normalized;
}
| Content_View_Helper_ContentList::closeList | ( | ) |
Returns the end of the html list.
{
return '</ul>' . PHP_EOL;
}
| Content_View_Helper_ContentList::contentList | ( | $ | query, |
| array $ | options = array() |
||
| ) |
Default method called for this view helper.
For more information on query construction
The options array can declare a template to use to render content through, an optional message to display if no entries are returned by the query, and a list of fields to render.
The fields array can be as simple as:
array('field1', 'field2', ...)
Or, more complex with display filters and decorators:
array( 'field1' => array( 'decorators' => array( 'decorator1' => array('option1' => 'value', 'option2'), ... ), 'filters' => array('filter1'...) ), 'optionIndex' => array( 'field' => 'field1', 'decorators' => array( 'decorator1' => array('option1' => 'value', 'option2'), ... ), 'filters' => array('filter1'...) ), 'field2' => array(...) )
Filters can contain options such as 'lucene' or 'categories' to have those modules subscribe to and influence the query. Note that these options do not work on subfilters.
| P4Cms_Record_Query | array | null | $query | The query or array to determines the list of content. |
| array | $options | Optional array of options. |
{
// P4Cms_Record::fetchAll normalizes the query for us on use
$this->_query = $query;
$this->_options = $this->_normalizeOptions($options);
return $this;
}
| Content_View_Helper_ContentList::getDecorators | ( | $ | fieldName, |
| $ | type | ||
| ) |
Get the decorator instances for a given field.
| string | $fieldName | The name of the field for which to obtain decorators. |
| P4Cms_Content_Type | $type | The type of the element's content entry. |
{
// will be empty if none were provided
if (empty($this->_options['fields'][$fieldName]['decorators'])) {
return $type->getDisplayDecorators($fieldName);
}
try {
$element = $this->_getElement();
$element->setDecorators($this->_options['fields'][$fieldName]['decorators']);
return $element->getDecorators();
} catch (Exception $e) {
P4Cms_Log::log(
"Failed to get user-specified decorators for field '"
. $fieldName . "' when displaying content with id " . $entry->getId()
. " as part of a list.",
P4Cms_Log::ERR
);
}
return array();
}
| Content_View_Helper_ContentList::getDisplayValue | ( | $ | fieldIndex, |
| $ | entry | ||
| ) |
Gets a rendered (decorated and filtered) field value.
| string | $fieldIndex | The index to the options entry for the field to display. |
| P4Cms_Content | $entry | The entry containing the field to display. |
{
$fieldName = $this->_options['fields'][$fieldIndex]['field'];
// if the requested field doesn't exist, silently return an empty value.
$type = $entry->getContentType();
if (!$type->hasElement($fieldName)) {
return '';
}
// filter the value.
$value = $entry->getExpandedValue($fieldName);
foreach ($this->getFilters($fieldIndex, $type) as $filter) {
$value = $filter->filter($value);
}
// set the field value on the element for decorators to access
// note, some elements (e.g. file/image) will ignore attempts to
// set a value; therefore, decorators will not be able to retrieve
// the field value from such elements directly - that is why we
// also set the content entry on enhanced elements.
$element = clone $type->getFormElement($fieldName);
$element->setValue($value);
if ($element instanceof P4Cms_Content_EnhancedElementInterface) {
$element->setContentRecord($entry);
}
// render display value using decorators.
$content = '';
foreach ($this->getDecorators($fieldIndex, $type) as $decorator) {
$decorator->setElement($element);
if ($decorator instanceof P4Cms_Content_EnhancedDecoratorInterface) {
$decorator->setContentRecord($entry);
}
$content = $decorator->render($content);
}
return $content;
}
| Content_View_Helper_ContentList::getFields | ( | ) |
Get list of fields configured for display including any options for those fields such as filters and decorators.
{
return $this->_options['fields'];
}
| Content_View_Helper_ContentList::getFilters | ( | $ | fieldName, |
| $ | type | ||
| ) |
Get the filter instances for a given field.
| string | $fieldName | The name of the field for which to obtain filters. |
| P4Cms_Content_Type | $type | The type of the element's content entry. |
{
// will be empty if no filters were provided
if (empty($this->_options['fields'][$fieldName]['filters'])) {
return $type->getDisplayFilters($fieldName);
}
try {
$element = $this->_getElement();
$element->setFilters($this->_options['fields'][$fieldName]['filters']);
return $element->getFilters();
} catch (Exception $e) {
P4Cms_Log::log(
"Failed to get user-specified filters for field '"
. $fieldName . "' when displaying content with id " . $entry->getId()
. " as part of a list.",
P4Cms_Log::ERR
);
}
return array();
}
| Content_View_Helper_ContentList::getTemplate | ( | ) |
Accessor for the optional template path.
{
return $this->_options['template'];
}
| Content_View_Helper_ContentList::openList | ( | ) |
Returns the start of the html list.
{
return '<ul class="content-list">' . PHP_EOL;
}
| Content_View_Helper_ContentList::render | ( | ) |
Render method for this view helper.
If a template has been supplied, renders the content list using the template, otherwise renders the content list as an unordered html list.
{
$view = clone $this->view;
$entries = P4Cms_Content::fetchAll($this->_query);
// allow caller to sort entries client-side
// sorting capabilities of server are limited.
if ($this->_options['postSort']) {
$entries->sortBy($this->_options['postSort']);
}
// tag the page cache so it can be appropriately cleared later
if (P4Cms_Cache::canCache('page')) {
P4Cms_Cache::getCache('page')->addTag('p4cms_content')
->addTag('p4cms_content_type')
->addTag('p4cms_content_list');
}
// if there is a template: clone view, add items, render template
if ($this->getTemplate()) {
$view->entries = $entries;
$view->options = $this->_options;
return $view->render($this->getTemplate());
}
if (!count($entries)) {
return $this->_options['emptyMessage'];
}
$count = 0;
$html = $this->openList();
foreach ($entries as $entry) {
$count++;
$html .= '<li class="content-list-entry-' . $count
. ' content-list-entry-' . ($count % 2 ? 'odd' : 'even')
. ' content-list-type-' . $view->escapeAttr($entry->getContentTypeId()) . '">';
foreach ($this->getFields() as $field => $options) {
$html .= $this->getDisplayValue($field, $entry);
}
$html .= '</li>' . PHP_EOL;
}
$html .= $this->closeList();
return $html;
}
Content_View_Helper_ContentList::$_defaultOptions [protected] |
array(
'template' => null,
'emptyMessage' => 'No content entries found.',
'fields' => array(
'title' => array(
'filters' => array(),
'decorators' => array('Value', 'ContentLink')
)
),
'postSort' => null
)
Content_View_Helper_ContentList::$_element = null [protected] |
Content_View_Helper_ContentList::$_options = array() [protected] |
Content_View_Helper_ContentList::$_query = null [protected] |