README

Message\Mothership\Report cogule提供了一种在新标签页中提供报告的框架。

创建新报告

注册报告

在模块的Service容器中注册您的报告。这是MS-User中的代码示例

public function registerReports($services)
{
	$services['user.user_summary'] = $services->factory(function($c) {
		return new User\Report\UserSummary(
			$c['db.query.builder.factory'],
			$c['routing.generator']
		);
	});

	$services['user.reports'] = function($c) {
		$reports = new ReportCollection;
		$reports
			->add($c['user.user_summary'])
		;
			return $reports;
	};
}

创建报告

如果不存在，在Src中创建一个名为Reports的文件夹。此模块的所有报告都将保存在这里。

初始设置

所有报告都必须扩展AbstractReport，并将使用

Message\Cog\DB\QueryBuilderInterface;
Message\Cog\DB\QueryBuilderFactory;
Message\Cog\Routing\UrlGenerator;

构造函数

设置

name：用作标识符并为下载文件命名。
displayName：用于前端。
description：用于前端。
reportGroup：用于在仪表板上对类似的报告进行分组。

设置报告中要使用的所有过滤器和图表。

设置报告首次查看时想要使用的任何默认过滤器。

此报告显示TableChart，并使用过滤器DateRange和Choices。它将表单默认的StartDate设置为一个月前。

		parent::__construct($builderFactory, $routingGenerator);
		$this->_setName('payments_refunds');
		$this->_setDisplayName('Payments & Refunds');
		$this->_setReportGroup('Transactions');
		$this->_setDescription('
			This report displays all payments & refunds.
			By default it includes all data from the last month (by completed date).
		');
		$this->_charts[]   = new TableChart;
		$this->_filters->add(new DateRange);
		$startDate = new \DateTime;
		$this->getFilters()
			->get('date_range')
			->setStartDate($startDate->setTimestamp(strtotime(date('Y-m-d H:i')." -1 month")));
		// Params for Choices filter: unique filter name, label, choices, multi-choice
		$this->_filters->add(new Choices(
			"type",
			"Type",
			[
				'payment' => 'Payment',
				'refund' => 'Refund',
			],
			false
		));
	}

getCharts()

所有报告都需要此功能

public function getCharts()
{
	$data = $this->_dataTransform($this->_getQuery()->run(), "json");
	$columns = $this->_parseColumns($this->getColumns());
		foreach ($this->_charts as $chart) {
		$chart->setColumns($columns);
		$chart->setData($data);
	}
	return $this->_charts;
}

getColumns()

将所需的所有列设置到一个数组中，键为名称，值为期望的数据类型。此类型用于Google Charts。

public function getColumns()
{
	return [
		'Date'         => 'string',
		'Created by'   => 'string',
		'Currency'     => 'string',
		'Method'       => 'string',
		'Amount'       => 'number',
		'Type'         => 'string',
		'Order/Return' => 'string',
	];
}

_getQuery()

使用QueryBuilder创建您的报告查询。一个简单的示例是用户摘要报告

protected function _getQuery()
{
	$queryBuilder = $this->_builderFactory->getQueryBuilder();
		$queryBuilder
		->select('user.user_id AS "ID"')
		->select('created_at AS "Created"')
		->select('CONCAT(surname,", ",forename) AS "User"')
		->select('email AS "Email"')
		->from('user')
		->orderBy('surname')
	;

	return $queryBuilder->getQuery();
}

_dataTransform()

此操作将查询中的数据转换为JSON格式的字符串以用于Google Charts，或简单的数组以用于CSV下载。

对于更复杂的数据，您可能需要传递一些可选属性。请参阅：https://developers.google.com/chart/interactive/docs/reference#cell_object

例如，要按数值顺序而不是按字母顺序对日期进行排序，您需要将时间戳作为value发送，但将字符串作为formatted value。

[
	'v' => $row->Created,
	'f' => date('Y-m-d H:i', $row->Created)
],

另一个示例是货币值

[
	'v' => (float) $row->Gross,
	'f' => (string) number_format($row->Gross,2,'.',',')
],

对于链接，如果您只发送html链接作为value，则将使用完整的html而不是显示文本来排序值。如果文本是用于创建URL的相同值，这很好。但在大多数情况下，ID不是将要显示的内容。在这种情况下，用户名作为value发送，而使用用户-id的html作为formatted value发送。

[
	'v' => utf8_encode($row->User),
	'f' => (string) '
		<a href ="'.$this->generateUrl('ms.cp.user.admin.detail.edit',
		['userID' => $row->ID]).'">'
		.ucwords(utf8_encode($row->User)).'</a>'
]

任何可能包含特殊字符的字符串都需要编码为UTF-8，如上例中用户操作所示。

用户摘要报告中使用的完整代码

	protected function _dataTransform($data, $output = null)
	{
		$result = [];

		if ($output === "json") {

			foreach ($data as $row) {

				$result[] = [
					$row->User ? [
						'v' => utf8_encode($row->User),
						'f' => (string) '<a href ="'.$this->generateUrl('ms.cp.user.admin.detail.edit', ['userID' => $row->ID]).'">'.ucwords(utf8_encode($row->User)).'</a>'
					] : $row->User,
					$row->Email,
					[
						'v' => $row->Created,
						'f' => date('Y-m-d H:i', $row->Created)
					],
				];

			}
			return json_encode($result);

		} else {

			foreach ($data as $row) {
				$result[] = [
					utf8_encode($row->User),
					$row->Email,
					date('Y-m-d H:i', $row->Created),
				];
			}
			return $result;

		}
	}

过滤器

日期范围

此功能包含两个日期时间表单字段，用于选择两个日期之间的数据范围。

日期

这是一个单独的日期表单字段，用于选择特定日期的数据。

选择项

根据报告中的数据，可以自定义“选择项”表单字段。

添加选择项表单时，必须添加以下参数

唯一的过滤器名称，它不能与其他报告相同
表单上显示的标签
选择项
该字段是否为多选

$this->_filters->add(new Choices(
	"type",
	"Sale Type",
		[
			'Order' => 'Order',
			'Return' => 'Return',
			'Exchange' => 'Exchange',
			'shipping' => 'Shipping',
		],
	true
));

图表

表格

TableChart是当前唯一的图表。 https://developers.google.com/chart/interactive/docs/gallery/table

mothership-ec / cog-mothership-reports

维护者

详细信息