Forms

This document provides an overview of all user interface elements supported by Kodosumi. The elements are organized into three main categories: Input Elements, Action Elements, and Content Elements.

1. Input Elements

Input elements are used to collect user data through various input methods.

Text Input (InputText)

• Type: text
• Purpose: Single-line text input
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • size: Input field size
  • pattern: Regex pattern for validation

Password Input (InputPassword)

• Type: password
• Purpose: Secure password input with masked characters
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • size: Input field size
  • min_length: Minimum password length
  • max_length: Maximum password length
  • pattern: Regex pattern for password validation
  • show_toggle: Option to show/hide password (boolean)

Number Input (InputNumber)

• Type: number
• Purpose: Numeric input with validation
• Properties:
  • All properties from InputText
  • min_value: Minimum allowed value
  • max_value: Maximum allowed value
  • step: Step increment for number input

Text Area (InputArea)

• Type: textarea
• Purpose: Multi-line text input
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • rows: Number of visible text lines
  • cols: Width of the text area
  • max_length: Maximum number of characters allowed

Date Input (InputDate)

• Type: date
• Purpose: Date selection input
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial date value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • min_date: Minimum allowed date (YYYY-MM-DD)
  • max_date: Maximum allowed date (YYYY-MM-DD)

Time Input (InputTime)

• Type: time
• Purpose: Time selection input
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial time value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • min_time: Minimum allowed time (HH:MM)
  • max_time: Maximum allowed time (HH:MM)
  • step: Time increment in seconds

Date-Time Input (InputDateTime)

• Type: datetime-local
• Purpose: Combined date and time selection
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • value: Initial date-time value
  • required: Whether the field is mandatory
  • placeholder: Placeholder text
  • min_datetime: Minimum allowed date-time (YYYY-MM-DDTHH:MM)
  • max_datetime: Maximum allowed date-time (YYYY-MM-DDTHH:MM)
  • step: Time increment in seconds

Checkbox (Checkbox)

• Type: boolean
• Purpose: Boolean toggle input
• Properties:
  • name: Field identifier (required)
  • option: Display text for the checkbox
  • label: Optional label
  • value: Initial state (true/false)

Select (Select)

• Type: select
• Purpose: Dropdown selection
• Properties:
  • name: Field identifier (required)
  • option: List of InputOption objects
  • label: Display label
  • value: Selected option value

Input Option (InputOption)

• Type: option
• Purpose: Individual option for Select elements
• Properties:
  • name: Option value (required)
  • label: Display text for the option
  • value: Whether this option is selected
• Usage: Used within Select elements to define available choices

File Input (InputFiles)

• Type: file
• Purpose: File upload input with support for multiple files and directory uploads
• Properties:
  • name: Field identifier (required)
  • label: Display label
  • required: Whether the upload is mandatory
  • multiple: Whether multiple files can be selected (boolean)
  • directory: Whether to allow directory uploads (boolean, uses webkitdirectory)

2. Action Elements

Action elements are used to trigger form submission or navigation.

Submit (Submit)

• Type: submit
• Purpose: Form submission button
• Properties:
  • text: Button label text

Cancel (Cancel)

• Type: cancel
• Purpose: Cancel form and return to home
• Properties:
  • text: Button label text

Action (Action)

• Type: action
• Purpose: Custom action button
• Properties:
  • name: Action identifier
  • value: Action value
  • text: Button label text

3. Content Elements

Content elements are used to structure and display information within the form.

HTML (HTML)

• Type: html
• Purpose: Raw HTML content
• Properties:
  • text: HTML content to render

Markdown (Markdown)

• Type: markdown
• Purpose: Markdown-formatted content
• Properties:
  • text: Markdown content to render
• Features:
  • Supports extra markdown features
  • Code highlighting
  • Table of contents
  • Fenced code blocks

Break (Break)

• Type: html (specialized)
• Purpose: Visual spacing element
• Properties: None

Horizontal Rule (HR)

• Type: html (specialized)
• Purpose: Visual separator line
• Properties: None

Errors (Errors)

• Type: errors
• Purpose: Display _global_ form validation errors
• Properties:
  • error: List of error messages
• Features:
  • Global error display
  • Styled error container
  • Bold error text

Usage Examples

Basic Form with File Upload

from kodosumi.core import forms as F

model = F.Model(
    F.Markdown("# File Processing Form"),
    F.InputText(
        name="title",
        label="Document Title",
        placeholder="Enter document title",
        required=True
    ),
    F.InputFiles(
        name="files",
        label="Upload Documents",
        multiple=True,
        required=True
    ),
    F.Checkbox(
        name="process_images",
        option="Include image processing",
        value=False
    ),
    F.Submit("Process Files"),
    F.Cancel("Cancel")
)

Advanced Form with Validation

model = F.Model(
    F.Markdown("## Data Import Configuration"),
    F.InputText(
        name="email",
        label="Email Address",
        placeholder="[email protected]",
        pattern=r"^[^\s@]+@[^\s@]+\.[^\s@]+$",
        required=True
    ),
    F.InputNumber(
        name="batch_size",
        label="Batch Size",
        min_value=1,
        max_value=1000,
        value=100
    ),
    F.InputDate(
        name="start_date",
        label="Start Date",
        required=True
    ),
    F.Select(
        name="format",
        label="Output Format",
        option=[
            F.InputOption("json", "JSON"),
            F.InputOption("csv", "CSV"),
            F.InputOption("xml", "XML")
        ],
        value="json"
    ),
    F.InputFiles(
        name="data_files",
        label="Data Files",
        multiple=True,
        directory=False,
        required=True
    ),
    F.HR(),
    F.Submit("Import Data"),
    F.Cancel("Cancel")
)

Form with Error Handling

model = F.Model(
    F.Markdown("# User Registration"),
    F.Errors(),  # Global error display
    F.InputText(
        name="username",
        label="Username",
        required=True
    ),
    F.InputPassword(
        name="password",
        label="Password",
        min_length=8,
        required=True
    ),
    F.InputPassword(
        name="confirm_password",
        label="Confirm Password",
        required=True
    ),
    F.Submit("Register"),
    F.Cancel("Cancel")
)