Views (Bookmarks)

Inertia Table offers a way for users to save and switch between different table states. This is useful for users who frequently work with the same filters, sorting, and columns. The Views are saved to the database.

Getting Started

To use the Views feature, you need to publish the database migration for the views database table. You can do this by running the following command:

php artisan vendor:publish --tag=inertia-table-migrations

After running the command, you will find a migration file in the database/migrations directory. You can then run the migration to create the views database table:

php artisan migrate

Defining Views

To enable Views, you can use the views() method in your Table class. This method should return an instance of the Views class.

use InertiaUI\Table\Views;

class Users extends Table
{
    public function views(): ?Views
    {
        return Views::make();
    }
}

Customizing Views

By default, the Views are stored per user. It uses Laravel's built-in authentication system to determine the current user using the Auth facade. You can disable this behavior or pass a custom resolver to retrieve the user ID.

Disabling User-based Views

To disable user-based views, you can pass false to the scopeUser argument of the Views::make() method. Alternatively, you can chain the scopeUser method on the Views instance. Please note that this will make the views shared across all users, so be cautious when using this feature.

Views::make(scopeUser: false);

Views::make()->scopeUser(false);

If you want to disable this feature globally, you may call the static defaultScopeUser, for example, in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultScopeUser(false);

Custom user ID Resolver

If you want to use a custom resolver to determine the user ID, you can pass a closure to the userResolver argument. Alternatively, you may chain the userResolver method on the Views instance.

Views::make(userResolver: fn () => current_user()->uuid);

Views::make()->userResolver(fn () => current_user()->uuid);

If you want to set a global resolver, you can call the static defaultUserResolver method in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultUserResolver(
    fn () => current_user()->uuid
);

Custom attributes

You may add additional columns to the table migration. You can then define attributes that will be used to both query and store the views. You can pass an array of attributes, or a closure that returns an array of attributes, to the attributes argument of the Views::make() method. Alternatively, you can chain the attributes method on the Views instance.

Views::make(attributes: ['tenant_id' => tenant_id()]);

Views::make()->attributes(fn () => ['tenant_id' => tenant_id()]);

If you want to set a global attributes array, you can call the static defaultAttributes method, for example, in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultAttributes(['tenant_id' => tenant_id()]);

Table name scoping

By default, the Views for a Table class are not scoped by the Table name. This means that if you reuse the same Table class across different pages, they will share the same stored views. This default behavior will most of the time be what you want, since Table names are usually only used when using multiple tables on the same page.

If you still want to scope the Views by the Table name, you can pass true to the scopeTableName argument of the Views::make() method. Alternatively, you can chain the scopeTableName method on the Views instance.

Views::make(scopeTableName: true);

Views::make()->scopeTableName(true);

If you want to do this globally, you can call the static defaultScopeTableName method, for example, in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultScopeTableName(true);

Stateful resources scoping

By default, the Views for a Table class are not scoped by the stateful resources. Imagine an Employees Table that accepts a Company Eloquent Model instance in its constructor:

class Employees extends Table
{
    public function __construct(
        #[Remember] public Company $company
    ) { }
}

By default, the Views are stored independently of the Company instance, so it doesn't matter which Company you pass to the Employees Table class.

If you want to scope the Views by the stateful resources, you can pass true to the scopeStatefulResources argument of the Views::make() method. Alternatively, you can chain the scopeStatefulResources method on the Views instance.

Views::make(scopeStatefulResources: true);

Views::make()->scopeStatefulResources(true);

If you want to do this globally, you can call the static defaultScopeStatefulResources method, for example, in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultScopeStatefulResources(true);

Custom Eloquent Model

The Views feature uses the built-in InertiaUI\Table\TableView Eloquent Model. If you want to use a custom model, you can pass the model class name to the modelClass argument of the Views::make() method. Alternatively, you can chain the modelClass method on the Views instance.

Views::make(modelClass: CustomTableView::class);

Views::make()->modelClass(CustomTableView::class);

If you want to set a global model class, you can call the static defaultModelClass method, for example, in your AppServiceProvider:

use InertiaUI\Table\Views;

Views::defaultModelClass(CustomTableView::class);

It's recommended to check the source code of the InertiaUI\Table\TableView model to see which scopes are defined and how they are used.

Custom texts

Texts used in the Views feature, such as the "Save View" button text, are part of the translation file. Please refer to the Translations documentation for more information on how to customize the texts.

Default Views

Instead of defining the views in your Table class, you can also define them globally. You may call the static defaultViewsResolver method on the Table class, for example, in your AppServiceProvider:

use InertiaUI\Table\Table;
use InertiaUI\Table\Views;

Table::defaultViewsResolver(
    fn (Table $table) => Views::make()->scopeUser(false)
);

This will apply the Views configuration to all Table classes unless overridden in a specific Table class. The callback receives the Table instance as an argument, allowing you to customize the Views based on the specific Table class.