Skip to Content
FrontendBundlesCRUDListing Components

Listing Components

The CRUD bundle provides a comprehensive set of listing components for displaying, filtering, and managing data tables. These components work together with the ListingContext to provide a complete data management solution.

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>
 
);
}

Best Practices

Performance Optimization - Always wrap components with appropriate context

providers - Use useMemo for expensive column calculations - Implement virtual scrolling for large datasets - Optimize API calls with proper caching

Common Pitfalls - Don’t forget the ListingContextProvider wrapper -

Ensure fqcn_bui configuration is consistent across components - Always handle loading and error states - Test responsive behavior on mobile devices

This comprehensive documentation covers all the listing components, their props, usage patterns, and advanced customization options. Each component is designed to work seamlessly together while also being flexible enough for individual use cases.

Last updated on
Import/Export ComponentsMetadata Components