PHP Class Piwik\Plugin\Visualization
Report visualizations that extend from this class will be displayed like all others in
the Piwik UI. The following extra UI controls will be displayed around the visualization
itself:
- report documentation,
- a footer message (if {@link Piwik\ViewDataTable\Config::$show_footer_message} is set),
- a list of links to related reports (if {@link Piwik\ViewDataTable\Config::$related_reports} is set),
- a button that allows users to switch visualizations,
- a control that allows users to export report data in different formats,
- a limit control that allows users to change the amount of rows displayed (if
{@link Piwik\ViewDataTable\Config::$show_limit_control} is true),
- and more depending on the visualization.
### Rendering Process
The following process is used to render reports:
- The report is loaded through Piwik's Reporting API.
- The display and request properties that require report data in order to determine a default
value are defaulted. These properties are:
- {@link Piwik\ViewDataTable\Config::$columns_to_display}
- {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_column}
- {@link Piwik\ViewDataTable\RequestConfig::$filter_sort_order}
- Priority filters are applied to the report (see {@link Piwik\ViewDataTable\Config::$filters}).
- The filters that are applied to every report in the Reporting API (called **generic filters**)
are applied. (see {@link Piwik\API\Request})
- The report's queued filters are applied.
- A {@link Piwik\View} instance is created and rendered.
### Rendering Hooks
The Visualization class defines several overridable methods that are called at specific
points during the rendering process. Derived classes can override these methods change
the data that is displayed or set custom properties.
The overridable methods (called **rendering hooks**) are as follows:
- **beforeLoadDataTable**: Called at the start of the rendering process before any data
is loaded.
- **beforeGenericFiltersAreAppliedToLoadedDataTable**: Called after data is loaded and after priority
filters are called, but before other filters. This
method should be used if you need the report's
entire dataset.
- **afterGenericFiltersAreAppliedToLoadedDataTable**: Called after generic filters are applied, but before
queued filters are applied.
- **afterAllFiltersAreApplied**: Called after data is loaded and all filters are applied.
- **beforeRender**: Called immediately before a {@link Piwik\View} is created and rendered.
- **isThereDataToDisplay**: Called after a {@link Piwik\View} is created to determine if the report has
data or not. If not, a message is displayed to the user.
### The DataTable JavaScript class
In the UI, visualization behavior is provided by logic in the **DataTable** JavaScript class.
When creating new visualizations, the **DataTable** JavaScript class (or one of its existing
descendants) should be extended.
To learn more read the
Visualizing Report Data
guide.
### Examples
**Changing the data that is loaded**
class MyVisualization extends Visualization
{
load the previous period's data as well as the requested data. this will change
$this->dataTable from a DataTable instance to a DataTable\Map instance.
public function beforeLoadDataTable()
{
$date = Common::getRequestVar('date');
list($previousDate, $ignore) = Range::getLastDate($date, $period);
$this->requestConfig->request_parameters_to_modify['date'] = $previousDate . ',' . $date;
}
since we load the previous period's data too, we need to override the logic to
check if there is data or not.
public function isThereDataToDisplay()
{
$tables = $this->dataTable->getDataTables()
$requestedDataTable = end($tables);
return $requestedDataTable->getRowsCount() != 0;
}
}
**Force properties to be set to certain values**
class MyVisualization extends Visualization
{
ensure that some properties are set to certain values before rendering.
this will overwrite any changes made by plugins that use this visualization.
public function beforeRender()
{
$this->config->max_graph_elements = false;
$this->config->datatable_js_type = 'MyVisualization';
$this->config->show_flatten_table = false;
$this->config->show_pagination_control = false;
$this->config->show_offset_information = false;
}
}
显示文件
Open project: piwik/piwik
Class Usage Examples
Protected Properties
Public Methods
Protected Methods
Private Methods
Method Details
__construct()
final public method
final public __construct ( $controllerAction, $apiMethodToRequestDataTable, $params = [] ) |
afterAllFiltersAreApplied()
public method
Use this method to format the report data before the view is rendered.
afterGenericFiltersAreAppliedToLoadedDataTable()
public method
Hook that is executed after generic filters are applied.
assignTemplateVar()
public method
Assigns a template variable making it available in the Twig template specified by
{@link TEMPLATE_FILE}.
beforeGenericFiltersAreAppliedToLoadedDataTable()
public method
Use this method if you need access to the entire dataset (since generic filters will
limit and truncate reports).
beforeLoadDataTable()
public method
Use this method to change the request parameters that is sent to the API when requesting
data.
beforeRender()
public method
Hook that is executed directly before rendering. Use this hook to force display properties to
be a certain value, despite changes from plugins and query parameters.
buildApiRequestArray()
public method
getClientSideParametersToSet()
protected method
This array defines things such as:
- name of the module & action to call to request data for this table
- optional filters information, eg. filter_limit and filter_offset
- etc.
The values are loaded:
- from the generic filters that are applied by default @see Piwik\API\DataTableGenericFilter::getGenericFiltersInformation()
- from the values already available in the GET array
- from the values set using methods from this class (eg. setSearchPattern(), setLimit(), etc.)
isThereDataToDisplay()
protected method
Derived classes should override this method if they change the amount of data that is loaded.
loadDataTableFromAPI()
protected method
Property Details
$report protected_oe property
protected Report,Piwik\Plugin $report |
return |
Report |
|