List

Description

The "List" module purpose - render list of some records from your database to work with them.

When the resolved list has no rows, Adminix renders a single No records found. table row. The empty state uses the same table width and responsive scroll container as regular records, including relation manager child lists.

1. Configuration

2. Lenses

3. Fields

4. Row details

5. Column visibility

6. Density and sticky table controls

7. Searching

8. Filters

9. Reset controls

10. Mobile behavior

11. Bulk actions

12. Actions

13. New item link

14. Appearance examples

Configuration

Basic example:

To add to the page List module you need paste AlexKudrya\Adminix\Modules\List\ListModule class instance as an argument to addModule or addModules method of AdminixPage object.

ListModule configuration

Full settings list:

Lenses

Lenses are server-defined saved views for ListModule. They are useful for common list presets such as Active, Drafts, Deleted, VIP, or Needs review.

The active lens is selected by the query key lens-{moduleName}. Adminix resolves this value only against lenses configured in PHP. Unknown lens names are ignored and the default list is rendered.

Lens criteria are applied after base ListModule::criteria() and before user filters, search, and sorting. Lens filters are defaults for configured list filters. Use the filter field as the key:

Result: when the URL contains lens-users=needs-review and does not contain filter-users-status, Adminix applies status = pending and shows the filter as selected. If the URL already contains filter-users-status, the request value wins and the lens default is not used. Date range defaults can use a nested from/to map or flat keys such as created_at-from. Lens sorting is a default sorting only: if the request contains a valid sort-{module}-{field} parameter, the user-selected sorting wins. Pagination links keep the active lens query parameter.

Use base criteria() for mandatory tenant/user scoping. Use lenses only for alternate server-owned views inside that scope.

Fields

Fields is an array, of fields to be rendered in the List.

To add Field to the List module you need paste AlexKudrya\Adminix\Modules\List\ListField class instance as an argument to addField or addFields method of ListModule object.

Row details

Use ListRowDetails when a list needs a compact primary row plus expandable read-only metadata. Adminix renders one toggle column and a hidden detail row for every visible record. The detail panel is prepared from the same server-side list datasource, base criteria, active lens, filters, search, sorting, pagination, and optional relation scope used for the rendered table.

ListRowDetails supports:

• make($title = null)/title() for an optional detail heading;

• columns(1..4) for the read-only field grid;

• addField()/addFields() with DetailField or another ResourceField subclass;

• expanded() to render all detail rows initially open, otherwise they are collapsed and toggled with JavaScript.

Row details do not add a write endpoint and do not trust browser-owned datasource, criteria, field names, or primary keys. Password fields are rendered without stored values, matching resource/detail password safety. Keep sensitive tenant, owner, credential, and internal audit columns out of row details unless they are intentionally visible to the admin user.

ListField configurations

Column visibility

columnVisibility() adds a Columns section to the compact list settings dropdown for the current ListModule. Only fields marked with hideable() or defaultHidden() are included in that section. The list settings dropdown grows to its content height and only uses vertical scrolling when the menu would exceed the viewport. On narrower desktop viewports, the list settings button shifts left only when its screen position vertically overlaps the fixed shell notification bell. Column toggles, density options, reset, and CSV export actions share the same menu item sizing, spacing, rounded corners, and hover treatment. Column toggles are rendered as switch controls, matching boolean field controls elsewhere in Adminix.

Result: Adminix shows a gear-icon settings button as a root-level absolute control aligned to the list title area. The control does not reserve toolbar or filter space; when a list has no title, it stays inside the list root without adding an empty row. The Customer column is visible by default and can be hidden by the user. The Internal note column is hidden by default and can be shown from the same settings menu. The hidden id field and service columns for inline edit or row actions are not controlled by column visibility.

Column visibility is a browser-only presentation setting. It is stored in local storage by list name and does not change request keys, datasource, criteria, filters, sorting, row actions, authorization, or export scope. For server-side list visibility, use ListField::hiddenOnIndex()/hideOnIndex(). Hidden-on-index fields are not rendered in the table and are not writable through inline edit.

Density and sticky table controls

densitySwitcher(), stickyHeader(), and stickyActions() are opt-in presentation helpers for wide or frequently used tables.

Result: Adminix renders Comfortable and Compact density choices inside the gear-icon list settings menu. The selected density is stored in browser local storage by list name. Compact density reduces table cell padding plus inline row controls such as editable inputs, selects, row action buttons, switches, date-range/key-value editors, async selects, and row images. Inline controls use a 32px minimum height, row images cap at 38px, cells align content vertically in the middle, and action button icons keep the normal UI-kit gap from text. stickyHeader() keeps table headers visible inside the scroll container. stickyActions() keeps the existing final service column visible while the table fits the available width. When a list table is wider than the available viewport, Adminix preserves the table's content width, moves the service column into the horizontal scroll flow, and uses horizontal scrolling instead of compressing or overlapping right-side columns into data cells.

These controls do not create a new action layer. Existing addAction()/addActions() links, non-GET forms, confirm prompts, tooltips, modal togglers, and record:*/param:* route parameters continue to render through the same row action contract. If the list also uses rowActionsDropdown(), stickyActions() keeps the dropdown trigger in the same service column.

CSV export

exportCsv() adds an Export CSV action to the list settings menu for the current ListModule. CSV export is disabled by default and must be enabled per list.

Result: Adminix shows an Export CSV action inside the gear-icon list settings menu. The endpoint applies the same server-side datasource, criteria, active lens, filters, search, and sorting as the list. The current pagination page is ignored, and export rows are capped by the configured limit. The default limit is 10000.

The browser cannot choose a datasource or arbitrary columns for CSV export. Adminix signs the current page params when rendering the export link so param:* criteria use the same route context as the visible list. ListFieldTypeEnum::HIDDEN fields are excluded by default. Use ListField::exportable() only for hidden fields that are safe to include in the CSV. Fields hidden with hiddenOnIndex() are also excluded unless they are explicitly marked exportable(). Row actions, inline edit controls, service columns, and UI-only column visibility are not exported.

Bulk actions

Bulk actions are opt-in server-side actions for selected rows in a ListModule. They render a checkbox column, Select all current page checkbox, action dropdown, selected count, and submit button above the table.

Result: Adminix shows bulk controls above the list. The button stays disabled until the user selects at least one current-page row and one configured action. When confirm() is configured, the browser shows that confirmation before submitting. The web endpoint redirects back with a success or error toast, or returns a direct Response when the handler returns one.

BulkAction settings:

• name() is the stable server-side action key submitted by the browser.

• title() is the dropdown label.

• icon() stores an optional Bootstrap icon class for package consumers and future renderers.

• tooltip() stores optional helper text for package consumers and future renderers.

• color() stores an optional ColorsEnum value or CSS color string.

• destructive() marks dangerous actions for custom renderers and future UI states.

• confirm() sets an optional submit confirmation message.

• criteria() stores optional action visibility criteria metadata; execution still uses the selected row scope.

• addField()/addFields() declare input fields shown before the selected bulk action is submitted.

• handler() accepts a callable, object, or class string. Implement BulkActionHandlerInterface for reusable actions.

• authorizeUsing()/authorization() accepts a boolean, callable, object with authorize(), or class string.

• batchLimit() caps selected scalar IDs before the handler runs. Default is 1000.

• queued('Message') dispatches the handler through Laravel queues after the normal server-side scope and authorization checks.

• progressTrigger() starts a matching ProgressBarModule trigger when the selected action is submitted.

• onConnection() and onQueue() optionally select the Laravel queue transport for queued bulk actions.

• actionMetadata() returns the shared Actions metadata DTO.

BulkActionRequest gives handlers:

• module() and action() from server-side configuration;

• requestedIds() from the request after scalar normalization;

• selectedIds() after applying the current list scope;

• query() already scoped to selected records;

• primaryKey() from the list module;

• httpRequest() for request/session context when needed.

• fields() and field($name, $default = null) for server-declared action field values.

Action fields are documented in Actions. They are submitted as adminix_action_fields[...], but Adminix only passes keys declared on the selected server-side BulkAction to the handler.

Handlers can return:

• BulkActionResult::success('Message');

• BulkActionResult::error('Message');

• BulkActionResult::validation(['field' => ['Message']]);

• BulkActionResult::redirect('/adminix/orders');

• BulkActionResult::openInNewTab('/adminix/orders/export.csv');

• BulkActionResult::modal('Title', 'Body');

• BulkActionResult::download($response) or a Symfony/Laravel Response for downloadable/custom responses.

Typed action responses are documented in Actions. Queued actions are documented in Actions.

The endpoint resolves page, module, relation context, and action from server-side module configuration. The browser submits only selected IDs and action name. Datasource, primary key, criteria, active lens, filters, search, sorting, relation parent scope, and page params are resolved server-side. IDs outside the current criteria/search/filter/relation scope are ignored; if no selected ID remains in scope, the request fails with a controlled validation error. After a handler returns a normalized result, Adminix dispatches BulkActionExecuted and passes the scope-filtered selected IDs in audit metadata. See Audit for recorder and listener examples.

Bulk actions do not replace row actions. Existing addAction()/addActions() links, non-GET row forms, modal togglers, confirm prompts, tooltips, and record:* params remain the row action contract.

Searching

Determines possibility to make full-text search in source table.

Example:

Filters

Add filters to the top of the module, near to search input. Provides the ability to filter the list by specific fields.

There are several types of filters available:

• ListFilter - AlexKudrya\Adminix\Modules\List\ListFilter

• ListDateFilter - AlexKudrya\Adminix\Modules\List\ListDateFilter

• ListDateRangeFilter - AlexKudrya\Adminix\Modules\List\ListDateRangeFilter

Reset controls

resetControls() adds a Reset view action to the list settings menu for the current ListModule. It is disabled until the current URL or browser storage contains state for that list.

Result: when the URL contains keys such as search-orders, filter-orders-status, sort-orders-created_at, lens-orders, or page, Adminix shows an enabled Reset view action inside the gear-icon list settings menu. The same action is enabled when browser-only view state exists for the list, such as hidden/shown columns or compact density. Clicking it returns to the same page without current-list URL state and clears current-list browser view state. Unrelated query parameters and another list module's view state are preserved.

This is a presentation and URL-state convenience only. It does not create a new server-side action endpoint and does not change list filters, row actions, datasource, or authorization behavior.

Mobile behavior

ListModule keeps the same PHP configuration and request contract on mobile. Search, lenses, filters, sorting, pagination, editable rows, row actions, and modal togglers still use the same module name and server-side configuration.

Example configuration:

Result:

• desktop renders filters inline above the table;

• narrow screens show a Filters button with an active-filter count;

• the button opens a drawer containing the same ListFilter, ListDateFilter, and ListDateRangeFilter controls;

• changing a filter still writes the same filter-{moduleName}-{field} query key and resets pagination;

• wide tables scroll horizontally inside the table area, not across the whole Adminix shell;

• row actions remain the existing buttons/forms/modal togglers, including route params, CSRF methods, confirm text, icons, and tooltips.

The mobile drawer is a presentation wrapper only. Do not add browser-owned datasource, action, or filter metadata; continue to configure lists from PHP classes.

Actions

"Actions" is an array of control buttons for every single record, to do some actions, such as "open", "edit", "delete", or wherever else you need.

Example:

To add Action buttons to List module you need paste AlexKudrya\Adminix\Modules\Link\AdminixLinkModule or AlexKudrya\Adminix\Modules\Link\LinkModule class instances as an argument to addAction or addActions method of AdminixPage object.

Action buttons syntax is similar to Link module

By default, Adminix renders row actions inline in the final service column. For dense tables with many row controls, call rowActionsDropdown() on the same ListModule to render one compact vertical three-dots button per row. Clicking it opens a small contextual dropdown next to the trigger and shows the same configured actions inside the menu.

Result: every row keeps a single bi-three-dots-vertical trigger in the action column. The dropdown contains the existing GET links, POST/PUT/PATCH/DELETE forms with CSRF and confirm prompts, and modal togglers. If an action has an icon but no title, the dropdown uses the action name() as a text label so the menu remains readable. Rows where criteria() hides all actions still render an empty service cell to keep the table columns aligned.

rowActionsDropdown() is presentation-only. It does not change action authorization, criteria evaluation, route parameter substitution, signed modal relation context, request payloads, datasource, or persistence behavior.

New item link

Usually, in the admin panels, lists have the ability to add new records, and the New resource module is used for this. In order to display a link to a page with such a module in the correct place in the "list" module, there is this directive

Format is similar to Link module or Actions

Example:

or

Appearance examples

Here is example of List without editable mode:

Here is example of List with editable mode: