Skip to main content

Timer Widget Documentation

Overview​

The Timer widget provides a comprehensive time tracking solution that can count up or count down from a specified duration. It displays time in HH:MM:SS format and includes functionality for starting, stopping, and tracking both active running time and break time periods.

Features​

  • Bidirectional Counting: Support for both count-up and count-down modes
  • Break Time Tracking: Automatically tracks break periods when timer is stopped
  • Visual Time Display: Shows time in readable HH:MM:SS format
  • Overflow Indicators: Shows (+) for overtime in count-up mode and (-) for negative time in count-down mode
  • Real-time Updates: Updates every second when active
  • Persistent State: Maintains timer state across page interactions

Configuration Options​

Basic Configuration​

Widget Identity​

  • Name: Display name for the widget
  • Variable/Model: The data model name that stores the timer values

Timer Settings​

Count Type​

Choose how the timer should behave:

  • Up: Timer counts upward from 00:00:00

    • Displays (+) prefix when exceeding the set duration
    • Useful for tracking elapsed time with optional time limits

  • Down: Timer counts downward from the set duration

    • Displays (-) prefix when going below zero
    • Useful for countdown timers and deadline tracking
Duration​
  • Input: Number of seconds for the timer duration
  • Purpose:
    • For count-up mode: Sets the target/limit time
    • For count-down mode: Sets the starting countdown value
  • Format: Enter value in seconds (e.g., 3600 for 1 hour)

Validation Settings​

The timer widget supports comprehensive validation rules across different screens:

Screen-based Validation​

Configure different behaviors for each screen in your application:

  • Available: Whether the widget appears on the screen
  • Visible: Whether the widget is visible (supports dynamic conditions)
  • Required: Whether interaction with the timer is mandatory
  • Disable: Whether the timer controls are disabled

Advanced Validation​

  • Dynamic Conditions: Use JavaScript expressions with model variables
  • Example: {{userRole}} === 'admin' to show timer only for admin users

Styling Options​

Layout​

  • Width: Set custom width for the timer display
  • Class Names: Add custom CSS classes for styling
  • Dynamic Classes: JavaScript expressions for conditional styling

Appearance​

  • Placeholder: Not applicable for timer widget
  • Border: Enable/disable border around the timer
  • Inline Layout: Display timer inline with other elements

Rules and Validation​

Custom Validation Rules​

Add validation rules to ensure proper timer usage:

  • Required: Make timer interaction mandatory
  • Custom Rules: JavaScript-based validation functions
  • Error Messages: Custom error messages for validation failures

Usage Instructions​

Basic Setup​

  1. Add Timer Widget: Drag the Timer widget to your interface
  2. Set Model Name: Choose a unique variable name (e.g., workTimer)
  3. Configure Count Type: Select "Up" or "Down" based on your needs
  4. Set Duration: Enter the duration in seconds

Count-Up Timer Example​

Configuration:

  • Count Type: Up
  • Duration: 3600 (1 hour)
  • Model: workSession

Behavior:

  • Starts at 00:00:00
  • Counts upward: 00:00:01, 00:00:02, etc.
  • Shows "(+) 01:00:01" when exceeding 1 hour

Count-Down Timer Example​

Configuration:

  • Count Type: Down
  • Duration: 1800 (30 minutes)
  • Model: breakTimer

Behavior:

  • Starts at 00:30:00
  • Counts downward: 00:29:59, 00:29:58, etc.
  • Shows "(-) 00:00:01" when going below zero

Timer Controls​

The timer widget provides the following methods that can be called programmatically:

  • startTimer(): Begins or resumes the timer
  • stopTimer(): Pauses the timer and begins break time tracking

Data Model​

Generated Variables​

When you create a timer with model name timerName, the system automatically creates:

Primary Variables​

  • timerName: Formatted time string (HH:MM:SS format)
  • timerName_runTime: Total running time in seconds
  • timerName_breakTime: Total break time in seconds

Usage in Other Components​

Access timer data in other widgets or actions:

// Get formatted time
let currentTime = {{timerName}};

// Get raw running time in seconds
let runSeconds = {{timerName_runTime}};

// Calculate net working time (run time minus breaks)
let netTime = {{timerName_runTime}} - {{timerName_breakTime}};

Advanced Features​

Break Time Management​

The timer automatically tracks break periods:

  • When stopTimer() is called, break time tracking begins
  • Break time continues until startTimer() is called again
  • Both run time and break time increment during break periods

Time Calculation Logic​

Count-Up Mode​

time = runTime - breakTime;
if (duration && time > duration) {
    prefix = '(+) ';
}

Count-Down Mode​

time = duration - (runTime - breakTime);
if (time < 0) {
    time = Math.abs(time);
    prefix = '(-) ';
}

Integration with Forms​

The timer integrates seamlessly with form validation:

  • Can be marked as required field
  • Supports form submission with timer data
  • Validates timer state before form processing

Event Handling​

onClick Events​

Configure actions to trigger when the timer display is clicked:

  • Navigate to detailed time tracking page
  • Show timer statistics
  • Export time data

Form Integration​

The timer automatically updates form data when:

  • Timer starts or stops
  • Time values change
  • Form is submitted

Best Practices​

Performance Optimization​

  • Use appropriate duration values (avoid extremely large numbers)
  • Consider impact of multiple timers on page performance
  • Implement proper cleanup when timers are not needed

User Experience​

  • Provide clear visual indicators for timer state
  • Use appropriate count type for the use case
  • Include instructions for users on how to operate the timer

Data Management​

  • Regularly save timer data to prevent loss
  • Consider server-side synchronization for important timing data
  • Implement backup mechanisms for critical time tracking

Troubleshooting​

Common Issues​

Timer Not Starting​

  • Check if widget is enabled and visible
  • Verify JavaScript console for errors
  • Ensure proper model name configuration

Incorrect Time Display​

  • Verify duration is set in seconds
  • Check count type matches intended behavior
  • Validate time calculation logic

Performance Issues​

  • Limit number of active timers per page
  • Check for memory leaks in interval management
  • Monitor browser performance with developer tools

Browser Compatibility​

  • Supports all modern browsers
  • Uses standard JavaScript timing functions
  • Responsive design works on mobile devices

Technical Implementation​

Dependencies​

  • Vue.js framework
  • Element UI components
  • Standard JavaScript timing functions

Browser Requirements​

  • Modern browser with JavaScript enabled
  • Support for setInterval/clearInterval functions
  • CSS3 support for styling

Security Considerations​

  • Timer data should be validated on server side
  • Consider rate limiting for timer operations
  • Implement proper session management for persistent timers