README

Shared RCX Laravel DataTables UI helpers for multiple consuming applications.

Known workspace consumers include Customer Service Dashboard (customerservicedashboard), RCX Fulfillment (rcxfulfillment), Territoria (Territoria), and League Performance Dashboard (LeaguePerformanceDashboard). Other applications can use the same public contracts; application-specific examples below do not limit the supported consumers.

Version 2.0.0 introduces breaking initialization and PHP constructor changes. See Upgrading from 1.x to 2.0.0 before upgrading.

This package owns reusable table infrastructure:

Rcx\DataTables\DataTableBuilder
Rcx\DataTables\DataTableSsp
<x-rcx-datatables.table :config="$config" />
<x-rcx-datatables.shared-filters ... />
DataTables initialization JS
Shared lifecycle events and browser formatting utilities
Safe CSV streaming for local or application-provided row sources
Package-owned table error presentation
Shared RCX DataTables SCSS

Applications still own their table registries, routes, datasets, SQL/API calls, and row formatting.

Toolbar Visibility

Table controls can be hidden independently through configuration:

[
    'showSearch' => false,
    'showTableStatus' => false,
    'showColumnControls' => false,
]

showTableStatus controls both the default “Showing all…” message and the filtered-results summary bar. Read-only tables without search or filters should normally disable all three options above.

The DataTables footer controls can also be hidden independently with showPagination, showInfo, and showPageLength. All three remain enabled by default. Pagination controls are automatically hidden when every matching row fits on one page. An explicit JavaScript layout configuration takes precedence.

Search Panel Contrast

Search and filter panels on a white surface can enable searchPanelShadow. The shared filter component supports the same setting with :search-panel-shadow="true".

Row Highlighting

Tables can highlight and reveal a row by matching a raw data field:

[
    'rowHighlight' => [
        'field' => 'invoiceId',
        'value' => request('invoice'),
    ],
]

Client-side tables move to the matching row's page and scroll it into view. Applications can also call window.RcxDataTables.highlightRow(dataTable, options) or import highlightRow from the JavaScript package.

Browser Requirements

The consuming application must load jQuery, DataTables 2, Bootstrap 5's JavaScript and CSS, and Bootstrap Icons before initializing the package. Pass Bootstrap's imported Tooltip constructor to initializeRcxDataTables; the package does not depend on Bootstrap's global or jQuery integrations. Load the DataTables ColReorder and FixedHeader extensions when the corresponding table options are enabled.

Date-range filters additionally require the daterangepicker jQuery plugin and the date library required by the selected daterangepicker distribution. Without that optional plugin, tables continue to initialize and date inputs remain usable as plain text controls. SweetAlert is optional; editable-cell confirmation and error messages fall back to browser dialogs.

Laravel pages that use Ajax tables or editable cells should include the standard CSRF meta element:

<meta name="csrf-token" content="{{ csrf_token() }}">

Laravel App Wiring

During local development, add this path repository to the consuming Laravel app:

"repositories": [
  {
    "type": "path",
    "url": "../rcxdatatableslaravel",
    "options": {
      "symlink": true,
      "versions": {
        "rcx/datatables-laravel": "dev-development"
      }
    }
  }
],
"require": {
  "rcx/datatables-laravel": "dev-development"
}

The service provider is registered through Laravel package auto-discovery. Import and initialize the package JS from the installed package, then import its SCSS:

import { Tooltip } from 'bootstrap';
import { initializeRcxDataTables } from '../../vendor/rcx/datatables-laravel/resources/js/rcx-datatables';

initializeRcxDataTables({ Tooltip });

@import "../../vendor/rcx/datatables-laravel/resources/sass/rcx-datatables";

Deployment Channels

Applications with the environment-channel installer (including CSD, fulfillment, and Territoria) use matching repository branches as environment channels. Verify each consumer's build scripts rather than assuming every application uses this strategy:

Application branch	Package branch	Composer version
`development`	`development`	`dev-development`
`stage`	`stage`	`dev-stage`
`production`	`production`	`dev-production`

The application build resolves the package branch through Packagist, captures its commit SHA, pins the deployment artifact's Composer requirement to that SHA, and installs the frontend tarball from the same SHA before compiling assets. A deployed application therefore changes package revisions only when that application is deployed, and its PHP and frontend package code always come from the same commit.

Promote package changes by merging development into stage, then stage into production. Git tags are optional release snapshots and are not used to select an environment channel.

The frontend package version is declared in package.json. Composer release versions come from Git tags, so composer.json intentionally has no hard-coded version. A v2.0.0 tag records a release snapshot; it does not redeploy applications or change the SHA already installed in a running deployment. See the migration notes for the release procedure and checks for consumers that use version constraints instead of channels.

Development Checks

The regression suite requires PDO SQLite and creates only an in-memory synthetic database. It checks count-query reuse, scoped/search counts, pagination, and export rows in addition to the static configuration and output contracts.

Run the dependency-light regression suite and package validation before handing off changes:

composer test
composer validate --strict
node --test tests/*.test.js

The Node tests require no installed browser dependencies. They exercise the shared export-request serializer, including cleared third-click sorts. A cleared sort is omitted just as it is in DataTables Ajax, allowing the same server ordering policy to apply to the table and CSV.

rcx / datatables-laravel

Package info

Security

Statistics