Branch Management

What This Page Does

The Branch Management page (manage-branches.php) provides a full CRUD interface for administering company branch locations. Administrators can create, view, edit, and delete branches — each with a name, unique code, address, state/city location, and optional bank account details.

The page loads all branches from branch_api.php on init, displays them in a desktop data table or mobile card layout, and exposes three modal dialogs for Add/Edit, View, and Delete operations. A live search input debounces queries at 350 ms and re-fetches filtered results from the API.

Page Structure

The page is built from five logical areas inside <main>, plus three modal overlays that sit outside the layout flow.

API Endpoints

Three PHP files are consumed. All return the standard {"success": bool, "data": ...} JSON envelope.

Stats Dashboard

Four KPI cards are rendered above the table. All four metrics are computed client-side from the branches array immediately after data loads — no additional API requests are made.

const tot    = branches.length;
const states = new Set(branches.map(b => b.branch_state).filter(Boolean)).size;
const banked = branches.filter(b => b.branch_bank).length;
const cities = new Set(branches.map(b => b.branch_city).filter(Boolean)).size;

Branch Listing

The listing renders identically from the same branches array into two parallel outputs — a desktop HTML table and a mobile card list. Both are always kept in sync. A search field at the top right triggers debSearch() with a 350 ms debounce, which re-calls load() with the ?search= query parameter.

A Branch Icons

Each branch is represented by a coloured circular/rounded icon with 1–2 letter initials, generated deterministically from the branch name using a simple hash function. The same icon is used consistently in the table row, mobile card, and view modal.

const iconColors = ['#2563eb','#1b3560','#5a7a62','#b85c38','#4a5568','#0a1628'];

// Consistent colour from name hash:
function bColor(s) {
  let h = 0;
  for (let i = 0; i < s.length; i++)
    h = s.charCodeAt(i) + ((h << 5) - h);
  return iconColors[Math.abs(h) % iconColors.length];
}

// 1–2 letter initials from name words:
function bInit(n) {
  return (n || 'BR').split(' ').slice(0,2)
    .map(w => w[0]?.toUpperCase() || '').join('');
}

B Skeleton Loading

While the initial data fetch is in progress, the table body is pre-populated with three skeleton rows using the .sk shimmer animation class. This prevents layout shift and gives visual feedback that loading is in progress.

C Empty & Error States

If the API returns an empty array, both the table and mobile card container render a centred empty state with a heading and helper text. If the fetch itself fails, an error banner appears at the top of the page and the table shows a connection error message.

Location Cascade

The branch form uses a two-level cascading location system. State and City are both stored in the database as plain text strings (VARCHAR columns), not foreign key IDs. This means the <option value> for both selects is the name, not the numeric ID.

async function onStateChange(sel) {
  const stateName = sel.value;                    // stored as-is in DB
  const stateId   = sel.options[sel.selectedIndex]?.dataset?.id; // used for city lookup only

  // Fetch cities if not already cached
  if (!citiesCache[stateId]) {
    const r = await fetch(`${LOC_API}?type=cities&state_id=${stateId}`);
    const j = await r.json();
    citiesCache[stateId] = j.data;            // ← in-memory cache
  }
  populateCitySelect(stateId);              // options use city_name as value
}

Cities are cached in citiesCache (keyed by state_id) so switching between states does not re-fetch previously loaded cities. When editing an existing branch, preselectLocation(stateName, cityName) looks up the matching state object, fetches/loads cities if needed, and pre-selects both dropdowns by name.

Add / Edit Modal

The same #formModal is reused for both create and update operations. The modal title and editId variable distinguish the mode. Saving calls saveBranch() which POSTs or PUTs to branch_api.php based on whether editId is set.

A Form Fields

View Modal

Opens when the eye icon is clicked in the actions column. Renders a detail card entirely from the in-memory branches array — no additional API call. An "Edit Branch" button in the modal footer immediately opens the edit form pre-filled with the same record.

Delete Modal

A compact confirmation dialog (max-width 360px). The branch name is shown in the confirmation message to prevent accidental deletion. Confirming calls confirmDelete() which sends a DELETE request to branch_api.php?id={delId}.

Database Schema

The branches table columns inferred from the page's field mappings and rendered data.

API Payload

Both POST (create) and PUT (update) send identical JSON bodies. The only difference is the endpoint URL — PUT appends ?id={editId}.

{
  "branch_name":      "Lagos Island Branch",
  "branch_code":      "LG-001",         // always uppercase
  "branch_address":   "15 Marina Street…",
  "branch_state":     "Lagos",           // name string, not ID
  "branch_city":      "Lagos Island",    // name string, not ID
  "branch_bank":      "First Bank of Nigeria",
  "branch_acct_no":  "0123456789",
  "branch_acct_name":"Sodlapp Microfinance Ltd"
  // branch_comp_fk intentionally omitted — set server-side
}

A Success Response

{
  "success": true,
  "data": { "branch_id": 14 }   // on create; null on update/delete
}

B Payload Fields

JavaScript State Variables

Functions

Validation Rules

Client-side validation runs inside saveBranch() before the API call. Failing fields are highlighted red for 1.5 s via hl(id) and the field is given focus. There is no error banner for form validation — the field highlight alone indicates what needs fixing.