Skip to content

SmartTable Developer Guide

Product: Merciglobal Cloud ERP Audience: Developers, Internal Merci Team, Sales Engineers

📌 Overview

SmartTable is a dynamic UI utility in Merciglobal Cloud ERP used to:

  • Fetch server-side data via AJAX
  • Render data in Table or Card view
  • Provide filtering, searching, pagination
  • Enable CRUD operations (Edit/Delete/Add)
  • Export data (Excel, Print)

It is designed for rapid module development with minimal UI effort.

⚙️ Function Signature

smartTable(div, table, filters=[], renderers=[], hiddenCol=[], customBtn=[], display='auto', options={}, varsToServer={}, pagination={page:1,perPage:25})

🧩 Parameters Explained

1. div

  • Type: String (CSS selector)
  • Description: Container where SmartTable will render
  • Example: .customerTable

2. table

  • Type: String
  • Description: Database table name
  • Used in backend API: /smarttable.php

3. filters

  • Type: Array
  • Description: Defines filter UI components

Example:

[
  { field: 'status', label: 'Status', type: 'select' },
  { field: 'type', label: 'Type', type: 'radio', values: ['Retail','Wholesale'] }
]

Supported Types:

  • select
  • radio
  • checkbox

4. renderers

  • Type: Array
  • Description: Custom rendering logic

Example:

[
  {
    field: 'amount',
    renderer: (val) => `<b>₹ ${val}</b>`
  }
]

Also supports:

  • cardrenderer for card view

5. hiddenCol

  • Type: Array
  • Description: Columns to hide

Example:

['id','compid']

6. customBtn

  • Type: Array
  • Description: Add custom buttons in filter bar

Example:

[
  {
    caption: 'Add',
    callback: 'addSmartNewXdlg',
    options: { table: 'customers' }
  }
]

7. display

  • Type: String

  • Values:

  • table

  • card
  • auto

Auto mode detects mobile device and switches to card view.

8. options

  • Type: Object

Available Options:

  • btns: ['Refresh','Print','Excel']
  • showButtons: true/false
  • showSmartSearch: true/false
  • showFilterSummary: true/false
  • smartFilterBar: true/false
  • showPaginationBar: true/false
  • showReserveKeyword: true/false

9. varsToServer

  • Type: Object
  • Description: Extra parameters passed to backend

Example:

{ status: 'active', compid: 1 }

10. pagination

  • Type: Object
{ page:1, perPage:25 }

🔄 Data Flow

  1. AJAX request sent to:

  2. /smarttable.php

  3. Backend returns:

json { result: "success", rows: [], totalRows: 100, stru: [] } 3. UI rendered dynamically

🧱 UI Components Generated

  • Filter Bar
  • Search Box
  • Action Buttons
  • Table/Card View
  • Pagination Bar

🎯 Features

  • Global search across all columns

🧮 Filters

  • Auto-populated from dataset
  • Supports multi-select

📄 Export

  • Excel download via XLSX
  • Print view support

✏️ CRUD Actions

  • Edit: Opens drawer
  • Delete: AJAX delete
  • Add: addSmartNewXdlg()

📱 Card View Support

To enable card view:

  • Define a function:
function customers_divCardSample(){
  return `<div class="card hidden customers_divCardSample">
            <div data-bind="name"></div>
          </div>`;
}

🧠 Internal Functions Used

  • createFilters()
  • renderSmartTableHeader()
  • renderSmartTableData()
  • renderSmartCards()
  • smartTableApplyFilters()
  • renderPagination()

🚀 Example Usage

smartTable(
  '.customerTable',
  'customers',
  [
    { field: 'status', label: 'Status', type: 'select' }
  ],
  [],
  ['id'],
  [
    { caption:'Add', callback:'addSmartNewXdlg', options:{ table:'customers' } }
  ],
  'auto',
  {
    btns:['Refresh','Excel','Print'],
    showButtons:true
  },
  {},
  { page:1, perPage:25 }
);

⚠️ Best Practices

  • Always define hiddenCol for system fields
  • Use renderers for formatting currency/date
  • Limit perPage for performance
  • Use varsToServer for server filtering

🧪 Module Integration Example (Real Project Usage)

Below is a real implementation pattern used inside a project JS file to integrate SmartTable with menu navigation:

$(document).on('click', '.xdlgMenu',function(){
   let table    = ($(this).data('table') + '').toLowerCase();
   let menutype = ($(this).data('menutype') || 'module').toLowerCase();

   $('.dashboardSection').hide();
   $('.xdlgSection').show();

   let title = $(this).find('span').text();
   $('.xdlgSection .title').text(title);
   $('.xdlgSection .xdlgAddBtn').data('table', table);

   if (menutype === 'module'){
       $('.xdlgSection .xdlgAddBtn').show();
   } else {
       $('.xdlgSection .xdlgAddBtn').hide();
   }

   let filters   = [];
   let renderers = [];
   let hiddenCol = [];
   let customBtn = [];

   //if you wish to apply filter for specific table:
   if (table == 'mst_subject') {
       filters = [
           { field:'subjectcode', label:'Codes',   type:'select' },
           { field:'subjectname', label:'Subject', type:'select' }
       ];
       hiddenCol = ['entrystamp_'];
   }

   let options = {
       btns: ['Refresh','Excel','Print'],
       showButtons: true,
       showSmartSearch: true,
       showFilterSummary: true,
       smartFilterBar: true,
       showPaginationBar: true,
       showReserveKeyword: false,
       isReport: (menutype === 'module') ? false : true
   };

   $('.xdlgModule').html('<div class="text-center py-5">Loading...</div>');

   smartTable('.xdlgModule', table, filters, renderers, hiddenCol, customBtn, 'table', options, {compCode, studentId});
});

$(document).on('click', '.xdlgAddBtn', function(){
   let table = $(this).data('table');
   genMobileModule(table,0,'ADD');
});

🔍 Explanation of Integration

  • Dynamic table binding using data-table
  • Filters configured per module
  • Conditional UI behavior using menutype
  • SmartTable re-used across multiple modules
  • Server variables (compCode, studentId) passed dynamically

✅ Key Benefits in Merciglobal Cloud ERP

  • Reusable UI pattern across modules
  • Minimal code for new screens
  • Centralized filtering & rendering logic
  • Scalable for large ERP datasets

🧱 Required HTML Layout (Frontend Integration)

The following HTML structure is required to properly support SmartTable in Merciglobal Cloud ERP screens:

<div class="flex h-screen bg-gray-50 overflow-hidden">
    <!-- Sidebar -->
    <?php include './includes/sidebar_student.php'; ?>

    <div class="flex-1 flex flex-col overflow-hidden w-full">
        <!-- Topbar -->
        <?php include './includes/topbar.php'; ?>

        <!-- Dashboard Section -->
        <main class="dashboardSection flex-1 overflow-y-auto p-6 lg:p-10">
            <!-- Your dashboard widgets/cards go here -->
        </main>

        <!-- SmartTable Section -->
        <div class="xdlgSection flex-1 overflow-y-auto p-6 lg:p-10">
            <div class="flex" style="justify-content:space-between;">
                <h1 class="title text-2xl font-bold text-gray-800 mb-6"></h1>
                <button type="button" class="xdlgAddBtn btn btn-primary btn-sm">+ Add</button>
            </div>

            <!-- SmartTable Render Container -->
            <div class="xdlgModule bg-white rounded-2xl shadow-sm border border-gray-100 p-8 min-h-[400px]"></div>
        </div>

        <!-- Add/Edit Drawer -->
        <div class="xdlgForm fixed inset-0 transform translate-y-full z-[9999] w-[50vw] h-[80vh]">
            <div class="flex items-center justify-between p-3 border-b">
                <h2 class="text-lg font-semibold xdlgTitle">Drawer Title</h2>
                <button onclick="$(this).closest('.xdlgForm').addClass('translate-y-full');">✕</button>
            </div>
            <div class="p-2 overflow-y-auto h-full xdlgFormContent"></div>
        </div>

        <!-- Search Drawer -->
        <div class="xdlgFormSearch fixed inset-0 transform translate-y-full z-[99999]">
            <div class="flex items-center justify-between p-3 border-b">
                <h2 class="text-lg font-semibold xdlgSearchTitle">Drawer Title</h2>
                <button onclick="$(this).closest('.xdlgFormSearch').addClass('translate-y-full');">✕</button>
            </div>
            <div class="p-2 overflow-y-auto h-full xdlgFormSearchContent"></div>
        </div>
    </div>
</div>

📦 Required Libraries (Header Includes)

To ensure SmartTable works correctly, include the following dependencies in your header file:

<!-- jQuery -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- Bootstrap (optional but recommended) -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>

<!-- Select2 (for filters) -->
<link href="https://cdn.jsdelivr.net/npm/select2@4.1.0/dist/css/select2.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/select2@4.1.0/dist/js/select2.min.js"></script>

<!-- XLSX (for Excel export) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/xlsx/0.18.5/xlsx.full.min.js"></script>

<!-- Custom Merciglobal Utilities -->
<script src="/apis/js/utils.js"></script>
<script src="/apis/js/smarttable.js"></script>

🔗 UI Flow Understanding

  • dashboardSection → Default landing UI
  • xdlgSection → SmartTable rendering area
  • xdlgModule → Target container passed to smartTable()
  • xdlgAddBtn → Triggers Add drawer
  • xdlgForm → Add/Edit drawer
  • xdlgFormSearch → Search drawer

🏁 Conclusion

SmartTable is a powerful abstraction layer in Merciglobal Cloud ERP that accelerates development by:

  • Reducing UI coding effort
  • Standardizing data presentation
  • Enabling rapid module deployment

It is highly flexible and should be used as the default data rendering engine across modules.

Maintained by: Merci Development Team