allanmcarvalho/cakephp-datatables

View on GitHub
src/Table/Option/Section/FeaturesOption.php

Summary

Maintainability
A
2 hrs
Test Coverage
<?php
/**
 * Copyright (c) Allan Carvalho 2020.
 * Under Mit License
 * php version 7.2
 *
 * link     https://github.com/allanmcarvalho/cakephp-data-renderer
 * author   Allan Carvalho <allan.m.carvalho@outlook.com>
 */
declare(strict_types = 1);

namespace DataTables\Table\Option\Section;

use Cake\Error\FatalErrorException;
use DataTables\Table\Option\ChildOptionAbstract;
use DataTables\Table\Option\MainOption;

/**
 * Class FeaturesOption
 *
 * @author   Allan Carvalho <allan.m.carvalho@outlook.com>
 * @license  MIT License https://github.com/allanmcarvalho/cakephp-datatables/blob/master/LICENSE
 * @link     https://github.com/allanmcarvalho/cakephp-datatables
 */
final class FeaturesOption extends ChildOptionAbstract {

    /**
     * @var array
     * @inheritDoc
     */
    protected $_mustPrint = [
        'serverSide' => true,
    ];

    /**
     * @var array
     * @inheritDoc
     */
    protected $_config = [
        'autoWidth' => true,
        'deferRender' => false,
        'info' => true,
        'lengthChange' => true,
        'ordering' => true,
        'paging' => true,
        'processing' => false,
        'scrollX' => false,
        'scrollY' => null,
        'searching' => true,
        'serverSide' => true,
        'stateSave' => false,
    ];

    /**
     * Checker method.
     * Enable or disable automatic column width calculation. This can be disabled as an optimisation(it takes a finite
     * amount of time to calculate the widths) if the tables widths are passed in using.
     *
     * @link https://datatables.net/reference/option/autoWidth
     * @return bool
     */
    public function isAutoWidth(): bool {
        return (bool)$this->_getConfig('autoWidth');
    }

    /**
     * Setter method.
     * Enable or disable automatic column width calculation. This can be disabled as an optimisation(it takes a finite
     * amount of time to calculate the widths) if the tables widths are passed in using.
     *
     * @param bool $autoWidth
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/autoWidth
     */
    public function setAutoWidth(bool $autoWidth): MainOption {
        $this->_setConfig('autoWidth', $autoWidth);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * By default, when DataTables loads data from an Ajax or Javascript data source (ajax and data respectively) it
     * will create all HTML elements needed up-front. When working with large data sets, this operation can take a
     * not-insignificant amount of time, particularly in older browsers such as IE6-8. This option allows DataTables to
     * create the nodes (rows and cells in the table body) only when they are needed for a draw.
     *
     * As an example to help illustrate this, if you load a data set with 10,000 rows, but a paging display length of
     * only 10 records, rather than create all 10,000 rows, when deferred rendering is enabled, DataTables will create
     * only 10. When the end user then sorts, pages or filters the data the rows needed for the next display will be
     * created automatically. This effectively spreads the load of creating the rows across the life time of the page.
     *
     * Note that when enabled, it goes without saying that not all nodes will always be available in the table, so when
     * working with API methods such as columns().nodes() you must take this into account. Below shows an example of
     * how to use jQuery delegated events to handle such a situation.
     *
     * @link https://datatables.net/reference/option/deferRender
     * @return bool
     */
    public function isDeferRender(): bool {
        return (bool)$this->_getConfig('deferRender');
    }

    /**
     * Setter method.
     * By default, when DataTables loads data from an Ajax or Javascript data source (ajax and data respectively) it
     * will create all HTML elements needed up-front. When working with large data sets, this operation can take a
     * not-insignificant amount of time, particularly in older browsers such as IE6-8. This option allows DataTables to
     * create the nodes (rows and cells in the table body) only when they are needed for a draw.
     *
     * As an example to help illustrate this, if you load a data set with 10,000 rows, but a paging display length of
     * only 10 records, rather than create all 10,000 rows, when deferred rendering is enabled, DataTables will create
     * only 10. When the end user then sorts, pages or filters the data the rows needed for the next display will be
     * created automatically. This effectively spreads the load of creating the rows across the life time of the page.
     *
     * Note that when enabled, it goes without saying that not all nodes will always be available in the table, so when
     * working with API methods such as columns().nodes() you must take this into account. Below shows an example of
     * how to use jQuery delegated events to handle such a situation.
     *
     * @param bool $deferRender
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/deferRender
     */
    public function setDeferRender(bool $deferRender): MainOption {
        $this->_setConfig('deferRender', $deferRender);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * When this option is enabled, Datatables will show information about the table including information about
     * filtered data if that action is being performed. This option allows that feature to be enabled or disabled.
     *
     * Note that by default the information display is shown below the table on the left, but this can be controlled
     * using dom and CSS).
     *
     * @link https://datatables.net/reference/option/info
     * @return bool
     */
    public function isInfo(): bool {
        return (bool)$this->_getConfig('info');
    }

    /**
     * Setter method.
     * When this option is enabled, Datatables will show information about the table including information about
     * filtered data if that action is being performed. This option allows that feature to be enabled or disabled.
     *
     * Note that by default the information display is shown below the table on the left, but this can be controlled
     * using dom and CSS).
     *
     * @param bool $info
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/info
     */
    public function setInfo(bool $info): MainOption {
        $this->_setConfig('info', $info);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * When pagination is enabled, this option will control the display of an option for the end user to change the
     * number of records to be shown per page. The options shown in the list are controlled by the lengthMenu
     * configuration option.
     *
     * Note that by default the control is shown at the top left of the table. That can be controlled using dom and
     * CSS.
     *
     * If this option is disabled (false) the length change input control is removed - although the page.len() method
     * can still be used if you wish to programmatically change the page size and pageLength can be used to specify the
     * initial page length. Paging itself is not affected.
     *
     * Additionally, if pagination is disabled using the paging option, this option is automatically disabled since it
     * has no relevance when there is no pagination.
     *
     * @link https://datatables.net/reference/option/lengthChange
     * @return bool
     */
    public function isLengthChange(): bool {
        return (bool)$this->_getConfig('lengthChange');
    }

    /**
     * Setter method.
     * When pagination is enabled, this option will control the display of an option for the end user to change the
     * number of records to be shown per page. The options shown in the list are controlled by the lengthMenu
     * configuration option.
     *
     * Note that by default the control is shown at the top left of the table. That can be controlled using dom and
     * CSS.
     *
     * If this option is disabled (false) the length change input control is removed - although the page.len() method
     * can still be used if you wish to programmatically change the page size and pageLength can be used to specify the
     * initial page length. Paging itself is not affected.
     *
     * Additionally, if pagination is disabled using the paging option, this option is automatically disabled since it
     * has no relevance when there is no pagination.
     *
     * @param bool $lengthChange
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/lengthChange
     */
    public function setLengthChange(bool $lengthChange): MainOption {
        $this->_setConfig('lengthChange', $lengthChange);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * Enable or disable ordering of columns - it is as simple as that! DataTables, by default, allows end users to
     * click on the header cell for each column, ordering the table by the data in that column. The ability to order
     * data can be disabled using this option.
     *
     * Note that the ability to add or remove sorting of individual columns can be disabled by the columns.orderable
     * option for each column. This parameter is a global option - when disabled, there are no sorting actions applied
     * by DataTables at all.
     *
     * @link https://datatables.net/reference/option/ordering
     * @return bool
     */
    public function isOrdering(): bool {
        return (bool)$this->_getConfig('ordering');
    }

    /**
     * Setter method.
     * Enable or disable ordering of columns - it is as simple as that! DataTables, by default, allows end users to
     * click on the header cell for each column, ordering the table by the data in that column. The ability to order
     * data can be disabled using this option.
     *
     * Note that the ability to add or remove sorting of individual columns can be disabled by the columns.orderable
     * option for each column. This parameter is a global option - when disabled, there are no sorting actions applied
     * by DataTables at all.
     *
     * @param bool $ordering
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/ordering
     */
    public function setOrdering(bool $ordering): MainOption {
        $this->_setConfig('ordering', $ordering);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * DataTables can split the rows in tables into individual pages, which is an efficient method of showing a large
     * number of records in a small space. The end user is provided with controls to request the display of different
     * data as the navigate through the data. This feature is enabled by default, but if you wish to disable it, you
     * may do so with this parameter.
     *
     * @link https://datatables.net/reference/option/paging
     * @return bool
     */
    public function isPaging(): bool {
        return (bool)$this->_getConfig('paging');
    }

    /**
     * Setter method.
     * DataTables can split the rows in tables into individual pages, which is an efficient method of showing a large
     * number of records in a small space. The end user is provided with controls to request the display of different
     * data as the navigate through the data. This feature is enabled by default, but if you wish to disable it, you
     * may do so with this parameter.
     *
     * @param bool $paging
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/paging
     */
    public function setPaging(bool $paging): MainOption {
        $this->_setConfig('paging', $paging);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * Enable or disable the display of a 'processing' indicator when the table is being processed (e.g. a sort). This
     * is particularly useful for tables with large amounts of data where it can take a noticeable amount of time to
     * sort the entries.
     *
     * @link https://datatables.net/reference/option/processing
     * @return bool
     */
    public function isProcessing(): bool {
        return (bool)$this->_getConfig('processing');
    }

    /**
     * Setter method.
     * Enable or disable the display of a 'processing' indicator when the table is being processed (e.g. a sort). This
     * is particularly useful for tables with large amounts of data where it can take a noticeable amount of time to
     * sort the entries.
     *
     * @param bool $processing
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/processing
     */
    public function setProcessing(bool $processing): MainOption {
        $this->_setConfig('processing', $processing);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * Enable horizontal scrolling. When a table is too wide to fit into a certain layout, or you have a large number
     * of columns in the table, you can enable horizontal (x) scrolling to show the table in a viewport, which can be
     * scrolled.
     *
     * This property can be true which will allow the table to scroll horizontally when needed (recommended), or any
     * CSS unit, or a number (in which case it will be treated as a pixel measurement).
     *
     * @link https://datatables.net/reference/option/scrollX
     * @return bool
     */
    public function isScrollX(): bool {
        return (bool)$this->_getConfig('scrollX');
    }

    /**
     * Setter method.
     * Enable horizontal scrolling. When a table is too wide to fit into a certain layout, or you have a large number
     * of columns in the table, you can enable horizontal (x) scrolling to show the table in a viewport, which can be
     * scrolled.
     *
     * This property can be true which will allow the table to scroll horizontally when needed (recommended), or any
     * CSS unit, or a number (in which case it will be treated as a pixel measurement).
     *
     * @param bool $scrollX
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/scrollX
     */
    public function setScrollX(bool $scrollX): MainOption {
        $this->_setConfig('scrollX', $scrollX);

        return $this->getMainOption();
    }

    /**
     * Getter method.
     * Enable vertical scrolling. Vertical scrolling will constrain the DataTable to the given height, and enable
     * scrolling for any data which overflows the current viewport. This can be used as an alternative to paging to
     * display a lot of data in a small area (although paging and scrolling can both be enabled at the same time if
     * desired).
     *
     * The value given here can be any CSS unit, or a number (in which case it will be treated as a pixel measurement)
     * and is applied to the table body (i.e. it does not take into account the header or footer height directly).
     *
     * @link https://datatables.net/reference/option/scrollY
     * @return string
     */
    public function getScrollY(): ?string {
        return (string)$this->_getConfig('scrollY');
    }

    /**
     * Setter method.
     * Enable vertical scrolling. Vertical scrolling will constrain the DataTable to the given height, and enable
     * scrolling for any data which overflows the current viewport. This can be used as an alternative to paging to
     * display a lot of data in a small area (although paging and scrolling can both be enabled at the same time if
     * desired).
     *
     * The value given here can be any CSS unit, or a number (in which case it will be treated as a pixel measurement)
     * and is applied to the table body (i.e. it does not take into account the header or footer height directly).
     *
     * @param string $scrollY
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/scrollY
     */
    public function setScrollY(?string $scrollY): MainOption {
        $this->_setConfig('scrollY', $scrollY);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * This option allows the search abilities of DataTables to be enabled or disabled. Searching in DataTables is
     * "smart" in that it allows the end user to input multiple words (space separated) and will match a row containing
     * those words, even if not in the order that was specified (this allow matching across multiple columns).
     *
     * Please be aware that technically the search in DataTables is actually a filter, since it is subtractive,
     * removing data from the data set as the input becomes more complex. It is named "search" here, and else where in
     * the DataTables API for consistency and to ensure there are no conflicts with other methods of a similar name
     * (specific the filter() API method).
     *
     * Note that if you wish to use the search abilities of DataTables this must remain true - to remove the default
     * search input box whilst retaining searching abilities (for example you might use the search() method), use the
     * dom option.
     *
     * @link https://datatables.net/reference/option/searching
     * @return bool
     */
    public function isSearching(): bool {
        return (bool)$this->_getConfig('searching');
    }

    /**
     * Setter method.
     * This option allows the search abilities of DataTables to be enabled or disabled. Searching in DataTables is
     * "smart" in that it allows the end user to input multiple words (space separated) and will match a row containing
     * those words, even if not in the order that was specified (this allow matching across multiple columns).
     *
     * Please be aware that technically the search in DataTables is actually a filter, since it is subtractive,
     * removing data from the data set as the input becomes more complex. It is named "search" here, and else where in
     * the DataTables API for consistency and to ensure there are no conflicts with other methods of a similar name
     * (specific the filter() API method).
     *
     * Note that if you wish to use the search abilities of DataTables this must remain true - to remove the default
     * search input box whilst retaining searching abilities (for example you might use the search() method), use the
     * dom option.
     *
     * @param bool $searching
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/searching
     */
    public function setSearching(bool $searching): MainOption {
        $this->_setConfig('searching', $searching);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * DataTables has two fundamental modes of operation:
     *  - Client-side processing - where filtering, paging and sorting calculations are all performed in the
     *    web-browser.
     *  - Server-side processing - where filtering, paging and sorting calculations are all performed by a server.
     *
     * By default DataTables operates in client-side processing mode, but can be switched to server-side processing
     * mode using this option. Server-side processing is useful when working with large data sets (typically >50'000
     * records) as it means a database engine can be used to perform the sorting etc calculations - operations that
     * modern database engines are highly optimised for, allowing use of DataTables with massive data sets (millions
     * of rows).
     *
     * When operating in server-side processing mode, DataTables will send parameters to the server indicating what
     * data it needs (what page, what filters are applied etc), and also expects certain parameters back in order that
     * it has all the information required to display the table. The client-server communication protocol DataTables
     * uses is detailed in the DataTables documentation.
     *
     * @link https://datatables.net/reference/option/serverSide
     * @return bool
     */
    public function isServerSide(): bool {
        return (bool)$this->_getConfig('serverSide');
    }

    /**
     * Setter method.
     * DataTables has two fundamental modes of operation:
     *  - Client-side processing - where filtering, paging and sorting calculations are all performed in the
     *    web-browser.
     *  - Server-side processing - where filtering, paging and sorting calculations are all performed by a server.
     *
     * By default DataTables operates in client-side processing mode, but can be switched to server-side processing
     * mode using this option. Server-side processing is useful when working with large data sets (typically >50'000
     * records) as it means a database engine can be used to perform the sorting etc calculations - operations that
     * modern database engines are highly optimised for, allowing use of DataTables with massive data sets (millions
     * of rows).
     *
     * When operating in server-side processing mode, DataTables will send parameters to the server indicating what
     * data it needs (what page, what filters are applied etc), and also expects certain parameters back in order that
     * it has all the information required to display the table. The client-server communication protocol DataTables
     * uses is detailed in the DataTables documentation.
     *
     * @param bool $serverSide
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/serverSide
     */
    public function setServerSide(bool $serverSide): MainOption {
        if ($serverSide === false) {
            throw new FatalErrorException("By the plugin business rule, you can't change this option.");
        }
        $this->_setConfig('serverSide', $serverSide);

        return $this->getMainOption();
    }

    /**
     * Checker method.
     * Enable or disable state saving. When enabled aDataTables will store state information such as pagination
     * position, display length, filtering and sorting. When the end user reloads the page the table's state will be
     * altered to match what they had previously set up.
     *
     * Data storage for the state information in the browser is performed by use of the localStorage or sessionStorage
     * HTML5 APIs. The stateDuration indicated to DataTables which API should be used (localStorage: 0 or greater, or
     * sessionStorage: -1).
     *
     * To be able to uniquely identify each table's state data, information is stored using a combination of the
     * table's DOM id and the current page's pathname. If the table's id changes, or the page URL changes, the state
     * information will be lost.
     *
     * Please note that the use of the HTML5 APIs for data storage means that the built in state saving option will not
     * work with IE6/7 as these browsers do not support these APIs. Alternative options of using cookies or saving the
     * state on the server through Ajax can be used through the stateSaveCallback and stateLoadCallback options.
     *
     * @link https://datatables.net/reference/option/stateSave
     * @return bool
     */
    public function isStateSave(): bool {
        return (bool)$this->_getConfig('stateSave');
    }

    /**
     * Setter method.
     * Enable or disable state saving. When enabled aDataTables will store state information such as pagination
     * position, display length, filtering and sorting. When the end user reloads the page the table's state will be
     * altered to match what they had previously set up.
     *
     * Data storage for the state information in the browser is performed by use of the localStorage or sessionStorage
     * HTML5 APIs. The stateDuration indicated to DataTables which API should be used (localStorage: 0 or greater, or
     * sessionStorage: -1).
     *
     * To be able to uniquely identify each table's state data, information is stored using a combination of the
     * table's DOM id and the current page's pathname. If the table's id changes, or the page URL changes, the state
     * information will be lost.
     *
     * Please note that the use of the HTML5 APIs for data storage means that the built in state saving option will not
     * work with IE6/7 as these browsers do not support these APIs. Alternative options of using cookies or saving the
     * state on the server through Ajax can be used through the stateSaveCallback and stateLoadCallback options.
     *
     * @param bool $stateSave
     * @return \DataTables\Table\Option\MainOption
     * @link https://datatables.net/reference/option/stateSave
     */
    public function setStateSave(bool $stateSave): MainOption {
        $this->_setConfig('stateSave', $stateSave);

        return $this->getMainOption();
    }

}