\Dewdrop\Fields\ListingBulkActions

The BulkActions class allows you to attach any number of actions to a Listing. The user (typically with some checkboxes on a table or tile view) will select one or more items and then choose an action.

The BulkActions class will then determine which action was selected (using the shouldProcess() method on each action object) and pass the IDs of the selected items to that action's process() method. The values in the array of IDs will be based upon whatever primary key field is set in the Listing object.

Note that there are two different ways BulkActions might select items:

1) An array of IDs explicitly checked by the user.

2) Retrieving a non-paginated, complete dataset from the Listing and using all IDs. This is done to allow users to select all items, even those not on the currently visible page.

If you're using multiple listings and multiple BulkActions objects on a single page, you'll want to adjust the $id of each BulkActions object so they don't collide.

Summary

Methods
Properties
Constants
__construct()
setId()
getId()
getRequest()
getPrimaryKey()
getSelected()
add()
addButton()
getActions()
process()
getSelectedItemsFromRequest()
No public properties found
ENABLE_LISTING_PAGINATION
DISABLE_LISTING_PAGINATION
No protected methods found
No protected properties found
N/A
fetchIdsFromListing()
$id
$listing
$fields
$actions
$selected
N/A

Constants

ENABLE_LISTING_PAGINATION

ENABLE_LISTING_PAGINATION

Constant to make params of fetchIdsFromListing() clearer when called.

DISABLE_LISTING_PAGINATION

DISABLE_LISTING_PAGINATION

Constant to make params of fetchIdsFromListing() clearer when called.

Properties

$id

$id : string

The ID used for the inputs rendered by this BulkActions object (e.g.

the checkboxes the user will use to select items).

Type

string

$listing

$listing : \Dewdrop\Fields\Listing

The Listing containing the items that will be selected.

Type

\Dewdrop\Fields\Listing

$fields

$fields : \Dewdrop\Fields

The Fields that will be used when fetching the data from the Listing.

Needed because the listing might alter its query based upon the fields. For example, fields might be used to filter or sort the listing, which could impact the BulkActions if we're doing the "select all, not just visible page mode".

Type

\Dewdrop\Fields

$actions

$actions : array

Any actions (implementers of ActionInterface) registered/added.

Type

array

$selected

$selected : array

The items selected from the Listing. Stored so we can check items when re-rendering due to a validation error, for example. Resets each time process() is called.

Type

array

Methods

__construct()

__construct(\Dewdrop\Fields\Listing  $listing, \Dewdrop\Fields  $fields) 

Provide the necessary Listing and Fields objects.

Parameters

\Dewdrop\Fields\Listing $listing
\Dewdrop\Fields $fields

setId()

setId(string  $id) : $this

Set the ID that should be used for inputs rendered by this object.

Parameters

string $id

Returns

$this

getId()

getId() : string

Get the ID used for inputs rendered by this object and related classes.

For example, the BulkActions ID will be used by the BulkActionsForm view helper to set an ID for the "check all" control.

Returns

string

getRequest()

getRequest() : \Dewdrop\Request

Get the Request used by the Listing. Method provided here so we can hide the Listing itself from actions, etc., while still providing access to the HTTP request.

Returns

\Dewdrop\Request

getPrimaryKey()

getPrimaryKey() : \Dewdrop\Db\Field

Get the primary key field from the Listing.

Returns

\Dewdrop\Db\Field

getSelected()

getSelected() : array

Get an array of selected items. Populated during process().

Returns

array

addButton()

addButton(string  $id, string  $title, callable  $callback) : \Dewdrop\Fields\Listing\BulkActions

Shortcut for adding a "button" action with a simple, single button that triggers a callback to process the selected items. This is a convenient way to handle typical bulk actions without having to implement ActionInterface on your own.

Parameters

string $id
string $title
callable $callback

Returns

\Dewdrop\Fields\Listing\BulkActions

getActions()

getActions() : array

Get all the actions that have been added. Primary use of this method would be to iterate over the actions and render their controls (e.g. in BulkActionsForm view helper).

Returns

array

process()

process() : boolean|\Dewdrop\Fields\Listing\BulkActions\Result

Process our actions. We only process if at least one item is selected and an action's shouldProcess() returns true. If we've processed an action, a Result object is returned. Otherwise, we return false. The Result object can be used to help with messaging and redirects in whatever controller is orchestrating usage of these BulkActions.

Returns

boolean|\Dewdrop\Fields\Listing\BulkActions\Result

getSelectedItemsFromRequest()

getSelectedItemsFromRequest() : array

Looking at the HTTP request, determine which items have been selected.

If we don't have an array of items, we return an empty array to maintain consistency in our return data type. If the request contains the "check_pages" input for these bulk actions, we retrieve a full data set from the Listing and return all the IDs. Otherwise, we return an array of the explicitly selected items. In each case, we ensure that the items legitimate records IDs from the Listing by comparing against the results of Listing->fetchData(). This means you can be sure the IDs supplied to your action's process() method are actual records in the DB that the user was allowed to see/select.

Returns

array

fetchIdsFromListing()

fetchIdsFromListing(boolean  $usePagination) : array

Using the Listing's fetchData() method, grab an array of IDs. Depending upon the selection mode the user has chosen, we may or may not paginate the result set.

Parameters

boolean $usePagination

Returns

array