Contents¶

When to use CRUD View¶

• When you need to implement an Admin interface that is generated from the Backend. If you want to create your interface using only javascript, please only use the CRUD plugin as it will help you creating the required API.

• When you want to take care about the rules of your data processing and not too much how the interface is going to look like.

• If you prefer tweaking, overriding and configuring instead of doing everything from scratch.

Status¶

This plugin is still in early development status, things may change suddenly, but it can be used in real projects already.

Requirements¶

• CakePHP 4.x

Getting the Code¶

The recommended installation method for this plugin is by using composer.

In your aplication forlder execute:

composer require friendsofcake/crud-view

It is highly recommended that you install the Search plugin as well:

composer require friendsofcake/search

Loading the plugin¶

Execute the following lines from your application folder:

bin/cake plugin load Crud
bin/cake plugin load CrudView
bin/cake plugin load BootstrapUI
bin/cake plugin load Search

App Controller¶

First, configure the Crud plugin.

Configuring the AppController¶

If you haven’t configured the CRUD plugin already, add the following lines to your src/Controller/AppController.php file

<?php
declare(strict_types=1);

namespace App\Controller;

class AppController extends \Cake\Controller\Controller
{
    use \Crud\Controller\ControllerTrait;

    public function initialize(): void
    {
        parent::initialize();

        $this->loadComponent('RequestHandler');
        $this->loadComponent('Flash');

        $this->loadComponent('Crud.Crud', [
            'actions' => [
                'Crud.Index',
                'Crud.View',
                'Crud.Add',
                'Crud.Edit',
                'Crud.Delete',
                'Crud.Lookup',
            ],
            'listeners' => [
                // New listeners that need to be added:
                'CrudView.View',
                'Crud.Redirect',
                'Crud.RelatedModels',
                // If you need searching. Generally it's better to load these
                // only in the controller for which you need searching.
                'Crud.Search',
                'CrudView.ViewSearch',
            ]
        ]);
    }

    /**
     * Before render callback.
     *
     * @param \Cake\Event\Event $event The beforeRender event.
     * @return void
     */
    public function beforeRender(\Cake\Event\EventInterface $event)
    {
        if ($this->viewBuilder()->getClassName() === null) {
            $this->viewBuilder()->setClassName('CrudView\View\CrudView');
        }
    }
}

If you are familair with the CRUD plugin already, you will immediately understand that Crud view is simply a listener for the events generated by the plugin. If this is new to you, don’t worry, it will be explained in the following sections.

Using It In Your Controllers¶

Any controller inheriting from AppController will automatically implement the specified actions loaded int the CRUD component configuration. Therefore, you can just leave your controller code empty!

<?php
namespace App\Controller;

class CategoriesController extends AppController
{
    // No code here, but we have all actions available to use!
}

View the Results¶

You can now access your categories list by pointing your browser to http://example.com/categories. Browse around your new Admin interface for each of the controllers you have in your application.

Implementing an Index List¶

Rendering a list of the rows in a table is a matter of just adding the Crud.Index action to the Crud component and the CrudView.View as a listener.

public function initialize(): void
{
    $this->loadComponent('Crud.Crud', [
        'actions' => [
            'Crud.Index',
            // ...
        ],
        'listeners' => [
            'CrudView.View',
            // ...
        ]
    ]);
}

There is no need to have an `index() function in your controller. But you can implement it to customize both the behavior and looks of the index listing page.

<?php
declare(strict_types=1);

namespace App\Controller;

class ArticlesController extends AppController
{
    public function index()
    {
        // Your customization and configuration changes here
        return $this->Crud->execute();
    }
}

Most configuration changes need to be done by using the config() function in the action object. The config() method can be used for both reading and writing.

public function index()
{
    $action = $this->Crud->action(); // Gets the IndexAction object
    debug($action->getConfig()); // Show all configuration related to this action
    return $this->Crud->execute();
}

Below is a list of the configuration values that can be used and how they affect the rendering of your view:

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.relations_blacklist', ['Authors', ...]);
    return $this->Crud->execute();
}

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.relations', ['Categories', 'Tags']);
    return $this->Crud->execute();
}

public function index()
{
    $this->Crud->on('beforePaginate', function ($event) {
        $paginationQuery  = $event->getSubject()->query;
        $paginationQuery->contain([
            'Categories',
            'Authors' => ['fields' => ['id', 'name']]
        ]);
    });
    return $this->Crud->execute();
}

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);
    return $this->Crud->execute();
}

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields', ['title', 'body', 'category', 'published_time']);
    return $this->Crud->execute();
}

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.actions_blacklist', ['delete']);
    return $this->Crud->execute();
}

public function index()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.actions', ['view', 'add', 'edit']);
    return $this->Crud->execute();
}

Implementing an Add Action¶

If you have read this far, you know almost everything there is to know about configuring any type of action using CrudView, but being explicit about what is available in all of them will not hurt.

Implementing the Add action is done by adding the Crud.View action to the Crud component configuration:

public function initialize()
{
    $this->loadComponent('Crud.Crud', [
        'actions' => [
            'Crud.Add',
            // ...
        ],
        'listeners' => [
            'CrudView.View',
            'Crud.Redirect'
            'Crud.RelatedModels'
            // ...
        ]
    ]);
}

For the Add action it is recommended that you add the Crud.Redirect and Crud.RelatedModels listeners. The former will help adding more redirection options after saving the record and the latter will send the required information to the view so that the select widgets for associations get the correct options.

Implementing an Edit Action¶

Likewise, edit actions can be implemented by adding the right configuration to the Crud component. This is the recommended configuration:

public function initialize(): void
{
    $this->loadComponent('Crud.Crud', [
        'actions' => [
            'Crud.Edit',
            // ...
        ],
        'listeners' => [
            'CrudView.View',
            'Crud.Redirect'
            'Crud.RelatedModels'
            // ...
        ]
    ]);
}

As with the Add action, the Crud.Redirect and Crud.RelatedModels listeners will help handling redirection after save and help populate the select widgets for associations.

Specifying the Fields to be Displayed¶

When adding or editing a record, you probably want to avoid some of the fields from being displayed as an input in the form. Use the scaffold.fields and scaffold.fields_blacklist.

For example, let’s avoid having inputs for the created and modified fields in the form:

public function add()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);
    return $this->Crud->execute();
}

It is also possible to directly specify which fields should have an input in the form by using the scaffold.fields configuration key:

public function edit()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields', ['title', 'body', 'category_id']);
    return $this->Crud->execute();
}

You can pass attributes or change the form input type to specific fields when using the scaffold.fields configuration key. For example, you may want to add the placeholder property to the title input:

public function add()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields', [
        'title' => ['placeholder' => 'Insert a title here'],
        'body',
        'category_id'
    ]);
    return $this->Crud->execute();
}

The configuration can be used in both add and edit actions.

Limiting the Associations Information¶

By default the RelatedModels listener will populate the select boxes in the form by looking up all the records from the associated tables. For example, when creating an Article, if you have a Categories association it will populate the select box for the category_id field.

For a full explanation on RelatedModels please visit the CRUD Documentation for the RelatedModelsListener.

If you want to alter the query that is used for an association in particular, you can use the relatedModels event:

public function add()
{
    $this->Crud->on('relatedModel', function(\Cake\Event\Event $event) {
        if ($event->getSubject()->association->name() === 'Categories') {
            $event->getSubject()->query->limit(3);
            $event->getSubject()->query->where(['is_active' => true]);
        }
    });
    return $this->Crud->execute();
}

The callback can be used in both add and edit actions.

public function edit()
{
    $action $this->Crud->action();
    // Only fetch association info for Categories and Tags
    $action->setConfig('scaffold.relations', ['Categories', 'Tags']);
    return $this->Crud->execute();
}

public function edit()
{
    $action $this->Crud->action();
    // Only fetch association info for Categories and Tags
    $action->setConfig('scaffold.relations_blacklist', ['Authors']);
    return $this->Crud->execute();
}

Disabling the Extra Submit Buttons¶

You may have noticed already that in the add form there are multiple submit buttons. If you wish to only keep the “Save” button, you set the scaffold.form_submit_extra_buttons configuration key to false:

public function add()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.form_submit_extra_buttons', false);
    return $this->Crud->execute();
}

Implementing a View Action¶

Implementing a View action, for displaying the full information for a record, including its associations is also achieved via configuring the Crud component:

public function initialize()
{
    $this->loadComponent('Crud.Crud', [
        'actions' => [
            'Crud.View',
            // ...
        ],
        'listeners' => [
            'CrudView.View',
            // ...
        ]
    ]);
}

For this type of action there are no extra recommended listeners that you can apply, but there are some configuration options you can use to customize the information that is displayed.

public function view()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);
    return $this->Crud->execute();
}

public function view()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.fields', ['title', 'body', 'category', 'published_time']);
    return $this->Crud->execute();
}

public function view()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.relations_blacklist', ['Authors', ...]);
    return $this->Crud->execute();
}

public function view()
{
    $action = $this->Crud->action();
    $action->setConfig('scaffold.relations', ['Categories', 'Tags']);
    return $this->Crud->execute();
}

public function view()
{
    $this->Crud->on('beforeFind', function ($event) {
        $event->getSubject()->query->contain([
            'Categories',
            'Authors' => ['fields' => ['id', 'name']]
        ]);
    });
    return $this->Crud->execute();
}

Bulk Actions¶

The Crud plugin provides bulk actions which can be easily used with crud view.

To set up crud action in controller do something like this in initialize method.

$this->loadComponent('Crud.Crud', [
    'actions' => [
        'deleteAll' => [
            'className' => 'Crud.Bulk/Delete',
        ],
    ]
]);

Once a bulk action has been mapped, the scaffold.bulk_actions configuration key can be specified. The scaffold.bulk_actions configuration key takes an array of key/value pairs, where the key is the url and the value is the title.

$action = $this->Crud->action();
$action->setConfig('scaffold.bulk_actions', [
    Router::url(['action' => 'deleteAll']) => __('Delete records'),
]);

Going Forward¶

The following chapters will show you how to customize the output of each field, how to override parts of the templates and implementing search auto-completion.

Customizing Fields¶

Fields may be specified via the scaffold.fields configuration key. By default, this will contain a list of all columns associated with the Table being in scope. To limit the fields used, simply specify an array of fields.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', ['title', 'description']);

You may also specify an options array. For forms, CrudView makes use of the FormHelper::inputs() method and will pass your array values as options when generating the output.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'thread_id' => [
        'type' => 'text'
    ],
    'featured' => [
        'checked' => 'checked'
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.field_settings', [
    'title' => [
        // options here
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'published_time' => [
        'formatter' => function ($name, $value, $entity) {
            return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name);
        }
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.field_settings', [
    'published_time' => [
        'formatter' => function ($name, Time $value, Entity $entity) {
            return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name);
        }
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'external_id' => [
        'formatter' => function ($name, $value, $entity, $options, $View) {
            return $View->Html->link($name, sprintf('https://example.com/view/%d', $value));
        }
    ],
]);

// In controller action or preferably in beforeRender()
$this->viewBuilder()->setHelpers([
    'CrudView' => [
        'className' => 'CrudView.CrudView',
        'fieldFormatters' => [
            // Key can be any valid column type of table schema.
            'datetime' => function ($name, $value, $entity, $options, $View) {
                return $View->Time->nice($value);
            },
            'boolean' => function ($name, $value, $entity, $options, $View) {
                return $value ? 'Yes' : 'No';
            },
        ],
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'published_time' => [
        'formatter' => 'element',
        'element' => 'search/published_time',
        'action' => 'index'
    ]
]);

// templates/element/search/published_time.ctp

echo $this->Html->link($value->timeAgoInWords(), [
    'action' => $options['action'],
    'published_time' => $value->format('Y-m-d')
]);

<a href="/articles?published_time=2015-06-23">4 days ago</a>

Changing Field Header or Label Names¶

CrudView infers the name of the field by splitting the field so that it can be read by a human. Sometimes this is just not enough, or you may wish to show an entirely different header in a table or label in a form.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'author_id' => ['label' => 'Author Name'],
    // The rest of the fields to display here
]);

Adding Controller Actions to utilize Crud Actions¶

It’s easy to add an action to a controller that makes use of another CrudView action.

This does use the template provided by the edit action:

public function account() {
    $this->Crud->mapAction('account', [
        'className' => 'Crud.Edit',
        'view' => 'edit',
    ]);
    return $this->Crud->execute(null, $this->Auth->user('id'));
}

By default, it can be overwritten by providing a custom register.ctp:

public function register() {
    $this->Crud->mapAction('register', [
        'className' => 'Crud.Add',
    ]);
    return $this->Crud->execute();
}

Overriding Template Elements¶

All the CrudView templates are built from several elements that can be overridden by creating them in your own templates/element folder. The following sections will list all the elements that can be overridden for each type of action.

In general, if you want to override a template, it is a good idea to copy the original implementation from vendor/friendsofcake/crud-view/templates/element

Adding Breadcrumbs¶

The scaffold.breadcrumbs configuration key takes an array of CrudView\Breadcrumb\Breadcrumb objects:

use CrudView\Breadcrumb\Breadcrumb;

$this->Crud->action()->setConfig('scaffold.breadcrumbs', [
    new BreadCrumb('Home'),
]);

By default, CrudView\Breadcrumb\Breadcrumb objects will output plain-text breadcrumb entries. However, they also take url and options arrays:

use CrudView\Breadcrumb\Breadcrumb;

$this->Crud->action()->setConfig('scaffold.breadcrumbs', [
    new BreadCrumb('Home', ['controller' => 'Posts', 'action' => 'index'], ['class' => 'derp']),
]);

Active Breadcrumb¶

You may also set any given breadcrumb to “active” by either setting the class option to ‘active’ or using a CrudView\Breadcrumb\ActiveBreadCrumb object:

// Using the "class" option method:
use CrudView\Breadcrumb\Breadcrumb;

$this->Crud->action()->setConfig('scaffold.breadcrumbs', [
    new BreadCrumb('Home', '#', ['class' => 'active']),
]);

// Using the ActiveBreadCrumb method:
use CrudView\Breadcrumb\ActiveBreadCrumb;

$this->Crud->action()->setConfig('scaffold.breadcrumbs', [
    new ActiveBreadCrumb('Home', '#'),
]);

Custom Layouts with Breadcrumbs¶

Breadcrumbs are output in the layout portion of template rendering, outside of action template rendering. If you wish to change the layout but reuse the breadcrumb template logic, use the CrudView.breadcrumbs element like so:

<?= $this->element('breadcrumbs') ?>

Site Title¶

You can use the scaffold.site_title config variable to modify the title. If not set, it will fallback to the following alternative:

• Configure::read('CrudView.siteTitle')

$action = $this->Crud->action();
$action->setConfig('scaffold.site_title', 'My Admin Site');

Site Title Link¶

You can use the scaffold.site_title_link config variable to modify the title link. If not set, the title will not be made into a link. Both urls and cakephp route arrays are supported.

$action = $this->Crud->action();
$action->setConfig('scaffold.site_title_link', '/');

Site Title Image¶

You can use the scaffold.site_title_image config variable to modify the title link. If set, it replaces scaffold.site_title.

$action = $this->Crud->action();
// Use an image included in your codebase
$action->setConfig('scaffold.site_title_image', 'site_image.png');

// Use an exact url
$action->setConfig('scaffold.site_title_image', 'http://www.google.com/images/logos/google_logo_41.png');

Specifying which tables to show¶

You can specify the exact tables to show in the sidebar via the scaffold.tables configuration key:

// only show the posts table
$this->Crud->action()->setConfig('scaffold.tables', ['posts']);

Blacklisting tables¶

As an alternative to whitelisting tables via scaffold.tables, you can use the scaffold.tables_blacklist configuration key to specify tables to exclude from the output:

// do not show the ``phinxlog`` and ``users`` tables
$this->Crud->action()->setConfig('scaffold.tables_blacklist', [
    'phinxlog',
    'users',
]);

You can also specify a global tables blacklist by setting CrudView.tablesBlacklist configuration key. By default the phinxlog table is blacklisted.

Configure::write('CrudView.tablesBlacklist', ['phinxlog']);

Disabling the Sidebar Navigation¶

The sidebar navigation can also be completely disabled by setting the value to false.

$this->Crud->action()->setConfig('scaffold.sidebar_navigation', false);

Custom Menus¶

The sidebar navigation is just like any other menu in the system. You can provide your own menu to be rendered in its place:

use CrudView\Menu\MenuDivider;
use CrudView\Menu\MenuItem;

$this->Crud->action()->setConfig('scaffold.sidebar_navigation', [
    new MenuItem('Section Header'),
    new MenuItem(
        'CrudView Docs',
        'https://crud-view.readthedocs.io/en/latest/contents.html',
        ['target' => 'blank']
    ),
    new MenuItem(
        'Profile',
        ['controller' => 'Users', 'action' => 'profile']
    ),
    new MenuItem(
        'Inbox',
        ['controller' => 'Users', 'action' => 'inbox']
    ),
    new MenuItem(
        'Settings',
        ['controller' => 'Site', 'action' => 'settings']
    ),
    new MenuDivider(),
    new MenuItem(
        'Log Out',
        ['controller' => 'Users', 'action' => 'logout']
    )
]);

Disabling the Utility Navigation¶

The utility navigation can also be completely disabled by setting the value to false.

$this->Crud->action()->setConfig('scaffold.utility_navigation', false);

Custom Menus¶

The utility navigation is just like any other menu in the system. You can provide your own menu to be rendered in its place:

use CrudView\Menu\MenuDivider;
use CrudView\Menu\MenuDropdown;
use CrudView\Menu\MenuItem;

$action = $this->Crud->action();
$action->setConfig('scaffold.utility_navigation', [
    new MenuItem(
        'CrudView Docs',
        'https://crud-view.readthedocs.io/en/latest/contents.html',
        ['target' => 'blank']
    ),
    new MenuDropdown(
        'John Smith',
        [
            new MenuItem(
                'Profile',
                ['controller' => 'Users', 'action' => 'profile']
            ),
            new MenuItem(
                'Inbox',
                ['controller' => 'Users', 'action' => 'inbox']
            ),
            new MenuItem(
                'Settings',
                ['controller' => 'Site', 'action' => 'settings']
            ),
            new MenuDivider(),
            new MenuItem(
                'Log Out',
                ['controller' => 'Users', 'action' => 'logout']
            )
        ]
    )
]);

Adding Cells to the Dashboard¶

Any number of cells may be added to the Dashboard. All cells must extend the \Cake\View\Cell class.

Cells can be added via the Dashboard::addToColumn() method. It takes a cell instance and a column number as arguments.

// assuming the `CellTrait` is in use, we can generate a cell via `$this->cell()`
$someCell = $this->cell('SomeCell');
$dashboard = new \CrudView\Dashboard\Dashboard(__('Site Administration'), 2);

// add to the first column
$dashboard->addToColumn($someCell);

// configure the column to add to
$dashboard->addToColumn($someCell, 2);

CrudView ships with the DashboardTable cell by default.

public function dashboard()
{
    // setting both the title and the number of columns
    $dashboard = new \CrudView\Dashboard\Dashboard(__('Site Administration'), 1);
    $dashboard->addToColumn($this->cell('CrudView.DashboardTable', [
        'title' => 'Important Links'
    ]));

    $this->Crud->action()->setConfig('scaffold.dashboard', $dashboard);
    return $this->Crud->execute();
}

public function dashboard()
{
    // setting both the title and the number of columns
    $dashboard = new \CrudView\Dashboard\Dashboard(__('Site Administration'), 1);
    $dashboard->addToColumn($this->cell('CrudView.DashboardTable', [
        'title' => 'Important Links',
        'links' => [
            new LinkItem('Example', 'https://example.com', ['target' => '_blank']),
        ],
    ]));

    $this->Crud->action()->setConfig('scaffold.dashboard', $dashboard);
    return $this->Crud->execute();
}

public function dashboard()
{
    $dashboard = new \CrudView\Dashboard\Dashboard(__('Site Administration'), 1);
    $dashboard->addToColumn($this->cell('CrudView.DashboardTable', [
        'title' => 'Important Links',
        'links' => [
            new ActionLinkItem('Posts', ['controller' => 'Posts'], [], [
                new LinkItem('Add', ['controller' => 'Posts', 'action' => 'add']),
            ]),
        ],
    ]));

    $this->Crud->action()->setConfig('scaffold.dashboard', $dashboard);
    return $this->Crud->execute();
}

Available Viewblocks¶

The following custom view blocks are available for use within forms:

• dashboard.before: Rendered before the entire dashboard is rendered.

• dashboard.after: Rendered after the entire dashboard is rendered.

Available Elements¶

All the CrudView templates are built from several elements that can be overridden by creating them in your own templates/element folder. The following sections will list all the elements that can be overridden for each type of action.

In general, if you want to override a template, it is a good idea to copy the original implementation from vendor/friendsofcake/crud-view/templates/element

action-header

Create templates/element/action-header.ctp to have full control over what is displayed at the top of the page. This is shared across all page types.

Customizing Fields¶

Fields may be specified via the scaffold.fields configuration key. By default, this will contain a list of all columns associated with the Table being in scope. To limit the fields used, simply specify an array of fields:

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', ['title', 'description']);

$action = $this->Crud->action();
$action->setConfig('scaffold.field_settings', [
    'title' => [
        // options here
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'published_time' => [
        'formatter' => function ($name, $value, $entity) {
            return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name);
        }
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.field_settings', [
    'published_time' => [
        'formatter' => function ($name, Time $value, Entity $entity) {
            return $value->nice() . sprintf(' (Approved by %s)', $entity->approver->name);
        }
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'external_id' => [
        'formatter' => function ($name, $value, $entity, $options, $View) {
            return $View->Html->link($name, sprintf('https://example.com/view/%d', $value));
        }
    ],
]);

// In controller action or preferably in beforeRender()
$this->viewBuilder()->setHelpers([
    'CrudView' => [
        'className' => 'CrudView.CrudView',
        'fieldFormatters' => [
            // Key can be any valid column type of table schema.
            'datetime' => function ($name, $value, $entity, $options, $View) {
                return $View->Time->nice($value);
            },
            'boolean' => function ($name, $value, $entity, $options, $View) {
                return $value ? 'Yes' : 'No';
            },
        ],
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'published_time' => [
        'formatter' => 'element',
        'element' => 'search/published_time',
        'action' => 'index'
    ]
]);

// templates/element/search/published_time.ctp

echo $this->Html->link($value->timeAgoInWords(), [
    'action' => $options['action'],
    'published_time' => $value->format('Y-m-d')
]);

<a href="/articles?published_time=2015-06-23">4 days ago</a>

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title' => [
        'disableSort' => true,
    ]
]);

Index Buttons¶

By default, the included index buttons are generated based on the mapped Crud actions. You can customize available buttons by using the scaffold.actions key:

$action = $this->Crud->action();

// restrict to just the add button, which will show up globally
$action->setConfig('scaffold.actions', [
    'add'
]);

// restrict to just the delete/edit/view actions, which are scoped to entities
$action->setConfig('scaffold.actions', [
    'delete',
    'edit',
    'view',
]);

You can also specify configuration for actions, which will be used when generating action buttons.

$action = $this->Crud->action();
$action->setConfig('scaffold.actions', [
    'duplicate' => [
        // An alternative title for the action
        'link_title' => 'Duplicate this record',

        // A url that this action should point to
        'url' => ['action' => 'jk-actually-this-action'],

        // The HTTP method to use. Defaults to GET. All others result in
        // a ``FormHelper::postLink``
        'method' => 'POST',

        // Whether to scope the action to a single entity or the entire table
        // Options: ``entity``, ``table``
        'scope' => 'entity',

        // All other options are passed in as normal to the options array
        'other' => 'options',
    ]
]);

$action = $this->Crud->action();

// For the PostsController, will generate
// /posts/translate/english/1
$action->setConfig('scaffold.actions', [
    'translate' => [
        'url' => ['action' => 'translate', 'english']
    ]
]);

$action = $this->Crud->action();

// For the PostsController, will generate
// /posts/translate/1/english
$action->setConfig('scaffold.actions', [
    'translate' => [
        'url' => ['action' => 'translate', ':primaryKey:', 'english']
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.actions_blacklist', ['add', 'delete']);

$action = $this->Crud->action();
$action->setConfig('scaffold.actions', ['view', 'edit', 'delete']);
$action->setConfig('scaffold.action_groups', [
    'Actions' => [
        'view',
        'edit',
        'delete',
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.actions', ['view', 'edit', 'delete', 'disable', 'delete']);
$action->setConfig('scaffold.action_groups', [
    'Actions' => [
        'view',
        'edit',
        'delete',
    ],
    'Destructive Actions' => [
        'disable',
        'delete',
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.actions', ['view', 'edit', 'delete', 'english', 'spanish']);
$action->setConfig('scaffold.action_groups', [
    'Actions' => [
        'view',
        'edit',
        'delete',
    ],
    'Translate' => [
        'english' => [
            'url' => ['action' => 'translate', 'english']
        ],
        'spanish' => [
            'url' => ['action' => 'translate', 'spanish']
        ],
    ]
]);

Bulk Actions¶

The Crud plugin provides bulk actions which can be easily used with crud view.

To set up crud action in controller do something like this in initialize method.

$this->loadComponent('Crud.Crud', [
    'actions' => [
        'deleteAll' => [
            'className' => 'Crud.Bulk/Delete',
        ],
    ]
]);

Once a bulk action has been mapped, the scaffold.bulk_actions configuration key can be specified. The scaffold.bulk_actions configuration key takes an array of key/value pairs, where the key is the url and the value is the title.

$action = $this->Crud->action();
$action->setConfig('scaffold.bulk_actions', [
    Router::url(['action' => 'deleteAll']) => __('Delete records'),
]);

Index Finder Scopes¶

In some cases, it is helpful to show quick links to pre-filtered datasets. Rather than force users to select all the filters, CrudView enables the ability to display “Finder Scope” links via the scaffold.index_finder_scopes configuration key. These are output below the action header, above the data that is being paginated.

The scaffold.index_finder_scopes option takes an array of finder scope data. Each sub-array should contain title and finder parameters.

$this->Crud->action()->setConfig('scaffold.index_finder_scopes', [
        [
            'title' => __('All'),
            'finder' => 'all',
        ],
        [
            'title' => __('Active'),
            'finder' => 'active',
        ],
        [
            'title' => __('Inactive'),
            'finder' => 'inactive',
        ],
]);

The all finder scope is special. This scope will be displayed by default, and should always be included in the scope list. It is not automatically injected.

Selecting a finder scope will reset any other querystring arguments. Selecting the all finder scope will result in being redirected to a page without querystring arguments.

Selecting a finder scope will not automatically apply the find to your paginated result-set. This must be done manually.

public function index()
{
    $this->Crud->action()->setConfig('scaffold.index_finder_scopes', [
        [
            'title' => __('All'),
            'finder' => 'all',
        ],
        [
            'title' => __('Active'),
            'finder' => 'active',
        ],
        [
            'title' => __('Inactive'),
            'finder' => 'inactive',
        ],
    ]);

    // We don't need to check for `all` as it is the default findMethod
    if (in_array($this->request->getQuery('finder'), ['active', 'inactive'])) {
        $this->Crud->action()->config('findMethod', $this->request->getQuery('finder'));
    }
    return $this->Crud->execute();
}

use Cake\ORM\Query;
use Cake\ORM\Table;

class PostsTable extends Table
{
    public function findActive(Query $query, array $options)
    {
        $query->where([$this->aliasField('active') => true]);

        return $query;
    }

    public function findInactive(Query $query, array $options)
    {
        $query->where([$this->aliasField('active') => false]);

        return $query;
    }
}

Index Filters¶

The ViewSearch listener generates filter inputs for filtering records on your index action. It requries friendsofcake/search <https://packagist.org/packages/friendsofcake/search> to be installed and filters configured for your model using the search manager.

<?php
declare(strict_types=1);

namespace App\Controller;
use App\Controller\AppController;

class SamplesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        // Enable PrgComponent so search form submissions
        // properly populate querystring parameters for the SearchListener
        $this->loadComponent('Search.Prg', [
            'actions' => [
                'index',
            ],
        ]);
    }

    public function index()
    {
        // Enable the SearchListener
        $this->Crud->addListener('search', 'Crud.Search', [
            // The search behavior collection to use. Default "default".
            'collection' => 'admin',
        ]);

        // Enable the ViewSearch listener
        $this->Crud->addListener('viewSearch', 'CrudView.ViewSearch', [
            // Indicates whether is listener is enabled.
            'enabled' => true,

            // Whether to use auto complete for select fields. Default `true`.
            // This requires you have `Crud.Lookup` action enabled for that
            // related model's controller.
            // http://crud.readthedocs.io/en/latest/actions/lookup.html
            'autocomplete' => true,

            // Whether to use selectize for select fields. Default `true`.
            'selectize' => true,

            // The search behavior collection to use. Default "default".
            'collection' => 'default',

            // Config for generating filter controls. If `null` the
            // filter controls will be derived based on filter collection.
            // You can use "form" key in filter config to specify control options.
            // Default `null`.
            'fields' => [
                // Key should be the filter name.
                'filter_1' => [
                    // Any option which you can use Form::control() options.
                ],
                // Control options for other filters.
            ]
        ]);

        return $this->Crud->execute();
    }
}

Here’s an e.g. of how configure filter controls options through search manager itself:

<?php
declare(strict_types=1);

namespace App\Model\Table;
use Cake\ORM\Table;

class SamplesTable extends Table
{
    public function initialize(array $config): void
    {
        parent::initialize($config);

        $this->addBehavior('Search.Search');
        $this->searchManager()
            ->useCollection('default')
            ->add('q', 'Search.Like', [
                'field' => ['title', 'body'],
                'form' => [
                    'data-foo' => 'bar'
                ]
            ])
            ->add('category_id', 'Search.Value', [
                'form' => [
                    'type' => 'select',
                    'class' => 'no-selectize'
                ]
            ]);
    }
}

Multiple Index Pages¶

Sometime you may want more than one index page for a resource to represent different views to the user. If multiple index pages exist, CrudView will automatically build links at the top of the index page. Including multiple views is simple and requires setting the index view in your action.

$action = $this->Crud->action();
$action->view('index');

Download Format Links¶

The scaffold.index_formats configuration key can be used to customize “Download Links”. These are alternative methods of displaying the current index page, and can be used to expose the paginated data in JSON, XML, or other formats. The output of each format can be customized to your specifications.

The scaffold.index_formats option takes an array of download format data. Each sub-array should contain title and url parameters.

use Cake\Routing\Router;

// link to the current page, except with extensions `json` or `xml`
// include the querystring argument as specified or you will lose any
// currently applied filters
$action = $this->Crud->action();
$action->setConfig('scaffold.index_formats', [
    [
        'title' => 'JSON',
        'url' => ['_ext' => 'json', '?' => $this->request->getQueryParams()]
    ],
    [
        'title' => 'XML',
        'url' => Router::url(['_ext' => 'xml', '?' => $this->request->getQueryParams()])
    ],
]);

Download links are displayed near the bottom-left of the index page and will open in a new window.

composer require friendsofcake/cakephp-csvview:~3.0

Router::scope('/', function (RouteBuilder $routes) {
    $routes->extensions(['csv']);
    // other routes go here
});

$this->loadComponent('RequestHandler', [
    'viewClassMap' => ['csv' => 'CsvView.Csv']
]);

public function index()
{
    // only show the id, title, and created fields for csv output
    if ($this->request->getParam('_ext') === 'csv') {
        $this->set('_serialize', ['posts']);
        $this->set('_extract', ['id', 'active', 'title', 'created']);
    }

    $this->Crud->action()->setConfig('scaffold.index_formats', [
        [
            'title' => 'CSV',
            'url' => ['_ext' => 'csv', '?' => $this->request->getQueryParams()]
        ],
    ]);
    return $this->Crud->execute();
}

Available Viewblocks¶

The following custom view blocks are available for use within forms:

• form.sidebar: Rendered on the side of a form. Will also change the form width.

• form.before_create: Rendered before FormHelper::create() is called.

• form.after_create: Rendered after FormHelper::create() is called.

• form.before_end: Rendered before FormHelper::end() is called.

• form.after_end: Rendered after FormHelper::end() is called. Used by embedded Form::postLink() calls.

Available Elements¶

All the CrudView templates are built from several elements that can be overridden by creating them in your own templates/element folder. The following sections will list all the elements that can be overridden for each type of action.

In general, if you want to override a template, it is a good idea to copy the original implementation from vendor/friendsofcake/crud-view/templates/element

action-header

Create templates/element/action-header.ctp to have full control over what is displayed at the top of the page. This is shared across all page types.

form/buttons

Create templates/element/form/buttons.ctp to change what is displayed for form submission. You can expect the $formSubmitButtonText and $formSubmitExtraButtons variables to be available

Available Variables¶

The following variables are available for use within the element:

• fields: List of fields to show and their options

• actions: A list of actions that can be displayed for the index page.

• bulkActions: A list of bulk actions associated with this resource

• primaryKey: The name of the record’s primary key field.

• singularVar: The singular version of the resource name.

• viewVar: Reference to the name of the variable holding all records.

• plural of viewVar: The set of records.

Customizing the Blog fields¶

The blog index type has two main options:

• scaffold.index_title_field: (default: displayField for current table) Controls the field used for the blog title.

• scaffold.index_body_field: (default: body) Controls the field used for the blog body.

$action = $this->Crud->action();
$action->setConfig('scaffold.index_title_field', 'name');
$action->setConfig('scaffold.index_body_field', 'content');

Available Variables¶

The following variables are available for use within the element:

• indexTitleField: The field containing the post title

• indexBodyField: The field containing the post body

• fields: List of fields to show and their options

• actions: A list of actions that can be displayed for the index page.

• bulkActions: A list of bulk actions associated with this resource

• primaryKey: The name of the record’s primary key field.

• singularVar: The singular version of the resource name.

• viewVar: Reference to the name of the variable holding all records.

• plural of viewVar: The set of records.

Customizing the Gallery fields¶

The gallery index type has several options:

• scaffold.index_title_field: (default: displayField for current table) Controls the field used for each gallery entry title.

• scaffold.index_image_field: (default: image) Controls the field used for each gallery entry image.

• scaffold.index_body_field: (default: body) Controls the field used for each gallery entry body.

• scaffold.index_gallery_css_classes: (default: col-sm-6 col-md-3) Controls the css classes applied to each gallery entry, useful for specifying how many entries should go on a single page.

$action = $this->Crud->action();
$action->setConfig('scaffold.index_title_field', 'name');
$action->setConfig('scaffold.index_image_field', 'image');
$action->setConfig('scaffold.index_body_field', 'content');
$action->setConfig('scaffold.index_gallery_css_classes', 'col-sm-4 col-md-2');

Customizing Gallery Field Output¶

For each field, we will also retrieve configuration from the scaffold.fields configuration key for formatting each field:

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'image' => [
        'width' => '240',
        'height' => '240'
    ],
]);

Default Image¶

If no image is retrieved, CrudView will default to the following transparent gif:

data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==

Available Variables¶

The following variables are available for use within the element:

• indexImageField: The field containing the gallery entry image

• indexTitleField: The field containing the gallery entry title

• indexBodyField: The field containing the gallery entry body

• fields: List of fields to show and their options

• actions: A list of actions that can be displayed for the index page.

• bulkActions: A list of bulk actions associated with this resource

• primaryKey: The name of the record’s primary key field.

• singularVar: The singular version of the resource name.

• viewVar: Reference to the name of the variable holding all records.

• plural of viewVar: The set of records.

Defining Columns¶

By default, all fields are displayed on the index page. To display an attribute or a method on a record, you can use the scaffold.fields config option.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', ['id', 'title']);

To specify the title used in the pagination header, you need to set scaffold.fields to an associative array and use the title parameter:

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
  'author_id' => ['title' => 'Author Name'],
]);

Index Action Elements¶

All the CrudView templates are built from several elements that can be overridden by creating them in your own templates/element folder. The following sections will list all the elements that can be overridden for each type of action.

In general, if you want to override a template, it is a good idea to copy the original implementation from vendor/friendsofcake/crud-view/templates/element

search

Create templates/element/search.ctp for having full control over how the search filters are displayed in your pagination table. You can expect the $searchInputs and $searchOptions variables to be available

index/table

Create templates/element/index/table.ctp To implement your own table.

index/pagination

Create templates/element/index/pagination.ctp To implement your own pagination links and counter.

index/bulk_actions/table

Create templates/element/index/bulk_actions/table.ctp for changing how the bulk action inputs for the whole table. You can expect the $bulkActions, $primaryKey and $singularVar variables to be available.

index/bulk_actions/record

Create templates/element/index/bulk_actions/record.ctp for changing how the bulk action inputs for each row are displayed. You can expect the $bulkActions, $primaryKey and $singularVar variables to be available.

index/bulk_actions/form_start

Create templates/element/index/bulk_actions/form_start.ctp To customize the Form create call for bulk actions

index/bulk_actions/form_end

Create templates/element/index/bulk_actions/form_end.ctp To customize the Form end call for bulk actions

Customizing Fields¶

Fields may be specified via the scaffold.fields configuration key. By default, this will contain a list of all columns associated with the Table being in scope. To limit the fields used, simply specify an array of fields.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', ['title', 'description']);

You may also specify an options array. For forms, CrudView makes use of the FormHelper::inputs() method and will pass your array values as options when generating the output.

$action = $this->Crud->action();
$action->setConfig('scaffold.fields', [
    'title',
    'thread_id' => [
        'type' => 'text'
    ],
    'featured' => [
        'checked' => 'checked'
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.field_settings', [
    'title' => [
        // options here
    ]
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.fields_blacklist', ['created', 'modified']);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_tab_groups', [
    'First Tab Header' => ['field_1', 'field_2'],
    'Second Tab Header' => ['field_3', 'field_4'],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_primary_tab', 'Key Info');

Form Submission¶

$this->set('_redirect_url', ['action' => 'home']);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_enable_dirty_check', true);

Submit Buttons¶

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_button_text', _('Submit'));

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_buttons', true);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_buttons', [
    [
        'title' => __d('crud', 'Save & continue editing'),
        'options' => ['class' => 'btn btn-success btn-save-continue', 'name' => '_edit', 'value' => true],
        'type' => 'button',
    ],
    [
        'title' => __d('crud', 'Save & create new'),
        'options' => ['class' => 'btn btn-success', 'name' => '_add', 'value' => true],
        'type' => 'button',
    ],
    [
        'title' => __d('crud', 'Back'),
        'url' => ['action' => 'index'],
        'options' => ['class' => 'btn btn-default', 'role' => 'button', 'value' => true],
        'type' => 'link',
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_left_buttons', true);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_left_buttons', [
    [
        'title' => __d('crud', 'Save & continue editing'),
        'options' => ['class' => 'btn btn-success btn-save-continue', 'name' => '_edit', 'value' => true],
        'type' => 'button',
    ],
]);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_buttons', false);

$action = $this->Crud->action();
$action->setConfig('scaffold.form_submit_extra_left_buttons', false);

Available Viewblocks¶

The following custom view blocks are available for use within forms:

• form.sidebar: Rendered on the side of a form. Will also change the form width.

• form.before_create: Rendered before FormHelper::create() is called.

• form.after_create: Rendered after FormHelper::create() is called.

• form.before_end: Rendered before FormHelper::end() is called.

• form.after_end: Rendered after FormHelper::end() is called. Used by embedded Form::postLink() calls.

Available Elements¶

All the CrudView templates are built from several elements that can be overridden by creating them in your own templates/element folder. The following sections will list all the elements that can be overridden for each type of action.

In general, if you want to override a template, it is a good idea to copy the original implementation from vendor/friendsofcake/crud-view/templates/element

action-header

Create templates/element/action-header.ctp to have full control over what is displayed at the top of the page. This is shared across all page types.

form/buttons

Create templates/element/form/buttons.ctp to change what is displayed for form submission. You can expect the $formSubmitButtonText and $formSubmitExtraButtons variables to be available