List

Description
Configuration
Fields
Searching
Filters
Actions
New item link
Appearance examples

Description

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

Configuration

Basic example:

use App\Models\User;
use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListModule;

    ...

    $page = new AdminixPage();
    
    ...
    
    $page->addModule(
        ListModule::name('users')
            ->title('USERS')
            ->dataSource(User::class)
            ->pagination(20)
            ->addFields(...)
    )
    ...

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:

Method	Description
name	Name of module, must be unique in current page. name('users')	Required
title	Title on the top of the module title('USERS')	Optional
pagination	Number of items per page. To disable pagination must be equal to 0 or not exist. pagination(20)	Optional
dataSource	Source of data for List, can be an `Eloquent Model` - `\App\Models\User::class` or name of table in database `users` or `public.users` dataSource(\App\Models\User::class)	Required
withDeleted	Determines render or not deleted records (working with models with included `SoftDeletes` trait) By default, is not active withDeleted()	Optional
editable	Determines possibility to edit records directly in the List. Editable possibility for every field determines in his personal config. By default, is not active editable(),	Optional
primaryKey	Primary key in source table. Used for editable mode. Usually it is "id" primaryKey('id')	Required if editable mode is enabled
criteria	Database `Builder` criteria to render records. For example to not show administrator you need paste this: criteria([ ['is_admin', '=', false] ]) Or you can paste parameter from route: criteria([ ['user_id', '=', 'param:1'] ]) For example, for `https://site.com/adminix/comments/21` it will be mean that you need all comments where `user_id ==21`.	Optional
resource	Laravel `JsonResource` to provide data. Example: `\App\Http\Resources\UserAdminResource::class` resource(\App\Http\Resources\UserAdminResource::class)	Optional
addField addFields	Methods by which you can add fields to List for displaying. Arguments can be only `AlexKudrya\Adminix\Modules\List\ListField` class instances. Detailed here #Fields addField( ListField::name('Name') ->field('name') ->type(ListFieldTypeEnum::STRING) ->sortable() )	Required
search	Render "Search" input on the top of module. Argument - `AlexKudrya\Adminix\Modules\List\ListSearch` class instance. search( ListSearch::searchFields(['name', 'email']) ->placeholder('Search users') ) Detailed settings described below. #Searching	Optional
addFilter addFilters	Methods by which you can add filters for current List. Arguments can be only several classes instances: `AlexKudrya\Adminix\Modules\List\ListFilter` `AlexKudrya\Adminix\Modules\List\ListDateFilter` `AlexKudrya\Adminix\Modules\List\ListDateRangeFilter` ->addFilters( ListFilter::field('role_id') ->name('Role') ->src( InputSelectSrc::nameField('name') ->valueField('id') ->dataSource(UserRole::class) ), ListDateRangeFilter::field('created_at') ->name('Registration time') ->withTime() ) Detailed settings described below. #Filters	Optional
addAction addActions	Methods by which you can add action buttons (Links) for every item in current List module. Arguments can be only several classes instances: `AlexKudrya\Adminix\Modules\Link\AdminixLinkModule` `AlexKudrya\Adminix\Modules\Link\LinkModule` addAction( AdminixLinkModule::name('user_details') ->title('DETAILS') ->icon('bi bi-pencil') ->uri(UserPage::URI) ->params(['record:id']), ) Detailed settings described below. #Actions	Optional
sorting	Basic sorting for records in current List module. Argument can be only `AlexKudrya\Adminix\Modules\Sorting` class instance. Example: sorting( Sorting::field('id') ->direction('asc') )	Optional
newItemLink	Setting for "New Item" button rendered between Title and List, near to Search input. Format is similar to Adminix Link module. newItemLink( AdminixLinkModule::name('new_user_btn') ->title('NEW USER') ->icon('bi bi-person-fill-add') ->uri(NewUserPage::URI) ) Detailed here #New item link	Optional

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.

Example:

use App\Models\User;
use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListModule;

    ...

    $page = new AdminixPage();

    ...

    $page->addModule(
        ListModule::name('users')
            ->title('USERS')
            ->dataSource(User::class)
            ->pagination(20)
            ->addFields(
                ListField::name('Avatar')
                    ->field('avatar')
                    ->type(ListFieldTypeEnum::IMAGE),

                ListField::name('Name')
                    ->field('name')
                    ->type(ListFieldTypeEnum::STRING)
                    ->sortable()
                    ->editable(),

                ListField::name('Role')
                    ->field('role_id')
                    ->type(ListFieldTypeEnum::SELECT)
                    ->editable()
                    ->src(
                        InputSelectSrc::nameField('name')
                            ->valueField('id')
                            ->dataSource(Role::class)
                    )
                    ->addValidationRules(
                        'integer',
                        'required',
                        'exists:'. Role::class.',id'
                    ),

                ListField::name('Rating')
                    ->field('rating')
                    ->type(ListFieldTypeEnum::INTEGER)
                    ->editable()
                    ->sortable()
                    ->addValidationRules(
                        'integer',
                        'required',
                        'min:0',
                    ),

                ListField::name('Registration')
                    ->field('created_at')
                    ->type(ListFieldTypeEnum::DATETIME)
                    ->sortable(),

                ListField::name('Administrator')
                    ->field('is_admin')
                    ->type(ListFieldTypeEnum::BOOLEAN),

                ListField::field('deleted_at')
                    ->type(ListFieldTypeEnum::HIDDEN),

                ListField::field('id')
                    ->type(ListFieldTypeEnum::HIDDEN),
            )
    )
    ...

`ListField` configurations

Method

Description

name

Title of the field displayed on the top of table (inside <th/> tag)

name('Role')

Required

type

Type of rendered field, can be provided only by AlexKudrya\Adminix\Modules\List\ListFieldTypeEnum Enum class

Available types for rendered field:

STRING
EMAIL
INTEGER
FLOAT
BOOLEAN
SELECT
DATE
DATETIME
HIDDEN
TEXTAREA

It determines data format to render, and type of input for editable mode.

Example:

type(ListFieldTypeEnum::SELECT)

Required

field

Name of field in database or resource (if resource was provided).

field('role_id')

Required

sortable

Determines the sorting possibility for current field.

Can not be used to fields which provided by resource, and not exist in database table, or his name was modified.

By default, is not enabled.

sortable()

Optional

editable

Determines the editable possibility for current field.

Can not be used to fields which provided by resource, and not exist in database table, or his name was modified.

This will not be working if in List module editable mode is not enabled.

To working correctly requires primary key (usually it is "id" field) in this fields list (can be hidden type).

By default, is not enabled.

editable()

Optional

src

Required for fields with type SELECT. Need to display correct value from related table.

For example, users table has related table roles, and relation made by role_id field in users table. To display normal role name from roles table, not role_id from users table, you need to configure src correctly.

Argument can be only AlexKudrya\Adminix\Modules\InputSelectSrc class instance.

Example:

ListField::name('Role')
    ->field('role_id')
    ->type(ListFieldTypeEnum::SELECT)
    ->editable()
    ->src(
        InputSelectSrc::nameField('name')
            ->valueField('id')
            ->dataSource(Role::class)
    )

InputSelectSrc configuration:

Methods	Description
dataSource	Source of data for filed items, can be an `Eloquent Model` - `\App\Models\Role::class` or name of table in database `roles`or `public.roles` dataSource(\App\Models\Role::class)
nameField	Name of field in related table to be displayed nameField('name')
valueField	Name of primary key field related to main table (usually it is "id") valueField('id')

addSelectRecords

Required for fields with type SELECT as an alternative for src(). Required if src is empty. It is a list of options, where name() is a title of <option/>, and value()is a value of <option/>

Arguments can be only AlexKudrya\Adminix\Modules\SelectRecord class instances.

Example:

ListField::name('Role')
    ->field('role_id')
    ->type(ListFieldTypeEnum::SELECT)
    ->editable()
    ->addSelectRecords(
        SelectRecord::name('Admin')->value(1),
        SelectRecord::name('Manager')->value(2),
        SelectRecord::name('Seller')->value(3),
        SelectRecord::name('Guest')->value(4),
    )
...

Searching

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

Example:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListSearch;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->search(
            ListSearch::searchFields(['name', 'email'])
                ->placeholder('Search users')
        )
)

...

Method	Description
searchFields	An array of fields which involved in the search process. The more fields, the slower but more accurate the search. Every field must be existed in main database table searchFields(['name', 'email'])	Required
placeholder	A placeholder for Search `<input/>` placeholder('Search users')	Optional

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

`ListFilter`

Basic filter - <select/> input with defined options

Example:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListFilter;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->addFilters(
            ListFilter::field('role_id')
                ->name('Role')
                ->src(
                    InputSelectSrc::nameField('name')
                        ->valueField('id')
                        ->dataSource(\App\Models\Role::class)
                ),
        )
)

...

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListFilter;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->addFilters(
            ListFilter::field('role_id')
                ->name('Role')
                ->addFilterRecords(
                    ListFilterRecord::name('Client')->value(1),
                    ListFilterRecord::name('Guest')->value(2),
                    ListFilterRecord::name('Manager')->value(3),
                    ListFilterRecord::name('Admin')->value(4),
                )
        )
)

...

Method

Description

name

Title of the filter

name('Role')

Required

field

Name of the field used for filtering. Field must be existed in base database table

field('role_id')

Required

src

Required if filter_records is empty. Has a format similar to select field src directive:

src(
    InputSelectSrc::nameField('name')
        ->valueField('id')
        ->dataSource(\App\Models\Role::class)
),

setting	Description
dataSource	Source of data for filed items, can be an `Eloquent Model` - `\App\Models\Role::class` or name of table in database `roles`or `public.roles`
nameField	Name of the field witch used as a title of `<option/>`
valueField	Name of the field witch used as a value of `<option/>` (usually it is "id")

Required if no filterRecords()

filterRecords

Required if src is empty. It is an array of options, where name is a title of <option/>, and valueis a value of <option/>

addFilterRecords(
    ListFilterRecord::name('Client')->value(1),
    ListFilterRecord::name('Guest')->value(2),
    ListFilterRecord::name('Manager')->value(3),
    ListFilterRecord::name('Admin')->value(4),
)

Required if no src

`ListDateFilter`

Date filter - allows you to select records within a selected date.

Example:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListDateFilter;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->addFilters(
            ListDateFilter::field('created_at')
                ->name('Registration date')
        )
)

...

Method	Description
field	Name of the field used for filtering. Field must have `timestamp`, `date` or `datetime` format. field('created_at')	Required
name	Title of the filter name('Registration date')	Required

`ListDateRangeFilter`

Date range filter - allows you to select records within a date range.

Example:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListDateRangeFilter;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->addFilters(
            ListDateRangeFilter::field('created_at')
                ->name('Registration date')
                ->withTime()
        )
)

...

Method	Description
field	Name of the field used for filtering. Field must have `timestamp`, `date` or `datetime` format. field('created_at')	Required
name	Title of the filter name('Registration date')	Required
withTime	Determines whether the filter will filter by time or only by dates. By default, filter only by date, without time. withTime()	Optional
filterFrom	Define "From" input. If set `false`, "From" `datepicker` will not be displayed. By default, it is enabled. filterFrom(false)	Optional
filterTo	Define "To" input. If set `false`, "To" `datepicker` will not be displayed. By default, it is enabled. filterTo(false)	Optional

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:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\Link\AdminixLinkModule;
use AlexKudrya\Adminix\Modules\Link\LinkModule;
use AlexKudrya\Adminix\Enums\HttpMethodsEnum;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->addActions(
            AdminixLinkModule::name('edit')
                ->title('EDIT')
                ->icon('bi bi-pencil')
                ->uri(UserPage::URI)
                ->params(['record:id']),
        
            LinkModule::name('delete')
                ->title('BAN')
                ->icon('bi bi-person-fill-slash')
                ->uri('ban_user')
                ->method(HttpMethodsEnum::POST)
                ->params(['record:id'])
                ->criteria([
                    ['deleted_at', '==', null]
                ]),
        
            LinkModule::name('restore')
                ->title('UNBAN')
                ->icon('bi bi-person-fill-up')
                ->uri('unban_user')
                ->method(HttpMethodsEnum::POST)
                ->params(['record:id'])
                ->criteria([
                    ['deleted_at', '!=', null]
                ]),
        )
)
...

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

Method	Description
name	Title which will be displayed on the button name('EDIT')	Optional
uri	In case `AdminixLinkModule` uri means the `uri` directive of page which defined in Adminix config file. In this case better to use `URI` constant from target page provider class. uri(UserPage::URI) In case `LinkModule` uri means the name of any route defined in router of your Laravel application. Just copy route name from router. uri('edit_user')	Required
icon	Icon class name from Bootsrap icons Example: to generate in the Link an icon `<i class="bi bi-people-fill"></i>` you need paste here `bi bi-people-fill` class name icon('bi bi-people-fill')	Optional
method	Type of HTTP request, can be provided only by `AlexKudrya\Adminix\Enums\HttpMethodsEnum` Enum class In case `AdminixLinkModule` method can be only GET so it is redundant. In case `LinkModule` method must be match to the route defined in uri directive. By default, it is equal to `HttpMethodsEnum::GET` method(HttpMethodsEnum::POST)	Required if not GET
params	Technically it is optional directive, but `action` without params makes it pointless, so it is make it required. It is list of parameters which you added to your action (usually it is "id"). When `record:id`, means that id of current record will be the parameter. By the way, for this purpose, if you not display id field i your list, you need add it to fields directive, if you do not want to display it you may add this field with `HIDDEN` type. Parameters adds to your link like this: /`parameter 1`/`parameter 2`... Example: params(['record:id']) For record with id = 123 action link will be `https://example/uri/123`	Required
criteria	Determines display or not this action button for current record. For example if you need display action button only for users without admin status, you can do it like this: criteria([ ['is_admin', '==', false] ]) or criteria([ ['deleted_at', '!=', null] ]) Attention! This directive support only `==` and `!=` operators, `>`, `<`, `>=`, `<=` is not working!	Optional

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:

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\Link\AdminixLinkModule;

$page = new AdminixPage();

...

$page->addModule(
    ListModule...
        ->newItemLink(
            AdminixLinkModule::name('new_user_btn')
                ->title('NEW USER')
                ->icon('bi bi-person-fill-add')
                ->uri(NewUserPage::URI)
        )
)

...

Appearance examples

Here is example of List without editable mode:

Here is example of List with editable mode:

Last modified: 05 June 2024

List

Description

Configuration

ListModule configuration

Fields

ListField configurations

Searching

Filters

ListFilter

ListDateFilter

ListDateRangeFilter

Actions

New item link

Appearance examples

`ListModule` configuration

`ListField` configurations

`ListFilter`

`ListDateFilter`

`ListDateRangeFilter`