\Dewdrop\Fields\ListingCounter

The Counter class assists in the creation of a simple kind of report that comes up frequently in data-heavy projects: group by a field and display the number of records that have a given value for that field. For example, if you had a database containing many people and their preferred shirt sizes, you could supply this class with the shirt_size_id field object, the full collection of Fields from your component and a Listing that would normally fetch all the people and their shirt sizes. Combining the data from the fetchData() method in this class with the Fields from its buildRenderFields() method, you could use those objects to easily render a table showing how many users requested a Small shirt, a Medium shirt, etc.

To accomplish this task, this class disables the pagination helper on the Listing and fetches all its data. It then iterates over the data, rendering the content for the $groupField using either a TableCell or CsvCell renderer helper. Using the output from that renderer, it groups the results and counts them. The Counter class takes this approach rather than attempting to manipulate the Listing's SQL to add a GROUP BY and COUNT(*) because using the rendered output maps more closely to the user's expectations, prevents potential bugs when the rendering code for the grouping field references multiple database columns, and avoids problems that could be introduced if the original Listing SQL was already using aggregate functions.

This design does, however, potentially introduce performance concerns if you have a very large number of records returned from your Listing's SQL statement. Because all records are fetched from the Listing and the contents rendered for each of those records for the $groupField, you may not be able to get an adequate response time out of this class without further caching. So just keep that in mind before using Counter in your user-facing components.

Summary

Methods
Properties
Constants
__construct()
buildRenderFields()
fetchData()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
$groupField
$fields
$listing
N/A

Properties

$groupField

$groupField : \Dewdrop\Fields\FieldInterface

The field by which records should be grouped before they are counted.

Type

\Dewdrop\Fields\FieldInterface

$fields

$fields : \Dewdrop\Fields

The fields used when fetching data from the Listing. Needed so the Listing can apply filters, etc.

Type

\Dewdrop\Fields

$listing

$listing : \Dewdrop\Fields\Listing

The Listing from which we'll fetch the raw data which will then be grouped and counted.

Type

\Dewdrop\Fields\Listing

Methods

__construct()

__construct(\Dewdrop\Fields\FieldInterface  $groupField, \Dewdrop\Fields  $fields, \Dewdrop\Fields\Listing  $listing) 

Supply the dependencies for the Counter: a field by which the user would like to group the Listing's data before counting, the Fields the Listing will use for filtering and sorting when fetching data, and the Listing itself.

Parameters

\Dewdrop\Fields\FieldInterface $groupField
\Dewdrop\Fields $fields
\Dewdrop\Fields\Listing $listing

buildRenderFields()

buildRenderFields() : \Dewdrop\Fields

Build a Fields object that can be used when rendering the grouped counts. Supplies a field to render the actual HTML value from the original Fields object used when fetching data for the listing and a field to render the count for that value. We don't do any escaping here because we assume that the original Fields object handled that in its rendering code. The fields object returned from this method supports both TableCell and CsvCell rendering.

Returns

\Dewdrop\Fields

fetchData()

fetchData(\Dewdrop\Fields\Helper\CellRendererInterface  $renderer) : array

This is the core of the Counter class. The overall logic implemented in this method is explained in detail in the primary docblock for this class.

The array returned from this method will contain one associative array for each distinct value of the $groupField found: the content for that field as generated by the supplied $renderer and the count of records that had that value.

Parameters

\Dewdrop\Fields\Helper\CellRendererInterface $renderer

Returns

array