Creates and returns a Hublify Datatable-Object.


Functions

Following functions are available for an datatable-instance:

analyzeFields(...)

Analyzes and summarizes fields (columns) of previously set data.

It calculates and caches internally per each field given, following values:

  • "sum"
  • "min"
  • "max"
  • "avg"
  • "cntNotEmpty" - int Number or data-rows that this value was not null or empty.
  • "cntEmpty" - int Number of data-rows where this value was undefined, null or empty (string).

This function is also internally used, when header/footer summary-rows are enabled.

Syntax

analyzeFields(?array $fields): hublify_var_ext_datatable

  • $fields
    Numerical array of the field-labels (columns) you want to analyze.


cellTplStr(...)

Sets a custom twig-template to format the complete cell-container and values for a given field.

Syntax

cellTplStr(string $field, ?string $tplStr): hublify_var_ext_datatable

  • $field
    The field to apply this to.

  • $tplStr
    The twig-template string that shall render the container and value for a cell-container.
    In this template string you must provide the container-html-elements for this cell, such as "<td>" or similar!

The twig-Template-String gets automatically injected following variables:

  • value - mixed The actual raw-data-value
  • field - string The field label (= $field)
  • row - array The complete data-row as an associative array.
  • prevValue - mixed The previous row's field value. Use this e.g. to detect whether this value is same or different than in previous row.
  • line - integer The current line number on rendering (1 ... n).
  • summary - array Optional summary array for this field. Regard: You have to call function analyzeFields(...) beforehand. Otherwise this summary might not be present or filled!


dataset(...)

Setting the internal dataset-label to which the fields & data belong to.


fieldDefinition(...)

Set a field definition for one field.

Syntax

fieldDefinition(string $field, $definition): hublify_var_ext_datatable

$definition can have following properties:

  • "type"
  • "sub_type"
  • "formatter"
  • "formatterTplStr"
  • "cellTplStr"


fieldDefinitions(...)

Sets multiple field definitions at once.

Syntax

fieldDefinitions(array $definitions): hublify_var_ext_datatable


fields(...)

Configures which fields of the data shall be rendered as datatable-columns.

Syntax

fields(array|null $fields) : hublify_var_ext_datatable

  • $fields
    Numerical array of field-labels to be rendered.
    The given order of the fields is regarded on rendering.
    NULL resets this filtering setting and resets the rendering all found fields in the data-array.


formatterTpl(...)

Defines a custom twig-template-file to render the values for a given field.

Syntax

formatterTplStr(string $field, ?string $tplFile, ?array $tplParams = null): hublify_var_ext_datatable

  • $field
    The field to apply this to.

  • $tplFile
    The twig-template-file to be used that shall render the value within the (<td>-) cell-container.
    In this template string you must not provide any container-html-elements for this cell, such as "<td>" or similar!
    E.g. "@hublify/app/some/path/to/_myFieldFormatter.html.twig"

  • $tplParams
    Optional array/object of parameters injected into the twig-template as variables for rendering.
    Attention this variables get merged with the standard variables, described below!

The twig-Template-String gets automatically injected following variables:

  • value - mixed The actual raw-data-value
  • field - string The field label (= $field)
  • row - array The complete data-row as an associative array.
  • prevValue - mixed The previous row's field value. Use this e.g. to detect whether this value is same or different than in previous row.
  • line - integer The current line number on rendering (1 ... n).
  • summary - array Optional summary array for this field. Regard: You have to call function analyzeFields(...) beforehand. Otherwise this summary might not be present or filled!


formatterTplId(...)

Defines a custom twig-template-file defined by its indexed ID within the Hublify-CMS to render the values for a given field.

Syntax

formatterTplStr(string $field, ?string $tplId, ?array $tplParams = null): hublify_var_ext_datatable

  • $field
    The field to apply this to.

  • $tplId
    The twig-template's ID that shall render the value within the (<td>-) cell-container.
    In this template string you must not provide any container-html-elements for this cell, such as "<td>" or similar!

  • $tplParams
    Optional array/object of parameters injected into the twig-template as variables for rendering.
    Attention this variables get merged with the standard variables, described below!

The twig-Template-String gets automatically injected following variables:

  • value - mixed The actual raw-data-value
  • field - string The field label (= $field)
  • row - array The complete data-row as an associative array.
  • prevValue - mixed The previous row's field value. Use this e.g. to detect whether this value is same or different than in previous row.
  • line - integer The current line number on rendering (1 ... n).
  • summary - array Optional summary array for this field. Regard: You have to call function analyzeFields(...) beforehand. Otherwise this summary might not be present or filled!


formatterTplStr(...)

Sets a custom inline twig-template to format the values for a given field.

Syntax

formatterTplStr(string $field, ?string $tplStr, ?array $tplParams = null): hublify_var_ext_datatable

  • $field
    The field to apply this to.

  • $tplStr
    The twig-template string that shall render the value within the (<td>-) cell-container.
    In this template string you must not provide any container-html-elements for this cell, such as "<td>" or similar!

  • $tplParams
    Optional array/object of parameters injected into the twig-template as variables for rendering.
    Attention this variables get merged with the standard variables, described below!

The twig-Template-String gets automatically injected following variables:

  • value - mixed The actual raw-data-value
  • field - string The field label (= $field)
  • row - array The complete data-row as an associative array.
  • prevValue - mixed The previous row's field value. Use this e.g. to detect whether this value is same or different than in previous row.
  • line - integer The current line number on rendering (1 ... n).
  • summary - array Optional summary array for this field. Regard: You have to call function analyzeFields(...) beforehand. Otherwise this summary might not be present or filled!


formatValue(...)

Renders a formatted value, defined by its field's (formatter) definition.

This function is primarily used internally.

Syntax

formatValue($value, $field = null): array

Returns

[str] - The formatted value

[align] - "left|center|right"


group(...)

Sets a field for grouping rows.

Syntax

group(string $groupField, array $params = null): hublify_var_ext_datatable


groups(...)

Sets multiple fields for grouping

Syntax

function groups(array $groups): hublify_var_ext_datatable


hasField(...)

Returns whether a field currently known within the data.

Syntax

hasField(string $field): bool


setLocale(...)

Sets the locale-string for this dataTable, for later data-formatting.

On dataTable-initialization the render-environment's locale-setting is automatically set.

Syntax

locale(?string $locale): hublify_var_ext_datatable

$locale can be e.g. "de-DE". If NULL localization is disabled.


params(...)

This function can be used to set many datatable-configurations at once.

This can be called multiple times.

Syntax

params(array $params): hublify_var_ext_datatable

Optional keys within $params are:

  • [dataset] - string The dataset label. See details in function dataset(...).
  • [lineNumbers] - bool
  • [columnHeaders] - bool
  • [sumHeader] - bool
  • [sumFooter] - bool
  • [fields] - string[] The fields (columns) to render. See details in function fields(...)
  • [fieldDefinitions] - string[][] See params-details in function fieldDefinitions(...).
  • [groups] - string[][] To enable render grouping. See details in function groups(...)
  • [sorts] - array[] See params-details in function sorts(...).
  • [locale] -string|null Sets the localization, e.g. "de-DE". NULL disabled localization.
  • [htmlTableClass] - string
  • [htmlTableStyle] - string

Optional keys within $params, used for render_csv():

  • [csvDelimiter] - string Optional delimiter-string, default: ';'
  • [csvEnclosure] - string Optional field-value enclosure-string, default: '"'
  • [csvEscape] - string Optional Escape-Character-string, default: '\\'
  • [csvEol] - string Optional End-of-Line-string, default: '\n;'
  • [csvBom] - boolean If TRUE then preceding BOM-Sequence is written into the resulting string.


render()

Renders the complete datatable into a string.

Syntax

render(): string


render_csv()

Renders the complete datatable in CSV-format into a string.

See function params(...) and all available "csv..."-settings for e.g. "delimiter", "enclosure", "BOM", ... etc.

Syntax

render_csv(): string


setData(...)

Sets the data to rendered as a datatable.

Regard: Which fields (aka columns) are finally being rendered and in which order can configured with the datatable-functions.

Syntax

setData($data): hublify_var_ext_datatable

$data - Two dimensional array.


setHtmlTableClass(...)

Sets the css-class-string that is usually injected into the <table ...>-element.

Syntax

setHtmlTableClass($cssClassStr = null): hublify_var_ext_datatable


sort(...)

Executes a sorting of the data on the given field. This is applied immediately to the contained data.

Syntax

sort(string $field, string $dir = 'asc'): hublify_var_ext_datatable


sorts(...)

Executes a multi-field sort. This is applied immediately to the contained data.

Syntax

sorts(array $params): hublify_var_ext_datatable

$params

@param array $params An array of fields and their sorting direction.
[
  {
    'field': '<field>',     // (required)
    'dir': '<asc|desc>'     // (optional, default "asc")
  },
  ...
]


Properties

HTML Templating

Following properties are used to render the actual html-table source code.


PropertyDefaultDescription
htmlTableOpen<table{%class%}{%style%}>
htmlTableClasshfyDataTableSets the css class for the opening <table>-tag.
htmlTableStylenullSets the css style for the opening <table>-tag.
htmlTableClose</table>
htmlHeaderOpen<thead>
htmlHeadereClose</thead>
htmlHeaderCellOpen<th{%class%}{%style%}{%attr%}>
htmlHeaderCellClose</th>
htmlBodyOpen<tbody>
htmlBodyClose</tbody>
htmlRowDataOpen<tr>
htmlRowDataClose</tr>
htmlDataCellOpen<td{%class%}{%style%}{%attr%}>
htmlDataCellClose</td>
htmlRowGroupOpen<tr class="hfyRowGroup">
htmlRowGroupClose</tr>
htmlFooterOpen<tfoot>
htmlFooterClose</tfoot>


Examples

Simple

A very simple example. Pure data - no extra configurations.

{# ---- Defining some static data ---- #}
{% set myData = [
     {
         'col1': 'Hello',
         'col2': 'World!',
         'col3': 10
     },
     {
         'col1': 'Aloha',
         'col2': 'Hublify!',
         'col3': 50
     },
     {
         'col1': 'Caramba ',
         'col2': 'Caracho!',
         'col3': 100
     },
   ] 
%}

{# ---- Creating a datatable-object ---- #}
{% set myDataTable = hublify.datatable(myData) %}

{# ---- Render the datatable ---- #}
{{ myDataTable }}



Example #2

Mixture of

{{ hublify.datatable( myStorageItemDataList )
            .dataset('storageitem')
            .fields([ 'si_name', 'si_amount_nominal', 'si_amount_reorder' ])
            .params({
                'lineNumbers': true,
                'columnHeaders': true,
                'sumsHeader': true,
                'sumsFooter': true,
            })
            .fieldDefinition('si_amount_nominal', {
                'type': 'float',
                'name': 'Nominal',
                'htmlHeader': null,
                'formatter': null,
                'formatterParams': null,
            })
            .fieldDefinition('si_amount_reorder', {
                'type': 'float',
                'htmlHeader': '&#10004;',
            })
            .group('node_path')
            .sorts([
                { 'field': 'si_amount_nominal', 'dir': 'desc' },
                { 'field': 'si_name' }
            ])
        }}


Simple - CSV

A very simple example, written as a CSV-string.

{# ---- Defining some static data ---- #}
{% set myData = [
     {
         'col1': 'Hello',
         'col2': 'World!',
         'col3': 10
     },
     {
         'col1': 'Aloha',
         'col2': 'Hublify!',
         'col3': 50
     },
     {
         'col1': 'Caramba ',
         'col2': 'Caracho!',
         'col3': 100
     },
   ] 
%}

{# ---- Creating a datatable-object ---- #}
{% set myDataTable = hublify.datatable(myData) %}

{# ---- Render (as CSV!) the datatable ---- #}
{{ myDataTable.render_csv() }}


Custom Formatter

You can easily define own mini-twig-templates to render your field's content.

{# ---- Defining some static data ---- #}
{% set myData = [
     {
         'col1': 'Hello',
         'col2': 'World!',
     },
     {
         'col1': 'Aloha',
         'col2': 'Hublify!',
     },
     {
         'col1': 'Caramba ',
         'col2': 'Caracho!',
     },
   ] 
%}

{{ hublify.dataTable(myData)
  .formatterTplStr('col1', '<b>{{ value }}</b>')
}}

You can also pass arrays as values.

{# ---- Defining some static data ---- #}
{% set myData = [
     {
         'col1': {
             'firstname': 'Jane',
             'lastname': 'Doe'
         },
         'col2': 'World!',
     },
     {
         'col1': {
             'firstname': 'John',
             'lastname': 'Smith'
         },
         'col2': 'Hublify!',
     }
   ] 
%}

{{ hublify.dataTable(myData)
  .formatterTplStr('col1', '<b>{{ value.firstname }} {{ value.lastname }}</b>')
}}