Steps Widget Documentation

Overview​

The Steps widget is a visual progress indicator that displays a sequence of steps in a process. It shows the current progress and allows users to understand where they are in a multi-step workflow. The widget is fully responsive and adapts to different screen sizes.

Basic Configuration​

Widget Properties​

Name​

• Field: Name
• Description: A unique identifier for the widget instance
• Type: Text input
• Required: Yes

Variable/Model​

• Field: Variable/Model
• Description: The data model that stores the current step index
• Type: Text input
• Required: Yes
• Default: Automatically generated based on widget name

Default Value​

• Field: Default Value
• Description: The initial step index (0-based)
• Type: Number
• Default: 0

Layout Configuration​

Direction​

• Field: Direction
• Description: Controls the orientation of the steps display
• Type: Dropdown
• Options:
  • horizontal: Steps are displayed horizontally (default)
  • vertical: Steps are displayed vertically
• Usage: Choose based on available space and design requirements

Simple Design​

• Field: Simple Design
• Description: Enables a simplified visual appearance
• Type: Toggle switch
• Default: False
• Effect: When enabled, reduces visual complexity for cleaner presentation

Data Source Configuration​

Static Data Source​

When using static data, configure individual steps directly in the widget settings:

Step Configuration​

Each step requires:

• Title: Display name for the step
• Description: Additional information about the step

Adding Steps​

1. Select "Static" as the data source
2. Configure each step with title and description
3. Steps are automatically numbered starting from 0

Variable Data Source​

For dynamic content, use variable data source:

Variable Binding​

• Model Variable: {model_name}_vb
• Label Property: Configure which field contains the step title
• Value Property: Configure which field contains the step description

Label Configuration​

• Field: Label
• Description: Specifies the property name for step titles
• Syntax Options:
  • Simple property: title
  • Dynamic expression: $.title + ' - ' + $.subtitle

Value Configuration​

• Field: Value/Description
• Description: Specifies the property name for step descriptions
• Syntax Options:
  • Simple property: description
  • Dynamic expression: $.description + ' (' + $.status + ')'

Responsive Behavior​

Desktop View (sm and up)​

• Full steps component with horizontal/vertical layout
• Complete step titles and descriptions visible
• Interactive progress indication

Mobile View (xs only)​

• Collapsible accordion-style interface
• Current step highlighted as placeholder
• Previous steps shown in green (completed)
• Future steps shown in gray (pending)
• Tap to expand and view all steps

Validation and Visibility​

Screen-based Validation​

Configure different behaviors for each screen:

Available​

• Type: Boolean
• Description: Controls if the widget is available on the screen
• Default: True

Visible​

• Type: Boolean or Expression
• Description: Controls widget visibility
• Options:
  • Simple boolean toggle
  • Advanced expression using variables

Required​

• Type: Boolean or Expression
• Description: Makes the widget required for form submission
• Default: False

Disable​

• Type: Boolean or Expression
• Description: Disables widget interaction
• Default: False

Advanced Conditions​

Use JavaScript expressions with model variables:

// Example visibility condition
{{user.role}} === 'admin' && {{form.step}} > 2

// Example required condition
{{process.status}} === 'pending'

Styling and Appearance​

CSS Classes​

• Field: Class
• Description: Add custom CSS classes for styling
• Type: Text input
• Usage: Space-separated class names

Dynamic Classes​

Configure conditional CSS classes based on data:

{
  "completed": "{{currentStep}} > 3",
  "error": "{{hasError}}",
  "highlight": "{{isImportant}}"
}

Width and Height​

• Width: Set custom width (e.g., "100%", "300px")
• Height: Set custom height (e.g., "auto", "200px")

Methods and Interactions​

Available Methods​

clearValue()​

Resets the current step to 0

this.$refs.stepWidget.clearValue();

setValue(value)​

Sets the current step to a specific index

this.$refs.stepWidget.setValue(2); // Set to step 3 (0-based)

Event Handling​

onClick Action​

Configure custom actions when steps are clicked:

• Field: On click
• Type: JavaScript expression
• Context: Access to step data and widget state

Data Binding Examples​

Static Configuration​

// Static steps configuration
{
  "options": [
    {
      "title": "Start Process",
      "description": "Initialize the workflow"
    },
    {
      "title": "Review Data",
      "description": "Validate input information"
    },
    {
      "title": "Complete",
      "description": "Finalize the process"
    }
  ]
}

Variable Configuration​

// Variable data structure
[
  {
    "name": "Setup",
    "info": "Initial configuration",
    "status": "completed"
  },
  {
    "name": "Processing",
    "info": "Data processing phase",
    "status": "current"
  },
  {
    "name": "Finished",
    "info": "Process completed",
    "status": "pending"
  }
]

// Label configuration: $.name
// Value configuration: $.info + ' (' + $.status + ')'

Integration Examples​

Form Integration​

// Update step based on form progress
function updateStep() {
  if (isFormValid()) {
    stepWidget.setValue(currentStep + 1);
  }
}

Workflow Integration​

// Sync with workflow status
function syncWithWorkflow(workflowData) {
  const currentStepIndex = workflowData.currentStep;
  stepWidget.setValue(currentStepIndex);
}

Best Practices​

Design Guidelines​

1. Keep titles concise: Use short, descriptive titles
2. Provide helpful descriptions: Add context without overwhelming
3. Choose appropriate direction: Horizontal for wide layouts, vertical for narrow
4. Consider mobile experience: Test accordion behavior on small screens

Performance​

1. Limit step count: Avoid too many steps (recommended max: 7-10)
2. Optimize dynamic data: Use efficient data structures for variable sources
3. Cache static data: Pre-configure static steps when possible

Accessibility​

1. Use semantic titles: Ensure screen readers can interpret steps
2. Provide clear descriptions: Help users understand each step's purpose
3. Test keyboard navigation: Ensure accessibility compliance

Troubleshooting​

Common Issues​

Steps not displaying​

• Check data source configuration
• Verify model variable binding
• Ensure data structure matches expected format

Responsive layout problems​

• Test on different screen sizes
• Verify CSS classes don't conflict
• Check container width constraints

Data not updating​

• Verify model binding syntax
• Check for JavaScript errors in expressions
• Ensure data source is properly connected

Debug Tips​

1. Use browser developer tools to inspect widget state
2. Check console for JavaScript errors
3. Verify data structure in network tab
4. Test with simplified configuration first

API Reference​

Component Properties​

• prop: Widget properties
• comp_model: Data model
• comp_management: Management state
• models: Available models
• management: Management configuration
• visible: Visibility state
• required: Required state
• disable: Disabled state
• class_config: CSS class configuration

Widget Options​

• direction: Layout direction
• classNames: CSS classes
• defaultValue: Initial step
• remote: Data source type
• options: Static step data
• props.label: Label property path
• props.value: Value property path
• isSimple: Simple design mode