silverstripe-reports/code/Report.php

503 lines
15 KiB
PHP
Raw Normal View History

2013-01-17 01:22:13 +01:00
<?php
2016-06-16 07:06:51 +02:00
namespace SilverStripe\Reports;
2017-06-21 06:30:14 +02:00
use ReflectionClass;
2017-12-14 01:37:25 +01:00
use SilverStripe\CMS\Model\SiteTree;
use SilverStripe\Control\Controller;
2017-12-14 01:37:25 +01:00
use SilverStripe\Control\HTTPRequest;
use SilverStripe\Core\ClassInfo;
2017-06-21 06:30:14 +02:00
use SilverStripe\Core\Convert;
2017-12-14 01:37:25 +01:00
use SilverStripe\Core\Injector\Injector;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\FormAction;
2017-12-14 01:37:25 +01:00
use SilverStripe\Forms\FormField;
2017-06-21 06:30:14 +02:00
use SilverStripe\Forms\GridField\GridField;
use SilverStripe\Forms\GridField\GridFieldButtonRow;
2017-06-21 06:30:14 +02:00
use SilverStripe\Forms\GridField\GridFieldConfig;
use SilverStripe\Forms\GridField\GridFieldDataColumns;
2017-06-21 06:30:14 +02:00
use SilverStripe\Forms\GridField\GridFieldExportButton;
use SilverStripe\Forms\GridField\GridFieldPaginator;
2017-06-21 06:30:14 +02:00
use SilverStripe\Forms\GridField\GridFieldPrintButton;
use SilverStripe\Forms\GridField\GridFieldSortableHeader;
use SilverStripe\Forms\LiteralField;
use SilverStripe\ORM\ArrayList;
use SilverStripe\ORM\CMSPreviewable;
2017-12-14 01:37:25 +01:00
use SilverStripe\ORM\DataList;
use SilverStripe\ORM\DataQuery;
2017-06-21 06:30:14 +02:00
use SilverStripe\ORM\SS_List;
use SilverStripe\Security\Member;
use SilverStripe\Security\Permission;
2017-06-09 06:48:30 +02:00
use SilverStripe\Security\Security;
use SilverStripe\View\ArrayData;
use SilverStripe\View\ViewableData;
2017-12-14 01:32:50 +01:00
2013-01-17 01:22:13 +01:00
/**
* Base "abstract" class creating reports on your data.
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* Creating reports
* ================
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* Creating a new report is a matter overloading a few key methods
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* {@link title()}: Return the title - i18n is your responsibility
* {@link description()}: Return the description - i18n is your responsibility
* {@link sourceQuery()}: Return a SS_List of the search results
* {@link columns()}: Return information about the columns in this report.
* {@link parameterFields()}: Return a FieldList of the fields that can be used to filter this
* report.
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* If you wish to modify the report in more extreme ways, you could overload these methods instead.
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* {@link getReportField()}: Return a FormField in the place where your report's TableListField
* usually appears.
2016-06-16 07:06:51 +02:00
* {@link getCMSFields()}: Return the FieldList representing the complete right-hand area of the
2013-01-17 01:22:13 +01:00
* report, including the title, description, parameter fields, and results.
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* Showing reports to the user
* ===========================
2016-06-16 07:06:51 +02:00
*
2013-01-17 01:22:13 +01:00
* Right now, all subclasses of SS_Report will be shown in the ReportAdmin. In SS3 there is only
2015-07-22 11:53:55 +02:00
* one place where reports can go, so this class is greatly simplifed from its version in SS2.
2017-12-14 01:37:25 +01:00
*
* @method SS_List|DataList sourceRecords($params = [], $sort = null, $limit = null) List of records to show for this report
2013-01-17 01:22:13 +01:00
*/
2016-09-09 08:11:38 +02:00
class Report extends ViewableData
2015-12-15 23:06:45 +01:00
{
2016-07-29 00:44:00 +02:00
/**
* This is the title of the report,
* used by the ReportAdmin templates.
*
* @var string
*/
protected $title = '';
/**
* This is a description about what this
* report does. Used by the ReportAdmin
* templates.
*
* @var string
*/
protected $description = '';
/**
* The class of object being managed by this report.
* Set by overriding in your subclass.
*/
2017-12-14 01:37:25 +01:00
protected $dataClass = SiteTree::class;
2016-07-29 00:44:00 +02:00
/**
* A field that specifies the sort order of this report
* @var int
*/
protected $sort = 0;
/**
* Reports which should not be collected and returned in get_reports
*
* @config
2016-07-29 00:44:00 +02:00
* @var array
*/
private static $excluded_reports = [
self::class,
ReportWrapper::class,
SideReportWrapper::class,
];
2016-07-29 00:44:00 +02:00
/**
* Return the title of this report.
*
* You have two ways of specifying the description:
* - overriding description(), which lets you support i18n
* - defining the $description property
*/
2015-12-15 23:06:45 +01:00
public function title()
{
2016-07-29 00:44:00 +02:00
return $this->title;
}
/**
* Allows access to title as a property
*
* @return string
*/
2015-12-15 23:06:45 +01:00
public function getTitle()
{
2016-07-29 00:44:00 +02:00
return $this->title();
}
/**
* Return the description of this report.
*
* You have two ways of specifying the description:
* - overriding description(), which lets you support i18n
* - defining the $description property
*/
2015-12-15 23:06:45 +01:00
public function description()
{
2016-07-29 00:44:00 +02:00
return $this->description;
}
2016-06-16 07:06:51 +02:00
2016-07-29 00:44:00 +02:00
/**
2017-12-14 01:37:25 +01:00
* Return the {@link DataQuery} that provides your report data.
*
* @param array $params
* @return DataQuery
2016-07-29 00:44:00 +02:00
*/
2015-12-15 23:06:45 +01:00
public function sourceQuery($params)
{
if (!$this->hasMethod('sourceRecords')) {
throw new \RuntimeException(
'Please override sourceQuery()/sourceRecords() and columns() or, if necessary, override getReportField()'
);
2016-07-29 00:44:00 +02:00
}
return $this->sourceRecords($params, null, null)->dataQuery();
2016-07-29 00:44:00 +02:00
}
/**
* Return a SS_List records for this report.
2017-12-14 01:37:25 +01:00
*
* @param array $params
* @return SS_List
2016-07-29 00:44:00 +02:00
*/
2015-12-15 23:06:45 +01:00
public function records($params)
{
2016-07-29 00:44:00 +02:00
if ($this->hasMethod('sourceRecords')) {
return $this->sourceRecords($params, null, null);
} else {
$query = $this->sourceQuery($params);
$results = ArrayList::create();
2016-07-29 00:44:00 +02:00
foreach ($query->execute() as $data) {
$class = $this->dataClass();
$result = Injector::inst()->create($class, $data);
2016-07-29 00:44:00 +02:00
$results->push($result);
}
return $results;
}
}
public function columns()
{
return [];
}
2016-07-29 00:44:00 +02:00
/**
* Return the data class for this report
*/
2015-12-15 23:06:45 +01:00
public function dataClass()
{
2016-07-29 00:44:00 +02:00
return $this->dataClass;
}
2015-12-15 23:06:45 +01:00
public function getLink($action = null)
{
2016-07-29 00:44:00 +02:00
return Controller::join_links(
ReportAdmin::singleton()->Link('show'),
2016-09-28 00:34:42 +02:00
$this->sanitiseClassName(static::class),
2016-07-29 00:44:00 +02:00
$action
);
}
2015-12-15 23:06:45 +01:00
2017-06-21 06:30:14 +02:00
/**
* Sanitise a model class' name for inclusion in a link
*
* @param string $class
* @return string
*/
protected function sanitiseClassName($class)
{
return str_replace('\\', '-', $class);
}
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
/**
2015-12-15 23:06:45 +01:00
* counts the number of objects returned
2016-09-09 08:11:38 +02:00
* @param array $params - any parameters for the sourceRecords
* @return int
2015-12-15 23:06:45 +01:00
*/
public function getCount($params = array())
{
$sourceRecords = $this->sourceRecords($params, null, null);
if (!$sourceRecords instanceof SS_List) {
2016-09-28 00:34:42 +02:00
user_error(static::class . "::sourceRecords does not return an SS_List", E_USER_NOTICE);
2015-12-15 23:06:45 +01:00
return "-1";
}
return $sourceRecords->count();
}
2016-07-29 00:44:00 +02:00
/**
* Return an array of excluded reports. That is, reports that will not be included in
* the list of reports in report admin in the CMS.
*
2016-07-29 00:44:00 +02:00
* @return array
*/
2015-12-15 23:06:45 +01:00
public static function get_excluded_reports()
{
return (array) self::config()->get('excluded_reports');
2016-07-29 00:44:00 +02:00
}
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
/**
* Return the SS_Report objects making up the given list.
2017-12-14 01:37:25 +01:00
*
* @return Report[] Array of Report objects
2016-07-29 00:44:00 +02:00
*/
2015-12-15 23:06:45 +01:00
public static function get_reports()
{
2016-07-29 00:44:00 +02:00
$reports = ClassInfo::subclassesFor(get_called_class());
2015-12-15 23:06:45 +01:00
$reportsArray = [];
2016-07-29 00:44:00 +02:00
if ($reports && count($reports) > 0) {
$excludedReports = static::get_excluded_reports();
// Collect reports into array with an attribute for 'sort'
2016-07-29 00:44:00 +02:00
foreach ($reports as $report) {
// Don't use the Report superclass, or any excluded report classes
if (in_array($report, $excludedReports)) {
2015-12-15 23:06:45 +01:00
continue;
}
2016-07-29 00:44:00 +02:00
$reflectionClass = new ReflectionClass($report);
// Don't use abstract classes
2015-12-15 23:06:45 +01:00
if ($reflectionClass->isAbstract()) {
continue;
}
2015-12-15 23:06:45 +01:00
2017-12-14 01:37:25 +01:00
/** @var Report $reportObj */
$reportObj = $report::create();
if ($reportObj->hasMethod('sort')) {
// Use the sort method to specify the sort field
2015-12-15 23:06:45 +01:00
$reportObj->sort = $reportObj->sort();
}
2016-07-29 00:44:00 +02:00
$reportsArray[$report] = $reportObj;
}
}
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
uasort($reportsArray, function ($a, $b) {
2015-12-15 23:06:45 +01:00
if ($a->sort == $b->sort) {
return 0;
} else {
return ($a->sort < $b->sort) ? -1 : 1;
}
2016-07-29 00:44:00 +02:00
});
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
return $reportsArray;
}
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
/////////////////////// UI METHODS ///////////////////////
2015-12-15 23:06:45 +01:00
2016-07-29 00:44:00 +02:00
/**
* Returns a FieldList with which to create the CMS editing form.
* You can use the extend() method of FieldList to create customised forms for your other
* data objects.
*
* @uses getReportField() to render a table, or similar field for the report. This
* method should be defined on the SS_Report subclasses.
*
* @return FieldList
*/
2015-12-15 23:06:45 +01:00
public function getCMSFields()
{
2016-07-29 00:44:00 +02:00
$fields = new FieldList();
2013-01-17 01:22:13 +01:00
2016-07-29 00:44:00 +02:00
if ($description = $this->description()) {
$fields->push(new LiteralField('ReportDescription', "<p>" . $description . "</p>"));
}
2016-06-16 07:06:51 +02:00
2016-07-29 00:44:00 +02:00
// Add search fields is available
if ($this->hasMethod('parameterFields') && $parameterFields = $this->parameterFields()) {
2017-12-14 01:37:25 +01:00
/** @var FormField $field */
2016-07-29 00:44:00 +02:00
foreach ($parameterFields as $field) {
// Namespace fields for easier handling in form submissions
$field->setName(sprintf('filters[%s]', $field->getName()));
$field->addExtraClass('no-change-track'); // ignore in changetracker
$fields->push($field);
}
2013-01-17 01:22:13 +01:00
2016-07-29 00:44:00 +02:00
// Add a search button
$formAction = FormAction::create('updatereport', _t('SilverStripe\\Forms\\GridField\\GridField.Filter', 'Filter'));
$formAction->addExtraClass('btn-primary mb-4');
2016-09-20 07:27:49 +02:00
$fields->push($formAction);
2016-07-29 00:44:00 +02:00
}
2016-06-16 07:06:51 +02:00
2016-07-29 00:44:00 +02:00
$fields->push($this->getReportField());
2013-01-17 01:22:13 +01:00
2016-07-29 00:44:00 +02:00
$this->extend('updateCMSFields', $fields);
2016-06-16 07:06:51 +02:00
2016-07-29 00:44:00 +02:00
return $fields;
}
2016-06-16 07:06:51 +02:00
2015-12-15 23:06:45 +01:00
public function getCMSActions()
{
2016-07-29 00:44:00 +02:00
// getCMSActions() can be extended with updateCMSActions() on a extension
$actions = new FieldList();
$this->extend('updateCMSActions', $actions);
return $actions;
}
/**
* Return a field, such as a {@link GridField} that is
* used to show and manipulate data relating to this report.
*
* Generally, you should override {@link columns()} and {@link records()} to make your report,
* but if they aren't sufficiently flexible, then you can override this method.
*
2016-11-10 14:01:37 +01:00
* @return \SilverStripe\Forms\FormField subclass
2016-07-29 00:44:00 +02:00
*/
2015-12-15 23:06:45 +01:00
public function getReportField()
{
$params = $this->getSourceParams();
2017-11-27 02:29:19 +01:00
$items = $this->sourceRecords($params, null, null);
2016-07-29 00:44:00 +02:00
$gridFieldConfig = GridFieldConfig::create()->addComponents(
new GridFieldButtonRow('before'),
new GridFieldPrintButton('buttons-before-left'),
new GridFieldExportButton('buttons-before-left'),
2017-11-27 02:29:19 +01:00
new GridFieldSortableHeader(),
2016-07-29 00:44:00 +02:00
new GridFieldDataColumns(),
new GridFieldPaginator()
);
/** @var GridField $gridField */
$gridField = GridField::create('Report', null, $items, $gridFieldConfig);
/** @var GridFieldDataColumns $columns */
2017-11-27 02:29:19 +01:00
$columns = $gridField->getConfig()->getComponentByType(GridFieldDataColumns::class);
$displayFields = [];
$fieldCasting = [];
$fieldFormatting = [];
2016-07-29 00:44:00 +02:00
// Parse the column information
foreach ($this->columns() as $source => $info) {
2015-12-15 23:06:45 +01:00
if (is_string($info)) {
2017-11-27 02:29:19 +01:00
$info = ['title' => $info];
2015-12-15 23:06:45 +01:00
}
2016-06-16 07:06:51 +02:00
2015-12-15 23:06:45 +01:00
if (isset($info['formatting'])) {
$fieldFormatting[$source] = $info['formatting'];
}
if (isset($info['csvFormatting'])) {
$csvFieldFormatting[$source] = $info['csvFormatting'];
}
if (isset($info['casting'])) {
$fieldCasting[$source] = $info['casting'];
}
2016-07-29 00:44:00 +02:00
if (isset($info['link']) && $info['link']) {
if (is_callable($info['link'])) {
$fieldFormatting[$source] = $info['link'];
} else {
$fieldFormatting[$source] = function ($value, $item) {
if ($item instanceof CMSPreviewable) {
/** @var CMSPreviewable $item */
return sprintf(
'<a class="grid-field__link-block" href="%s" title="%s">%s</a>',
Convert::raw2att($item->CMSEditLink()),
Convert::raw2att($value),
Convert::raw2xml($value)
);
}
return $value;
};
}
2016-07-29 00:44:00 +02:00
}
2013-01-17 01:22:13 +01:00
2016-07-29 00:44:00 +02:00
$displayFields[$source] = isset($info['title']) ? $info['title'] : $source;
}
$columns->setDisplayFields($displayFields);
$columns->setFieldCasting($fieldCasting);
$columns->setFieldFormatting($fieldFormatting);
2013-01-17 01:22:13 +01:00
2016-07-29 00:44:00 +02:00
return $gridField;
}
2016-06-16 07:06:51 +02:00
2016-07-29 00:44:00 +02:00
/**
* @param Member $member
* @return boolean
*/
2015-12-15 23:06:45 +01:00
public function canView($member = null)
{
if (!$member && $member !== false) {
2017-06-09 06:48:30 +02:00
$member = Security::getCurrentUser();
2016-07-29 00:44:00 +02:00
}
$extended = $this->extendedCan('canView', $member);
if ($extended !== null) {
return $extended;
}
if ($member && Permission::checkMember($member, array('CMS_ACCESS_LeftAndMain', 'CMS_ACCESS_ReportAdmin'))) {
return true;
}
return false;
}
/**
* Helper to assist with permission extension
*
* {@see DataObject::extendedCan()}
*
* @param string $methodName Method on the same object, e.g. {@link canEdit()}
* @param Member|int $member
* @return boolean|null
*/
public function extendedCan($methodName, $member)
{
$results = $this->extend($methodName, $member);
if ($results && is_array($results)) {
// Remove NULLs
2017-06-21 06:30:14 +02:00
$results = array_filter($results, function ($v) {
return !is_null($v);
});
2016-07-29 00:44:00 +02:00
// If there are any non-NULL responses, then return the lowest one of them.
// If any explicitly deny the permission, then we don't get access
if ($results) {
return min($results);
}
}
return null;
}
/**
* Return the name of this report, which is used by the templates to render the name of the report in the report
* tree, the left hand pane inside ReportAdmin.
2016-07-29 00:44:00 +02:00
*
* @return string
*/
2015-12-15 23:06:45 +01:00
public function TreeTitle()
{
2016-07-29 00:44:00 +02:00
return $this->title();
}
/**
* Return additional breadcrumbs for this report. Useful when this report is a child of another.
*
* @return ArrayData[]
*/
public function getBreadcrumbs()
{
return [];
}
/**
* Get source params for the report to filter by
*
* @return array
*/
protected function getSourceParams()
{
$params = [];
if (Injector::inst()->has(HTTPRequest::class)) {
/** @var HTTPRequest $request */
$request = Injector::inst()->get(HTTPRequest::class);
$params = $request->param('filters') ?: $request->requestVar('filters') ?: [];
}
$this->extend('updateSourceParams', $params);
return $params;
}
2013-01-17 01:22:13 +01:00
}