ZAB ERP Formatter & Tools for VS Code

A comprehensive, production-grade Visual Studio Code extension built for ZAB ERP development. Provides Prettier-like code formatting, real-time diagnostic validation (Crystal Reports, button sequences, list counts, filename matching), Smart Quick Fixes, Emmet-style boilerplate generators, snippet libraries, syntax highlighting, and custom file icons.

Table of Contents

1. Supported File Formats
2. Key Features
   • Code Formatting
   • Crystal Reports Validation
   • Form Button Sequence Validation & Quick Fixes
   • List Objects & Headers Validation
   • Root Declaration & Filename Matching
   • Dynamic Emmet Expansion & Snippets
   • Custom File Icon Theme
3. Installation Guide
   • Method 1: Install from VSIX via VS Code UI (Recommended)
   • Method 2: Install via Command Line Terminal
   • Method 3: Build from Source
4. Recommended Configuration (settings.json)
5. Settings Reference
6. Keyboard Shortcuts
7. PDF Documentation

Supported File Formats

Key Features

1. Code Formatting (Prettier-like)

• Shortcut: Shift + Alt + F (Windows/Linux) or Shift + Option + F (macOS).
• Format on Save: Automatically formats documents upon saving.
• Pipe Alignment: Automatically aligns pipe columns (|) into clean, readable tabular columns in .menu and .column files.
• Block Indentation: Formats nested structural blocks (table, form, list, grid, text, field, event, card, chart, query, jscript).
• Control Flow Indentation: Indents nested if / else if / else / end if and while / end while statements.
• Block Spacing: Automatically enforces exactly a 1-line gap between structural blocks (collapses multiple blank lines and inserts a gap if none exists).
• Continuation Lines (~): Correctly indents multi-line statements ending with ~ in objects, columns, and headers.
• Inline Comments Inside Continuation Blocks: Comments (// ...) inside multi-line columns or objects declarations maintain uniform indentation without breaking or resetting the block.
• Embedded JavaScript & CSS Beautification: Auto-formats JavaScript code inside <script> and CSS rules inside <style> within jscript ... end jscript blocks using js-beautify.

2. Real-Time Crystal Reports Validation

Validates Crystal Reports invocations in both .screen and .menu files:

In .screen files:

class careports(getReport{<reportName>;<paramCount>;<datatypes>;<internalParams>;<passedParams>;<buttonName>})

• Example:

  class careports(getReport{acvoucher;2;in,st;zid,svoucher;xvoucher;Print Voucher})
  

• Validation Checks:
  1. Verifies <reportName>.rpt exists in WEB-INF/reports/ (one step back from resource/).
  2. Verifies parameter count $N$ matches the number of datatypes (in,st).
  3. Verifies parameter count $N$ matches internal parameters (zid,svoucher).
  4. Verifies passed parameters equal $N - 1$ (xvoucher), because session zid is supplied implicitly.
  5. Ignores commented-out lines (// ...).

In .menu files:

*viewcrystal <reportName>(<paramCount>;<datatypes>;<internalParams>;<promptMappings>[;...])

• Example:

  Department Wise Roaster | #classPath+"/login?screen=*viewcrystal employeeroaster(5;in,st,st,in,in;zid,empcat,dept,year,per;xempcategory=Concern,xdeptname=Department Name,xyear=Year,xper=Month,xviewtype=Report View)"
  

• Validation Checks:
  1. Verifies <reportName>.rpt exists in WEB-INF/reports/.
  2. Verifies parameter count $N$ matches datatypes, internal params, and prompt mappings (all must equal $N$, since xviewtype is included as the final mapping).
  3. Supports additional segments (e.g. ;rptproc=zabsp_...).

3. Form Button Sequence Validation & Multi-Line Quick Fixes

Enforces standard button sequences declared in objects for forms in .screen files:

• Detail Screens: Add, Update, Delete, Show, Clear, Top, Next, Previous, Bottom (or Top, Previous, Next, Bottom)
• Header Screens: Show, Clear, Add, Update, Delete, Top, Next, Previous, Bottom (or Top, Previous, Next, Bottom)

Smart Rules:

• Allowed Missing Buttons: If your form only has Show, Add, Update, no warning is triggered because their relative order is preserved.
• Navigation Order Flexibility: Accepts both standard navigation orders: Top, Next, Previous, Bottom and Top, Previous, Next, Bottom (along with legacy First/Last equivalents).
• Multi-Line Continuation (~) Support: If objects buttons are split across lines with ~, the validator inspects the complete button sequence and the Quick Fix reorders buttons across all continuation lines while preserving comments (e.g. //Delete, //,Product Tag,) and indentation.
• Smart Quick Fix (Ctrl + .): Reorders only existing buttons into the correct sequence without injecting missing buttons.

4. Two-Tier Field & Column Validation with Chained Quick Fixes

Ensures strict schema integrity across .screen, .list, .def, and .column files:

1. In Table Definition Files (.def):

• Column Validation: Validates that every column declared in columns exists in a .column dictionary file (table.column, medical.column, fa.column, etc.).
• Real-Time Error: Any undeclared column is highlighted: Column '<fieldName>' is not declared in any .column file.
• Quick Fix (Ctrl + .): Prompts for data type (or select direct presets like varchar, decimal, int, date), formats and appends the new column into table.column, and opens the column file directly at the new row.

2. In Form & List Files (.screen & .list):

• Configurable Auto-Inclusion (Default: OFF): Form objects validation against .def and table.column files is controlled by the setting zab.formatter.autoIncludeFormColumns. By default, it is off (false). When enabled:
  • Table Definition Check First: When a form or list block declares a table (table <tableName>), the validator checks <tableName>.def:
    • If <tableName>.def exists and the field is not in its columns list, an error is highlighted: Field '<fieldName>' is not declared in '<tableName>.def'.
    • Chained Quick Fix (Ctrl + .): Automatically appends the field to <tableName>.def (preserving continuation lines ~ and proper indentation) AND, if it's not already in table.column, appends it to table.column as well (prompting for type)! It then opens <tableName>.def and jumps right to the updated column.
    • Author Tracking: Newly added columns in table.column and .def include an author identifier comment (the PC's MAC address or configured author ID):
      • In .def: // {column name} added by : {id}
      • In table.column: ... | // {column name} added by : {id}
    • Fallback for Views: If <tableName>.def does not exist (e.g. database view or external table), it automatically falls back to checking .column dictionary files directly.
  • Smart Filtering: Action buttons and commands (any token not starting with x, e.g. Patient_Registration, Confirm, Sync), layout tokens ("<p>"), custom embed buttons (embed onclick), and local fields (defined with attrib local or attrib(local) either in-line or in a later field <name> block) are safely recognized and excluded from table checks.
  • Live In-Memory Buffer Synchronization: Updates in open unsaved editor buffers (.column, .def, .screen, .list) instantly reflect across all diagnostics without needing to save to disk first.

5. List Objects, Headers & Totals Validation

• Scans list blocks across .screen, .list, and .lrpt files.
• Ensures the number of column headers declared in header / headers matches the count of objects in objects.
• Ensures the number of totals items declared in total / totals matches the count of objects in objects and headers.
• Supports comma-separated items, empty column tokens (e.g. totals "Total", , , sum, sum), single quoted grouped strings, and multi-line continuations (~).
• Accounts for hidden fields (display(hide)), multi-line continuation statements (~), SQL functions (attrib(...)), and grouped header/totals strings.
• Displays clear error diagnostics with the exact count of headers or totals vs visible and total objects.

6. Root Declaration & Filename Matching

Ensures that the root declaration matches the file name:

• acheader.screen must start with screen acheader
• mmadmission.def must start with table mmadmission
• aclist.list / aclist.lrpt must start with list aclist
• hrm.dashboard / hrm.dbqr must start with dashboard hrm

6. Dynamic Emmet Expansion & Snippet Library

Dynamic Boilerplate (!):

In an empty .screen or .def file, type ! and press Tab or Enter:

• In customerentry.screen, typing ! expands into a complete boilerplate with screen customerentry, sidebar list detail, form one, and standard buttons.
• In customerentry.def, typing ! expands into table customerentry, columns, and primary key.

Autocompletion Snippets:

7. Modal Display Expansion & Hide Navbar Directives

Modal Display Expansion:

Inside button field blocks in .screen files, declaring display modal automatically completes the full modal configuration:

caption <Caption Name>
display modal
icon <i class="fas fa-solid fa-list-ul" aria-hidden="true"></i>
src /login?screen=<Screen Name>

• Smart Duplicate Prevention: If caption is already defined on the line above, the extension preserves your caption without duplicating it.
• Quick Fix (Ctrl + .): Press Ctrl + . on any display modal statement to immediately expand missing modal properties (caption, icon, src).
• Snippets: Available via display modal, modal, disp:modal, and fld:modal.

Hide Navbar Directive (//hide navbar):

When you add the comment //hide navbar:

//hide navbar

• Existing <style> Block: If a <style> block is available anywhere in the file, the extension seamlessly injects:

  .topnav,
  .btn-slide,
  #floatingMenuButton {
    display: none !important;
  }
  

  directly inside the <style> block before </style>, removing the comment.
• No Existing <style> Block: If no <style> block exists, it creates the <style> block containing the rules at the comment location.
• Multiple Triggers: Works instantly through Document Formatting (Save / Format Document), Quick Fix lightbulb (Ctrl + .), or auto-completion snippets.

8. Custom File Icon Theme

A complete file icon theme specifically tailored for ZAB ERP files and general web languages:

• .screen ➔ Cyan Display Icon
• .def ➔ Amber Database Table Icon
• .list ➔ Emerald List Icon
• .menu ➔ Purple Navigation Tree Icon
• .column ➔ Sky Blue Column Definition Icon
• .lrpt ➔ Teal Report Icon
• .dashboard ➔ Indigo Dashboard Icon
• .dbqr ➔ Amber Query Icon

Installation Guide

Method 1: Install from VSIX via VS Code UI (Recommended)

1. In VS Code, open the Extensions view (Ctrl + Shift + X).
2. Click the ... (Views and More Actions) icon in the top-right corner of the Extensions panel.
3. Select Install from VSIX....
4. Browse to the repository folder and select:

   vscode-zab-formatter-1.3.4.vsix
   

5. Click Install. VS Code will install the extension and reload automatically.

Method 2: Install via Command Line Terminal

Open PowerShell or Command Prompt in the repository folder and run:

code --install-extension vscode-zab-formatter-1.3.4.vsix

Method 3: Build from Source

If you want to modify the source code and build the extension package:

1. Clone the repository:

   git clone https://github.com/nawfs254/vscode-zab-formatter.git
   cd vscode-zab-formatter
   

2. Install dependencies:

   npm install
   

3. Run the unit test suite:

   node tests/test-formatter.js
   

4. Package the extension into a .vsix file:

   npx @vscode/vsce package --no-git-tag-version
   

Recommended Configuration (settings.json)

To enable automatic formatting on save and activate the icon theme, add the following to your VS Code settings.json (Ctrl + Shift + P ➔ Preferences: Open User Settings (JSON)):

{
  "editor.formatOnSave": true,
  "workbench.iconTheme": "zab-icons",

  "[zab-screen]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-def]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-list]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-menu]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-column]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-lrpt]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-dashboard]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  },
  "[zab-dbqr]": {
    "editor.defaultFormatter": "zab-tools.vscode-zab-formatter"
  }
}

Settings Reference

Configurable in VS Code Settings (Ctrl + , ➔ search zab.formatter):

Keyboard Shortcuts

PDF Documentation

A complete, beautifully styled installation and user guide PDF is included in the repository:

• File: ZAB_ERP_Formatter_Installation_and_User_Guide.pdf

Contains full step-by-step instructions, troubleshooting tips, screenshots, and syntax references for all ZAB developers.