corrad-bp/documentation/02-form-builder.md
2025-07-24 16:14:13 +08:00

407 lines
16 KiB
Markdown

# Form Builder
## Table of Contents
1. [Accessing Form Builder](#accessing-form-builder)
2. [Form Builder Interface](#form-builder-interface)
3. [Form Components](#form-components)
4. [Creating Your First Form](#creating-your-first-form)
5. [Form Builder Features](#form-builder-features)
---
## Accessing Form Builder
**Step-by-Step Instructions:**
1. From the main menu, click **"Form Builder"**
2. Click **"Create New Form"** button
3. Enter a form name in the header field
4. You're now ready to build your form
## Form Builder Interface
**Interface Layout:**
- **Left Panel**: Component library with all available form components
- **Center Canvas**: Drag-and-drop area where you build your form
- **Right Panel**: Component settings and configuration panel
- **Top Header**: Form name, save button, and preview toggle
**Navigation:**
- Use the search bar in the component library to find specific components
- Click components to add them to your form
- Drag components to reposition them on the canvas
## Form Components
### Text Inputs Category
**Text Field**
- **How to Add**: Drag "Text Field" from the Text Inputs category
- **Configuration**:
- Click the component to open settings
- Set label, placeholder, and help text
- Configure validation rules (required, min/max length)
- **Use Case**: Names, titles, short descriptions
- **Zakat Scenario**:
- **When to Use**: Collecting applicant's full name, IC number, or address
- **Example**: "Nama Penuh Pemohon" field for Zakat Asnaf application
- **Configuration**: Set as required field with validation for Malaysian IC format
**Text Area**
- **How to Add**: Drag "Text Area" from the Text Inputs category
- **Configuration**:
- Set label and placeholder text
- Configure rows and character limits
- Enable rich text formatting if needed
- **Use Case**: Descriptions, comments, long-form content
- **Zakat Scenario**:
- **When to Use**: Collecting detailed reasons for Zakat application
- **Example**: "Sebab Permohonan Zakat" field for explaining financial hardship
- **Configuration**: Set minimum 50 characters, maximum 500 characters
**Number Field**
- **How to Add**: Drag "Number Field" from the Text Inputs category
- **Configuration**:
- Set minimum and maximum values
- Configure decimal places and step increments
- Add validation rules
- **Use Case**: Quantities, amounts, scores
- **Zakat Scenario**:
- **When to Use**: Collecting monthly income, number of dependents, or property values
- **Example**: "Pendapatan Bulanan (RM)" field for income assessment
- **Configuration**: Set minimum 0, maximum 50,000, 2 decimal places
**Email Field**
- **How to Add**: Drag "Email Field" from the Text Inputs category
- **Configuration**:
- Set label and placeholder
- Email validation is automatic
- **Use Case**: Contact information, user registration
- **Zakat Scenario**:
- **When to Use**: Collecting applicant's email for notifications
- **Example**: "Emel Pemohon" field for Zakat application updates
- **Configuration**: Set as optional field with email format validation
**Password Field**
- **How to Add**: Drag "Password Field" from the Text Inputs category
- **Configuration**:
- Set label and placeholder
- Configure password strength requirements
- **Use Case**: User authentication, account creation
- **Zakat Scenario**:
- **When to Use**: Creating secure login for Zakat portal
- **Example**: "Kata Laluan" field for applicant account creation
- **Configuration**: Set minimum 8 characters with strength indicator
**URL Field**
- **How to Add**: Drag "URL Field" from the Text Inputs category
- **Configuration**:
- Set label and placeholder
- URL validation is automatic
- **Use Case**: Links, references, social media profiles
- **Zakat Scenario**:
- **When to Use**: Collecting social media profiles for verification
- **Example**: "Profil Facebook" field for additional contact verification
- **Configuration**: Set as optional field with URL validation
**Phone Field**
- **How to Add**: Drag "Phone Field" from the Text Inputs category
- **Configuration**:
- Set label and placeholder
- Configure phone number format
- **Use Case**: Contact information, customer details
- **Zakat Scenario**:
- **When to Use**: Collecting applicant's contact number
- **Example**: "Nombor Telefon" field for Zakat application contact
- **Configuration**: Set Malaysian phone format (01X-XXXXXXX)
**Masked Input**
- **How to Add**: Drag "Masked Input" from the Text Inputs category
- **Configuration**:
- Set custom mask pattern (e.g., ###-###-####)
- Configure placeholder and help text
- **Use Case**: Credit cards, social security numbers, postal codes
- **Zakat Scenario**:
- **When to Use**: Collecting IC number with proper formatting
- **Example**: "Nombor IC" field with format 000000-00-0000
- **Configuration**: Set mask pattern ###-###-#### for IC format
**Hidden Field**
- **How to Add**: Drag "Hidden Field" from the Text Inputs category
- **Configuration**:
- Set default value
- Note: This field is not visible to users
- **Use Case**: Default values, system data, calculations
- **Zakat Scenario**:
- **When to Use**: Storing application date or system-generated values
- **Example**: "Tarikh Permohonan" field automatically set to current date
- **Configuration**: Set default value to current date/time
### Selection & Toggle Category
**Select Dropdown**
- **How to Add**: Drag "Select Dropdown" from the Selection & Toggle category
- **Configuration**:
- Click component to open settings
- Add options in the "Options" section
- Set placeholder text
- Configure validation
- **Use Case**: Categories, status options, country selection
- **Zakat Scenario**:
- **When to Use**: Selecting Zakat category or state of residence
- **Example**: "Kategori Zakat" dropdown with options: Asnaf, Fakir, Miskin, etc.
- **Configuration**: Add options: Asnaf, Fakir, Miskin, Amil, Muallaf, Riqab, Gharimin, Fisabilillah
**Checkbox Group**
- **How to Add**: Drag "Checkbox Group" from the Selection & Toggle category
- **Configuration**:
- Add multiple options in the settings
- Set label and help text
- Configure minimum/maximum selections
- **Use Case**: Interests, skills, preferences
- **Zakat Scenario**:
- **When to Use**: Selecting multiple sources of income or types of assistance needed
- **Example**: "Sumber Pendapatan" checkbox group
- **Configuration**: Options: Gaji Tetap, Kerja Sampingan, Perniagaan, Sewa, Lain-lain
**Radio Group**
- **How to Add**: Drag "Radio Group" from the Selection & Toggle category
- **Configuration**:
- Add mutually exclusive options
- Set label and help text
- Configure validation
- **Use Case**: Gender, yes/no questions, priority levels
- **Zakat Scenario**:
- **When to Use**: Selecting marital status or employment status
- **Example**: "Status Perkahwinan" radio group
- **Configuration**: Options: Bujang, Berkahwin, Bercerai, Janda/Duda
**Switch Toggle**
- **How to Add**: Drag "Switch Toggle" from the Selection & Toggle category
- **Configuration**:
- Set label and help text
- Configure default state (on/off)
- **Use Case**: Settings, feature enablement, consent
- **Zakat Scenario**:
- **When to Use**: Consent for data sharing or agreement to terms
- **Example**: "Persetujuan Terma dan Syarat" toggle
- **Configuration**: Set default to off, required for form submission
### Date & Pickers Category
**Date Picker**
- **How to Add**: Drag "Date Picker" from the Date & Pickers category
- **Configuration**:
- Set label and help text
- Configure date range limits
- Set default date if needed
- **Use Case**: Birth dates, appointment scheduling, deadlines
- **Zakat Scenario**:
- **When to Use**: Collecting birth date or application submission date
- **Example**: "Tarikh Lahir" field for age verification
- **Configuration**: Set maximum date to current date, minimum date to 1900
**Time Picker**
- **How to Add**: Drag "Time Picker" from the Date & Pickers category
- **Configuration**:
- Set label and help text
- Choose 12 or 24-hour format
- Set time intervals
- **Use Case**: Meeting times, business hours, schedules
- **Zakat Scenario**:
- **When to Use**: Scheduling Zakat interview appointments
- **Example**: "Masa Temuduga" field for interview scheduling
- **Configuration**: Set 24-hour format, intervals of 30 minutes
**Date & Time**
- **How to Add**: Drag "Date & Time" from the Date & Pickers category
- **Configuration**:
- Set label and help text
- Configure date and time limits
- **Use Case**: Event scheduling, deadline tracking
- **Zakat Scenario**:
- **When to Use**: Scheduling Zakat verification appointments
- **Example**: "Tarikh dan Masa Temuduga" field for home visits
- **Configuration**: Set minimum date to current date, business hours only
**Range Slider**
- **How to Add**: Drag "Range Slider" from the Date & Pickers category
- **Configuration**:
- Set minimum and maximum values
- Configure step increments
- Set default value
- **Use Case**: Ratings, preferences, quantity selection
- **Zakat Scenario**:
- **When to Use**: Indicating monthly household income range
- **Example**: "Julat Pendapatan Bulanan (RM)" slider
- **Configuration**: Set range 0-10,000 RM, step 500 RM
**Color Picker**
- **How to Add**: Drag "Color Picker" from the Date & Pickers category
- **Configuration**:
- Set label and help text
- Configure default color
- **Use Case**: Design preferences, theme selection
- **Zakat Scenario**:
- **When to Use**: Selecting preferred notification colors
- **Example**: "Warna Notifikasi Pilihan" for personalized alerts
- **Configuration**: Set default to blue (#3B82F6)
### Advanced & Upload Category
**File Upload**
- **How to Add**: Drag "File Upload" from the Advanced & Upload category
- **Configuration**:
- Set accepted file types
- Configure file size limits
- Set maximum number of files
- **Use Case**: Documents, images, attachments
- **Zakat Scenario**:
- **When to Use**: Uploading supporting documents for Zakat application
- **Example**: "Dokumen Sokongan" field for IC, payslips, bank statements
- **Configuration**: Accept PDF, JPG, PNG files, max 5MB per file, max 10 files
**Image Preview**
- **How to Add**: Drag "Image Preview" from the Advanced & Upload category
- **Configuration**:
- Set image URL or upload image
- Configure caption and alt text
- Enable/disable zoom capability
- **Use Case**: Product images, profile pictures, documentation
- **Zakat Scenario**:
- **When to Use**: Displaying Zakat calculation examples or guidelines
- **Example**: "Contoh Pengiraan Zakat" image with calculation breakdown
- **Configuration**: Show zoom capability, add caption explaining calculation
**Repeating Group**
- **How to Add**: Drag "Repeating Group" from the Advanced & Upload category
- **Configuration**:
- Set group label and help text
- Configure minimum and maximum items
- Add fields within the group
- **Use Case**: Family members, work experience, education history
- **Zakat Scenario**:
- **When to Use**: Collecting information about family members/dependents
- **Example**: "Maklumat Ahli Keluarga" group for dependent details
- **Configuration**: Min 1, max 10 family members, fields: Name, IC, Age, Relationship
**Dynamic List**
- **How to Add**: Drag "Dynamic List" from the Advanced & Upload category
- **Configuration**:
- Set label and placeholder text
- Configure item type (text, number, etc.)
- Enable search, sorting, and bulk operations
- **Use Case**: Skills, interests, inventory items
- **Zakat Scenario**:
- **When to Use**: Listing monthly expenses or sources of income
- **Example**: "Senarai Perbelanjaan Bulanan" for expense tracking
- **Configuration**: Text items, enable search, allow duplicates, max 20 items
**Data Table**
- **How to Add**: Drag "Data Table" from the Advanced & Upload category
- **Configuration**:
- Define table columns and their types
- Set validation rules for each column
- Configure edit and delete permissions
- **Use Case**: Employee records, inventory, financial data
- **Zakat Scenario**:
- **When to Use**: Tracking monthly income and expenses in tabular format
- **Example**: "Jadual Pendapatan dan Perbelanjaan" table
- **Configuration**: Columns: Month, Income (RM), Expenses (RM), Balance (RM), Remarks
**OTP Input**
- **How to Add**: Drag "OTP Input" from the Advanced & Upload category
- **Configuration**:
- Set number of digits (typically 6)
- Configure validation
- **Use Case**: Two-factor authentication, verification codes
- **Zakat Scenario**:
- **When to Use**: SMS verification for Zakat application submission
- **Example**: "Kod Pengesahan SMS" field for application verification
- **Configuration**: 6 digits, auto-focus, required validation
**File Dropzone**
- **How to Add**: Drag "File Dropzone" from the Advanced & Upload category
- **Configuration**:
- Set accepted file types and size limits
- Configure drag-and-drop text
- Set maximum number of files
- **Use Case**: Bulk file uploads, document management
- **Zakat Scenario**:
- **When to Use**: Bulk upload of multiple supporting documents
- **Example**: "Seret Dokumen ke Sini" dropzone for multiple file uploads
- **Configuration**: Accept PDF, JPG files, max 10MB total, drag-and-drop interface
**Button**
- **How to Add**: Drag "Button" from the Advanced & Upload category
- **Configuration**:
- Set button text and type (submit, reset, button)
- Choose button style and size
- Configure custom actions if needed
- **Use Case**: Submit, reset, custom actions
- **Zakat Scenario**:
- **When to Use**: Form submission or calculation triggers
- **Example**: "Hantar Permohonan Zakat" submit button
- **Configuration**: Primary style, large size, submit type
## Creating Your First Form
**Step-by-Step Instructions:**
1. **Start Form Builder**
- Navigate to Form Builder
- Click "Create New Form"
- Enter a descriptive form name
2. **Add Basic Components**
- Drag a "Text Field" for the name
- Drag an "Email Field" for contact information
- Drag a "Select Dropdown" for category selection
3. **Configure Components**
- Click each component to open settings
- Set appropriate labels and placeholders
- Add validation rules where needed
4. **Add Advanced Components**
- Drag a "File Upload" for attachments
- Drag a "Text Area" for comments
- Add a "Button" for form submission
5. **Test Your Form**
- Click "Preview" to test the form
- Fill out the form as an end user would
- Verify all functionality works correctly
6. **Save Your Form**
- Click "Save" button
- Enter a descriptive name
- Add a description for future reference
## Form Builder Features
**Drag & Drop Interface**
- **How to Use**: Click and drag components from the left panel to the canvas
- **Repositioning**: Drag components on the canvas to move them
- **Resizing**: Use the resize handles to adjust component size
**Component Configuration**
- **How to Access**: Click any component on the canvas
- **Settings Panel**: Opens on the right side
- **Configuration Options**: Labels, validation, conditional logic, styling
**Preview Mode**
- **How to Access**: Click "Preview" button in the header
- **Testing**: Fill out the form as an end user
- **Exit Preview**: Click "Edit" to return to builder mode
**Save & Version Control**
- **Save**: Click "Save" button regularly
- **History**: Access form history to view previous versions
- **Restore**: Click on any previous version to restore it
---
*Previous Chapter: [Introduction & Getting Started](01-introduction-getting-started.md)*
*Next Chapter: [Form Management](03-form-management.md)*