TypeDialog Logo
# Configuration Files Pre-configured settings for each TypeDialog backend and environment. ## Overview Configuration files are organized by **backend** (CLI, TUI, Web) and **environment** (default, dev, production). ```text config/ ├── cli/ │ ├── default.toml # Standard CLI settings │ ├── dev.toml # Development (debugging enabled) │ └── production.toml # Production (optimized, hardened) ├── tui/ │ ├── default.toml # Standard TUI settings │ ├── dev.toml # Development features enabled │ └── production.toml # Optimized for deployment └── web/ ├── default.toml # Standard web server settings ├── dev.toml # Development (hot reload) └── production.toml # Hardened for production ``` ## Backend Configurations ### CLI Backend **command-line interface** - Simple text-based forms for scripts and automation. | Config | Purpose | Debug | Colors | Timeout | | -------- | --------- | ------- | -------- | --------- | | default | Standard | No | Yes | 300 s | | dev | Development | Yes | Yes | 300 s | | production | Production | No | Yes | 3600 s | **Usage:** ```bash typedialog --config config/cli/production.toml form.toml ``` **Features:** - Inline validation - Optional mouse support - Placeholder text display - Help text display ### TUI Backend **terminal user interface** - Interactive multi-panel forms with navigation. | Config | Purpose | Borders | Animations | Render | | -------- | --------- | --------- | ----------- | -------- | | default | Standard | Rounded | Enabled | Auto | | dev | Development | Double | Enabled | Debug | | production | Production | Rounded | Disabled | Optimized | **Usage:** ```bash typedialog-tui --config config/tui/production.toml form.toml ``` **Features:** - 3-panel layout (fields, input, buttons) - Mouse support - Keyboard navigation - Real-time field updates ### Web Backend **HTTP server** - Browser-based forms with REST API. | Config | Purpose | CORS | HTTPS | Rate Limit | | -------- | --------- | ------ | ------- | ----------- | | default | Standard | Localhost | No | Unlimited | | dev | Development | Enabled | No | Unlimited | | production | Production | Restricted | Required | 100/min | **Basic Usage:** ```bash typedialog-web form.toml # Server starts on http://localhost:8080 ``` **With Options:** ```bash # Load defaults from .ncl file typedialog-web form.toml --defaults values.ncl # Save results to file after form submission typedialog-web form.toml --output result.json # Combine with custom locale typedialog-web form.toml --defaults config.ncl --output result.json --locale es-ES # Run on custom port typedialog-web form.toml --port 9000 ``` **Features:** - HTML/CSS rendering - CSRF protection - Response caching - Gzip compression - Array field management (RepeatingGroup) - Default value loading from Nickel (.ncl) or JSON - Output to file (JSON format) ## Configuration by Environment ### Development Configuration Enabled features for development and debugging: ```toml # CLI Dev debug_output = true log_level = "debug" show_field_types = true # TUI Dev show_field_indices = true trace_rendering = false # Web Dev hot_reload = true debug = true logs = "/tmp/typedialog-web.log" ``` **Usage:** ```bash typedialog --config config/cli/dev.toml form.toml typedialog-tui --config config/tui/dev.toml form.toml typedialog-web --config config/web/dev.toml ``` ### Production Configuration Hardened settings optimized for deployment: ```toml # CLI Production debug_output = false log_level = "error" show_placeholders = false timeout = 3600 # TUI Production enable_animations = false render_throttle = 16ms max_fps = 60 # Web Production require_https = true csrf_enabled = true rate_limit = 100 cache_ttl = 3600 ``` **Usage:** ```bash typedialog --config config/cli/production.toml form.toml typedialog-tui --config config/tui/production.toml form.toml typedialog-web --config config/web/production.toml ``` ## Common Settings ### Form Configuration ```toml [form] title = "Form Title" description = "Optional description" [form.validation] validate_on_change = true show_errors_inline = true strict_validation = true ``` ### Output Configuration ```toml [output] format = "json" # json, yaml, toml, text pretty_print = true debug_output = false ``` ### Logging ```toml [logging] level = "info" # debug, info, warn, error file = "/var/log/typedialog/app.log" ``` ## Custom Configuration ### Creating Custom Configurations Create a new TOML file based on an environment template: ```bash # Copy production config as base cp config/cli/production.toml config/cli/custom.toml # Edit for your needs nano config/cli/custom.toml # Use it typedialog --config config/cli/custom.toml form.toml ``` ### Override Specific Settings Use environment variables to override config: ```bash # CLI Backend export TYPEDIALOG_DEBUG=1 export TYPEDIALOG_LOG_LEVEL=debug typedialog --config config/cli/default.toml form.toml # TUI Backend export TYPEDIALOG_TUI_BORDER=double typedialog-tui --config config/tui/default.toml form.toml # Web Backend export TYPEDIALOG_WEB_PORT=3000 export TYPEDIALOG_WEB_CORS_ORIGINS="localhost,example.com" typedialog-web --config config/web/default.toml # Fragment Search Paths (All Backends) export TYPEDIALOG_FRAGMENT_PATH="/path/to/fragments:/another/path/fragments" # On Windows use semicolon separator: # set TYPEDIALOG_FRAGMENT_PATH=C:\fragments;D:\other\fragments typedialog form.toml ``` **TYPEDIALOG_FRAGMENT_PATH:** Colon-separated list (semicolon on Windows) of directories to search for fragment files. Fragments are reusable form components loaded via `includes` directive in group definitions. Search order: 1. Form's directory (backward compatible) 2. Directories in TYPEDIALOG_FRAGMENT_PATH (left to right) Example: ```bash export TYPEDIALOG_FRAGMENT_PATH="/usr/local/share/typedialog/fragments:$HOME/.typedialog/fragments" typedialog form.toml ``` **For complete documentation on fragment search paths, see:** [Fragment Search Paths](./fragment-search-paths.md) - Cascading search, use cases, troubleshooting ## CLI Backend Configuration Details ```toml [terminal] use_raw_mode = true # Enable raw terminal mode enable_mouse = false # Mouse support use_color = true # Colored output [appearance] theme = "default" # Color theme show_help = true # Display field help show_placeholders = true # Show placeholder text [validation] validate_on_change = true # Real-time validation show_errors_inline = true # Inline error messages [timeout] max_duration = 3600 # Max form time (seconds) input_timeout = 300 # Field input timeout ``` ## TUI Backend Configuration Details ```toml [terminal] use_raw_mode = true enable_mouse = true enable_scrolling = true height = -1 # -1 = auto width = -1 # -1 = auto [ui] show_borders = true show_focus = true highlight_on_hover = true enable_animations = true [appearance] theme = "default" border_style = "rounded" # rounded, double, simple color_scheme = "default" [keyboard] vi_mode = false emacs_mode = false [performance] render_throttle = 16 # milliseconds max_fps = 60 # frames per second ``` ## Web Backend Configuration Details ```toml [server] host = "0.0.0.0" port = 8080 workers = 4 [html] css_framework = "none" # bootstrap, tailwind, none inline_styles = false responsive = true dark_mode = true [submission] method = "post" webhook_url = "https://api.example.com/forms" redirect_on_success = true redirect_url = "https://example.com/thank-you" [security] csrf_enabled = true rate_limit = 100 # requests per minute require_https = true add_security_headers = true [performance] cache_static = true cache_ttl = 3600 enable_compression = true compression_threshold = 1024 ``` ## Distribution Configurations When creating release distributions, all configurations are included: ```bash # Build and package just distro::build-release just distro::create-package # Result includes all configs distribution/typedialog-0.1.0/ ├── config/ │ ├── cli/ │ ├── tui/ │ └── web/ └── ... ``` Users can then choose configs during installation: ```bash # Extract distribution tar -xzf typedialog-0.1.0.tar.gz cd typedialog-0.1.0 # Install bash installers/install.sh # Use specific config typedialog --config ~/.config/typedialog/cli/production.toml form.toml ``` ## Best Practices ### Development - Use `dev` configurations for local development - Enable debugging and verbose logging - Use shorter timeouts for faster iteration ### Testing - Use `default` configurations for testing - Run integration tests with all environments ### Production - Always use `production` configurations - Verify HTTPS is enabled (web backend) - Set appropriate rate limits - Configure logging to persistent location - Test thoroughly in staging first ## Related Documentation - [BUILD_AND_DISTRIBUTION.md](../BUILD_AND_DISTRIBUTION.md) - Build guide - [DISTRIBUTION_WORKFLOW.md](../DISTRIBUTION_WORKFLOW.md) - Release workflow - [README.md](../README.md) - Main documentation