README

Carpenter是一个PHP包，可以轻松地将数据集合转换为HTML表格。

它还处理分页、排序，并使表格可以在您的应用程序中重复使用。

内容

安装
Laravel 5集成
Laravel 4集成
创建表格实例
表格标记
- 基于类的表格
设置表格数据
- 分页结果
添加列
添加操作
过滤表格数据
渲染表格
- 使用模板渲染
- 从表格实例获取数据

安装

此包需要PHP 5.4+，并包括Laravel 5服务提供者和外观。

要通过composer安装，请将包包含在您的composer.json中。

"michaeljennings/carpenter": "1.0.*"

运行composer install或composer update以下载依赖项，或者您可以运行composer require michaeljennings/carpenter。

Laravel 5集成

要使用Laravel 5的包，首先将carpenter服务提供者添加到app/config/app.php中的服务提供者列表中。

'providers' => array(

  Michaeljennings\Carpenter\CarpenterServiceProvider::class

);

将Carpenter外观添加到您的别名数组中。

'aliases' => array(

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

使用php artisan vendor:publish --provider="Michaeljennings\Carpenter\CarpenterServiceProvider"发布配置文件。

要访问carpenter，您可以使用外观或carpenter实例已绑定到IOC容器，然后可以通过其契约进行依赖注入。

Carpenter::get('foo');

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

Laravel 4集成

要使用Laravel 4的包，首先将carpenter服务提供者添加到app/config/app.php中的服务提供者列表中。

'providers' => array(

  'Michaeljennings\Carpenter\Laravel4ServiceProvider'

);

将Carpenter外观添加到您的别名数组中。

'aliases' => array(

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

使用php artisan config:publish michaeljennings/carpenter发布配置文件。

要访问carpenter，您可以使用外观或carpenter实例已绑定到IOC容器，然后可以通过其契约进行依赖注入。

Carpenter::get('foo');

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

创建表格实例

要开始创建表格，首先您想要创建一个表格实例。有几种不同的方法可以实现。

首先，Carpenter允许您将表格绑定到一个键，然后在需要时检索它。

要绑定一个实例，请使用add。

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

然后，您可以通过使用get方法检索实例。

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

一旦检索到表格，您就可以运行以下任何表格方法来修改表格。或者，如果您愿意，可以将闭包作为第二个参数传递，并在其中修改表格。

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

$table->column('bar');

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

但是，如果您希望创建一个未绑定表格的单个表格实例，则可以使用make方法。

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

使用make方法时，作为第一个参数传递的键不用于绑定表格，但它用于保持所有会话数据对表格是唯一的。

表格标记

现在您有了表格实例，是时候开始定义表格的标记了。为此，您可以将匿名函数传递给add或make方法，或者传递要使用的类的名称。

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

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

基于类的表格

默认情况下，当使用类来定义表格标记时，您需要提供一个构建方法。这将传递表格实例。

use Michaeljennings\Carpenter\Contracts\Table;

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

如果您想使用不同的方法名，则只需在创建表格实例时指定它，通过在类名和方法名之间使用@来分隔。

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

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

设置表格数据

目前，您可以使用Eloquent或CodeIgniter模型，或多维数组来填充表格。

要设置使用的模型，请使用model方法。

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

或者要使用数组，请将数组传递给data方法。

$table->data($data);

分页结果

要分页表格，请将每页希望显示的结果数量传递给paginate方法。

$table->paginate(15);

添加列

要添加新列或从表格中检索现有列，请使用column方法。

$table->column('foo');

排序列

默认情况下，所有列都设置为可排序，这将由carpenter处理。但是，如果您希望停止某列可排序，请使用unsortable方法。或者，如果您希望使列可排序，请使用sortable方法。

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

在排序时，包将尝试按列键排序，但是如果您访问的数据存储中不存在该列，这可能会引起问题。一个例子是如果您正在访问laravel中的mutator。

为了解决这个问题，您可以使用sort方法设置一个用于排序列的自定义闭包。闭包将传递两个参数；您正在查询的数据存储和是否按降序排序。

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

列标签

默认情况下，列将从列名计算出要使用的标签。如果列名包含下划线，则将其替换为空格，然后首字母大写。

如果您想指定特定的标签，可以使用setLabel方法。

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

格式化列数据

有时您可能希望格式化列中的每个值。例如，如果您正在显示物品的价格，则可能希望将其格式化为货币。为此，您可以使用一个presenter。

要开始使用，请使用presenter方法。这会传递一个匿名函数，用于格式化值。

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

您可能还希望从行的其余部分获取数据。例如，您可能只想在物品设置为在线时显示价格。为此，只需向闭包传递第二个参数。

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

添加操作

有时您可能需要在每行或表格顶部添加按钮或链接。为此，我们使用actions。

要向表格添加操作或检索现有操作，请使用action方法。第一个参数是操作的键，第二个参数是表格中的位置。默认情况下，操作放在表格顶部，但要将它们放在行末，请将位置作为第二个参数传递。

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

默认情况下，操作设置为按钮，但是如果您设置href属性，它将成为一个锚点。或者，您可以使用setTag方法设置一个自定义元素。当设置元素时，不要传递任何箭头，这将在操作渲染时添加。

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

在默认模板中，表格被一个表单包裹，这是操作提交的位置。默认情况下，表单提交到当前页面，但是如果您想提交到特定URL，可以使用setFormAction方法。此外，如果您不想表单提交，可以使用setFormMethod方法设置方法。

$table->setFormAction('/search');
$table->setFormMethod('GET');

设置操作链接

要为操作设置URL，请使用setHref方法。

$table->action('create')->setHref('/create');

如果您正在使用行操作，您可能还希望访问行数据。为此，向setHref方法传递一个闭包。

$table->action('edit', 'row')->setHref(function($id) {
	return '/edit/' . $id;
});

$table->action('edit', 'row')->setHref(function($id, $row) {
	return '/edit/' . $row->slug;
});

设置操作标签

要设置操作的标签，请使用setLabel方法。

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

设置操作属性

要向操作添加类，请使用setClass方法。

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

要设置其他属性，您可以使用属性名作为方法名，或者使用setAttribute方法。

$table->action('edit', 'row')->id('edit-item');
$table->action('edit', 'row')->setAttribute('id', 'edit-item');

与setHref方法类似，您可以将闭包作为值传递以从行中获取属性。

$table->action('edit', 'row')->setAttribute('data-id', function($id, $row) {
	return $id;
});

确认操作

对于某些操作，例如删除，您可能希望用户确认他们想要运行操作。为此，您可以使用confirmed方法。这将利用默认的JavaScript确认方法。

《confirmed》方法接受一个参数；要么是你希望确认框显示的文本，要么如果你使用行操作，则可以传递一个闭包来访问表格行的属性。

$table->action('delete', 'table')->confirmed('Are you use you to delete that?');
$table->action('delete', 'row')->confirmed(function($id, $row) {
	return "Are you sure you want to delete {$row->name}?";
});

这将为操作添加一个确认属性。

<button confirmed="Are you use you to delete that?"></button>

Carpenter附带一个jQuery插件来处理确认功能，或者你可以监听该属性。要使用插件，只需包含carpenter.js文件，然后在表格的父元素上运行carpenterJs()方法。

<script type="text/javascript" src="/path/to/script/carpenter.js"></script>
<script type="text/javascript">
    $('.table-parent').carpenterJs();
</script>

其他表格方法

设置表格标题

要设置表格标题，请使用setTitle方法。在默认模板中，它将显示在表格的左上角。

$table->setTitle('FooBar Table');

过滤表格数据

有时你可能想要查询表格中的数据。为此，你可以使用过滤器。

你可以在创建表格标记时添加过滤器，或者在检索表格实例后添加。

要使用过滤器，将闭包传递给filter方法，并将闭包传递给你正在使用的数据存储的实例。如果你使用模型，你可以使用该模型上的任何方法。

$table->filter(function($q) {
	$q->orderBy('foo');
});

$table->get('foo')->filter(function($q) {
	$q->where('foo', '=', 'bar');
});

渲染表格

有两种方式来渲染表格；你可以使用模板，或者从表格实例获取数据。

使用模板渲染

要使用模板渲染表格，请在表格实例上调用render方法。

$table->render();

默认情况下，当你调用render方法时，它将使用配置文件中设置的模板。如果你想为特定表格使用模板，请使用setTemplate方法，或者在你调用render方法时传递模板。你还可以在调用render方法时传递任何数据作为数组。如果你想传递数据但使用默认模板，则只需传递null而不是模板路径。

$table->setTemplate('path/to/template.php');

$table->render('path/to/template.php');
$table->render('path/to/template.php', ['foo' => 'bar']);
$table->render(null, ['foo' => 'bar']);

目前，Carpenter支持Laravel、CodeIgniter和原生PHP模板渲染器。你可以在配置文件中设置要使用的渲染器。

Carpenter还附带三个默认模板，但创建自己的模板非常简单。

从表格实例获取数据

获取表格列

要获取表格列，请使用getColumns()方法。

foreach ($table->getColumns() as $column) {
	//
}

列方法

获取列HTML属性。

$table->getAttributes();

获取列标题标签。

$table->getLabel();

检查列是否可排序。

$table->isSortable();

获取列href。

$table->getHref();

获取表格行

要获取行，请使用getRows方法。

foreach ($table->getRows() as $row) {
	//
}

你还可以使用hasRows方法检查表格是否有任何行。

if ($table->hasRows()) {
	//
}

行方法

要获取行中的单元格，请使用getCells方法。

foreach ($row->getCells() as $cell) {
	echo $cell->value;
}

要检查行是否有任何操作，请使用hasActions方法。

if ($row->hasActions()) {
	//
}

然后，要获取行的操作，请使用getActions方法。最后，在操作上使用render方法来渲染操作。

foreach ($row->getActions() as $action) {
	echo $action->render();
}

获取表格操作

要检查表格是否有任何表格操作，请使用hasActions方法。

if ($table->hasActions()) {
	//
}

要获取在表格顶部播放的操作，请使用getActions方法。然后，在操作上使用render方法来渲染操作。

foreach ($table->getActions() as $action) {
	echo $action->render();
}

获取分页链接

要检查表格是否有任何分页链接，请使用hasLinks方法。

if ($table->hasLinks()) {
	//
}

然后，要获取分页链接，请使用getLinks方法。

echo $table->getLinks();

其他表格方法

获取表格标题

要获取标题，请使用getTitle方法。

$table->getTitle();

获取表单操作

要获取表单操作，请使用getFormAction方法。

$table->getFormAction();

还可以使用getFormMethod方法获取表单方法。

$table->getFormMethod();

michaeljennings / carpenter

维护者

详细信息

README

内容

安装

Laravel 5集成

Laravel 4集成

创建表格实例

表格标记

基于类的表格

设置表格数据

分页结果

添加列

排序列

列标签

格式化列数据

添加操作

设置操作链接

设置操作标签

设置操作属性

确认操作

其他表格方法

设置表格标题

过滤表格数据

渲染表格

使用模板渲染

从表格实例获取数据

获取表格列

列方法

获取表格行

行方法

获取表格操作

获取分页链接

其他表格方法

获取表格标题

获取表单操作