Custom Fields System

Custom Field Creation

Adding Custom Fields to Contact Forms

The custom field system allows you to tailor contact forms to your business needs:

Field Creation Process:

• Custom fields are created through a dedicated modal interface
• Fields are automatically associated with the current team
• Each field requires a name and type specification
• Fields are linked to specific models (like contacts)

Required Information:

• Field Name: Descriptive name for the custom field (required, max 255 characters)
• Field Type: Data type for the field (text or number)
• Target Model: Automatically set to "App\Models\Contact" for contact fields

Creation Interface:

• Modal-based creation for easy field addition
• Real-time validation of field requirements
• Automatic team assignment for proper access control
• Integration with contact creation and editing forms

Field Management and Organization

Custom fields are organized systematically within teams:

Team-Based Organization:

• All custom fields are scoped to specific teams
• Team isolation ensures fields are only visible to team members
• Fields are filtered by team ID in all queries
• Cross-team field access is prevented

Model-Specific Fields:

• Fields are associated with specific models through the "fieldable" attribute
• Contact custom fields are separate from other model fields
• Polymorphic relationship allows fields to be used across different models
• Model-specific filtering ensures relevant fields appear in correct forms

Field Types and Validation

Available Field Types

The system supports multiple field types for different data requirements:

Basic Field Types:

• Text Fields: For string data input with standard text validation
• Number Fields: For numeric data with number-specific validation
• Boolean Fields: For true/false data (referenced in migration comments)
• Date Fields: For date-specific data entry (referenced in migration comments)

Field Type Implementation:

• Type validation ensures only supported types are used
• Frontend components render appropriate input types based on field type
• Text fields use standard text input components
• Number fields use HTML number input with numeric validation

Validation Rules:

• Field names are required and limited to 255 characters
• Field types must be valid supported types
• Team association is required for all fields
• Model association (fieldable) is required for proper organization

Field Value Management

Custom field values are managed through a separate value system:

Value Storage:

• Values are stored in a dedicated custom_field_values table
• Polymorphic relationship links values to specific records (contacts)
• Each value is associated with a custom field through custom_field_id
• Values support text storage with nullable values

Value Operations:

• Create: Values are created when contacts are created with custom field data
• Update: Values use updateOrCreate for efficient value management
• Read: Values are loaded with contacts for display in forms
• Delete: Values are cascade deleted when custom fields are removed

Custom Field Values

Managing Field Data

Custom field values are integrated into contact management workflows:

Value Creation:

• Values are created during contact creation if custom field data is provided
• Each custom field value links to a specific custom field and contact
• Values can be null/empty for optional fields
• Automatic value creation for all defined custom fields

Value Updates:

• Contact editing includes custom field value updates
• UpdateOrCreate pattern ensures values are properly maintained
• Existing values are updated, new values are created as needed
• Field removal from forms doesn't delete existing values

Value Display:

• Custom field values are loaded with contact data for editing
• Values are mapped to custom fields for proper form population
• Display includes field names and current values
• Form components render appropriate input types based on field types

Value Integration with Contact Forms

Custom field values integrate seamlessly with contact forms:

Form Integration:

• Custom fields appear in contact creation forms
• Existing values populate edit forms automatically
• Form validation includes custom field requirements
• Values are submitted as part of contact data

Data Structure:

• Values are passed as custom_field_values array in forms
• Each value includes custom_field_id and value data
• Form components map values to appropriate field types
• Validation occurs at both frontend and backend levels

Field Organization

Team and Purpose Organization

Custom fields are organized systematically for efficient management:

Team-Based Separation:

• All custom fields are scoped to specific teams through team_id
• Team filtering ensures fields are only visible to appropriate users
• Cross-team field access is completely prevented
• Team-specific field management and organization

Model-Specific Organization:

• Fields are organized by target model through "fieldable" attribute
• Contact fields are separate from deal fields or other model fields
• Model-specific queries ensure relevant fields appear in correct contexts
• Polymorphic relationships support flexible field usage

Purpose-Based Usage:

• Fields can be organized by business purpose or data type
• Field names support descriptive organization
• Label generation provides user-friendly field display
• Sequence and ordering support planned for future organization

Field Display and Management

Custom fields are presented in organized, user-friendly interfaces:

Display Features:

• Automatic label generation from field names using title case
• Field types determine appropriate input components
• Organized presentation in contact forms and lists
• Integration with existing contact management interfaces

Management Interface:

• Modal-based field creation for streamlined management
• Field listing and organization within team contexts
• Integration with contact index and management pages
• Real-time field addition and form updates

Custom Field Integration

Integration with Contact Workflows

Custom fields integrate deeply with contact management processes:

Contact Creation Integration:

• Custom fields appear in contact creation forms
• Field values are saved during contact creation process
• Validation includes custom field requirements
• Automatic field-value relationship creation

Contact Editing Integration:

• Existing custom field values populate edit forms
• Values can be modified through standard edit process
• UpdateOrCreate pattern ensures data consistency
• Field changes are tracked with contact updates

Contact Display Integration:

• Custom fields appear in contact detail views
• Field values are displayed with appropriate formatting
• Integration with contact search and filtering capabilities
• Field data included in contact export and reporting

System-Wide Integration

Custom fields integrate with broader system functionality:

Search Integration:

• Custom field values are included in contact searches
• Field data supports filtering and organization
• Integration with global search capabilities
• Field-based contact organization and grouping

Reporting Integration:

• Custom field data available for reporting and analytics
• Field values included in contact data exports
• Integration with team reporting and analysis tools
• Custom field metrics and usage tracking

Team Collaboration:

• Custom fields support team-wide contact management
• Field definitions shared across team members
• Consistent field usage across team workflows
• Field-based contact organization and assignment