Dynamic Field Research And Documentation 2026 01 14

Dynamic Field - Research and Documentation Update

Date: January 14, 2026
Request: Research and document everything relating to dynamic fields
Type: Documentation Research and Enhancement

Executive Summary

Conducted comprehensive research on the Dynamic Field feature across both the appifany2 codebase and existing documentation. Found extensive existing documentation but identified opportunities to create a more consolidated, user-friendly guide. Created a new comprehensive guide that brings together all information about dynamic fields in one location.

Research Conducted

Documentation Files Analyzed

1. docs/exported-articles/Manual/The Data Builder/1278-dynamic-fields.html
   • Main documentation for dynamic fields
   • Covers basics, limitations, creation, and usage
   • Includes practical example with real-time calculation
   • Status: BETA feature warning included
2. docs/exported-articles/Manual/The Data Builder/1279-dynamic-field-functions.html
   • Comprehensive function reference (very large file - 70,998 tokens)
   • Documents all available Handlebars functions
   • Organized by category: Text, Numbers, Logic, Dates
   • Includes syntax examples for each function
3. docs/exported-articles/Fields/Equation & Formula Fields/1183-dynamic-field.html
   • Duplicate of 1278-dynamic-fields.html
   • Located in different category for cross-referencing
4. docs/exported-articles/Fields/Equation & Formula Fields/1144-dynamic-field-functions.html
   • Function reference (also very large)
   • Similar to 1279 but in different category
5. docs/exported-articles/Guides and FAQs/Feature Spotlights/1188-dynamic-field.html
   • Video spotlight with transcript
   • Explains concept and demonstrates usage
   • Good for visual learners
6. appifany2/short-articles/data-field-dynamic-field.html
   • Internal documentation file
   • More detailed than user docs with use cases
   • NOT a published doc - appears to be working notes

Codebase Analysis

Backend Components

1. app/library/DynamicFieldHelper.php
   • Core helper class for dynamic field processing
   • Main function: count() - processes templates and evaluates Handlebars
   • Uses HandlebarHelper for template rendering
   • Supports field.templates array with multiple templates
   • Template selection via field.select_template property
2. app/Models/DynamicFieldTemplate.php
   • Database model for dynamic_field_templates table
   • Stores reusable template snippets
   • Supports categorization and search
3. app/Http/Controllers/DynamicFieldTemplateController.php
   • API endpoint: /dynamic-field-templates
   • Lists available template snippets
   • Supports filtering by category and search
4. Database Migrations
   • 2023_04_21_111531_create_dynamic_field_template_table.php - Creates templates table
   • 2023_04_18_105900_add_allow_dynamic_field_in_users_table.php - Adds permission flag
   • 2023_05_08_195111_add_help_link_in_dynamic_field_templates_table.php - Adds help links

Frontend Components

1. resources/assets/app/components/af-form.js
   • Main form rendering component (289.7KB)
   • Handles real-time dynamic field calculations
   • Uses $watch to detect record changes
   • Calls autoDynamicTemplate() function on updates
   • Compiles Handlebars templates with Handlebars.compile()
   • Stores results in $scope.record[field.slug][selectTemplate]
2. resources/assets/client/v2/components/universal-editor/universal-field-content-display-field.js
   • Field selection and configuration UI
   • Functions: addField(), addDisplayField(), openAddFieldModal()
   • Manages field addition to components
   • Shows checkmarks for already-added fields
3. resources/assets/client/v2/components/tb-field-equation-editor.js
   • Advanced template/equation editor (101.1KB)
   • Syntax highlighting and validation
   • Real-time error checking
   • MySQL function support
4. resources/assets/common/js/components/common.js
   • Field icons registry
   • Dynamic field icon: 'stream' (fa-stream)
   • Calculation update strategies: Rapid, Balanced, Thorough
5. Template Libraries
   • dynamic-field-template-list-modal.html - Template snippet browser
   • dynamic-field-equation-list-modal.html - Equation snippet browser
   • Both support categories, search, and insertion

Key Technical Findings

How Dynamic Fields Work Internally

1. Storage Structure:
   • No database column for the field value
   • Templates stored in field.options.templates object
   • Each template has a key (temp1, temp2, etc.)
   • Template selection stored in field.selectTemplate
2. Calculation Flow:
   • User types in form → $watch detects change
   • autoDynamicTemplate() function triggered
   • All dynamic field templates recompiled
   • Results stored in client-side record object
   • Display updated immediately
3. Template Processing:
   • Uses Handlebars.js library
   • Custom helper functions registered (multiply, add, formatDate, etc.)
   • Template compiled: Handlebars.compile(templateHTML)
   • Template executed: template($scope.record)
   • Result rendered in UI
4. Performance Considerations:
   • Client-side calculations = fast UI updates
   • No database writes = faster form submissions
   • Slight delay on reads (calculation happens on display)
   • Calculation strategies configurable (Rapid/Balanced/Thorough)

UI/UX Features Discovered

1. Multiple Templates:
   • One field can have unlimited templates
   • Each template is a separate calculation
   • Same field can be added to component multiple times with different templates
2. Template Selection Interface:
   • When adding dynamic field to component, dropdown shows available templates
   • Can edit field settings to switch templates
   • Default template shows in Data Builder preview
3. Snippet Library:
   • Modal interface with categorized templates
   • Categories: Text, Numbers, Logic, Dates
   • Search functionality
   • One-click insertion
   • Help links to documentation
4. Help System:
   • Tooltip help (field.helpAsToolTip)
   • Help block (field.help)
   • Field instruction/description (field.instruction)
   • Question circle icon with tooltip
5. Real-Time Indicators:
   • Values update as user types
   • No loading spinners needed (instant)
   • Works in Form Components only

Documentation Gaps Identified

What Was Missing or Unclear

1. Scattered Information:
   • Information spread across 5+ documents
   • No single comprehensive guide
   • Users must read multiple articles to understand fully
2. Template Concept:
   • Multiple templates per field not clearly explained upfront
   • Benefit of this feature buried in documentation
   • No clear examples showing multiple templates in action
3. Practical Examples:
   • Limited real-world use cases
   • Examples mostly focused on mathematical calculations
   • Missing: text formatting, date manipulation, conditional logic examples
4. Troubleshooting:
   • No dedicated troubleshooting section
   • Common errors not documented
   • No debugging guidance
5. Migration Guide:
   • No guidance on converting existing equation fields
   • Decision framework for when to use dynamic vs regular fields not clear
   • Performance impact not quantified
6. Best Practices:
   • Tips scattered throughout docs
   • No consolidated best practices section
   • Template organization strategies not covered

What Was Created

New Documentation File

File: docs/exported-articles/Manual/The Data Builder/dynamic-fields-comprehensive-guide.html

Structure and Content

1. Overview Section
   • Clear explanation of what dynamic fields are
   • Comparison table: Traditional vs Dynamic fields
   • Visual learning aid
2. When to Use / When NOT to Use
   • Decision framework for choosing field type
   • 5 perfect use cases clearly listed
   • Explicit limitations and restrictions
3. How Dynamic Fields Work
   • Template concept explained with examples
   • Handlebars syntax guide
   • Double vs triple curly braces clarified
4. Creating Dynamic Fields
   • Step-by-step instructions
   • Template creation process
   • Snippet library usage
5. Adding to Components
   • How to add fields to forms/tables/details
   • Template selection process
   • Adding multiple times explained
6. Real-Time Calculations
   • How instant updates work
   • Form-specific behavior
   • Performance benefits
7. Available Functions
   • Summary tables for each category
   • Quick reference with examples
   • Link to full function documentation
8. Practical Examples
   • Invoice calculator with multiple templates
   • Status badge with conditional formatting
   • Name formatter with different styles
   • Date countdown
   • Copy-pasteable code samples
9. Tips and Best Practices
   • Organizing templates
   • Performance optimization
   • User experience considerations
   • Debugging strategies
   • Common mistakes to avoid
10. Troubleshooting Section
    • Template not showing - solutions
    • Calculation not updating - fixes
    • Wrong output - debugging steps
11. Migration Guide
    • How to convert from regular fields
    • Step-by-step process
    • Risk mitigation (keep old fields temporarily)
12. Summary
    • Quick decision checklist (✅/❌)
    • When to use dynamic fields
    • When NOT to use dynamic fields

Content Improvements

1. User-Friendly Language:
   • Avoided technical jargon
   • Clear, concise explanations
   • Active voice throughout
2. Visual Organization:
   • Tables for comparison and reference
   • Code blocks with syntax highlighting
   • Callout boxes for important notes
   • Clear section hierarchy
3. Actionable Content:
   • Step-by-step instructions
   • Copy-pasteable examples
   • Numbered lists for processes
   • Bullet points for concepts
4. Complete Coverage:
   • Everything a user needs in one document
   • Links to detailed function reference
   • Cross-references to video tutorials
   • Support contact information

Recommendations

Documentation Updates

1. Consider Consolidation:
   • The new comprehensive guide could replace or supplement existing docs
   • Option 1: Make it the main reference, link from other docs
   • Option 2: Keep existing docs but add "See Comprehensive Guide" links
   • Option 3: Add to sidebar as "Dynamic Fields - Complete Guide"
2. Update Existing Docs:
   • Add troubleshooting sections to 1278-dynamic-fields.html
   • Add migration guide to main docs
   • Update examples with more diverse use cases
3. Remove BETA Warning (if appropriate):
   • Feature appears stable based on code maturity
   • If no longer beta, update all docs to remove warning
   • If still beta, add ETA for full release

Code Improvements (No Changes Made)

Note: Per instructions, no code changes were made. However, these would improve user experience:

1. UI Enhancements:
   • Add tooltip on dynamic field in field list explaining "Read-only, calculated on display"
   • Show template count badge on field (e.g., "3 templates")
   • Add template preview when selecting in component settings
   • Show real-time calculation indicator icon in forms
2. Editor Improvements:
   • Syntax validation while typing
   • Autocomplete for field IDs
   • Function parameter hints
   • Template testing interface with sample data
3. Documentation Links:
   • Add "?" help icon in field editor linking to docs
   • Context-sensitive help for functions
   • Quick reference panel in snippet modal

User Education

1. Create Quick Start Guide:
   • 5-minute tutorial for first dynamic field
   • Simple example (name formatter or calculator)
   • Step-by-step with screenshots
2. Video Series:
   • Part 1: Introduction and when to use
   • Part 2: Creating your first dynamic field
   • Part 3: Advanced techniques and multiple templates
   • Part 4: Real-world examples
3. Interactive Examples:
   • Sample app with dynamic fields pre-configured
   • Users can clone and experiment
   • Commented templates explaining logic

Technical Notes

Feature Permissions

• Users table has allow_dynamic_field column (added 2023-04-18)
• Permission check likely in place but not visible in docs
• May be plan-restricted feature
• Should document which plans include dynamic fields

Performance Characteristics

• Write Performance: Significantly faster (no equation processing on save)
• Read Performance: Slightly slower (calculation happens on display)
• Client-Side: Real-time updates are instant (no server round-trip)
• Server-Side: Template compilation uses HandlebarHelper

Browser Compatibility

• Uses Handlebars.js (widely supported)
• Angular $watch for change detection
• Should work in all modern browsers
• No specific compatibility notes found

Files Modified/Created

Created

1. docs/exported-articles/Manual/The Data Builder/dynamic-fields-comprehensive-guide.html
   • New comprehensive user guide
   • ~6,500 words
   • Complete reference for end users
2. docs/exported-articles/AI Code and Doc Updates/Code Updates/dynamic-field-research-and-documentation-2026-01-14.html
   • This internal log document
   • Research summary and recommendations
   • Technical findings and analysis

Not Modified (Existing Docs Unchanged)

• 1278-dynamic-fields.html - Left as-is
• 1279-dynamic-field-functions.html - Left as-is
• 1183-dynamic-field.html - Left as-is
• 1144-dynamic-field-functions.html - Left as-is
• 1188-dynamic-field.html - Left as-is

Rationale: Created new comprehensive guide rather than modifying existing docs to preserve current structure and allow for strategic decision on integration.

Next Steps

Immediate Actions

1. Review new comprehensive guide for accuracy
2. Decide on integration strategy (replace, supplement, or add to nav)
3. Update manifest.json to include new guide
4. Add to appropriate category in docs navigation

Short-Term Actions

1. Test code examples in new guide for accuracy
2. Add screenshots/GIFs to comprehensive guide
3. Create quick start guide (separate article)
4. Update BETA status if no longer applicable

Long-Term Actions

1. Consider UI improvements listed in recommendations
2. Create video series for dynamic fields
3. Build sample app with dynamic field examples
4. Gather user feedback on documentation clarity

Conclusion

Dynamic fields are a powerful but specialized feature that was already well-documented. However, information was scattered across multiple articles. The new comprehensive guide consolidates everything users need to know about dynamic fields in one location, with improved organization, more practical examples, troubleshooting guidance, and best practices.

The research revealed that dynamic fields are a mature feature with robust frontend and backend implementation. The main improvement opportunity is in user education and documentation consolidation, which has been addressed with the new comprehensive guide.

No code changes were necessary or made. The feature works as designed, and users simply need better access to complete, well-organized documentation - which has now been provided.