Steps Widget Documentation

Overview​

The Steps widget displays a step-by-step progress indicator that shows the current position in a multi-step process. It provides a visual representation of progress through a sequence of tasks or stages, making it ideal for wizards, forms, or any workflow that requires step-by-step navigation.

Basic Configuration​

Global Settings​

Name​

• Field: Name
• Description: Display name for the widget in the interface builder
• Type: Text input
• Required: Yes

Variable/Model​

• Field: Variable/Model
• Description: The variable name that will store the current active step number (0-based index)
• Type: Text input
• Required: Yes
• Example: currentStep

Default Value​

• Field: Default Value
• Description: The initial step to display when the widget loads
• Type: Number
• Default: 0
• Example: Set to 1 to start on the second step

Steps Configuration​

Direction​

• Field: Direction
• Description: Controls the layout orientation of the steps
• Type: Dropdown selection
• Options:
  • horizontal: Steps are displayed in a horizontal line
  • vertical: Steps are stacked vertically
• Default: horizontal

Simple Design​

• Field: Simple Design
• Description: Enable a simplified visual style for the steps
• Type: Toggle switch
• Default: false
• Effect: Removes extra visual elements for a cleaner appearance

Data Source Configuration​

The Steps widget supports two data source types:

Static Data Source​

When using static data, steps are predefined in the widget configuration.

Configuration Steps:​

1. In the Data Source section, select Static
2. Add step items with the following properties:
   • Title: The main text displayed for each step
   • Description: Optional descriptive text shown below the title

Example Static Configuration:​

// Static steps configuration
[
  {
    title: "Personal Information",
    description: "Enter your basic details"
  },
  {
    title: "Contact Details", 
    description: "Provide contact information"
  },
  {
    title: "Review & Submit",
    description: "Verify and submit your application"
  }
]

Variable Data Source​

When using variable data, steps are loaded dynamically from a data array.

Configuration Steps:​

1. In the Data Source section, select Variable
2. Configure the Label and Value properties:
   • Label: Field name for the step title (supports dynamic expressions)
   • Value: Field name for the step description (supports dynamic expressions)

Dynamic Expression Examples:​

• Static field reference: title (uses the 'title' field from each step object)
• Dynamic expression: $.name + ' - ' + $.status (combines multiple fields)

Variable Data Structure:​

// Example data structure for variable steps
steps_vb = [
  {
    name: "Setup",
    status: "Complete",
    description: "Initial configuration"
  },
  {
    name: "Process",
    status: "In Progress", 
    description: "Processing data"
  },
  {
    name: "Finish",
    status: "Pending",
    description: "Final verification"
  }
]

Responsive Behavior​

The Steps widget automatically adapts to different screen sizes:

Desktop/Tablet View (sm and up)​

• Displays the full steps component with all styling
• Shows steps according to the configured direction
• Full title and description visibility

Mobile View (xs only)​

• Transforms into a collapsible dropdown-style interface
• Shows current step prominently with title and description
• Previous steps shown in green (completed)
• Future steps shown in gray (pending)
• Interactive expansion for better mobile experience

Interaction Methods​

JavaScript Methods​

The widget provides several methods for programmatic control:

clearValue()​

Resets the current step to 0

// Reset to first step
this.$refs.stepWidget.clearValue();

setValue(value)​

Sets the current active step

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

Validation Configuration​

Screen-Based Validation​

Configure visibility and behavior across different interface screens:

Available​

• Controls whether the widget is available on specific screens
• Type: Boolean toggle per screen

Visible​

• Controls widget visibility with support for dynamic conditions
• Type: Boolean toggle or JavaScript expression
• Dynamic Example: {{user.role}} === 'admin'

Required​

• Makes the widget required for form validation
• Type: Boolean toggle or JavaScript expression

Disable​

• Disables user interaction with the widget
• Type: Boolean toggle or JavaScript expression

Advanced Validation Conditions​

Use JavaScript expressions for complex validation logic:

// Show only if user has completed previous sections
{{user.profileComplete}} && {{user.contactComplete}}

// Require only for certain user types
{{user.type}} === 'premium'

Styling Configuration​

Layout Options​

• Width: Set custom width (supports CSS units)
• Height: Set custom height (supports CSS units)
• Class: Add custom CSS classes for styling

Dynamic Classes​

Configure conditional CSS classes based on data:

{
  "completed": "{{currentStep}} > 2",
  "error": "{{hasErrors}}",
  "highlight": "{{isImportant}}"
}

On Click Actions​

Configure custom JavaScript to execute when steps are interacted with:

Basic Action Example:​

// Navigate to specific step
this.currentStep = 2;

Advanced Action Example:​

// Validate current step before allowing navigation
if (this.validateCurrentStep()) {
  this.currentStep = SF_input.value;
  this.saveProgress();
} else {
  this.$message.error('Please complete current step');
}

Best Practices​

Design Guidelines​

1. Keep step titles concise - Use short, descriptive names
2. Provide clear descriptions - Help users understand what each step involves
3. Logical progression - Ensure steps follow a natural workflow
4. Consistent styling - Use the same visual approach throughout your interface

Accessibility Considerations​

1. Meaningful labels - Ensure screen readers can understand step purposes
2. Keyboard navigation - Test navigation without mouse interaction
3. Color contrast - Ensure sufficient contrast for all users
4. Progress indication - Clearly show current position and total steps

Performance Tips​

1. Static vs Variable - Use static data when steps don't change
2. Minimal data - Keep step objects lightweight for better performance
3. Lazy loading - For many steps, consider paginated loading

Common Use Cases​

Form Wizard​

// Multi-step form with validation
steps = [
  { title: "Personal Info", description: "Basic details" },
  { title: "Address", description: "Contact information" }, 
  { title: "Payment", description: "Billing details" },
  { title: "Confirmation", description: "Review and submit" }
]

Process Tracking​

// Order or application status tracking
steps = [
  { title: "Submitted", description: "Application received" },
  { title: "Review", description: "Under evaluation" },
  { title: "Approved", description: "Decision made" },
  { title: "Complete", description: "Process finished" }
]

Onboarding Flow​

// User onboarding process
steps = [
  { title: "Welcome", description: "Getting started" },
  { title: "Setup Profile", description: "Personal information" },
  { title: "Preferences", description: "Customize experience" },
  { title: "Ready", description: "Start using the platform" }
]

Integration Examples​

With Form Validation​

// Validate before step progression
if (this.validateStep(this.currentStep)) {
  this.currentStep++;
} else {
  this.$message.error('Please complete required fields');
}

With Data Loading​

// Load step-specific data
watch: {
  currentStep(newStep) {
    this.loadStepData(newStep);
  }
}

With Navigation Guards​

// Prevent navigation if conditions not met
beforeStepChange(from, to) {
  if (!this.isStepComplete(from)) {
    return false;
  }
  return true;
}

Troubleshooting​

Common Issues​

Steps not displaying correctly

• Check data source configuration
• Verify variable names match data structure
• Ensure proper label/value field mapping

Mobile view not working

• Verify responsive CSS is not overridden
• Check container width constraints
• Test on actual mobile devices

Step progression not working

• Confirm variable/model binding is correct
• Check JavaScript console for errors
• Verify setValue method calls

Styling issues

• Review custom CSS class conflicts
• Check theme compatibility
• Validate CSS syntax in custom classes

Debug Tips​

1. Use browser developer tools to inspect generated HTML
2. Check console for JavaScript errors
3. Verify data binding in Vue DevTools
4. Test with minimal configuration first