@protonemedia/inertiajs-tables-laravel-query-builder

    1.3.4 • Public • Published

    Inertia.js Tables for Laravel Query Builder

    Latest Version on NPM npm Latest Version on Packagist Software License run-tests

    This package provides a DataTables-like experience for Inertia.js with support for searching, filtering, sorting, toggling columns, and pagination. It generates URLs that can be consumed by Spatie's excellent Laravel Query Builder package, with no additional logic needed. The components are styled with Tailwind CSS 2.0, but it's fully customizable and you can bring your own components. The data refresh logic is based on Inertia's Ping CRM demo.

    Inertia.js Table for Laravel Query Builder

    Launcher 🚀

    Hey! We've built a Docker-based deployment tool to launch apps and sites fully containerized. You can find all features and the roadmap on our website, and we are on Twitter as well!

    Support

    We proudly support the community by developing Laravel packages and giving them away for free. Keeping track of issues and pull requests takes time, but we're happy to help! If this package saves you time or if you're relying on it professionally, please consider supporting the maintenance and development.

    Features

    • Global search
    • Search per field
    • Filters
    • Toggle columns
    • Sort columns
    • Pagination
    • Automatically updates the query string (by using Inertia's replace feature)

    Compatibility

    Roadmap

    • Remove @tailwindcss/forms dependency
    • Debounce delay for inputs
    • Convert Table.vue styling to proper Tailwind syntax
    • Improve styling on really small screens
    • Better documentation about customization and move to real renderless components

    Installation

    You need to install both the server-side package as well as the client-side package. Note that this package is only compatible with Laravel 8, Vue 2.6 + 3.0 and requires the Tailwind Forms plugin.

    Server-side installation (Laravel)

    You can install the package via composer:

    composer require protonemedia/inertiajs-tables-laravel-query-builder

    The package will automatically register the Service Provider which provides a table method that you can use on an Interia Response.

    Search fields

    With the addSearch method, you can specify which attributes are searchable. Search queries are passed to the URL query as a filter. This integrates seamlessly with the filtering feature of the Laravel Query Builder package.

    You need to pass in the attribute and the label as arguments. With the addSearchRows method, you can add multiple attributes at once.

    Inertia::render('Page/Index')->table(function ($table) {
        $table->addSearch('name', 'Name');
    
        $table->addSearchRows([
            'email' => 'Email',
            'job_title' => 'Job Title',
        ]);
    });

    Filters

    Filters are similar to search fields, but they use a select element instead of an input element. This way, you can present the user a pre-defined set of options. Under the hood, this uses the same filtering feature of the Laravel Query Builder package.

    This method takes three arguments: the attribute, the label, and a key-value array with the options.

    Inertia::render('Page/Index')->table(function ($table) {
        $table->addFilter('language_code', 'Language', [
            'en' => 'Engels',
            'nl' => 'Nederlands',
        ]);
    });

    Columns

    With the addColumn method, you can specify which columns you want to be toggleable. You need to pass in a key and label for each column. With the addColumns method, you can add multiple columns at once.

    Inertia::render('Page/Index')->table(function ($table) {
        $table->addColumn('name', 'Name');
    
        $table->addColumns([
            'email' => 'Email',
            'language_code' => 'Language',
        ]);
    });

    The addColumn method has an optional third parameter to disable the column by default:

    $table->addColumn('name', 'Name', false);

    Disable global search

    By default, global search is enabled. This query will be applied to the filters by the global attribute. If you don't want to use the global search, you can use the disableGlobalSearch method.

    Inertia::render('Page/Index')->table(function ($table) {
        $table->disableGlobalSearch();
    });

    Example controller

    <?php
    
    namespace App\Http\Controllers;
    
    use App\Models\User;
    use Inertia\Inertia;
    use ProtoneMedia\LaravelQueryBuilderInertiaJs\InertiaTable;
    use Spatie\QueryBuilder\AllowedFilter;
    use Spatie\QueryBuilder\QueryBuilder;
    
    class UserIndexController
    {
        public function __invoke()
        {
            $globalSearch = AllowedFilter::callback('global', function ($query, $value) {
                $query->where(function ($query) use ($value) {
                    $query->where('name', 'LIKE', "%{$value}%")->orWhere('email', 'LIKE', "%{$value}%");
                });
            });
    
            $users = QueryBuilder::for(User::class)
                ->defaultSort('name')
                ->allowedSorts(['name', 'email', 'language_code'])
                ->allowedFilters(['name', 'email', 'language_code', $globalSearch])
                ->paginate()
                ->withQueryString();
    
            return Inertia::render('Users/Index', [
                'users' => $users,
            ])->table(function (InertiaTable $table) {
                $table->addSearchRows([
                    'name' => 'Name',
                    'email' => 'Email address',
                ])->addFilter('language_code', 'Language', [
                    'en' => 'Engels',
                    'nl' => 'Nederlands',
                ])->addColumns([
                    'email' => 'Email address',
                    'language_code' => 'Language',
                ]);
            });
        }
    }

    Client-side installation (Inertia)

    You can install the package via either npm or yarn:

    npm install @protonemedia/inertiajs-tables-laravel-query-builder --save
    
    yarn add @protonemedia/inertiajs-tables-laravel-query-builder

    Add the repository path to the purge array of your Tailwind configuration file. This ensures that the styling also works on production builds.

    module.exports = {
      purge: [
        './node_modules/@protonemedia/inertiajs-tables-laravel-query-builder/**/*.{js,vue}',
      ]
    }

    Table component

    To use the Table component and all its related features, you need to add the InteractsWithQueryBuilder mixin to your component and add the Tailwind2.Table component to the components key.

    You can use the named #head slot to provide the table header and the named #body slot to provide the table body. You can use the showColumn method to determine if a column should be visible or not. You can use the sortBy method to set the column you want to sort by.

    Page component example

    <template>
      <Table
        :filters="queryBuilderProps.filters"
        :search="queryBuilderProps.search"
        :columns="queryBuilderProps.columns"
        :on-update="setQueryBuilder"
        :meta="users"
      >
        <template #head>
          <tr>
            <th @click.prevent="sortBy('name')">Name</th>
            <th v-show="showColumn('email')" @click.prevent="sortBy('email')">Email</th>
            <th v-show="showColumn('language_code')" @click.prevent="sortBy('language_code')">Language</th>
          </tr>
        </template>
    
        <template #body>
          <tr v-for="user in users.data" :key="user.id">
            <td>{{ user.name }}</td>
            <td v-show="showColumn('email')">{{ user.email }}</td>
            <td v-show="showColumn('language_code')">{{ user.language_code }}</td>
          </tr>
        </template>
      </Table>
    </template>
    
    <script>
    import { InteractsWithQueryBuilder, Tailwind2 } from '@protonemedia/inertiajs-tables-laravel-query-builder';
    
    export default {
      mixins: [InteractsWithQueryBuilder],
    
      components: {
        Table: Tailwind2.Table
      },
    
      props: {
        users: Object
      }
    };
    </script>

    Attributes and pagination

    The filters, search, columns, and on-update attributes of the Table component are required, but the the InteractsWithQueryBuilder mixin magically provides the values for those attributes. You just have to specify them like the example template above.

    When you pass a meta object to the table, it will automatically provide a pagination component.

    You can override the default pagination translations with the setTranslations method of the base component. You can do this in your main JavaScript file:

    import { Components } from "@protonemedia/inertiajs-tables-laravel-query-builder";
    
    Components.Pagination.setTranslations({
      no_results_found: "No results found",
      previous: "Previous",
      next: "Next",
      to: "to",
      of: "of",
      results: "results",
    });

    Table.vue slots

    The Table.vue has several slots that you can use to inject your own implementations.

    Slot Description
    tableFilter The location of the button + dropdown to select filters.
    tableGlobalSearch The location of the input element that handles the global search.
    tableAddSearchRow The location of the button + dropdown to add additional search rows.
    tableColumns The location of the button + dropdown to toggle columns.
    tableSearchRows The location of the input elements that handle the additional search rows.
    tableWrapper The components that wraps the table element, handling overflow, shadow, padding, etc.
    table The actual table element.
    head The location of the table header.
    body The location of the table body.
    pagination The location of the paginator.

    Each slot is provided with props to interact with the parent Table component.

    <template>
      <Table ...>
        <template v-slot:tableGlobalSearch="slotProps">
          <input
            placeholder="Custom Global Search Component..."
            :value="slotProps.search.global.value"
            @input="slotProps.changeGlobalSearchValue($event.target.value)"
          />
        </template>
    
        <template #body>
          ...
        </template>
      </Table>
    </template>

    Bring your own components

    The templates and logic of the components are entirely separated. This way, you can create new templates while reusing the existing logic.

    There are nine components that you can import and use as a mixin for your templates. For example, to write your own TableGlobalSearch component, you can import the base component and use its logic by adding it as a mixin.

    <template>
      <input
        class="form-input"
        placeholder="Custom Global Search Component..."
        :value="value"
        @input="onChange($event.target.value)"
      />
    </template>
    
    <script>
    import { Components } from '@protonemedia/inertiajs-tables-laravel-query-builder';
    
    export default {
      mixins: [Components.TableGlobalSearch],
    };
    </script>

    Available components:

    • Components.ButtonWithDropdown
    • Components.OnClickOutside
    • Components.Pagination
    • Components.Table
    • Components.TableAddSearchRow
    • Components.TableColumns
    • Components.TableFilter
    • Components.TableGlobalSearch
    • Components.TableSearchRows

    A good starting point would be to duplicate the js/Tailwind2 folder into your app and start customizing the templates from there.

    Testing

    You can run the PHP test suite with composer:

    composer test

    You can run the JS test suite with either npm or yarn:

    npm run test
    
    yarn test

    Changelog

    Please see CHANGELOG for more information what has changed recently.

    Contributing

    Please see CONTRIBUTING for details.

    Other Laravel packages

    • Laravel Analytics Event Tracking: Laravel package to easily send events to Google Analytics.
    • Laravel Blade On Demand: Laravel package to compile Blade templates in memory.
    • Laravel Cross Eloquent Search: Laravel package to search through multiple Eloquent models.
    • Laravel Eloquent Scope as Select: Stop duplicating your Eloquent query scopes and constraints in PHP. This package lets you re-use your query scopes and constraints by adding them as a subquery.
    • Laravel Eloquent Where Not: This Laravel package allows you to flip/invert an Eloquent scope, or really any query constraint.
    • Laravel FFMpeg: This package provides an integration with FFmpeg for Laravel. The storage of the files is handled by Laravel's Filesystem.
    • Laravel Form Components: Blade components to rapidly build forms with Tailwind CSS Custom Forms and Bootstrap 4. Supports validation, model binding, default values, translations, includes default vendor styling and fully customizable!
    • Laravel Mixins: A collection of Laravel goodies.
    • Laravel Verify New Email: This package adds support for verifying new email addresses: when a user updates its email address, it won't replace the old one until the new one is verified.
    • Laravel Paddle: Paddle.com API integration for Laravel with support for webhooks/events.
    • Laravel WebDAV: WebDAV driver for Laravel's Filesystem.

    Security

    If you discover any security related issues, please email pascal@protone.media instead of using the issue tracker.

    Credits

    License

    The MIT License (MIT). Please see License File for more information.

    Keywords

    none

    Install

    npm i @protonemedia/inertiajs-tables-laravel-query-builder

    DownloadsWeekly Downloads

    405

    Version

    1.3.4

    License

    MIT

    Unpacked Size

    96 kB

    Total Files

    45

    Last publish

    Collaborators

    • protonemedia