Skip to Content
FrontendBundlesCRUDListing Components

Listing Components

Components for displaying, filtering, sorting, and bulk-managing data tables. All rely on ListingContext for shared state.

Core Architecture

ListingContext

All listing components rely on the ListingContext for state management. The context provides:

interface ListingContextProps {
  // Data Management
  data: any[]; // Current page data
  loading: boolean; // Loading state
  totalItems: number; // Total items count
  fetchData: () => void; // Data fetching function
  updateData: Dispatch<SetStateAction<any>>; // Data update function
 
  // Pagination
  currentPage: number; // Current page number
  limit: number; // Items per page
  setLimit: (limit: number) => void; // Set items per page
  setCurrentPage: (page: number) => void; // Change page
 
  // Filtering & Search
  searchFilter: any; // Active filters
  setSearchFilter: (filters: any) => void; // Update filters
  sortableFields: Array<{ field: string; order: string }>; // Sorting config
 
  // Selection & Actions
  selectedItems: number[]; // Selected item IDs
  toggleSelectItem: (id: number) => void; // Toggle item selection
  selectAllItems: () => void; // Select all items
  enabledActions: string[]; // Available actions
  setEnabledActions: (actions: any) => void; // Update actions
 
  // UI Configuration
  listedFields: string[]; // Visible columns
  setListedFields: (fields: any) => void; // Update visible columns
  fqcn_bui: IFQCN_BUI; // Component configuration
 
  // Bulk Operations
  handleDeleteItem: (id: number) => void; // Delete single item
  handleBunchDelete: () => void; // Delete selected items
  handleDuplicateItem: (id: number) => void; // Duplicate item
  bunchDeleting: boolean; // Bulk delete loading state
}

Component Overview

1. ListingTable

The main table component that displays data in a tabular format with advanced features.

Props

interface ListingTableProps {
  mainColumns: MainColumnsListing[]; // Column definitions
  resource: string; // API resource name
  fqcn_bui: IFQCN_BUI; // Component configuration
  showActions?: boolean; // Show action buttons column
  formInputs?: FilterField[]; // Form input configuration for modals
  isSidebox?: boolean; // Is being used in a sidebox
  isTreeView?: boolean; // Enable tree view functionality
  user: User | null; // Current user
  locale?: string; // Locale for translations
  tenant: string; // Tenant identifier
  csrfJwt: string; // CSRF token
}

Column Configuration

interface MainColumnsListing {
  title: string; // Column header label
  key: string; // Data field path
  type?: ColumnTypeEnum; // Data type (text, date, number, etc.)
  entity?: string; // Entity name for relations
  sortable?: boolean; // Enable sorting
  link?: string; // Link URL template
  alignment?: "left" | "right" | "center"; // Text alignment
  defaultOrder?: "desc" | "asc"; // Default sort order
  pagePathname?: string; // Page pathname for links
  icon?: boolean; // Show icon
  placeholder?: string; // Placeholder text
  targetResourceAsync?: string; // For async resources
  isMulti?: boolean; // Multiple values
  optionsArrayFinite?: {
    // Static options
    label: string;
    value: string | boolean;
  }[];
  required?: boolean; // Is required
  resourceAsyncLabelParam?: string; // Async label parameter
  prefixOnSubmit?: string; // Submission prefix
}

Usage Example

import {
  ListingTable,
  ListingContextProvider,
} from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
const columns: MainColumnsListing[] = [
  {
    key: "id",
    title: "ID",
    type: ColumnTypeEnum.NUMBER,
    sortable: true,
    alignment: "right",
  },
  {
    key: "name",
    title: "Name",
    type: ColumnTypeEnum.TEXT,
    sortable: true,
  },
  {
    key: "created_at",
    title: "Created",
    type: ColumnTypeEnum.DATETIME,
    sortable: true,
  },
];
 
function UsersList() {
  return (
    <ListingContextProvider>
      <ListingTable
        fqcn_bui={{ Bundle: "user", Unit: "management", Interface: "list" }}
        resource="users"
        mainColumns={columns}
        enableSelection={true}
        enableQuickAdd={true}
        user={user}
        tenant={tenant}
        csrfJwt={csrfToken}
      />
    </ListingContextProvider>
  );
}

2. ListingTableHeader

Provides the header section with search, filters, export, and action buttons.

Props

type ListingTableHeaderProps = {
  fqcn_bui: IFQCN_BUI; // Component configuration
  resource: string; // API resource name
  mainColumns: MainColumnsListing[]; // Column definitions
  defaultActions?: string[]; // Default enabled actions
  fieldsAll?: string[]; // All available fields
  selectedFields?: string[]; // Currently selected fields
  advanceOptions?: boolean; // Show advanced options
  formInputs?: FilterField[]; // Form input configuration
  isSidebox?: boolean; // Is being used in a sidebox
  qField?: string; // Query field for identification
  hasTreeView?: boolean; // Has tree view capability
  user: User | null; // Current user
  locale?: string; // Locale for translations
  tenant: string; // Tenant identifier
  csrfJwt: string; // CSRF token
};

Features

  • Search Bar: Global search across searchable columns
  • Quick Actions: Add, Import, Export buttons
  • View Toggles: Table/Kanban/Tree view switching
  • Column Selector: Show/hide columns dynamically
  • Export Options: CSV, Excel, JSON export formats
  • Bulk Actions: Actions for selected items

Usage Example

import { ListingTableHeader } from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
function UsersListHeader() {
  return (
    <ListingTableHeader
      fqcn_bui={fqcn_bui}
      resource="users"
      mainColumns={columns}
      enableQuickAdd={true}
      enableImport={true}
      enableExport={true}
      enableKanban={true}
      filterFields={userFilterFields}
      user={user}
      tenant={tenant}
      csrfJwt={csrfToken}
    />
  );
}

3. ListingActions

Row-level actions for individual items (edit, delete, duplicate, etc.).

Props

interface ListingActionsProps {
  fqcn_bui: IFQCN_BUI; // Component configuration
  resource: string; // API resource name
  id: number; // Item ID
  formInputs?: FilterField[]; // Form configuration for quick edit
  isKanban?: boolean; // Is in kanban view
  locale?: string; // Locale for translations
  user: User | null; // Current user
  tenant: string; // Tenant identifier
  csrfJwt: string; // CSRF token
}

Available Actions

  • View: Navigate to detail view
  • Edit: Navigate to edit form or quick edit modal
  • Delete: Delete item with confirmation
  • Duplicate: Create copy of item
  • Flag: Mark as default/featured

Usage Example

import { ListingActions } from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
// In table cell renderer
function renderActions(item: any) {
  return (
    <ListingActions
      fqcn_bui={fqcn_bui}
      resource="users"
      id={item.id}
      formInputs={userFormFields}
      user={user}
      tenant={tenant}
      csrfJwt={csrfToken}
    />
  );
}

4. ListingFilters

Advanced filtering interface with multiple filter types and query string management.

Props

interface ListingFiltersProps {
  fqcn_bui: IFQCN_BUI; // Component configuration
  defaultFilters?: { [key: string]: any }; // Default filter values
  resource: string; // API resource name
  filterFields: FilterField[]; // Available filters
  locale?: string; // Locale for translations
  tenant: string; // Tenant identifier
  csrfJwt: string; // CSRF token
}

Filter Field Configuration

interface FilterField {
  key: string; // Field identifier/name
  title?: string; // Display label
  type: ColumnTypeEnum; // Field type
  placeholder?: string; // Input placeholder
  targetResourceAsync?: string; // For async selects
  isMulti?: boolean; // Multiple selections
  optionsArrayFinite?: {
    // Static options
    label: string;
    value: string | boolean;
  }[];
  required?: boolean; // Is required field
  resourceAsyncLabelParam?: string; // API label parameter
  prefixOnSubmit?: string; // Prefix for submission
  default?: boolean; // Default value
  range?: boolean; // Range input
  rangeKeys?: {
    // Range field keys
    min: string;
    max: string;
  };
  translatable?: boolean; // Multi-language support
  itemSpecificPath?: string; // Item-specific path
  helperText?: string; // Help text
}

Supported Filter Types

  • Text: Simple text search
  • Select: Dropdown selection
  • Multi-Select: Multiple selections
  • Date Range: Start and end dates
  • Number Range: Min and max values
  • Boolean: True/false toggle
  • Async Select: Dynamic options from API

Usage Example

import { ListingFilters } from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
const filterFields: FilterField[] = [
  {
    title: "Id",
    key: "id",
    placeholder: "Select Id",
    type: ColumnTypeEnum.SELECT_ASYNC,
    targetResourceAsync: "accounting_entries",
    isMulti: true,
    default: true,
  },
  {
    title: "Account",
    key: "account",
    placeholder: "Select Account",
    type: ColumnTypeEnum.SELECT_ASYNC,
    targetResourceAsync: "accounts",
    isMulti: false,
    default: false,
  },
  {
    title: "Amount",
    key: "amount",
    placeholder: "Input the Amount",
    type: ColumnTypeEnum.CURRENCY,
    default: false,
  },
];
 
function UsersFilters() {
  return (
    <ListingFilters
      fqcn_bui={fqcn_bui}
      resource="users"
      filterFields={filterFields}
      defaultFilters={{ status: "active" }}
      tenant={tenant}
      csrfJwt={csrfToken}
    />
  );
}

5. TablePagination

Pagination controls with page navigation and items per page selection.

Props

interface TablePaginationProps {
  locale?: string; // Locale for translations
}

Features

  • Page Navigation: First, Previous, Next, Last buttons
  • Direct Page Input: Jump to specific page
  • Items Per Page: Configurable page size (10, 25, 50, 100)
  • Item Count Display: Shows “X-Y of Z items”
  • Keyboard Navigation: Hotkeys for pagination
  • Query String: Displays current query parameters

Usage Example

import { TablePagination } from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
function UsersListPagination() {
  return (
    <div className="mt-4">
      <TablePagination locale="en" />
    </div>
  );
}

6. KanbanBoard

Kanban-style board view for visual data management with drag-and-drop.

Props

interface KanbanBoardProps {
  resource: string; // API resource name
  fqcn_bui: IFQCN_BUI; // Component configuration
  statusFieldPath?: string; // Field that determines column (default: "status")
  orderField?: string; // Field for ordering (default: "position")
  formInputs?: FilterField[]; // Form configuration for quick edit
  user: User | null; // Current user
  locale?: string; // Locale for translations
  tenant: string; // Tenant identifier
  csrfJwt: string; // CSRF token
}

Features

  • Drag & Drop: Move cards between columns
  • Dynamic Columns: Columns based on status field values
  • Card Actions: Quick edit, delete, duplicate
  • Custom Styling: Column colors and icons
  • Responsive Design: Mobile-friendly layout

Usage Example

import {
  KanbanBoard,
  KanbanListingContextProvider,
} from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
function TasksKanban() {
  return (
    <KanbanListingContextProvider>
      <KanbanBoard
        resource="tasks"
        fqcn_bui={fqcn_bui}
        statusFieldPath="status"
        orderField="priority"
        formInputs={taskFormFields}
        user={user}
        tenant={tenant}
        csrfJwt={csrfToken}
      />
    </KanbanListingContextProvider>
  );
}

7. ContextualListingPageFooter

Footer component with contextual actions and interface controls.

Props

interface ContextualListingPageFooterProps {
  fqcn_bui: IFQCN_BUI; // Component configuration
  resource: string; // API resource name
  user: User | null; // Current user
  locale?: string; // Locale for translations
}

Features

  • Print: Print current table view
  • Reset: Reset interface to defaults
  • Save Interface: Save current column/filter preferences
  • Settings: Interface customization options

Complete Implementation Example

Here’s a complete example showing how to use all listing components together:

import React from 'react';
import {
  ListingContextProvider,
  ListingTableHeader,
  ListingTable,
  ListingFilters,
  TablePagination,
  ContextualListingPageFooter
} from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
interface UsersListingPageProps {
user: User | null;
tenant: string;
csrfJwt: string;
}
 
export default function UsersListingPage({ 
  user, 
  tenant, 
  csrfJwt 
}: UsersListingPageProps) {
  const fqcn_bui = {
    Bundle: "user",
    Unit: "management", 
    Interface: "list"
  };
 
// Inputs on listing page to put into the quick add and edit modal
const formModalInputs: FilterField[] = [
{
title: "Username",
key: "username",
type: ColumnTypeEnum.TEXT,
placeholder: "Input the Username",
required: true,
},
{
title: "Email",
key: "email",
type: ColumnTypeEnum.TEXT,
placeholder: "Input the Email",
required: true,
},
{
title: "Email Auth Code Enabled",
key: "emailAuthCodeEnabled",
type: ColumnTypeEnum.BOOLEAN,
placeholder: "Select the Email Auth Code Enabled",
required: true,
},
{
title: "Is Verified",
key: "isVerified",
type: ColumnTypeEnum.BOOLEAN,
placeholder: "Select the Is Verified",
required: true,
},
{
title: "Last Name",
key: "lastName",
type: ColumnTypeEnum.TEXT,
placeholder: "Input the Last Name",
required: true,
},
];
 
// All the fields on the listing page
const mainColumns: MainColumnsListing[] = [
{
title: "Id",
key: "id",
sortable: true,
},
{
title: "Username",
key: "username",
type: ColumnTypeEnum.TEXT,
},
{
title: "Email",
key: "email",
type: ColumnTypeEnum.TEXT,
},
];
 
// Inputs on the detailed create and edit pages
const formInputs: FormInput[] = [
{
title: "General",
fields: [
{
title: "Username",
key: "username",
type: ColumnTypeEnum.TEXT,
placeholder: "Input the Username",
required: true,
},
{
title: "Email",
key: "email",
type: ColumnTypeEnum.TEXT,
placeholder: "Input the Email",
required: true,
},
],
},
];
 
// Fields on listing page to filter the records
const filterFields: FilterField[] = [
{
title: "Last Name",
key: "lastName",
placeholder: "Input the Last Name",
type: ColumnTypeEnum.TEXT,
default: false,
},
{
title: "Id",
key: "id",
placeholder: "Select Id",
type: ColumnTypeEnum.SELECT_ASYNC,
targetResourceAsync: "users",
isMulti: true,
default: true,
},
{
title: "Slug",
key: "slug",
placeholder: "Input the Slug",
type: ColumnTypeEnum.TEXT,
default: true,
},
];
 
return (
 
<ListingContextProvider>
<div className="space-y-6">
{/* Header with search and actions */}
<ListingTableHeader
          fqcn_bui={fqcn_bui}
          resource="users"
          mainColumns={mainColumns}
          enableQuickAdd={true}
          enableImport={true}
          enableExport={true}
          enableKanban={true}
          filterFields={filterFields}
          formInputs={formInputs}
          user={user}
          tenant={tenant}
          csrfJwt={csrfJwt}
        />
 
        {/* Advanced filters */}
        <ListingFilters
          fqcn_bui={fqcn_bui}
          resource="users"
          filterFields={filterFields}
          tenant={tenant}
          csrfJwt={csrfJwt}
        />
 
        {/* Main data table */}
        <ListingTable
          fqcn_bui={fqcn_bui}
          resource="users"
          mainColumns={mainColumns}
          enableSelection={true}
          enableQuickAdd={true}
          formInputs={formInputs}
          user={user}
          tenant={tenant}
          csrfJwt={csrfJwt}
        />
 
        {/* Pagination controls */}
        <TablePagination />
 
        {/* Footer with contextual actions */}
        <ContextualListingPageFooter
          fqcn_bui={fqcn_bui}
          resource="users"
          user={user}
        />
      </div>
    </ListingContextProvider>
 
);
}
Last updated on
Form ComponentsModal Components