Module Builder for PerfexCRM – Complete Documentation

✨ Introduction

Module Builder is a powerful, code-generation tool for PerfexCRM that allows you to create complete, production-ready modules without writing a single line of code! 🎉

Whether you need:

Custom CRM extensions 🏢
Client portals with specific functionality 👥
Internal tools for your team 🔧
Integration with existing database tables 🗃️

Module Builder generates everything you need:

✅ Controllers (Admin & Client)
✅ Models with full CRUD operations
✅ Views with DataTables integration
✅ Language files (multi-language ready)
✅ Database migrations
✅ Dashboard with analytics (optional)
✅ REST API with authentication (optional)
✅ Complete file structure
✅ Addon export capability

Time saved: Hours of coding reduced to minutes! ⏱️

⚙️ Installation

📥 System Requirements

Requirement

Minimum

Recommended

PerfexCRM

2.9.0+

3.0.0+

PHP

7.4

8.0+

MySQL

5.6

8.0+

Memory Limit

128M

256M

Step 1: Upload Module

Download the Module Builder ZIP file
Extract the contents
Upload the module_builder folder to your PerfexCRM modules/ directory

Step 2: Install Module

Log in to your PerfexCRM Admin Panel
Navigate to Setup → Modules
Find Module Builder in the list
Click the Activate button

Step 3: Configure Permissions

Go to Setup → Staff → Roles, edit the role and check the permissions: View Own, View, Create, Edit, Delete, Install Addons.

Step 4: Configure Role-Based Permissions (Optional)

Go to Module Builder → Role Permissions to configure granular permissions for each staff role:

Download Module ZIP
Export as Addon
Export Module/Form JSON
Import Module/Form
Delete Module Configuration/Files
Delete Database Tables
Save Form as Template
Generate Module Files
Set usage limits per action (0 = unlimited)

Step 5: Verify Installation ✅

After activation, you should see a new Module Builder menu item and database tables created automatically.

🎯 Features

🏗️ Core Features

No Coding Required

Point-and-click module creation

Multiple Forms per Module

Each module can have unlimited forms

Drag & Drop Form Builder

Visual form design with rows and columns

Auto-Generate from Tables

Create forms from existing database tables

Auto-Generate from CSV/Excel

Upload a file and automatically create a form

Soft Delete

Recover deleted records

🎨 New Field Types v3.5.5

AI Chat Assistant

Add AI-powered chat to any form (OpenAI, Anthropic, Google)

Image Gallery

Multi-image upload with drag & drop reordering

Invoice/Quotation Items

Dynamic line items table with auto-calculation

Star Rating

Configurable rating field with half-star support

Google Maps Picker

Location selection with search and current location

🔌 Advanced Features

Complete REST API Generation

Full CRUD endpoints with multiple auth methods

Addon System

Extend Module Builder with custom addons

Role-Based Permissions

Granular access control with usage limits

Security Scanner

Automatic detection of dangerous code patterns

Dark Mode

Full PerfexCRM dark mode with custom colors

Client Dashboard

Analytics dashboard for clients showing only their own records

🎬 Creating Your First Module

1

Navigate to Module Builder

Click on Module Builder in the sidebar, then click the Create New Module button.

2

Fill Module Information

Enter Module Name (system), Display Name, Description, Version, Menu Position, and Icon.

3

Configure Advanced Settings

Enable Dashboard, Export/Import, Activity Log, REST API, Module Licensing, etc.

4

Save Module Configuration

Click Save Module Configuration. Your module appears in the list.

Field

Description

Example

Module Name (System)

System identifier (lowercase, underscores only)

support_tickets

Display Name

User-friendly name shown in menus

Support Tickets

Description

Brief description

Manage customer support tickets

Version

Module version

1.0.0

Menu Position

Where in sidebar (lower numbers appear first)

15

Menu Icon

FontAwesome icon for menu

fa-ticket

🧩 Understanding Module Configuration

Module List View: ID, Module Name, Display Name, Version, Status, Actions.

Action Buttons: Edit, Generate, Rebuild, Download ZIP, Export as Addon, Delete Files, Delete Config.

Advanced Options when creating/editing a module:

Enable Dashboard - Creates an analytics dashboard with charts
Generate Client Dashboard - Creates a client-specific analytics dashboard
Enable Export/Import - Adds CSV/Excel capabilities
Enable Activity Log - Tracks all changes
Enable REST API - Generates complete API endpoints
Enable Module Licensing - Adds Envato purchase code verification

📝 Adding Forms

Pro Tip: You can also generate forms from CSV/Excel files or use pre-built form templates!

Step 1: Access Module Forms

From module list, click Edit on your module, scroll down to Forms in this Module section, click Add New Form button.

Step 2: Configure Form Information

Field

Description

Form Name (System)

System identifier (lowercase, underscores)

Display Name

User-friendly name

Custom Table Name

Override default table name

Soft Delete

Use deleted_at instead of permanent deletion

Step 3: Define Fields Using Drag & Drop Builder

The Drag & Drop Builder appears automatically with Field Toolbox (Left), Form Canvas (Center), and Field Editor (Right).

Step 4: Save Form

Click Save Form Configuration. Form appears in the module's forms list.

🎨 Drag & Drop Form Builder

The Drag & Drop Form Builder is the heart of Module Builder! It lets you design complex forms visually.

┌─────────────────────────────────────────────────────────────┐
│  [Field Toolbox]            [Form Canvas]     [Field Editor] │
│  ┌─────────────────┐        ┌─────────────┐   ┌──────────┐  │
│  │ Basic Fields    │        │  Row 1      │   │ Settings │  │
│  │ • Text          │        │  ┌───┐ ┌───┐│   │ • Name   │  │
│  │ • Textarea      │        │  │F1 │ │F2 ││   │ • Label  │  │
│  │ • Number        │        │  └───┘ └───┘│   │ • Type   │  │
│  │ • Email         │        │             │   │ • Valid  │  │
│  │ • URL           │        │  Row 2      │   │ • Default│  │
│  │ • Phone         │        │  ┌─────────┐│   └──────────┘  │
│  │ • Star Rating   │        │  │   F3    ││                  │
│  └─────────────────┘        │  └─────────┘│                  │
│  [Advanced Fields]           └─────────────┘                  │
│  [Choice Fields]                                              │
│  [Relational Fields]                                          │
│  [Upload Fields]                                              │
└─────────────────────────────────────────────────────────────┘

Row Controls:

Add Column - Add a new column
2/3/4 Col - Quickly set column count
🗑️ Delete Row - Remove the entire row

Field Properties:

Field Name - Database column name (lowercase, underscores)
Display Label - User-facing label
Validation - Required, Unique, Email, etc.
Default Value - Pre-filled value
Options - For select/radio fields (comma separated)
Show in List - Include in table view
Show in Form - Include in create/edit form

🤖 Auto-Generating Forms

From Database Tables

One of the most powerful features! 🚀

In module edit view, find Generate Forms from Database Tables panel
Click the table selector and choose existing database tables
Configure Form Access (Staff Only / Clients Only / Both)
Select Form Layout (One Column / Two Columns)
Click Preview Fields to see what will be generated
Click Generate Forms - forms are created automatically with all fields mapped

From CSV/Excel Files New!

In module edit view, find Generate Forms from CSV/Excel panel
Upload a CSV, XLSX, or XLS file (first row must contain column headers)
System displays first 5 rows of data and detects field types
Configure field mapping for each column
Click Generate Form from CSV/Excel - form is created with all fields mapped

🎨 Field Types and Options

Basic Field Types:

Text, Textarea, Number, Email, URL, Date, DateTime, Time, Color, Phone, Currency

Choice Field Types:

Select, Radio, Checkbox, Boolean

File Field Types:

File, Image

Relationship Field Types:

Staff, Client, Project, Related

Advanced Field Types v3.5.5

Map - Google Maps location picker with search and current location detection
Invoice Items - Dynamic invoice items table with auto-calculation
Quotation Items - Dynamic quotation items table with auto-calculation
AI Chat - AI-powered chat assistant (OpenAI, Anthropic, Google)
Gallery - Multi-image upload with gallery view and lightbox
Star Rating - Configurable rating with half-star support

Validation Options:

None, Required, Required + Unique, Email Format, Numeric Only, URL Format

✨ New Field Types (v3.5.5)

🤖 AI Chat Assistant Field

Add AI-powered chat to any form with support for multiple providers:

AI Provider: OpenAI, Anthropic (Claude), Google (Gemini), or Custom API
Temperature: Controls randomness (0 = precise, 2 = creative)
System Message: Instructions for the AI assistant
Chat Style: Floating button or inline widget
Button Position: Bottom-right, bottom-left, top-right, top-left

🖼️ Image Gallery Field

Multi-image upload with powerful gallery features:

Maximum Files: Limit number of images (1-50)
Gallery Layout: Grid, Masonry, Carousel, or List
Enable Lightbox: Click to enlarge images
Enable Reorder: Drag & drop to reorder images
Thumbnail Size: Small (80x80), Medium (120x120), Large (160x160)

📄 Invoice/Quotation Items Field

Dynamic line items table with auto-calculation:

Currency Symbol: $, €, £, etc.
Show Tax Column: Display tax rate column
Allow Discount: Enable discount input
Auto-calculates subtotal, tax, discount, and total

⭐ Star Rating Field

Maximum Stars: 3, 5, or 10 stars
Allow Half-Stars: Enable 0.5 increments
Star Size: Small, Medium, or Large

🗺️ Google Maps Field

Map Height: Height of the map container (pixels)
Default Location: Set initial center coordinates
Show Search Box: Enable address search
Show Current Location: Show "use my location" button

⚙️ Advanced Form Settings

Form Access:

Staff Only - Accessible only in admin area
Clients Only - Accessible only in client portal
Both Staff and Clients - Accessible everywhere
Public Access - Form accessible without login

Client Permissions (when client access enabled):

Allow clients to edit their records
Allow clients to delete their records (use with caution!)

Form Layout:

Two Columns (Default) - Fields arranged side by side
One Column - Fields stacked vertically

Form Templates New!

Apply a Template: Click the dropdown button next to "Add New Form" and select "Choose Template" - browse categories (Contact, Registration, Business, etc.) and use the template.

Save as Template: Build your form, click "Save as Template", name it and choose a category.

Import/Export

Export Form: Click dropdown next to "Add New Form" → "Export Form" - JSON file downloads with all configuration.

Import Form: Click dropdown → "Import Form" - Upload JSON file.

🔗 Belongs To Configuration

This feature allows you to restrict forms to specific parent records. Perfect for creating hierarchical data relationships! 🏗️

Configuration Options:

Belongs To Field - Select parent field (client_id, project_id, etc.)
Belongs To Value - Fixed value or Dynamic (from URL)

When Dynamic is checked, the value comes from URL: /projects/view/5 → Parent ID: 5

Example URLs:

Admin: /admin/project_management/tasks?parent_id=5
Client: /project_management/clients/tasks?parent_id=5

💻 Custom Controller & Model Logic

Controller Hooks:

Hook

When Executed

Before Save

Before creating new record

After Save

After creating new record

Before Update

Before updating record

After Update

After updating record

Before Delete

Before deleting record

After Delete

After deleting record

// After Save hook example
$admin_email = get_option('admin_email');
$this->emails_model->send_simple_email(
    $admin_email,
    'New Record Created',
    'A new record has been submitted.'
);

Custom Model Methods:

public function get_stats_by_status() {
    return $this->db->select('status, COUNT(*) as count')
        ->group_by('status')
        ->get($this->table)
        ->result_array();
}

🛠️ Controller Constructor Builder

The Constructor Builder allows you to visually select which models, helpers, and libraries to load in your controller's constructor.

Available Models:

Core Models: clients_model, staff_model, projects_model, tasks_model, invoices_model, estimates_model, proposals_model, contracts_model, leads_model, tickets_model
Communication Models: emails_model, notifications_model
Financial Models: payments_model, expenses_model, credit_notes_model, currencies_model, taxes_model

Available Helpers:

file, directory, download, path, text, string, inflector, typography, form, url, html, array, date, number, security, cookie

Available Libraries:

email, session, form_validation, upload, image_lib, pagination, encryption, zip, parser, pdf, excel

🛠️ REST API Generation

When you enable the REST API option for your module, a complete set of API endpoints is generated automatically!

Authentication Methods:

API Key - Simple key-based authentication via X-API-Key header
JWT - JSON Web Token authentication via Authorization: Bearer header
OAuth2 - OAuth2 token-based authentication
Basic Auth - HTTP Basic Authentication

Rate Limiting:

Configurable requests per minute (default: 60). Rate limits are tracked by API key or IP address.

API Endpoints for Each Form:

Endpoint

Method

Description

/api/form_name

GET

List all records

/api/form_name/{id}

GET

Get single record

/api/form_name/search

GET

Search records

/api/form_name/create

POST

Create new record

/api/form_name/update/{id}

POST

Update record

/api/form_name/delete/{id}

DELETE

Delete record

# Example API Request
GET /api/tickets?page=2&limit=10&sort=id&order=DESC&filter={"status":"open"}
X-API-Key: your_api_key_here

🔌 Addon System

The Addon Manager allows you to extend Module Builder functionality with custom addons.

Addon Structure:

addons/your_addon/
├── init.php                 # Addon information and initialization
├── install.php              # Installation script (required)
├── uninstall.php            # Uninstallation script (optional)
├── config/
│   └── config.php           # Addon configuration
├── controllers/
├── models/
├── views/
├── libraries/
├── helpers/
├── assets/
└── language/

init.php Format:

<?php
/*
Addon Name: My Custom Addon
Description: Extends Module Builder functionality
Version: 1.0.0
Author: Your Name
*/

function my_addon_init() {
    hooks()->add_action('module_builder_form_created', 'my_addon_on_form_created');
}

my_addon_init();

Installing Addons:

Go to Module Builder → Addons
Upload addon ZIP file
Click Install
Activate the addon

🔐 Role-Based Permissions

Granular permissions can be assigned to each staff role with optional usage limits.

Action

Description

Limit Option

Download Module ZIP

Download generated module as ZIP

Yes

Export as Addon

Export module as standalone addon

Yes

Delete Database Tables

Drop module database tables

No

Save Form as Template

Save form design as reusable template

Yes

Generate Module Files

Generate controller/model/view files

Yes

🛡️ Security Scanner

The Security Scanner automatically checks all custom code fields for dangerous patterns.

Blocked Patterns:

File system operations (unlink, file_put_contents, fopen, chmod)
Command execution (shell_exec, exec, system, passthru)
Code execution (eval, assert, create_function)
SQL injection patterns (DROP TABLE, UNION SELECT)
Database schema modifications (ALTER TABLE, CREATE TABLE, TRUNCATE)
Module theft (ZipArchive, reading /modules/ path)

Security Violation Levels:

Level

Action

Critical

Blocked, logged, admin alerted

High

Blocked, logged

Medium

Warning, logged

Low

Warning, logged

🌙 Dark Mode

Full PerfexCRM dark mode support with custom colors and scheduling options.

Toggle Button - Manual light/dark toggle
Scheduled Mode - Always, sunset, or custom hours
Custom Color Pickers - Personalize your dark mode colors
Full CRM Scope - Can apply to entire CRM, not just Module Builder

📝 Form Templates

Save and reuse form designs with the template system.

Core Templates Included: Contact forms, Registration forms, Business forms, Healthcare forms, Education forms, Marketing forms
Category System: Organize templates by category
Save Custom Templates: Save any form design as a reusable template
Preview Templates: See template details and fields before applying

📁 Generated Module Structure

modules/your_module_name/
├── your_module_name.php              # Main module file
├── install.php                       # Installation script
├── uninstall.php                     # Uninstallation script
├── controllers/
│   ├── FormName.php                  # Staff controller
│   ├── api/
│   │   ├── Api.php                   # Main API controller
│   │   └── FormName.php              # Form API controller
│   └── clients/
│       └── FormName.php              # Client controller
├── models/
│   └── Your_module_name_model.php    # Main model with CRUD
├── views/
│   ├── form_name/                    # Admin views
│   ├── api/
│   │   ├── docs.php                  # API documentation
│   │   └── keys.php                  # API key management
│   └── clients/                      # Client views
├── language/
│   └── english/
│       └── your_module_name_lang.php
├── assets/
│   ├── css/
│   └── js/
├── libraries/
├── helpers/
├── config/
│   └── api_routes.php
└── migrations/

👥 Client Portal Integration

In form settings, select Form Access: Clients Only or Both. Configure Client Permissions (edit/delete).

Client Portal URLs:

Client Portal Access: /your_module/clients/form_name
Client Create: /your_module/clients/form_name/create
Client Edit: /your_module/clients/form_name/edit/123

All records automatically filtered by client_id. Clients cannot access other clients' data.

Client Dashboard:

When enabled, clients see analytics dashboards showing only their own records with charts and statistics.

API Endpoints Reference

Module Builder Admin Endpoints:

GET /admin/module_builder - Main index page
POST /admin/module_builder/save_module - Save module config
POST /admin/module_builder/create_module_files/{id} - Generate files
GET /admin/module_builder/download_zip/{id} - Download module
POST /admin/module_builder/export_as_addon/{id} - Export as addon

Database Utilities:

GET /admin/module_builder/get_database_tables - List tables
POST /admin/module_builder/generate_forms_from_tables - Auto-generate
POST /admin/module_builder/generate_forms_from_csv - CSV/Excel generation

Security & Logging:

GET /admin/module_builder/security_logs - View security violations
GET /admin/module_builder/activity_logs - View user activity

📝 Language Files

// your_module_name_lang.php
$lang['your_module'] = 'Your Module';
$lang['your_module_view'] = 'View';
$lang['your_module_edit'] = 'Edit';
$lang['your_module_added_successfully'] = 'Record added successfully';
$lang['ai_chat_assistant'] = 'AI Chat Assistant';
$lang['gallery'] = 'Image Gallery';
$lang['invoice_items'] = 'Invoice Items';

Create folders for other languages like language/spanish/ and copy/translate the language file.

🔐 Permissions

Module Builder Permissions:

view_own - View own modules only
view - View all modules
create - Create new modules
edit - Edit existing modules
delete - Delete modules
install_addons - Install and manage addons

Generated Module Permissions:

Each generated module automatically gets its own permissions: {module_name}_view_own, {module_name}_view, {module_name}_create, {module_name}_edit, {module_name}_delete.

has_permission('module_name', '', 'view')
has_permission('module_name', '', 'edit')
has_permission('module_name', '', 'delete')

📚 Action Hooks Reference

Module Lifecycle Hooks:

module_builder_module_created - After module is created
module_builder_module_updated - After module is updated
module_builder_module_deleted - After module is deleted
module_builder_files_generated - After module files are generated

Form Lifecycle Hooks:

module_builder_form_created - After form is created
module_builder_form_updated - After form is updated
module_builder_form_deleted - After form is deleted
module_builder_form_imported - After form is imported
module_builder_form_exported - When form is exported
module_builder_template_applied - When template is applied

Security Hooks:

module_builder_security_violation - When a security violation is detected
module_builder_code_validation - Filter code validation rules

hooks()->add_action('module_builder_module_created', 'my_custom_function', 10, 2);
function my_custom_function($module_id, $module_data) {
    log_message('debug', "Module {$module_id} was created");
}

❓ Troubleshooting

Issue

Solution

🔴 Module files won't generate

Check folder permissions (775 or 777), ensure module name uses only lowercase and underscores

🔴 Database table not created

Check if table name already exists, verify MySQL user has CREATE permissions

🔴 Client portal forms not showing

Verify form access is set to clients or both, ensure client is logged in

🔴 File uploads not working

Check upload directory permissions (777 for uploads/), verify PHP upload settings

🔴 AI Chat not working

Verify API keys are configured, check provider credentials

🔴 Gallery images not uploading

Check upload directory permissions, verify PHP memory limit

🔴 API returns 401 Unauthorized

Verify API key is valid, check authentication method

Debugging Tips:

Enable Perfex debug mode in application/config/app-config.php
Check PHP error logs in /logs/
Use browser developer tools (F12) to inspect AJAX responses
Check security logs at Module Builder → Security Logs

🔧 Advanced Usage

Creating Nested Resources

Scenario: Tasks that belong to projects. Create main module, create tasks form, configure Belongs To with project_id.

Complex Reporting with Custom Methods

public function get_dashboard_stats() {
    $data['total'] = $this->db->count_all($this->table);
    $data['by_status'] = $this->db->select('status, COUNT(*) as count')
        ->group_by('status')->get($this->table)->result_array();
    $data['recent'] = $this->db->order_by('created_at', 'DESC')
        ->limit(5)->get($this->table)->result_array();
    return $data;
}

Working with Generated Models

$records = $this->your_module_model->get_all_form1_name();
$record = $this->your_module_model->get_form1_name($id);
$id = $this->your_module_model->create_form1_name($data);
$success = $this->your_module_model->update_form1_name($id, $data);
$success = $this->your_module_model->delete_form1_name($id);
$client_records = $this->your_module_model->get_client_form1_name($client_id);

📊 Database Schema

tblmodule_builder_modules

id, module_name, module_display_name, module_description, module_version
menu_position, menu_icon, author_name, author_uri
generate_controller, generate_model, generate_views, generate_language, generate_migration
enable_export, enable_import, enable_activity_log, enable_comments, enable_rest_api, enable_licensing
created_at, created_by, updated_at, updated_by, status

tblmodule_builder_forms

id, module_id, form_name, form_display_name, form_description, table_name
soft_delete, enable_audit, menu_position, form_access, form_layout
client_can_edit, client_can_delete, belongs_to_field, belongs_to_value
controller_before_save, controller_after_save, model_custom_methods, layout_data

Additional Tables (v3.5.5):

tblmodule_builder_templates - Form templates storage
tblmodule_builder_api_keys - API key management
tblmodule_builder_security_logs - Security violation logging
tblmodule_builder_usage_log - User action logging

📝 Changelog

Version 3.5.5 (Current)

✨ New: AI Chat Assistant Field - Add AI-powered chat to any form (OpenAI, Anthropic, Google, Custom API)
✨ New: Image Gallery Field - Multi-image upload with drag-and-drop reordering, multiple layouts, lightbox support
✨ New: Invoice & Quotation Items Fields - Dynamic line items table with auto-calculation
✨ New: Star Rating Field - Configurable star count, half-star support
✨ New: Google Maps Field - Location picker with search and current location detection
✨ New: Complete REST API Generation - Full CRUD endpoints, multiple auth methods, rate limiting
✨ New: Module Licensing System - Envato purchase code verification
✨ New: Addon System - Standalone addon manager with ZIP upload
✨ New: Role-Based Permissions - Granular control with usage limits
✨ New: Security Scanner - Automatic detection of dangerous code patterns
✨ New: CSV/Excel Form Generation - Upload a file and auto-create a form
✨ New: Module/Form Import/Export - Complete JSON export/import
✨ New: Form Templates with Categories - Save and reuse form designs
✨ New: Dark Mode with Full PerfexCRM Scope - Toggle button, scheduled mode, custom colors
✨ New: Client Dashboard Generation - Analytics dashboard for clients
✨ New: Controller Constructor Builder - GUI to select models/helpers/libraries
✨ New: Custom View Code Override - Load, modify, and save custom view code
✨ New: Activity & Security Logging - Comprehensive logging with email alerts

Version 1.0.2 (Previous)

✨ Addon Manager for extending functionality
✨ Template system for saving and reusing form designs
✨ Import/Export functionality (JSON format)
✨ Client dashboard generation with charts
✨ Public form access option

Version 1.0.0 (Initial)

🎉 Initial release
✨ Basic CRUD generation
✨ Drag & Drop form builder
✨ Database table analysis
✨ Staff/Client access control

🏁 Conclusion

Module Builder transforms PerfexCRM development from hours of coding into minutes of configuration! 🎉

What You Can Build:

✅ Custom CRM modules
✅ Client portals
✅ Internal tools
✅ Reporting systems
✅ Project management extensions
✅ Support ticket systems
✅ Inventory management
✅ AI-powered forms
✅ REST APIs for mobile apps

Key Benefits:

⏱️ Save Time - Generate complete modules in minutes
🧠 No Coding Required - Perfect for non-developers
🔧 Flexible - Customize with PHP when needed
👥 Client-Ready - Built-in client portal support
🔒 Secure - Proper permissions and access control
📦 Portable - Download as installable ZIP or addon
🔌 Extensible - Addon system for custom functionality
🤖 AI Ready - Built-in AI chat assistant support
🌐 API First - Complete REST API for every module

Quick Start Checklist:

Install Module Builder
Create your first module
Add a form
Design your form with Drag & Drop
Configure advanced settings (if needed)
Generate module files
Test in admin area
Configure client access (optional)
Download ZIP or export as addon

Ready to build your first module?

Join hundreds of users who have already saved thousands of hours.

Get Module Builder for $197

30‑day money‑back guarantee