Appearance

Custom Fields Management ​

This comprehensive guide covers everything about custom fields - creating, managing, and using custom fields across different modules in your application.

Table of Contents ​

  1. Overview
  2. Accessing Custom Fields
  3. Creating Custom Fields
  4. Field Types Reference
  5. Field Validation Rules
  6. Field Display Settings
  7. Managing Custom Fields
  8. Using Custom Fields
  9. Best Practices

Overview ​

What are Custom Fields? ​

Custom fields allow you to add additional data fields to any module without modifying the core code. They provide flexibility to collect and store module-specific information.

Features ​

  • ✅ Add fields to any module
  • ✅ Multiple field types
  • ✅ Custom validation
  • ✅ Field ordering
  • ✅ Visibility control
  • ✅ Default values
  • ✅ Help text and placeholders

Supported Modules ​

Custom fields can be added to:

  • Quotes
  • Products
  • Services
  • Users
  • Posts
  • And more...

Accessing Custom Fields ​

From Admin Panel ​

Route Pattern: /admin/{model}/custom-fields

Examples:

  • Quotes: /admin/quotes/custom-fields
  • Products: /admin/products/custom-fields
  • Services: /admin/services/custom-fields

  1. Go to Module:

    • Navigate to the module
    • Look for Custom Fields in menu
    • Or go directly to custom fields URL

  2. Access Custom Fields:

    • Click Custom Fields
    • View existing fields
    • Create new fields

Creating Custom Fields ​

Step-by-Step Guide ​

Step 1: Navigate to Custom Fields ​

  1. Go to the module you want to add fields to
  2. Click Custom Fields in the menu
  3. Or navigate to: /admin/{model}/custom-fields

Step 2: Click Create New Field ​

  1. Click Create New Field button
  2. Field creation form appears

Step 3: Fill Field Information ​

Basic Information:

  • Label: Display name (required)
  • Key: Internal identifier (auto-generated, can edit)
  • Type: Field type (required)
  • Description: Optional description

Field Configuration:

  • Required: Make field mandatory
  • Placeholder: Placeholder text
  • Default Value: Pre-filled value
  • Help Text: Instructions for users
  • Visibility: Public/Private/Admin Only

Display Settings:

  • Field Order: Display order (lower = first)
  • Active: Enable/disable field

Step 4: Configure Field Type ​

Depending on Field Type:

  • Select/Radio/Checkbox: Add options
  • Number: Set min/max values
  • Date: Configure date format
  • File: Set allowed file types

Step 5: Save Field ​

  1. Review all settings
  2. Click Save or Create
  3. Field created and available

Field Types Reference ​

Text Fields ​

Text ​

  • Use For: Single-line text input
  • Examples: Name, title, short text
  • Configuration:
    • Max length
    • Min length
    • Pattern (regex)

Textarea ​

  • Use For: Multi-line text input
  • Examples: Description, notes, long text
  • Configuration:
    • Rows (height)
    • Max length
    • Min length

Email ​

  • Use For: Email addresses
  • Examples: Contact email, notification email
  • Validation: Automatic email format validation

URL ​

  • Use For: Website links
  • Examples: Website URL, social media links
  • Validation: Automatic URL format validation

Phone ​

  • Use For: Phone numbers
  • Examples: Contact phone, mobile number
  • Format: Configurable format

Number Fields ​

Number ​

  • Use For: Numeric values
  • Examples: Quantity, price, measurement
  • Configuration:
    • Min value
    • Max value
    • Step (increment)
    • Decimal places

Currency ​

  • Use For: Money amounts
  • Examples: Price, budget, cost
  • Format: Currency symbol and formatting

Date/Time Fields ​

Date Picker ​

  • Use For: Dates
  • Examples: Birth date, deadline, event date
  • Configuration:
    • Date format
    • Min date
    • Max date

Time Picker ​

  • Use For: Times
  • Examples: Meeting time, schedule
  • Configuration:
    • Time format (12/24 hour)
    • Min time
    • Max time

DateTime Picker ​

  • Use For: Date and time
  • Examples: Event datetime, appointment
  • Configuration:
    • DateTime format
    • Min datetime
    • Max datetime

Selection Fields ​

Select ​

  • Use For: Single choice dropdown
  • Examples: Category, status, type
  • Configuration:
    • Options list
    • Default option
    • Allow empty

Radio ​

  • Use For: Single choice (visual)
  • Examples: Priority, rating, choice
  • Configuration:
    • Options list
    • Default option
    • Layout (horizontal/vertical)

Checkbox ​

  • Use For: Multiple choices
  • Examples: Features, tags, options
  • Configuration:
    • Options list
    • Default selections
    • Layout

Multi-Select ​

  • Use For: Multiple selection dropdown
  • Examples: Categories, tags, multiple choices
  • Configuration:
    • Options list
    • Default selections
    • Max selections

File Fields ​

File Upload ​

  • Use For: Single file
  • Examples: Document, image, attachment
  • Configuration:
    • Allowed file types
    • Max file size
    • Min file size

Multiple Files ​

  • Use For: Multiple files
  • Examples: Gallery, attachments, documents
  • Configuration:
    • Allowed file types
    • Max file size
    • Max number of files

Other Fields ​

Hidden ​

  • Use For: Internal data
  • Examples: System values, calculated fields
  • Note: Not visible to users

HTML ​

  • Use For: Rich content
  • Examples: Custom HTML, formatted content
  • Configuration:
    • HTML content
    • CSS styling

Section ​

  • Use For: Organizing fields
  • Examples: Field groups, sections
  • Note: Visual separator only

Field Validation Rules ​

Required Fields ​

Configuration:

  • Required: Yes/No toggle
  • Error Message: Custom error message
  • Enforcement: Server-side and client-side

Text Validation ​

Available Rules:

  • Min Length: Minimum characters
  • Max Length: Maximum characters
  • Pattern: Regex pattern
  • Custom: Custom validation function

Example:

  • Min Length: 3
  • Max Length: 50
  • Pattern: ^[A-Za-z\s]+$ (letters and spaces only)

Number Validation ​

Available Rules:

  • Min Value: Minimum number
  • Max Value: Maximum number
  • Step: Increment value
  • Type: Integer or Decimal

Example:

  • Min Value: 0
  • Max Value: 100
  • Step: 1
  • Type: Integer

Date Validation ​

Available Rules:

  • Min Date: Earliest allowed date
  • Max Date: Latest allowed date
  • Format: Date format
  • Custom: Custom validation

Example:

  • Min Date: Today
  • Max Date: +1 year
  • Format: YYYY-MM-DD

File Validation ​

Available Rules:

  • File Types: Allowed extensions (e.g., jpg, png, pdf)
  • Max Size: Maximum file size (e.g., 5MB)
  • Min Size: Minimum file size
  • Dimensions: Image dimensions (for images)

Example:

  • File Types: jpg, png, pdf
  • Max Size: 5MB
  • Dimensions: 1200x800 (for images)

Field Display Settings ​

Field Order ​

Configuration:

  • Order Number: Display order
  • Lower Numbers: Appear first
  • Higher Numbers: Appear later
  • Drag and Drop: Reorder visually

Visibility ​

Options:

  • Public: Visible to everyone
  • Private: Visible to admin only
  • Admin Only: Admin panel only

Display Options ​

Settings:

  • Show Label: Display field label
  • Show Help Text: Display help text
  • Show Placeholder: Show placeholder
  • Show Default Value: Pre-fill default

Conditional Display ​

Advanced:

  • Show If: Conditional display
  • Hide If: Conditional hiding
  • Dependencies: Field dependencies

Managing Custom Fields ​

Viewing Fields ​

Field List:

  • All fields for module
  • Display order
  • Field type
  • Required status
  • Active status

Editing Fields ​

  1. Click Edit:

    • Click Edit on field
    • Modify settings
    • Update configuration

  2. Save Changes:

    • Click Update
    • Changes saved
    • Applied immediately

Deleting Fields ​

  1. Click Delete:

    • Click Delete on field
    • Confirm deletion

  2. Warning:

    • Data may be lost
    • Cannot be undone
    • Backup recommended

Reordering Fields ​

Methods:

  • Drag and Drop: Visual reordering
  • Order Number: Set order number
  • Save Order: Save new order

Using Custom Fields ​

In Forms ​

Automatic Display:

  • Fields appear in create/edit forms
  • Based on field order
  • Respects visibility settings

In Display ​

Showing Values:

  • Fields displayed in detail views
  • Based on visibility
  • Formatted according to type

In Search/Filter ​

Searchable Fields:

  • Text fields searchable
  • Number fields filterable
  • Date fields filterable

Best Practices ​

Field Naming ​

  1. Clear Labels:

    • Use descriptive names
    • Avoid abbreviations
    • Be specific

  2. Consistent Keys:

    • Use lowercase
    • Use underscores
    • Be descriptive

Field Organization ​

  1. Logical Order:

    • Group related fields
    • Order logically
    • Use sections

  2. Helpful Text:

    • Add help text
    • Provide examples
    • Include instructions

Data Management ​

  1. Validate Properly:

    • Use appropriate validation
    • Test validation rules
    • Handle errors

  2. Backup Before Changes:

    • Backup data
    • Test changes
    • Document changes

Troubleshooting ​

Field Not Appearing ​

Solutions:

  1. Check field is active
  2. Verify field order
  3. Check visibility settings
  4. Clear cache
  5. Refresh page

Validation Not Working ​

Solutions:

  1. Check validation rules
  2. Verify field type
  3. Test validation
  4. Check error messages
  5. Review validation code

Data Not Saving ​

Solutions:

  1. Check field configuration
  2. Verify validation passes
  3. Check database schema
  4. Review error logs
  5. Test save process

Last Updated: [Date will be updated during final review]

Released under the MIT License.

Copyright © 2024 OmniSuite CMS