Carpenter

Carpenter is a PHP package to make creating HTML tables from a collection of data a breeze.

It also handles paginating, sorting, and makes tables reusable throughout your application.

Contents

• Installation
• Laravel 5 Integration
• Laravel 4 Integration
• Creating a Table Instance
• Table Markup
  • Class Based Tables
• Setting Table Data
  • Paginating Results
• Adding Columns
  • Sorting Columns
  • Column Labels
  • Formatting Column Data
• Adding Actions
  • Set the Action Link
  • Set the Action Label
  • Set the Action Attributes
  • Confirm an Action
• Filtering Table Data
• Rendering Tables
  • Rendering With a Template
  • Getting Data From a Table Instance

Installation

This package requires PHP 5.4+, and includes a Laravel 5 Service Provider and Facade.

To install through composer include the package in your composer.json.

"michaeljennings/carpenter": "1.0.*"

Run composer install or composer update to download the dependencies or you can run composer require michaeljennings/carpenter.

Laravel 5 Integration

To use the package with Laravel 5 firstly add the carpenter service provider to the list of service providers in app/config/app.php.

'providers' => array(

  Michaeljennings\Carpenter\CarpenterServiceProvider::class

);

Add the Carpenter facade to your aliases array.

'aliases' => array(

  'Carpenter' => Michaeljennings\Carpenter\Facades\Carpenter::class,
  
);

Publish the config files using php artisan vendor:publish --provider="Michaeljennings\Carpenter\CarpenterServiceProvider"

To access carpenter you can either use the Facade or the carpenter instance is bound to the IOC container and you can then dependency inject it via its contract.

Carpenter::get('foo');

public function __construct(Michaeljennings\Carpenter\Contracts\Carpenter $carpenter)
{
    $this->carpenter = $carpenter;
}

Laravel 4 Integration

To use the package with Laravel 4 firstly add the carpenter service provider to the list of service providers in app/config/app.php.

'providers' => array(

  'Michaeljennings\Carpenter\Laravel4ServiceProvider'

);

Add the Carpenter facade to your aliases array.

'aliases' => array(

  'Carpenter' => 'Michaeljennings\Carpenter\Facades\Carpenter',
  
);

Publish the config files using php artisan config:publish michaeljennings/carpenter

To access carpenter you can either use the Facade or the carpenter instance is bound to the IOC container and you can then dependency inject it via its contract.

Carpenter::get('foo');

public function __construct(Michaeljennings\Carpenter\Contracts\Carpenter $carpenter)
{
    $this->carpenter = $carpenter;
}

Creating a Table Instance

To get started creating tables firstly you want to make a table instance. There are two different ways to go about this.

Firstly Carpenter allows you to bind a table to a key and then retrieve it when you need it.

To bind an instance use the add.

$carpenter->add('foo', function($table) {});

You can then retrieve and instance by using the get method.

$table = $carpenter->get('foo');

Once you've retrieved a table you can run any of the table methods below to alter the table. Or if you wish you can pass a closure as a second parameter and alter the table in there.

$table = $carpenter->get('foo');

$table->column('bar');

$table = $carpenter->get('foo', function($table) {
	$table->column('bar');
});

However if you wish to make a single table instance without binding the table then you can use the make method.

$table = $carpenter->make('foo', function($table) {});

With the make method the key passed as the first argument is not used to bind the table, but it is used to keep all session data unique to the table.

Table Markup

Now that you have your table instance it's time to start defining the markup of your table. To this you may either pass an annonymous function to either the add or make method or pass it the name of class to use.

$carpenter->add('foo', function($table) {
	// Table logic goes here.
});

$carpenter->add('bar', Bar::class);

Class Based Tables

By default when using a class to define your table markup you need to provide a build method. This will be passed the table instance.

use Michaeljennings\Carpenter\Contracts\Table;

class Bar 
{
	public function build(Table $table)
	{
		//
	}
}

If you want to use a different method name then you just need to specify it when you create your table instance by seperating the class name and method name with an @.

$carpenter->add('bar', "Bar@table");

class Bar
{
	public function table(Table $table)
	{
		//
	}
}

Setting Table Data

At present you can either use Eloquent or CodeIgniter models, or multidimensional arrays to populate the table.

To set the model to be used use the model method.

$table->model(FooModel::class);

Or to use an array pass the array to the data method.

$table->data($data);

Paginating Results

To paginate the table pass the amount of results you wish to show on each page to the paginate method.

$table->paginate(15);

Adding Columns

To add a new column or retrieve an existing column from the table use the column method.

$table->column('foo');

Sorting Columns

By default all columns are set to be sortable and this will be handled by carpenter. However if you wish to stop a column from being sortable the use the unsortable method. Or if you wish to make the column sortable use the sortable method.

$table->column('foo')->sortable();
$table->column('foo')->unsortable();

When sorting the package will attempt to sort by the column key, however if you are accessing a column that doesn't exist in your data store this can cause issues. An example of this would be if you were accessing a mutator in laravel.

To help get around this you can use the sort method to set a custom closure to be used to sort the column. The closure will be passed two parameters; the data store you are querying, and whether the sort is in descending order.

$table->column('foo')->sort(function($query, $desc) {
	if ($desc) {
	 	$query->orderBy('bar', 'desc');
	} else {
		$query->orderBy('bar', 'asc');
	}
});

Column Labels

By default the column will work out the label to use for the column from the column name. If the column name has an underscore then it will replace it with a space and then it will capitalise all words.

If you want to specify a specific label you can use the setLabel method.

$table->column('foo'); // Label: Foo
$table->column('foo_bar'); // Label: Foo Bar
$table->column('foo_bar')->setLabel('Baz') // Label: Baz

Formatting Column Data

Occasionally you may wish to format each value in a column. For example if you were showing the price of an item then you may want to format to a currency. To do this you can use a presenter.

To get started use the presenter method. This is passed an annonymous function for you to format the value.

$table->column('price')->presenter(function($value) {
	return '&' . number_format($value, 2);
});

You may also wish to get data from the reset of the row. For example you may only want to show the price if the item is set to online. To do this just pass a second parameter to the closure.

$table->column('price')->presenter(function($value, $row) {
	if ($row->online) {
		return '&' . number_format($value, 2);
	}
});

Adding Actions

Occasionally you may need to add buttons or links to each row, or to the top of the table. To do this we use actions.

To add an action to the table, or retrieve and existing action, use the action method. The first parameter is a key for the action and the second is the position in the table. By default the actions go to the top of the table but to put them at the end of the row pass the position as the second argument.

$table->action('create');
$table->action('edit', 'row');

By default actions are set as buttons, however if you set an href attribute it will become an anchor. Or you can use the setTag method to set a custom element. When you set an element don't pass any chevrons as this will be added when the action is rendered.

$table->action('create')->setTag('div');

In the default templates the table is wrapped in a form which is where the actions post to. By default the form posts to the cu