Skip to main content

Form Widget Documentation

The Form widget is a powerful container component that allows you to create structured forms with multiple input fields, validation rules, and advanced layout options. It serves as a parent container for other form elements and provides comprehensive form management capabilities.

Overview​

The Form widget creates a structured form layout using a grid system. It can contain various input components, handle validation, and manage form submission. The widget supports different screen configurations, conditional visibility, and advanced validation rules.

Configuration Options​

Global Settings​

Basic Configuration​

  • Name: Display name for the form widget
  • Variable/Model: The data model that will store the form values (e.g., userForm, contactData)

Grid Settings​

  • Gutter: Space between columns in pixels (controls spacing between form elements)
  • Loop: Enable to create repeatable form sections (useful for dynamic lists)
  • Form: Create a separate form instance from the main page form
  • Default Length: When loop is enabled, sets the initial number of form instances
  • Show Button: Always display the add button in loop mode
  • Add Text: Custom text for the add button in loop mode

Layout Configuration​

Form Layout​

  • Label Position: Choose how labels are positioned relative to inputs
    • left: Labels appear to the left of inputs
    • right: Labels appear to the right of inputs
    • top: Labels appear above inputs

Grid Layout​

  • Justify: Horizontal alignment of form elements

    • start: Align to the start
    • end: Align to the end
    • center: Center alignment
    • space-around: Distribute with space around
    • space-between: Distribute with space between

  • Align: Vertical alignment of form elements

    • top: Align to top
    • middle: Center vertically
    • bottom: Align to bottom

Visual Options​

  • Shadowed: Add shadow effect to the form
  • Fixed: Make the form position fixed
  • Collapse: Enable collapsible form sections

Validation Configuration​

The form widget supports comprehensive validation across different screens (views/pages).

Screen-Based Validation​

For each screen in your application, you can configure:

  • Available: Whether the form is available on this screen
  • Visible: Control form visibility with boolean or conditional expressions
  • Required: Make form fields required on specific screens
  • Disable: Disable the entire form on certain screens

Advanced Validation​

  • Conditional Expressions: Use dynamic expressions for visibility and validation
    • Reference other form fields: {{fieldName}}
    • Use comparison operators: {{age}} > 18
    • Complex conditions: {{userType}} === 'admin' && {{status}} === 'active'

Validation Rules​

Configure custom validation rules for form behavior:

  • Rule Types: Select from predefined validation rules
  • Custom Messages: Define error messages for validation failures
  • Dynamic Validation: Create context-sensitive validation logic

Form Columns Structure​

The form uses a column-based layout system where you can:

  1. Add Columns: Create new columns with specific span widths

  2. Configure Responsive Breakpoints:

    • xs: Extra small screens
    • sm: Small screens
    • md: Medium screens
    • lg: Large screens
    • xl: Extra large screens

  3. Drag and Drop: Reorder columns using the drag handles

  4. Remove Columns: Delete unnecessary columns

Click Actions​

Configure actions that trigger when form elements are interacted with:

  • On Click: Define JavaScript functions or actions to execute
  • Action Templates: Use predefined action templates for common behaviors
  • Custom Scripts: Write custom JavaScript for complex interactions

Style Configuration​

Basic Styling​

  • Width: Set form width (pixels, percentages, or CSS units)
  • Height: Set form height
  • Class Names: Add custom CSS classes for styling
  • Dynamic Classes: Apply classes based on conditions

Layout Options​

  • Layout Mode:
    • Block: Form takes full width
    • Inline: Form elements display inline
  • Border: Enable/disable form border

Data Integration​

Form Data Management​

  • Model Binding: Forms automatically bind to the specified data model
  • Nested Data: Support for complex nested form structures
  • Data Validation: Built-in validation before form submission

Loop Configuration​

When loop mode is enabled:

  • Dynamic Addition: Users can add new form instances
  • Data Arrays: Form data is stored as arrays
  • Index Access: Each loop instance has access to its index

Usage Examples​

Basic Contact Form​

// Configuration
{
  name: "Contact Form",
  model: "contactData",
  labelPosition: "top",
  gutter: 20
}

Dynamic Product List​

// Configuration with loop
{
  name: "Product List",
  model: "products",
  loop: true,
  defaultLength: 3,
  addText: "Add Product",
  showButton: true
}

Conditional Form​

// Validation with conditions
{
  visible: "{{userRole}} === 'admin'",
  required: "{{formType}} === 'official'",
  disable: "{{status}} === 'readonly'"
}

Best Practices​

Form Design​

  1. Logical Grouping: Group related fields in the same column
  2. Responsive Design: Configure appropriate breakpoints for different screen sizes
  3. Clear Labels: Use descriptive labels for form fields
  4. Validation Feedback: Provide clear error messages

Performance​

  1. Efficient Models: Use specific model names to avoid data conflicts
  2. Conditional Loading: Use visibility conditions to load forms only when needed
  3. Minimal Nesting: Avoid excessive nesting of form components

User Experience​

  1. Progressive Disclosure: Use collapse feature for complex forms
  2. Visual Hierarchy: Use spacing and alignment to guide user attention
  3. Feedback: Provide immediate validation feedback
  4. Accessibility: Ensure proper label associations and keyboard navigation

Data Management​

  1. Consistent Naming: Use consistent naming conventions for models
  2. Validation Strategy: Implement both client-side and server-side validation
  3. Error Handling: Plan for graceful error handling and recovery

Technical Implementation​

Component Structure​

The form widget generates a Vue.js component that:

  • Manages form state and validation
  • Handles nested component communication
  • Provides data binding capabilities
  • Supports dynamic form generation

Integration Points​

  • Parent Components: Can be embedded in pages, popups, or other containers
  • Child Components: Contains and manages various input widgets
  • Data Layer: Integrates with the application's data management system
  • Validation System: Connects to the platform's validation framework

This documentation provides a comprehensive guide to configuring and using the Form widget effectively in your application interface.