silverstripe-framework/Forms/GridField/GridField.php

<?php

namespace SilverStripe\Forms\GridField;

use SilverStripe\ORM\ArrayList;
use SilverStripe\ORM\DataList;
use SilverStripe\ORM\DataObject;
use SilverStripe\ORM\SS_List;
use SilverStripe\ORM\FieldType\DBField;
use SilverStripe\ORM\DataModel;
use SilverStripe\ORM\DataObjectInterface;
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Control\Session;
use SilverStripe\Control\HTTPResponse_Exception;
use SilverStripe\Control\HTTPResponse;
use SilverStripe\Control\RequestHandler;
use SilverStripe\Forms\FormField;
use SilverStripe\Forms\Form;
use LogicException;
use InvalidArgumentException;
use SilverStripe\View\Requirements;

/**
 * Displays a {@link SS_List} in a grid format.
 *
 * GridField is a field that takes an SS_List and displays it in an table with rows and columns.
 * It reminds of the old TableFields but works with SS_List types and only loads the necessary
 * rows from the list.
 *
 * The minimum configuration is to pass in name and title of the field and a SS_List.
 *
 * <code>
 * $gridField = new GridField('ExampleGrid', 'Example grid', new DataList('Page'));
 * </code>
 *
 * Caution: The form field does not include any JavaScript or CSS when used outside of the CMS context,
 * since the required frontend dependencies are included through CMS bundling.
 *
 * @see SS_List
 *
 * @property GridState_Data $State The gridstate of this object
 */
class GridField extends FormField {
	/**
	 * @var array
	 */
	private static $allowed_actions = array(
		'index',
		'gridFieldAlterAction',
	);

	/**
	 * Data source.
	 *
	 * @var SS_List
	 */
	protected $list = null;

	/**
	 * Class name of the DataObject that the GridField will display.
	 *
	 * Defaults to the value of $this->list->dataClass.
	 *
	 * @var string
	 */
	protected $modelClassName = '';

	/**
	 * Current state of the GridField.
	 *
	 * @var GridState
	 */
	protected $state = null;

	/**
	 * @var GridFieldConfig
	 */
	protected $config = null;

	/**
	 * Components list.
	 *
	 * @var array
	 */
	protected $components = array();

	/**
	 * Internal dispatcher for column handlers.
	 *
	 * Keys are column names and values are GridField_ColumnProvider objects.
	 *
	 * @var array
	 */
	protected $columnDispatch = null;

	/**
	 * Map of callbacks for custom data fields.
	 *
	 * @var array
	 */
	protected $customDataFields = array();

	/**
	 * @var string
	 */
	protected $name = '';

	/**
	 * @param string $name
	 * @param string $title
	 * @param SS_List $dataList
	 * @param GridFieldConfig $config
	 */
	public function __construct($name, $title = null, SS_List $dataList = null, GridFieldConfig $config = null) {
		parent::__construct($name, $title, null);

		$this->name = $name;

		if($dataList) {
			$this->setList($dataList);
		}

		if(!$config) {
			$config = GridFieldConfig_Base::create();
		}

		$this->setConfig($config);

		$state = $this->config->getComponentByType('SilverStripe\\Forms\\GridField\\GridState_Component');

		if (!$state) {
			$this->config->addComponent(new GridState_Component());
		}

		$this->state = new GridState($this);

		$this->addExtraClass('grid-field');
	}

	/**
	 * @param HTTPRequest $request
	 *
	 * @return string
	 */
	public function index($request) {
		return $this->gridFieldAlterAction(array(), $this->getForm(), $request);
	}

	/**
	 * Set the modelClass (data object) that this field will get it column headers from.
	 *
	 * If no $displayFields has been set, the display fields will be $summary_fields.
	 *
	 * @see GridFieldDataColumns::getDisplayFields()
	 *
	 * @param string $modelClassName
	 *
	 * @return $this
	 */
	public function setModelClass($modelClassName) {
		$this->modelClassName = $modelClassName;

		return $this;
	}

	/**
	 * Returns a data class that is a DataObject type that this GridField should look like.
	 *
	 * @return string
	 *
	 * @throws LogicException
	 */
	public function getModelClass() {
		if($this->modelClassName) {
			return $this->modelClassName;
		}

		/** @var DataList|ArrayList $list */
		$list = $this->list;
		if($list && $list->hasMethod('dataClass')) {
			$class = $list->dataClass();

			if($class) {
				return $class;
			}
		}

		throw new LogicException(
			'GridField doesn\'t have a modelClassName, so it doesn\'t know the columns of this grid.'
		);
	}

	/**
	 * @return GridFieldConfig
	 */
	public function getConfig() {
		return $this->config;
	}

	/**
	 * @param GridFieldConfig $config
	 *
	 * @return $this
	 */
	public function setConfig(GridFieldConfig $config) {
		$this->config = $config;

		return $this;
	}

	/**
	 * @return ArrayList
	 */
	public function getComponents() {
		return $this->config->getComponents();
	}

	/**
	 * Cast an arbitrary value with the help of a $castingDefinition.
	 *
	 * @todo refactor this into GridFieldComponent
	 *
	 * @param mixed $value
	 * @param string|array $castingDefinition
	 *
	 * @return mixed
	 */
	public function getCastedValue($value, $castingDefinition) {
		$castingParams = array();

		if(is_array($castingDefinition)) {
			$castingParams = $castingDefinition;
			array_shift($castingParams);
			$castingDefinition = array_shift($castingDefinition);
		}

		if(strpos($castingDefinition, '->') === false) {
			$castingFieldType = $castingDefinition;
			$castingField = DBField::create_field($castingFieldType, $value);

			return call_user_func_array(array($castingField, 'XML'), $castingParams);
		}

		list($castingFieldType, $castingMethod) = explode('->', $castingDefinition);

		$castingField = DBField::create_field($castingFieldType, $value);

		return call_user_func_array(array($castingField, $castingMethod), $castingParams);
	}

	/**
	 * Set the data source.
	 *
	 * @param SS_List $list
	 *
	 * @return $this
	 */
	public function setList(SS_List $list) {
		$this->list = $list;

		return $this;
	}

	/**
	 * Get the data source.
	 *
	 * @return SS_List
	 */
	public function getList() {
		return $this->list;
	}

	/**
	 * Get the data source after applying every {@link GridField_DataManipulator} to it.
	 *
	 * @return SS_List
	 */
	public function getManipulatedList() {
		$list = $this->getList();

		foreach($this->getComponents() as $item) {
			if($item instanceof GridField_DataManipulator) {
				$list = $item->getManipulatedData($this, $list);
			}
		}

		return $list;
	}

	/**
	 * Get the current GridState_Data or the GridState.
	 *
	 * @param bool $getData
	 *
	 * @return GridState_Data|GridState
	 */
	public function getState($getData = true) {
		if($getData) {
			return $this->state->getData();
		}

		return $this->state;
	}

	/**
	 * Returns the whole gridfield rendered with all the attached components.
	 *
	 * @param array $properties
	 * @return string
	 */
	public function FieldHolder($properties = array()) {
		$columns = $this->getColumns();

		$list = $this->getManipulatedList();

		$content = array(
			'before' => '',
			'after' => '',
			'header' => '',
			'footer' => '',
		);

		foreach($this->getComponents() as $item) {
			if($item instanceof GridField_HTMLProvider) {
				$fragments = $item->getHTMLFragments($this);

				if($fragments) {
					foreach($fragments as $fragmentKey => $fragmentValue) {
						$fragmentKey = strtolower($fragmentKey);

						if(!isset($content[$fragmentKey])) {
							$content[$fragmentKey] = '';
						}

						$content[$fragmentKey] .= $fragmentValue . "\n";
					}
				}
			}
		}

		foreach($content as $contentKey => $contentValue) {
			$content[$contentKey] = trim($contentValue);
		}

		// Replace custom fragments and check which fragments are defined. Circular dependencies
		// are detected by disallowing any item to be deferred more than 5 times.

		$fragmentDefined = array(
			'header' => true,
			'footer' => true,
			'before' => true,
			'after' => true,
		);

		reset($content);

		while(list($contentKey, $contentValue) = each($content)) {
			if(preg_match_all('/\$DefineFragment\(([a-z0-9\-_]+)\)/i', $contentValue, $matches)) {
				foreach($matches[1] as $match) {
					$fragmentName = strtolower($match);
					$fragmentDefined[$fragmentName] = true;

					$fragment = '';

					if(isset($content[$fragmentName])) {
						$fragment = $content[$fragmentName];
					}

					// If the fragment still has a fragment definition in it, when we should defer
					// this item until later.

					if(preg_match('/\$DefineFragment\(([a-z0-9\-_]+)\)/i', $fragment, $matches)) {
						if(isset($fragmentDeferred[$contentKey]) && $fragmentDeferred[$contentKey] > 5) {
							throw new LogicException(sprintf(
								'GridField HTML fragment "%s" and "%s" appear to have a circular dependency.',
								$fragmentName,
								$matches[1]
							));
						}

						unset($content[$contentKey]);

						$content[$contentKey] = $contentValue;

						if(!isset($fragmentDeferred[$contentKey])) {
							$fragmentDeferred[$contentKey] = 0;
						}

						$fragmentDeferred[$contentKey]++;

						break;
					} else {
						$content[$contentKey] = preg_replace(
							sprintf('/\$DefineFragment\(%s\)/i', $fragmentName),
							$fragment,
							$content[$contentKey]
						);
					}
				}
			}
		}

		// Check for any undefined fragments, and if so throw an exception.
		// While we're at it, trim whitespace off the elements.

		foreach($content as $contentKey => $contentValue) {
			if(empty($fragmentDefined[$contentKey])) {
				throw new LogicException(sprintf(
					'GridField HTML fragment "%s" was given content, but not defined. Perhaps there is a supporting GridField component you need to add?',
					$contentKey
				));
			}
		}

		$total = count($list);

		if($total > 0) {
			$rows = array();

			foreach($list as $index => $record) {
				if($record->hasMethod('canView') && !$record->canView()) {
					continue;
				}

				$rowContent = '';

				foreach($this->getColumns() as $column) {
					$colContent = $this->getColumnContent($record, $column);

					// Null means this columns should be skipped altogether.

					if($colContent === null) {
						continue;
					}

					$colAttributes = $this->getColumnAttributes($record, $column);

					$rowContent .= $this->newCell(
						$total,
						$index,
						$record,
						$colAttributes,
						$colContent
					);
				}

				$rowAttributes = $this->getRowAttributes($total, $index, $record);

				$rows[] = $this->newRow($total, $index, $record, $rowAttributes, $rowContent);
			}
			$content['body'] = implode("\n", $rows);
		}

		// Display a message when the grid field is empty.

		if(empty($content['body'])) {
			$cell = FormField::create_tag(
				'td',
				array(
					'colspan' => count($columns),
				),
				_t('GridField.NoItemsFound', 'No items found')
			);

			$row = FormField::create_tag(
				'tr',
				array(
					'class' => 'ss-gridfield-item ss-gridfield-no-items',
				),
				$cell
			);

			$content['body'] = $row;
		}

		$header = $this->getOptionalTableHeader($content);
		$body = $this->getOptionalTableBody($content);
		$footer = $this->getOptionalTableFooter($content);

		$this->addExtraClass('ss-gridfield grid-field field');

		$fieldsetAttributes = array_diff_key(
			$this->getAttributes(),
			array(
				'value' => false,
				'type' => false,
				'name' => false,
			)
		);

		$fieldsetAttributes['data-name'] = $this->getName();

		$tableId = null;

		if($this->id) {
			$tableId = $this->id;
		}

		$tableAttributes = array(
			'id' => $tableId,
			'class' => 'table grid-field__table',
			'cellpadding' => '0',
			'cellspacing' => '0'
		);

		if($this->getDescription()) {
			$content['after'] .= FormField::create_tag(
				'span',
				array('class' => 'description'),
				$this->getDescription()
			);
		}

		$table = FormField::create_tag(
			'table',
			$tableAttributes,
			$header . "\n" . $footer . "\n" . $body
		);

		return FormField::create_tag(
			'fieldset',
			$fieldsetAttributes,
			$content['before'] . $table . $content['after']
		);
	}

	/**
	 * @param int $total
	 * @param int $index
	 * @param DataObject $record
	 * @param array $attributes
	 * @param string $content
	 *
	 * @return string
	 */
	protected function newCell($total, $index, $record, $attributes, $content) {
		return FormField::create_tag(
			'td',
			$attributes,
			$content
		);
	}

	/**
	 * @param int $total
	 * @param int $index
	 * @param DataObject $record
	 * @param array $attributes
	 * @param string $content
	 *
	 * @return string
	 */
	protected function newRow($total, $index, $record, $attributes, $content) {
		return FormField::create_tag(
			'tr',
			$attributes,
			$content
		);
	}

	/**
	 * @param int $total
	 * @param int $index
	 * @param DataObject $record
	 *
	 * @return array
	 */
	protected function getRowAttributes($total, $index, $record) {
		$rowClasses = $this->newRowClasses($total, $index, $record);

		return array(
			'class' => implode(' ', $rowClasses),
			'data-id' => $record->ID,
			'data-class' => $record->ClassName,
		);
	}

	/**
	 * @param int $total
	 * @param int $index
	 * @param DataObject $record
	 *
	 * @return array
	 */
	protected function newRowClasses($total, $index, $record) {
		$classes = array('ss-gridfield-item');

		if($index == 0) {
			$classes[] = 'first';
		}

		if($index == $total - 1) {
			$classes[] = 'last';
		}

		if($index % 2) {
			$classes[] = 'even';
		} else {
			$classes[] = 'odd';
		}

		$this->extend('updateNewRowClasses', $classes, $total, $index, $record);

		return $classes;
	}

	/**
	 * @param array $properties
	 * @return string
	 */
	public function Field($properties = array()) {
		$this->extend('onBeforeRender', $this);
		return $this->FieldHolder($properties);
	}

	/**
	 * {@inheritdoc}
	 */
	public function getAttributes() {
		return array_merge(
			parent::getAttributes(),
			array(
				'data-url' => $this->Link(),
			)
		);
	}

	/**
	 * Get the columns of this GridField, they are provided by attached GridField_ColumnProvider.
	 *
	 * @return array
	 */
	public function getColumns() {
		$columns = array();

		foreach($this->getComponents() as $item) {
			if($item instanceof GridField_ColumnProvider) {
				$item->augmentColumns($this, $columns);
			}
		}

		return $columns;
	}

	/**
	 * Get the value from a column.
	 *
	 * @param DataObject $record
	 * @param string $column
	 *
	 * @return string
	 *
	 * @throws InvalidArgumentException
	 */
	public function getColumnContent($record, $column) {
		if(!$this->columnDispatch) {
			$this->buildColumnDispatch();
		}

		if(!empty($this->columnDispatch[$column])) {
			$content = '';

			foreach($this->columnDispatch[$column] as $handler) {
				/**
				 * @var GridField_ColumnProvider $handler
				 */
				$content .= $handler->getColumnContent($this, $record, $column);
			}

			return $content;
		} else {
			throw new InvalidArgumentException(sprintf(
				'Bad column "%s"',
				$column
			));
		}
	}

	/**
	 * Add additional calculated data fields to be used on this GridField
	 *
	 * @param array $fields a map of fieldname to callback. The callback will
	 *                      be passed the record as an argument.
	 */
	public function addDataFields($fields) {
		if($this->customDataFields) {
			$this->customDataFields = array_merge($this->customDataFields, $fields);
		} else {
			$this->customDataFields = $fields;
		}
	}

	/**
	 * Get the value of a named field  on the given record.
	 *
	 * Use of this method ensures that any special rules around the data for this gridfield are
	 * followed.
	 *
	 * @param DataObject $record
	 * @param string $fieldName
	 *
	 * @return mixed
	 */
	public function getDataFieldValue($record, $fieldName) {
		if(isset($this->customDataFields[$fieldName])) {
			$callback = $this->customDataFields[$fieldName];

			return $callback($record);
		}

		if($record->hasMethod('relField')) {
			return $record->relField($fieldName);
		}

		if($record->hasMethod($fieldName)) {
			return $record->$fieldName();
		}

		return $record->$fieldName;
	}

	/**
	 * Get extra columns attributes used as HTML attributes.
	 *
	 * @param DataObject $record
	 * @param string $column
	 *
	 * @return array
	 *
	 * @throws LogicException
	 * @throws InvalidArgumentException
	 */
	public function getColumnAttributes($record, $column) {
		if(!$this->columnDispatch) {
			$this->buildColumnDispatch();
		}

		if(!empty($this->columnDispatch[$column])) {
			$attributes = array();

			foreach($this->columnDispatch[$column] as $handler) {
				/**
				 * @var GridField_ColumnProvider $handler
				 */
				$columnAttributes = $handler->getColumnAttributes($this, $record, $column);

				if(is_array($columnAttributes)) {
					$attributes = array_merge($attributes, $columnAttributes);
					continue;
				}

				throw new LogicException(sprintf(
					'Non-array response from %s::getColumnAttributes().',
					get_class($handler)
				));
			}

			return $attributes;
		}

		throw new InvalidArgumentException(sprintf(
			'Bad column "%s"',
			$column
		));
	}

	/**
	 * Get metadata for a column.
	 *
	 * @example "array('Title'=>'Email address')"
	 *
	 * @param string $column
	 *
	 * @return array
	 *
	 * @throws LogicException
	 * @throws InvalidArgumentException
	 */
	public function getColumnMetadata($column) {
		if(!$this->columnDispatch) {
			$this->buildColumnDispatch();
		}

		if(!empty($this->columnDispatch[$column])) {
			$metaData = array();

			foreach($this->columnDispatch[$column] as $handler) {
				/**
				 * @var GridField_ColumnProvider $handler
				 */
				$columnMetaData = $handler->getColumnMetadata($this, $column);

				if(is_array($columnMetaData)) {
					$metaData = array_merge($metaData, $columnMetaData);
					continue;
				}

				throw new LogicException(sprintf(
					'Non-array response from %s::getColumnMetadata().',
					get_class($handler)
				));
			}

			return $metaData;
		}

		throw new InvalidArgumentException(sprintf(
			'Bad column "%s"',
			$column
		));
	}

	/**
	 * Return how many columns the grid will have.
	 *
	 * @return int
	 */
	public function getColumnCount() {
		if(!$this->columnDispatch) {
			$this->buildColumnDispatch();
		}

		return count($this->columnDispatch);
	}

	/**
	 * Build an columnDispatch that maps a GridField_ColumnProvider to a column for reference later.
	 */
	protected function buildColumnDispatch() {
		$this->columnDispatch = array();

		foreach($this->getComponents() as $item) {
			if($item instanceof GridField_ColumnProvider) {
				$columns = $item->getColumnsHandled($this);

				foreach($columns as $column) {
					$this->columnDispatch[$column][] = $item;
				}
			}
		}
	}

	/**
	 * This is the action that gets executed when a GridField_AlterAction gets clicked.
	 *
	 * @param array $data
	 * @param Form $form
	 * @param HTTPRequest $request
	 *
	 * @return string
	 */
	public function gridFieldAlterAction($data, $form, HTTPRequest $request) {
		$data = $request->requestVars();

		// Protection against CSRF attacks
		$token = $this
			->getForm()
			->getSecurityToken();
		if(!$token->checkRequest($request)) {
			$this->httpError(400, _t("Form.CSRF_FAILED_MESSAGE",
				"There seems to have been a technical problem. Please click the back button, ".
				"refresh your browser, and try again."
			));
		}

		$name = $this->getName();

		$fieldData = null;

		if(isset($data[$name])) {
			$fieldData = $data[$name];
		}

		$state = $this->getState(false);

		/** @skipUpgrade */
		if(isset($fieldData['GridState'])) {
			$state->setValue($fieldData['GridState']);
		}

		foreach($data as $dataKey => $dataValue) {
			if(preg_match('/^action_gridFieldAlterAction\?StateID=(.*)/', $dataKey, $matches)) {
				$stateChange = Session::get($matches[1]);
				$actionName = $stateChange['actionName'];

				$arguments = array();

				if(isset($stateChange['args'])) {
					$arguments = $stateChange['args'];
				};

				$html = $this->handleAlterAction($actionName, $arguments, $data);

				if($html) {
					return $html;
				}
			}
		}

		if($request->getHeader('X-Pjax') === 'CurrentField') {
			return $this->FieldHolder();
		}

		return $form->forTemplate();
	}

	/**
	 * Pass an action on the first GridField_ActionProvider that matches the $actionName.
	 *
	 * @param string $actionName
	 * @param mixed $arguments
	 * @param array $data
	 *
	 * @return mixed
	 *
	 * @throws InvalidArgumentException
	 */
	public function handleAlterAction($actionName, $arguments, $data) {
		$actionName = strtolower($actionName);

		foreach($this->getComponents() as $component) {
			if($component instanceof GridField_ActionProvider) {
				$actions = array_map('strtolower', (array) $component->getActions($this));

				if(in_array($actionName, $actions)) {
					return $component->handleAction($this, $actionName, $arguments, $data);
				}
			}
		}

		throw new InvalidArgumentException(sprintf(
			'Can\'t handle action "%s"',
			$actionName
		));
	}

	/**
	 * Custom request handler that will check component handlers before proceeding to the default
	 * implementation.
	 *
	 * @todo copy less code from RequestHandler.
	 *
	 * @param HTTPRequest $request
	 * @param DataModel $model
	 *
	 * @return array|RequestHandler|HTTPResponse|string|void
	 *
	 * @throws HTTPResponse_Exception
	 */
	public function handleRequest(HTTPRequest $request, DataModel $model) {
		if($this->brokenOnConstruct) {
			user_error(
				sprintf(
					"parent::__construct() needs to be called on %s::__construct()",
					__CLASS__
				),
				E_USER_WARNING
			);
		}

		$this->setRequest($request);
		$this->setDataModel($model);

		$fieldData = $this->getRequest()->requestVar($this->getName());

		/** @skipUpgrade */
		if($fieldData && isset($fieldData['GridState'])) {
			$this->getState(false)->setValue($fieldData['GridState']);
		}

		foreach($this->getComponents() as $component) {
			if($component instanceof GridField_URLHandler && $urlHandlers = $component->getURLHandlers($this)) {
				foreach($urlHandlers as $rule => $action) {
					if($params = $request->match($rule, true)) {
						// Actions can reference URL parameters.
						// e.g. '$Action/$ID/$OtherID' → '$Action'

						if($action[0] == '$') {
							$action = $params[substr($action, 1)];
						}

						if(!method_exists($component, 'checkAccessAction') || $component->checkAccessAction($action)) {
							if(!$action) {
								$action = "index";
							}

							if(!is_string($action)) {
								throw new LogicException(sprintf(
									'Non-string method name: %s',
									var_export($action, true)
								));
							}

							try {
								$result = $component->$action($this, $request);
							} catch(HTTPResponse_Exception $responseException) {
								$result = $responseException->getResponse();
							}

							if($result instanceof HTTPResponse && $result->isError()) {
								return $result;
							}

							if($this !== $result && !$request->isEmptyPattern($rule) && is_object($result) && $result instanceof RequestHandler) {
								$returnValue = $result->handleRequest($request, $model);

								if(is_array($returnValue)) {
									throw new LogicException(
										'GridField_URLHandler handlers can\'t return arrays'
									);
								}

								return $returnValue;
							}

							if($request->allParsed()) {
								return $result;
							}

							return $this->httpError(
								404,
								sprintf(
									'I can\'t handle sub-URLs of a %s object.',
									get_class($result)
								)
							);
						}
					}
				}
			}
		}

		return parent::handleRequest($request, $model);
	}

	/**
	 * {@inheritdoc}
	 */
	public function saveInto(DataObjectInterface $record) {
		foreach($this->getComponents() as $component) {
			if($component instanceof GridField_SaveHandler) {
				$component->handleSave($this, $record);
			}
		}
	}

	/**
	 * @param array $content
	 *
	 * @return string
	 */
	protected function getOptionalTableHeader(array $content) {
		if($content['header']) {
			return FormField::create_tag(
				'thead', array(), $content['header']
			);
		}

		return '';
	}

	/**
	 * @param array $content
	 *
	 * @return string
	 */
	protected function getOptionalTableBody(array $content) {
		if($content['body']) {
			return FormField::create_tag(
				'tbody', array('class' => 'ss-gridfield-items'), $content['body']
			);
		}

		return '';
	}

	/**
	 * @param $content
	 *
	 * @return string
	 */
	protected function getOptionalTableFooter($content) {
		if($content['footer']) {
			return FormField::create_tag(
				'tfoot', array(), $content['footer']
			);
		}

		return '';
	}

}