Manual Configuration Guide

This guide provides detailed instructions for configuring and implementing the Platform Grid Component in your application.

Basic Grid Setup

1. Grid Component Implementation

import Grid from "~/components/platform/Grid/Server";

export default async function Page() {
  return (
    <Grid
      totalCount={totalCount}
      data={items}
      config={{
        entity: "your_entity",
        title: "Your Grid Title",
        columns: gridColumns,
      }}
    />
  );
}

Column Configuration

1. Define Column Structure

Create a separate configuration file (e.g., _config/columns.ts) to manage your grid columns:

const gridColumns = [
  {
    id: "code",
    header: "Code",
    accessorKey: "code",
  },
  {
    id: "name",
    header: "Name",
    accessorKey: "name",
  },
  // Add more columns as needed
];

// Optional: Define columns to hide on mobile devices
export const TO_HIDE_COLUMNS_WHEN_MOBILE = ["created_date", "updated_date"];

export default gridColumns;

2. Column Properties

Columns are defined using the ColumnDef type from TanStack Table:

import { type ColumnDef } from "@tanstack/react-table";

const gridColumns: ColumnDef[] = [ ... ];

Key column properties:

• id: Unique identifier for the column
• header: Display name in the grid header
• accessorKey: Property name from your data object
• enableSorting: Enable/disable column sorting (boolean)
• enableFiltering: Enable/disable column filtering (boolean)
• cell: Custom cell renderer function (optional)
• size: Column width (number)
• minSize: Minimum column width (number)
• maxSize: Maximum column width (number)

Example with advanced properties:

const gridColumns: ColumnDef[] = [
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    enableSorting: true,
    enableFiltering: true,
    size: 150,
    cell: ({ row }) => (
      <Badge
        variant={row.original.status === "active" ? "success" : "error"}
      >
        {row.original.status}
      </Badge>
    )
  },
  {
    id: "created_date",
    header: "Created Date",
    accessorKey: "created_date",
    enableSorting: true,
    cell: ({ row }) => formatDate(row.original.created_date)
  }
];

Dynamic Data Integration

1. Configure TRPC API Integration

Prerequisites

Important Requirements

Before installing the Platform CLI, ensure you have:

• TRPC: await api."your custom trpc".items
• TRPC Relative Path: src/server/api/routers "you can create your own custom trpc"

// Define data fetching parameters
const _pluck = [
  "id",
  "code",
  "name",
  "status",
  "created_date",
  "updated_date",
];

// Fetch data using TRPC
const { items = [], totalCount } = await api.yourEntity.items({
  current: +(pagination?.current_page ?? "0"),
  limit: +(pagination?.limit_per_page ?? "100"),
  entity: "your_entity",
  pluck: _pluck,
  sorting: sorting?.length ? sorting : defaultSorting,
  advance_filters: filters?.advanceFilter?.length ? filters?.advanceFilter : [],
});

2. Search Configuration

searchConfig: {
  router: "your_entity",
  resolver: "mainGrid",
  query_params: {
    entity: "your_entity",
    pluck: _pluck,
  },
}

Advanced Features

1. Sorting Configuration

// _config/sorting.ts
export const defaultSorting = [
  {
    id: "created_date",
    desc: true,
  },
];

2. Advanced Filtering

// _config/advanceFilter.ts
export const defaultAdvanceFilter = [
  {
    id: "status",
    operator: "equals",
    value: "active",
  },
];

3. Mobile Responsiveness

Configure mobile-specific behavior:

config: {
  // ... other config
  hideColumnsOnMobile: TO_HIDE_COLUMNS_WHEN_MOBILE,
}

4. Custom Features

config: {
  // ... other config
  enableAutoCreate: false, // Disable automatic creation
  defaultValues: {
    categories: ["Category1", "Category2"],
  },
}

Best Practices

1. Modular Configuration

   • Keep configurations in separate files
   • Use TypeScript for better type safety

2. Performance Optimization

   • Implement proper pagination
   • Use pluck to fetch only needed fields
   • Configure appropriate page sizes

3. Responsive Design

   • Configure mobile-specific column visibility
   • Test grid behavior across different screen sizes

4. Error Handling

   • Implement proper error boundaries
   • Handle loading and error states

Example Implementation

Here's a complete example combining all the features:

import gridColumns from "./_config/columns";
import defaultAdvanceFilter from "./_config/advanceFilter";
import defaultSorting from "./_config/sorting";

export default async function Page() {
  const { sorting, pagination, filters } = (await getGridCacheData()) ?? {};

  const headerList = headers();
  const pathname = headerList.get("x-pathname") || "";
  const [, , main_entity] = pathname.split("/");

  const _pluck = ["id", "code", "status", "created_date", "updated_date"];

  const { items = [], totalCount } = await api.grid.items({
    entity: main_entity!,
    pluck: _pluck,
    current: +(pagination?.current_page ?? "0"),
    limit: +(pagination?.limit_per_page ?? "100"),
    sorting: sorting?.length ? sorting : defaultSorting,
    advance_filters: filters?.advanceFilter?.length
      ? filters?.advanceFilter
      : [],
  });

  return (
    <Grid
      totalCount={totalCount || 0}
      data={items}
      defaultSorting={defaultSorting}
      defaultAdvanceFilter={defaultAdvanceFilter}
      config={{
        entity: "your_entity",
        title: "Your Grid",
        columns: gridColumns,
        hideColumnsOnMobile: TO_HIDE_COLUMNS_WHEN_MOBILE,
        searchConfig: {
          router: "your_entity",
          resolver: "mainGrid",
          query_params: {
            entity: "your_entity",
            pluck: _pluck,
          },
        },
      }}
    />
  );
}