|
| 1 | +--- |
| 2 | +name: add-bulk-action |
| 3 | +description: Use when adding a new bulk action (a button that runs an operation on the rows selected in a list/datagrid) or modifying an existing one, in any NRA project. |
| 4 | +--- |
| 5 | + |
| 6 | +# Skill: Add or Modify a Bulk Action |
| 7 | + |
| 8 | +> **Use this skill when:** asked to add a new bulk action to an entity's list, or to change what an existing bulk action does. |
| 9 | +
|
| 10 | +--- |
| 11 | + |
| 12 | +## Context |
| 13 | + |
| 14 | +Only the generic *plumbing* for bulk actions lives in the shared submodules and is reused by all four NRA projects: |
| 15 | +- Client base components: `client/shared` (submodule `nra-client`) → `components/crudContainers/` |
| 16 | +- Server base plumbing: `server/shared` (submodule `nra-server`) → `base-entity/` |
| 17 | + |
| 18 | +A specific bulk action's wiring and business logic is **project-local by default** — it lives in that project's own `client/src/entities/<entity>.jsx` and `server/src/entity-modules/<entity>.config.ts`, not in the shared submodules. It only becomes shared (usable by other projects) if you deliberately extract it: |
| 19 | +- Client: a reusable preset button component in `client/shared/components/crudContainers/` (like `BulkFixReferenceButton.jsx`), which other projects' entity files can then import. |
| 20 | +- Server: a reusable util in `server/shared/utils/entity/` (like `fixReference.util.ts`), which other projects' service overrides can then call. |
| 21 | + |
| 22 | +Don't extract to shared unless the action (or its logic) is genuinely reusable across projects — a one-off action just needs the project-local wiring below. |
| 23 | + |
| 24 | +A bulk action has two halves that are linked by a single **name string**: |
| 25 | +- **Client**: a button rendered in an entity's `Datagrid`, which calls `dataProvider.action(resource, name, params)`. |
| 26 | +- **Server**: a `case` in that entity's `doAction()` override, matched on `req.parsed.extra.action === name`. |
| 27 | + |
| 28 | +The request flow: button click → `POST /:resource/action?extra.action=<name>&extra.ids=<selectedIds>&...` → `BaseEntityController.doAction` → `<Entity>Service.doAction` → your `switch` case. |
| 29 | + |
| 30 | +## Client-side building blocks (`client/shared/components/crudContainers/`) |
| 31 | + |
| 32 | +| Component | Use for | Notes | |
| 33 | +|---|---|---| |
| 34 | +| `BulkActionButton.jsx` | A generic action, fire-and-forget or with a params form | Calls `dataProvider.action(resource, name, { 'extra.ids': selectedIds, ...formData })` | |
| 35 | +| `BulkReportButton.jsx` | An action that downloads a generated file | Calls `dataProvider.execAndDownload(resource, 'report?...', ...)` instead | |
| 36 | +| `BulkFixReferenceButton.jsx` | Thin preset over `BulkActionButton` for the `fixReferences` action | Copy this pattern for other one-off preset buttons | |
| 37 | +| `BulkRequestButton.jsx` | Shared UI both of the above use | Renders a plain button, or (if you pass `children` inputs) a dialog to collect extra params first, caching last-used values | |
| 38 | + |
| 39 | +Common props: `name` (must match the server-side `action` string), `label`, `icon`, `reloadOnEnd` (refresh the list after the mutation), `defaultRequestValues`, and `children` (react-admin `<Input>` elements) if the action needs user-supplied parameters. |
| 40 | + |
| 41 | +## Steps: add a new bulk action |
| 42 | + |
| 43 | +0. **Decide scope**: is this action specific to one project, or genuinely reusable across the four NRA apps? Default to project-local (steps 1-2 below); only add to `client/shared`/`server/shared` if reuse is the actual goal (see Context). |
| 44 | +1. **Client** — in the entity file (`client/src/entities/<entity>.jsx`): |
| 45 | + - Import `BulkActionButton` (or `BulkReportButton`), or import a shared preset if one already fits (e.g. `BulkFixReferenceButton`). |
| 46 | + - Add an entry to that file's `additionalBulkButtons` array with a unique `key` and a `name` — pass `children` inputs if the action needs params. |
| 47 | + - Pass `additionalBulkButtons={additionalBulkButtons}` to `CommonDatagrid` (already wired if the file already has other bulk buttons). |
| 48 | + - If the action should be reusable across projects, build the preset in `client/shared/components/crudContainers/` instead (following `BulkFixReferenceButton.jsx`) and import it from there. |
| 49 | +2. **Server** — in `server/src/entity-modules/<entity>.config.ts`: |
| 50 | + - Override `doAction(req, body)` on the entity's service class (extend `BaseEntityService`) if not already overridden. |
| 51 | + - Add a `case '<name>':` to the `switch (req.parsed.extra.action)` matching the client's `name`. |
| 52 | + - Read ids/params via `@shared/utils/queryParam.util` helpers (`getAsNumberArray`, `getAsDate`, `getAsBoolean`) off `req.parsed.extra`. |
| 53 | + - Do the work, then `return` a user-facing (Hebrew) result string. Fall through to `super.doAction(req, body)` for unmatched actions. |
| 54 | + - If the logic is genuinely reusable across projects, extract it into a util in `server/shared/utils/entity/` (following `fixReference.util.ts`) and call that from the `case`. |
| 55 | +3. Restart the project (`bash scripts/start-project.sh <project>`) and verify: select rows in the entity's list, trigger the button, confirm the success/error notification and (if `reloadOnEnd`) the list refresh. |
| 56 | + |
| 57 | +## Steps: modify an existing bulk action |
| 58 | + |
| 59 | +1. Find the button by its `name`/`label` in `client/src/entities/<entity>.jsx`. |
| 60 | +2. Find the matching `case '<name>':` in that entity's `doAction()` in `server/src/entity-modules/<entity>.config.ts`. |
| 61 | +3. Change client-side params (add/remove `children` inputs) and/or server-side logic together — they share the `extra.*` param names. |
| 62 | + |
| 63 | +## Reference example (`fixReferences`, on `Klass`) |
| 64 | + |
| 65 | +- Client wiring: `client/src/entities/klass.jsx` — `additionalBulkButtons` array, `<BulkFixReferenceButton key="fixReferences" label="תיקון שיוך" />` |
| 66 | +- Client preset: `client/shared/components/crudContainers/BulkFixReferenceButton.jsx` |
| 67 | +- Server: `server/src/entity-modules/klass.config.ts` — `KlassService.doAction`, `case 'fixReferences'` |
| 68 | +- Shared util: `server/shared/utils/entity/fixReference.util.ts` |
| 69 | + |
| 70 | +Other examples worth reading: `klass.jsx` also has `klassAttendanceReport` (a `BulkReportButton` with a params dialog and file download), and `user.jsx` has `bulkUpdatePaid`. |
| 71 | + |
| 72 | +## Troubleshooting |
| 73 | + |
| 74 | +| Symptom | Likely cause | |
| 75 | +|---|---| |
| 76 | +| Button click does nothing / no network request | `name` prop missing, or button not included in `additionalBulkButtons` passed to `CommonDatagrid` | |
| 77 | +| Server returns "done nothing" | No `case` matches `req.parsed.extra.action` — check the `name` strings match exactly on both sides | |
| 78 | +| Params form fields come back `undefined` on the server | Field `source` name doesn't match what you read via `req.parsed.extra.<field>` | |
| 79 | +| Selected rows don't clear after the action | `BulkActionButton`/`BulkReportButton` call `onUnselectItems()` on success — check your custom implementation does too if you wrote one from scratch | |
0 commit comments