Skip to content
Nevela 0.33.1: New: customers get a shop in the mobile app, each sees only their own orders, and an administrator manages people and roles from the phone. Build it in the new drinks-app tutorial.A drinks app on the phone

Actions on a record

Create, edit and delete are not everything an app does to its records. An application gets accepted. A list of subscribers gets an announcement. An action is one of those: you name it in the descriptor and write what it does in one class. Nevela gives it a route, a permission, a button, a confirmation, a form for what it asks, and a message when it is done.

Add an actions section to the resource’s descriptor, nevela/resources/internship-application.json:

"actions": {
"accept": {
"label": "Accept",
"icon": "check",
"on": "record",
"confirm": "Send the acceptance letter to this applicant?",
"when": { "acceptedAt": null }
}
}

Then:

Terminal window
nevela generate

That writes app/Nevela/Actions/InternshipApplication/Accept.php, once, and the button is on every application’s page and in its row’s menu. There is nothing else to wire.

Key Meaning
the name (accept) camelCase. It is in the address, and its class is named from it.
label What the button says. Defaults to the name in words.
icon A Lucide icon name, one of those in apps/web/components/dashboard/resource-action.tsx (check, send, archive, mail and others). Add another there. Optional.
on record: a button on a record’s page and in its row menu. collection: a button beside New, for the list as a whole. Defaults to record.
confirm A question asked first, in the dialog Delete uses. Optional.
when Field values a record must have for the action to apply: one value, or a list it may be any of ({ "status": ["pending", "accepted"] }). The button is hidden on a record that doesn’t match, and Laravel refuses it there too. Optional, and for record actions only.
set What it does, when that is only to give fields values: { "status": "accepted" }. Nevela does it, and no class is written. See Moving a status on.
fields What it asks for before it runs. See Asking for something.
many true lets a record action run on the rows selected in the table as well.

The class is yours. It is written once and never touched again.

namespace App\Nevela\Actions\InternshipApplication;
use App\Mail\AcceptanceLetter;
use App\Models\InternshipApplication;
use Illuminate\Support\Facades\Mail;
class Accept
{
public function handle(InternshipApplication $internshipApplication, array $input): ?string
{
$internshipApplication->update(['accepted_at' => now()]);
Mail::to($internshipApplication->email)->queue(new AcceptanceLetter($internshipApplication));
return "Accepted {$internshipApplication->name}. Their letter is on its way.";
}
}

What it returns is the message the person sees. Return nothing and they are told it is done.

By the time handle() runs, Nevela has checked that the person holds the action’s permission, that they may see the record, that the record matches when, and that what was filled in is valid.

It runs inside a database transaction. If it throws, what it changed in the database is undone, and the person is told that it didn’t work and that nothing was changed. While the Laravel app is in debug mode they are also told why. To refuse with a message of your own, use abort(409, 'This applicant has withdrawn.').

Until you have written it, the class says so: pressing the button answers “Accept does nothing yet”, with the file to write it in.

Many actions do one thing: move a record to its next step. Accept an order, mark it ready, cancel it. For those, say the values in set, and there is nothing to write:

"actions": {
"accept": { "label": "Accept", "when": { "status": "pending" }, "set": { "status": "accepted" } },
"markReady": { "label": "Ready", "when": { "status": "accepted" }, "set": { "status": "ready" } },
"callOff": { "label": "Cancel with a reason", "when": { "status": ["pending", "accepted"] }, "set": { "status": "cancelled" }, "fields": { "reason": { "kind": "text" } } }
}

Each value must be one the field can have: an option of an enum, and not nothing for a required field. nevela generate says which, if not. If you write the action’s class anyway, it runs after the values are set, for what else should happen (a text message, say).

Every record action that is done is kept, as a step in the record’s history: what was done, by whom, when, what it changed and what was filled in for it. Unlike the activity log, nothing is merged: three steps are three rows. The record’s page in the dashboard shows them, and so does the mobile app, to whoever may see the record. For an order that belongs to a customer, that is the customer too.

When the resource has an owner, the person a record belongs to is told of each step through the bell, unless they took it themselves: Your order JM-0014 is now Ready, with the reason as the notice’s text when the action asked for one. A step they take themselves, such as a customer cancelling, is told instead to those who may edit the resource: Order JM-0014 is now Cancelled, by Amara Okafor.

GET /api/_nevela/history/{slug}/{id}

answers { "data": [ { "action", "label", "user": { "id", "name" }, "changes": { "status": { "from", "to" } }, "input", "at" } ] }, oldest first, and 404 for a record the person may not see.

A placed order shouldn’t be edited after the fact, by anyone. Make the resource with --fixed, or put "fixed": true in its descriptor, and once a record is made:

  • Nobody signed in edits or deletes it: not staff, not the administrator. The dashboard and the mobile app offer no Edit and no Delete, and Laravel answers 409 to anything that tries, from wherever.
  • Its lines can’t be added to, changed or taken away.
  • It moves on only through its actions, each a step in its history.
  • Someone who may not edit the resource (a customer) can’t choose, when they make one, the values its actions set. A new order of theirs is pending, whatever the request said.

What is still allowed: finishing a record in the request that made it (its lines, and a total worked out from them in itemsSaved()), an action, and anything run where nobody is signed in: seeders, the console, queued jobs and the scheduler. Removing a test order is done there: php nevela tinker, then App\Models\Order::find($id)->forceDelete().

On a fixed resource the Edit permission no longer edits anything once a record is made. With an owner it still says who runs the place: those who hold it see every record.

An action can ask for values first. They are filled in a sheet that opens from the button, with the same inputs a form has:

"actions": {
"announce": {
"label": "Send announcement",
"icon": "megaphone",
"on": "collection",
"fields": {
"subject": { "kind": "string" },
"message": { "kind": "text" }
}
}
}
namespace App\Nevela\Actions\NewsletterSubscription;
class Announce
{
public function handle(array $input): ?string
{
$subscribers = NewsletterSubscription::query()->pluck('email');
foreach ($subscribers as $email) {
Mail::to($email)->queue(new Announcement($input['subject'], $input['message']));
}
return "Queued for {$subscribers->count()} subscribers.";
}
}

A field is written as in a resource: a kind (string, text, int, float, boolean, date, datetime or enum), and optionally format, options, optionLabels, currency, required, label and maxLength. A money field ("format": "money") on the sheet shows its currency, or the app’s, as on a resource. They are validated by the rules a resource’s field of that kind has, and a problem is shown on the field in the sheet. $input holds what passed.

An action on the collection has no record, so its handle() takes $input alone.

Each action is a permission of its own, named from the table and the action: internship_applications.accept. It is on the Roles screen under the resource, beside Create, View, Edit and Delete.

An administrator has it. Nobody else does until it is given to their role by name. In particular, a role with everything for a resource, or for all resources (as EDITOR has), does not have its actions: being allowed to edit applications is not being allowed to send acceptance letters.

Without the permission the button isn’t shown and the address answers 403.

In your own code it is checked like any other: $user->can('internship_applications.accept').

With "many": true, a record action is also offered in the bar that appears when rows are ticked. It runs for each selected record it applies to and passes over the rest, and says how many of each. It is one transaction: if it fails for one, none are changed.

POST /api/{slug}/{id}/_actions/{action} On one record. Body: { "input": { … } }. Answers { "message", "record" }.
POST /api/{slug}/_actions/{action} On the collection: { "input": { … } }. Or a many record action on a selection: { "ids": [ … ], "input": { … } }, which answers { "message", "done", "skipped" }.
Status When
403 The person doesn’t hold the action’s permission.
404 No such action, or no such record, or one they may not see.
409 The record doesn’t match when. code is NOT_APPLICABLE. Also an edit or a deletion of a fixed record, by any address.
422 Something in input is not valid. issues says what, by field.
500 The class threw. Nothing was changed.