# Forms Wizard (cf.cplace.formsWizard)

## Overview

The Forms Wizard app enables the creation and configuration of multi-step input wizards. These wizards display forms in individual steps that can be configured as required and enriched with Low-Code scripts to cover a variety of use cases. The Forms Wizard can also be accessed by external users who are not logged into cplace, making it suitable for public-facing data collection scenarios.

## Dependencies

When installing `cf.cplace.formsWizard`, the following apps are automatically installed:

| App | Qualified Name | Purpose |
|-----|----------------|---------|
| Attribute Dependencies | `cf.cplace.attributeDependencies` | Enables conditional attribute visibility and mandatory field rules based on other attribute values |

## Types Provided

### cf.cplace.formsWizard.wizard (Wizard)

The main configuration type for a Forms Wizard. Each wizard defines the overall flow, appearance, and behavior.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Display Name | `cf.cplace.formsWizard.name` | Shown as heading in the wizard dialog (required) |
| Description | `cf.cplace.formsWizard.description` | Optional description text |
| Header Image | `cf.cplace.formsWizard.logo` | Logo/image displayed in wizard header |
| Target Workspaces | `cf.cplace.formsWizard.targetWorkspaces` | Where created pages will be stored (defaults to wizard's workspace) |
| Triggering Types | `cf.cplace.formsWizard.triggerTypes` | Types whose creation will launch this wizard instead |
| Active | `cf.cplace.formsWizard.activeState` | Whether the wizard can be used (required) |
| Show progress bar | `cf.cplace.formsWizard.showProgressBar` | Display progress indicator (required) |
| Show progress in percent | `cf.cplace.formsWizard.showPercentInProgressBar` | Show percentage in progress bar (required) |
| Start Step | `cf.cplace.formsWizard.startStep` | First step of the wizard flow |
| Final Steps | `cf.cplace.formsWizard.finalSteps` | Steps that complete the wizard |
| Summary | `cf.cplace.formsWizard.summary` | Summary display configuration |
| Cleanup Script | `cf.cplace.formsWizard.cleanupScript` | Script to run on wizard cancellation |
| External Wizard | `cf.cplace.formsWizard.externalWizard` | Allow access without cplace login (required) |
| External Access User | `cf.cplace.formsWizard.externalAccessUser` | User context for external access |
| Show Captcha | `cf.cplace.formsWizard.externalShowCaptcha` | Display captcha for external users (required) |
| Persist automatically | `cf.cplace.formsWizard.autoPersist` | Auto-save form pages (required) |
| Refresh page after finishing | `cf.cplace.formsWizard.refreshEmbeddingPageAfterFinish` | Reload embedding page on completion (required) |
| Localizations | `cf.cplace.formsWizard.localizations` | Multi-language text configuration |

### cf.cplace.formsWizard.step (Step)

Individual steps within a wizard. Steps define the navigation flow and can be of different types.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Wizard | `cf.cplace.formsWizard.wizard` | Parent wizard reference (required) |
| Title | `cf.cplace.formsWizard.title` | Step title displayed to users |
| Description | `cf.cplace.formsWizard.description` | Step description text |
| Type | `cf.cplace.formsWizard.stepType` | Step type: Form, Table, Info, Script, Decision (required) |
| Configuration | `cf.cplace.formsWizard.configurationReference` | Link to type-specific configuration |
| Next possible Steps | `cf.cplace.formsWizard.next` | Steps that can follow this one |
| Identifier | `cf.cplace.formsWizard.identifier` | Unique ID within the wizard (required) |
| Target Types | `cf.cplace.formsWizard.targetTypes` | Page types this step creates |
| Skip to | `cf.cplace.formsWizard.skipto` | Step to jump to when skipping |
| Label for "Skip" button | `cf.cplace.formsWizard.skiptoLabel` | Custom skip button text |
| Skip to finish | `cf.cplace.formsWizard.skiptoFinish` | Allow skipping to end (required) |

### cf.cplace.formsWizard.step.form.configuration (Form Step Configuration)

Configuration for form-type steps that collect user input.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Used attributes | `cf.cplace.formsWizard.step.form.configuration.typeNameToAttributesMapping` | Which attributes to show in the form |
| Layout | `cf.cplace.formsWizard.step.form.configuration.layout` | Form layout configuration |
| Single column layout | `cf.cplace.formsWizard.step.form.configuration.isOneColumnLayout` | Use one-column layout (required) |
| Step | `cf.cplace.formsWizard.stepConfiguration.step` | Parent step reference (required) |

### cf.cplace.formsWizard.step.table.configuration (Table Step Configuration)

Configuration for table-type steps that display and allow selection from existing pages.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Search | `search` | Search query to populate table |
| Columns | `columns` | Table column configuration |
| Column Filters | `filters` | Filter options for columns |
| Table Result Mode | `cf.cplace.formsWizard.step.table.configuration.tableResultMode` | How selections are handled (required) |
| Step | `cf.cplace.formsWizard.stepConfiguration.step` | Parent step reference (required) |

### cf.cplace.formsWizard.step.info.configuration (Info Step Configuration)

Configuration for informational steps that display content without collecting input.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Info | `cf.cplace.formsWizard.step.info.configuration.info` | Rich text content to display |
| Script | `cf.cplace.formsWizard.step.info.configuration.script` | Dynamic content generation script |
| Step | `cf.cplace.formsWizard.stepConfiguration.step` | Parent step reference (required) |

### cf.cplace.formsWizard.step.script.configuration (Script Step Configuration)

Configuration for script-type steps that execute Low-Code logic without UI.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Script | `cf.cplace.formsWizard.step.script.configuration.script` | cplaceJS script to execute (required) |
| Step | `cf.cplace.formsWizard.stepConfiguration.step` | Parent step reference (required) |

### cf.cplace.formsWizard.step.decision.configuration (Decision Step Configuration)

Configuration for decision steps that branch the wizard flow based on user choice.

| Attribute | Internal Name | Description |
|-----------|---------------|-------------|
| Text | `cf.cplace.formsWizard.step.decision.configuration.text` | Question/prompt text (required) |
| Option 1 step | `cf.cplace.formsWizard.step.decision.configuration.option1` | Step for first choice (required) |
| Option 1 button label | `cf.cplace.formsWizard.step.decision.configuration.option1Label` | First button text (required) |
| Option 2 step | `cf.cplace.formsWizard.step.decision.configuration.option2` | Step for second choice (required) |
| Option 2 button label | `cf.cplace.formsWizard.step.decision.configuration.option2Label` | Second button text (required) |
| Step | `cf.cplace.formsWizard.stepConfiguration.step` | Parent step reference (required) |

## Widgets Provided

| Widget | Widget Kind | Description | Use Case |
|--------|-------------|-------------|----------|
| Forms Wizard Localizations | `cf.cplace.formsWizard.wizardLocalizations` | UI for managing multi-language translations of wizard text | Configuring wizard for multiple languages |
| Step Preview | `cf.cplace.formsWizard.stepPreview` | Live preview of how a step will appear to end users | Testing step configuration during setup |
| Step Editor | `cf.cplace.formsWizard.stepEditorWidget` | Detailed configuration interface for individual steps | Full step configuration on Step pages |
| Step Editor for Wizards | `cf.cplace.formsWizard.stepEditorForWizardWidget` | Quick inline step editing from the Wizard page | Rapid step configuration without navigation |
| Step Manager | `cf.cplace.formsWizard.stepManager` | Table overview of all steps with CRUD operations | Managing wizard structure and step order |
| Forms Wizard Analysis | `cf.cplace.formsWizard.wizardAnalysis` | Validation checks for wizard completeness | Pre-activation testing and troubleshooting |
| Wizard Activation | `cf.cplace.formsWizard.wizardActivation` | Toggle to activate/deactivate the wizard | Controlling wizard availability |
| Horizontal Divider | `cf.cplace.formsWizard.horizontalDivider` | Visual separator line within form layouts | Grouping attributes visually in forms |

## Usage Notes

### When to Use This App

- **Multi-step data entry**: When creating a page requires collecting information in logical stages
- **Guided processes**: Onboarding flows, request submissions, approval workflows
- **Conditional branching**: When the path through data entry depends on user choices
- **External data collection**: Surveys, feedback forms, or submissions from non-cplace users
- **Type interception**: Automatically launch wizard when users try to create certain page types

### Common Patterns

1. **Linear Wizard**: Start Step -> Form Step 1 -> Form Step 2 -> Final Step
2. **Branching Wizard**: Info Step -> Decision Step -> (Branch A / Branch B) -> Final Step
3. **Data Selection + Entry**: Table Step (select existing) -> Form Step (add details) -> Script Step (process)
4. **External Survey**: External-enabled wizard with Captcha -> Form Steps -> Script Step (notification)

### Key Considerations

- **Triggering Types**: Install "Forms Wizard Launcher" app in workspaces where triggering should occur
- **External Access**: Requires configuring an External Access User for permission context
- **Auto-Persist**: Disable only if you need custom persistence logic in Script steps
- **Attribute Dependencies**: Leverage the auto-installed dependency app for conditional fields
- **Localization**: Use the Localizations attribute for multi-language wizard deployments

### Step Type Selection Guide

| Step Type | Use When |
|-----------|----------|
| Form | Collecting user input for page attributes |
| Table | User needs to select from existing pages |
| Info | Displaying instructions, confirmations, or dynamic content |
| Script | Running background logic (validation, calculations, API calls) |
| Decision | Branching the wizard based on user choice |