cakedc / cakephp-datatables
CakePHP datatables plugin for CakePHP
Installs: 3 818
Dependents: 0
Suggesters: 0
Security: 0
Stars: 8
Watchers: 16
Forks: 4
Open Issues: 0
Language:JavaScript
Type:cakephp-plugin
Requires
- php: >=8.1
- cakephp/cakephp: ^5.0.0
Requires (Dev)
- cakephp/cakephp-codesniffer: ^5.0
- phpunit/phpunit: ^10.1.0
- dev-main
- dev-1.next-cake4
- 3.0.0-RC1
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.1.0
- 1.0.0
- 1.0.0-alpha
- dev-2.next-cake4
- dev-3.next-cake5
- dev-feature/add-class-and-title-on-linkformatter
- dev-feature/support-multiple-order-fields
- dev-feature/refactor-links-logic
- dev-feature/add-callback-created-row
- dev-hotfix/33877
- dev-bug/33855
- dev-feature/csrf-config
- dev-feature/fix_related_filteres_tableId
- dev-feature/32005-datatable-plugin
- dev-feature/32535
- dev-feature/fix-bake
- dev-feature/pagination-fixes
- dev-feature/conditional-display-link
- dev-feature/new-funcionalities
This package is auto-updated.
Last update: 2024-10-17 11:02:37 UTC
README
IMPORTANT: This plugin is under heavy development now, use it at your own risk.
Installation
You can install this plugin into your CakePHP application using composer.
The recommended way to install composer packages is:
composer require cakedc/cakephp-datatables
Load plugin
To bake datatable index pages.
bin/cake plugin load CakeDC/Datatables
To bake datatable index pages.
bin/cake bake all Articles -t CakeDC/Datatables
Setting up the datatable fields
You can set a simple array with the columns to print or a more complex one with render callbacks, or a mix of them.
Simple entity visible fields
<?= $this->Datatable->setFields($article->getVisible()) ?>
Manual simple columns configuration
<?= $this->Datatable->setFields(['id', 'title', 'user_id', 'user.name']); ?>
Set complex columns configurations with render callback.
In this case print some random number.
<?= $this->Datatable->setFields([ [ 'name' => 'user_id', 'render' => ' function(data, type) { return Math.floor(Math.random() * 1000); } ' ] ]); ?>
Set complex columns configurations with render callback.
Print data from the record, hard coded values. Also add parameters to the link URL.
<?= $this->Datatable->setFields([ [ 'name' => 'title', 'links' => [ // Will produce a dynamic link with object data, i.e. // <a href="/articles/view/' + obj.id + '">hard coded</a> ['url' => ['action' => 'view', 'extra' => ("/' + obj.id + '")], 'label' => 'hard coded'], // Will produce a fixed link with a hard coded label, i.e. // <a href="/articles/view/d">hard coded</a> ['url' => ['action' => 'view', 'd'], 'label' => 'hard coded'], // Will produce a fixed link with a dynamic label, i.e. // <a href="/articles/edit">' + obj.user_id + '</a> ['url' => ['action' => 'edit'], 'value' => 'obj.user_id'], // Will produce a fixed link without an external URL in the href attribute, i.e. // <a href="#">' + obj.user_id + '</a> ['url' => '#', 'value' => 'obj.user_id'], ] ], ]); ?>
Add conditions to disable links
Add the disable option in the link, with a javascript closure that returns a boolean value, true for show value without the link, and false to return it with the link, this function receives the value of the current column and the row object.
<?= $this->Datatable->setFields([ [ 'name' => 'title', 'links' => [ [ 'url' => ['action' => 'view', 'extra' => ("/' + obj.id + '")], 'label' => 'hard coded', 'disable' => 'function (value) { return value === "N/A" }', ], [ 'url' => ['action' => 'view', 'd'], 'label' => 'hard coded' 'disable' => 'function (value, obj) { return obj.status === "inactive" }', ], ] ], ]); ?>
Add postLink and confirmation message
Add the type => "POST"
to the link, and the message in the confirm
option
<?= $this->Datatable->setFields([ [ 'name' => 'action', 'links' => [ [ 'url' => ['action' => 'delete', 'extra' => ("/' + obj.id + '")], 'label' => 'delete record', 'type' => \CakeDC\Datatables\Datatables::LINK_TYPE_POST, 'confirm' => __('Are you sure you want to delete this item?'), ], ] ], ]); ?>
NOTE: For now postLink does not support SecurityComponent, it is recommended to disable the method to use in the controller
Change method for confirmation message
The condition for the confirmation message is a javascript closure that receives the message and returns a boolean value.
<?= $this->Datatable->setFields([ [ 'name' => 'action', 'links' => [ [ 'url' => ['action' => 'delete', 'extra' => ("/' + obj.id + '")], 'label' => 'delete record', 'type' => \CakeDC\Datatables\Datatables::LINK_TYPE_POST, 'confirm' => __('Are you sure you want to delete this item?'), 'confirmCondition' => 'function (message){ return window.confirm(message); }', ], ] ], ]); ?>
A mix of simple and complex columns conditions
$this->Datatable->setFields( [ 'id', [ 'name' => 'title', 'links' => [ ['url' => ['action' => 'view', 'extra' => ("/' + obj.id + '")], 'label' => 'hard coded'], ['url' => ['action' => 'view', 'd'], 'label' => 'hard coded'], ['url' => ['action' => 'edit'], 'value' => 'obj.user_id'], ['url' => '#', 'value' => 'obj.user_id'], ] ], [ 'name' => 'user_id', 'render' => ' function(data, type) { return Math.floor(Math.random() * 1000); } ' ], 'user.name' ] ); $this->Datatable->getDatatableScript("table-articles");
Will produce the following script.
// API callback let getData = async () => { let res = await fetch('/articles.json') } // Datatables configuration $(() => { $('#table-articles').DataTable({ ajax: getData(), processing: true, serverSide: true, columns: [ {data:'id'}, { data:'title', render: function(data, type, obj) { return '<a href="/articles/view/' + obj.id + '">hard coded</a>' + '<a href="/articles/view/d">hard coded</a>' + '<a href="/articles/edit">' + obj.user_id + '</a>' + '<a href="#">' + obj.user_id + '</a>' } }, { data:'user_id', render: function(data, type) { return Math.floor(Math.random() * 1000); } }, {data:'user.name'} ] }); });
Types of inputs to search in colunms:
Now have 4 types of inputs: input select select multiple date
to define the type of search need in definition of columns especificate this array:
'searchInput' => [ 'type' => '{{any-type}}', 'options' => [ ['id' => 1, 'name' => 'one'], ], ],
for input type text:
not need make anything is for default:
for type select:
'searchInput' => [ type => 'select', 'options' => [ ['id' => 1, 'name' => 'one'], ['id' => 2, 'name' => 'two'], .... ] ],
for type multiple:
'searchInput' => [ type => 'multiple', 'options' => [ ['id' => 1, 'name' => 'one'], ['id' => 2, 'name' => 'two'], .... ] ],
for type date:
need jquery-ui or jquery-datepicker
'searchInput' => [ type => 'date', 'options' => [], ]
it is to integrate for columns definition:
ejample:
<?= $this->Datatable->setFields([ [ 'name' => 'user_id', 'searchInput' => [ 'type' => 'select', 'options' => [ ['id' => 1, 'name' => 'one'], ['id' => 2, 'name' => 'two'], .... ] ], 'render' => ' function(data, type) { return Math.floor(Math.random() * 1000); } ' ] ]); ?>
in options is posible utilize find('list) and put names id and name. if not want to search column is necesary to especify this,
php 'searchable' => false,
getting the datatable input delay 2 second:
<?php $this->Datatable->setConfigKey('delay', 2000, true); ?>
Getting the datatable script.
All you need is to tell the help to create the script for you, pass the tag id to be used for the datatable.
<?= $this->Datatable->getDatatableScript("table-articles") ?>
Setting the table headers.
Optionally you can format and translate the table header as follows:
<?= $this->Datatable->getTableHeaders($article->getVisible(), true) ?>
Create multiple datatables in the same template
Resets the datatable instance, and then you can set up a new one
<?= $this->Datatable->reset() ?>
Indicate a specific url to obtain the data
For example if you are in /pages/index but you et date from /pages/list, is usefull when you have multiple tables in the same page
<?= $this->Datatable->getInstance()->setConfig('ajaxUrl', ['controller' => 'Pages', 'action' => 'list']); ?>
Indicate specific type for ajax call
You can specify on config "ajaxType" if would that ajax calls are GET or POST, for example
<?php $this->Datatable->getInstance()->setConfig('ajaxType', 'POST'); $this->Datatable->getInstance()->setConfig('csrfToken', $this->getRequest()->getAttribute("csrfToken")); ?>
Important: if you set POST you must set "unlockedActions" on Security Component, specify the target action in the controller's initialize function
public function initialize(): void { parent::initialize(); ... if ($this->components()->has('Security')) { $this->Security->setConfig('unlockedActions', ['list']); } ... }
Add callback when row is created
For example, if you need to add a css class (to change row color) to each tr according to a specific value in the data
$this->Datatable->setCallbackCreatedRow( 'function( row, data, dataIndex ) { if (!data.viewed) { $(row).addClass("rowhighlight"); } }' ); ``