Download the PHP package daveawb/datatables without Composer

Notice: This package is deprecated and no longer maintained.

Laravel-Datatables (Deprecated as of Laravel 5)

Introduction

This project is aimed at anyone using the fantastic dataTables jQuery plugin written by SpryMedia and Laravel 4.1 or greater. It was written originally for dataTables 1.9.x, however since 1.10.x has now been released with a new API and data structure there will be updates to allow you to make use of the new syntax in the near future. If you haven't used datatables before check it out at Datatables.net.

For the mean time you will need to use the old 1.9.x API that is still compatable with 1.10.x. You can find the docs at the legacy Datatables site.

Supported datatables components

• Client side column re-ordering
• Per column sorting
• Global search
• Search in a specific column
• Set number of rows to return
• Filtered and Total rows

Supported features

• MongoDb support
• Eloquent and Query builder support
• Custom DB driver support
• Basic column decoration
• Custom column decoration / manipulation using closures
• Basic multi field support
  • no support for search and ordering on multiple columns yet

All components above require no extra configuration (other than database drivers). In a future release there will be the ability to send back named attributes per row such as DT_RowClass and any other data you want to return by row or if you want in the top level of the returned JSON for global data.

Requirements

• = PHP 5.4

• = Laravel 4.1.*

Installation

Composer

Add the following to your composer.json file

`

Add the Laravel service provider

Once you have run a composer update you will need to add the service provider.

Open up config/app.php and add the followng to the service providers array.

`

Publish package configuration

From the command line php artisan config:publish daveawb\datatables

Add the Laravel facade (optional)

Add the following to your config/app.php alias' array.

`

Basic Usage

``

The columns method takes an array in the order you wish to send data back to the client. Each field maps to a field in the database available from the query you've injected.

The query method maps directly to the driver being used, as standard Eloquent models/builders and query builders are accepted: Illuminate\Database\Eloquent\Model or Illuminate\Database\Eloquent\Builder

Example passing in a standard query builder.

``

As thequery method accepts builder instances you can pass a predefined query before inserting it into the datatables package.

``

Or using a standard query builder

``

Column interpretation / decoration

Every now and again you find that you need to merge the contents of fields or wrap them in HTML tags. This is where column interpretation / decoration comes in. Each of the decorations / interpretations are executed in the order you declare them. If you use two or more decorators on the same column, the result of the previous operation will be the value passed into the next decorator. This will allow you to build some complex decorations with a few core methods.

At present the first field declared is modified to hold the result of the combination of the two fields.

Built in methods

• Append
• Prepend
• Combine

Append

Append takes two arguments, the value to append and an optional separator. `` If your data to append === a key in the data from the database, it will be swapped out for that value

Prepend

Prepend takes two arguments, the value to prepend and an optional separator. ``

If your data to prepend === a key in the data from the database, it will be swapped out for that value

Combine

` Instead of passing a string into the column we pass an array, with the last value always being an array that declares the decorators/interpreters you want to use with their unique settings. Each interpreter will have separate documentation in the future. For now onlycombineis available and takes in field names to combine with the last value being the seperator. If the database values returned arefirst_name = "David"andlast_name = "Barker"` the above code would produce:

`` You can combine as many fields as you like, you are not limited to two.

Chaining interpreters / decorators

You can chain as many decorators together as you like, interpreters are slightly different as they have terminal and non terminal expressions. For now all interpreters are terminal expressions and treat each call as a new interpretation.

``

Use a closure on your column!

To allow some fine grained control over the contents of a specific field you can use a closure instead / as well as the decorators. You must declare a closure BEFORE any decorators / interpreters. Also be aware your closure will be executed AFTER decorators / interpretaters have been run.

``

Please note that to date the second field is not subject to any search, ordering or any other database related functionality. This will more than likely be added in the future.

Custom database drivers

The built in driver will allow you to use Eloquent models and builders as well as standard Query builders as the base query input into the package. Each driver extends Daveawb\Datatables\Driver that sets standard methods for all drivers such as setting the column factory and implements abstract methods.

There are two drivers that are bundled with this package:

• The default Laravel driver
• MongoDB driver

Any driver can be swapped in to replace the default driver at runtime using the driver method.

Using the MongoDB driver

``

Rather than using the query method to pass in an instance of Eloquent or a Query builder, we have a few different options for Mongo.

Configuration

If you haven't already published the packages config, now is a good time to do it. From the command line php artisan config:publish daveawb/datatables.

The configuration file has settings for your MongoDB database, replica sets and multiple servers are supported as well as authorisation, just set the configuration options accordingly.

Building the query

Using a collection

``

Setting predefined query data

`` The closure must always return an array

Getting results

Everything else is exactly the same, set columns with interpreters / decorators any way you wish and just return $datatable->result() to get all your results formatted in datatables style.

Building your own custom driver

Checkout the abstract driver class if you haven't already. Make sure that your driver implements all the methods it needs. At a later date there will be a detailed wiki entry on how to create custom database drivers with ease. For now take a look at how the two pre-packaged drivers work to get an idea how your driver needs to get data and return it.

Roadmap

• Support for dataTables 1.10.x options
• A query extension allowing for query manipulation after datatables has taken a count of the fields in the database

Testing

There are a full suite of tests written to make sure that this project works as expected. If you want to run the tests you will need to be running on a Linux OS with SQLite3 and PHPUnit. The tests are portable to mySQL however as it stands there is no support for it in the project. MongoDB is required for mongo driver tests.

Changelog

0.3.1

• Bug fixes to drivers specifically Laravel query builders
• Comprehensive module and acceptance tests added to qualify the above
• Drivers return raw data not formatted data
• Response object now holds the responsibility to format data
• Response tests added

0.3.0

• Config added, package now needs config published to set database defaults for custom drivers
• Interpreters updated to accept field names
• Database driver interface added
• MongoDB database driver added

0.2.6

• Append interpreter added
• Prepend interpreter added
• Closure capability for columns added

0.2.0

• Column interpreter language and decoration now included
• Combine interpreter added
• Driver interface now included for custom driver creation (work in progress)
• Fixed numerous bugs