Module - Cool Clock Documentation

Extension Page: Module - CoolClock

Quick Start

Get a clock running in under 2 minutes:

Install mod_coolclock through Joomla's extension manager
Create a new module: Extensions → Modules → New → CoolClock
Select a skin from the dropdown (default: swissRail)
Assign to a module position
Save and view your site

That's it. You now have a fully functional analog clock.

Basic Configuration

Basic Tab

The Basic tab provides core clock functionality with real-time preview:

Skin Selection

Choose from 27 pre-built skins or create your own custom skin
Preview updates immediately as you select different skins
See Skin Gallery for visual examples

Display Options

Show Second Hand

Toggle the second hand on/off
Default: Enabled
Useful for minimalist displays or reduced animation

Show AM/PM

Display AM/PM indicator within the clock face
Default: Disabled
Position: Below center, unobtrusive design
Particularly useful for 12-hour time display contexts

Smooth Second Hand

Enable smooth sweep motion vs. tick motion
Default: Enabled
Smooth motion uses requestAnimationFrame for 60fps animation
Disable for classic clock behavior

Time Settings

Timezone

Select any global timezone
Default: Site default timezone
Server converts timezone to GMT offset automatically
Essential for multi-timezone displays

NTP Sync

Enable network time synchronization
Default: Disabled
Ensures clock accuracy by syncing with server time
See NTP Time Synchronization for details

Skin Gallery

mod_coolclock includes 27 professionally designed skins across three categories:

Classic Skins (Original CoolClock)

swissRail (default) Clean, minimalist design inspired by Swiss railway clocks. Black hands, red second hand, simple tick marks.

chunkySwiss Bold version of swissRail with thicker hands and more prominent markers.

chunkySwissOnBlack High-contrast version with white elements on black background.

fancy Ornate design with decorative elements and styled numerals.

machine Industrial aesthetic with mechanical-inspired details.

Community Skins

classic (bonstio.net) Traditional analog clock design with Roman numerals.

modern (bonstio.net) Contemporary minimalist approach with geometric precision.

simple (bonstio.net) Ultra-minimal design, perfect for professional sites.

securephp (securephp) Security-themed design with unique color palette.

Tes2 (securephp) Alternative security-inspired aesthetic.

Lev, Sand, Sun, Tor, Cold, Babosa, Tumb, Stone, Disc Community-contributed designs offering diverse visual styles.

New Modern Skins

minimal Ultra-clean design with subtle gray accents. White face, thin markers, red second hand. Perfect for modern web design.

dark Dark mode optimized. Black face (#1a1a1a), white hands, cyan second hand. Ideal for dark-themed sites.

neon Cyberpunk aesthetic. Black background with magenta/cyan neon colors. High visual impact.

ocean Calming blue theme. Light blue face with navy accents. Professional yet distinctive.

sunset Warm orange/amber palette. Cream background with sunset-inspired colors. Inviting and energetic.

forest Natural green theme. Soft background with deep forest greens. Organic and grounded.

luxury Premium gold aesthetic. Black background with gold accents. Elegant and sophisticated.

retro Vintage-inspired design. Cream background with burnt orange and warm browns. Nostalgic appeal.

customSkin Build your own - see Custom Skin Editor

Custom Skin Editor

The Custom Skin Editor provides visual, real-time customization of every clock element.

Access

Navigate to the Custom tab in module configuration. You'll see:

Live preview canvas (second hand and AM/PM always enabled)
Visual controls for all clock elements
Direct JSON editing for advanced users

Customizable Elements

Face Background

Enable/disable background fill
Color picker for background color
Opacity slider (0.0 - 1.0)
Creates solid or semi-transparent clock face

Face Border

Enable/disable outer border
Color selection
Border width (0-10 pixels)
Border radius (0-100, affects roundness)
Opacity control
Use radius to create circular or square clock faces

Hour Markers

Enable/disable tick marks
Single color for all markers
Small marker width (1-8 pixels) - used for minute marks
Large marker width (1-12 pixels) - used for hour marks
Start position (radius percentage)
End position (radius percentage)
Customize marker length by adjusting start/end values

Hour Hand

Color selection
Line width (1-10 pixels)
Hand length (0-95% of radius)
Tail length (0-30% behind center)
Longer tails create balanced, traditional look

Minute Hand

Independent color control
Line width (1-10 pixels)
Length (0-95% of radius)
Tail length (0-30% behind center)
Typically longer than hour hand

Second Hand

Color selection (often red for visibility)
Line width (1-10 pixels)
Length (0-95% of radius)
Tail length (0-30% behind center)
Can extend past minute hand for classic look

Center Dot

Enable/disable center decoration
Color selection
Radius (0-10 pixels)
Covers hand pivot point for clean appearance

Advanced JSON Editing

For precise control, directly edit the JSON configuration:

Make changes using visual controls to generate base JSON
Copy JSON from the Custom Skin textarea
Modify values directly (colors, positions, alpha values)
Paste back into Custom Skin textarea
Save module to apply changes

Note: Any changes to visual controls will regenerate JSON, overwriting manual edits. Make visual changes first, then fine-tune in JSON as a final step.

Example Custom Skin JSON:

json

{
  "face": {
    "radius": 100,
    "fillColor": "#ffffff",
    "alpha": 1
  },
  "outerBorder": {
    "lineWidth": 2,
    "radius": 95,
    "color": "#000000",
    "alpha": 1
  },
  "hourHand": {
    "lineWidth": 6,
    "startAt": -10,
    "endAt": 50,
    "color": "#333333",
    "alpha": 1,
    "lineCap": "round"
  }
}

Logo Embedding

Add text, images, or SVG graphics to your clock face for branding, timezone labels, or decorative purposes.

Access

Navigate to the Logo tab in module configuration.

Logo Types

Text Logo Perfect for timezone labels, company names, or location identifiers.

Text: Enter any text content
Font Size: 1-100 pixels
Color: Color picker for text color
Font Family: Any web-safe or loaded font (e.g., Arial, Georgia, custom fonts)
Font Weight: Normal, Bold, Bolder, Lighter
Position: X,Y coordinates relative to center (e.g., "0,-50")

URL Image Load images from local server or remote URLs.

Image Source: Full URL to image file
- Local: /images/logos/company-logo.png
- Remote: https://example.com/logo.png
- Data URLs supported: data:image/png;base64,...
Width: Image width as percentage of clock radius (1-100)
Height: Image height as percentage of clock radius (1-100)
Position: X,Y coordinates relative to center

SVG Graphics Paste SVG markup directly for scalable, resolution-independent graphics.

SVG Content: Paste complete SVG markup
Width: Display width as percentage of clock radius (1-100)
Height: Display height as percentage of clock radius (1-100)
Position: X,Y coordinates relative to center

Positioning

Logo position uses X,Y coordinates relative to the clock center:

0,0 = Center of clock
0,-50 = Above center (common for timezone labels)
0,50 = Below center
-40,0 = Left of center
40,0 = Right of center

Experiment with values to achieve desired placement. Preview updates in real-time.

Advanced Technique: Custom Clock Faces

Use image or SVG logos scaled to clock size to create elaborate custom clock faces:

Create or source a decorative clock face image (circular, 400x400px recommended)
Set logo type to URL or SVG
Set width and height to cover entire clock (e.g., 200,200)
Position at center: "0,0"
Use transparent or semi-transparent background
Layer behind hands using alpha/opacity

This technique allows unlimited visual customization while maintaining functional clock hands.

NTP Time Synchronization

Ensures clock accuracy by synchronizing with server time rather than relying on visitor's local system clock.

How It Works

When NTP Sync is enabled:

Module makes AJAX request to your Joomla server
Extracts Date header from HTTP response
Calculates offset between server time and browser time
Applies offset to all time calculations
Sets cookie to prevent repeated requests (reduces server load)

No external dependencies. No third-party NTP services. No API keys. Just your server's time.

When to Enable

Essential for:

Financial applications (accurate timestamps)
Booking systems (prevent timezone confusion)
Auction sites (precise countdown synchronization)
Multi-timezone corporate sites (consistent time display)
Any situation where accuracy matters

Less critical for:

Decorative clocks
Personal blogs
Non-time-sensitive content

Server Requirements

Your server must be NTP synchronized for this feature to provide accurate time. Most hosting providers sync servers automatically, but verify with your host if accuracy is critical.

Performance

Cookie-based caching means time sync occurs once per visitor session, not on every page load. Performance impact is negligible.

Advanced Use Cases

Multi-Timezone Display

Scenario: Display current time at multiple office locations.

Implementation:

Create one clock module per timezone
Configure each with appropriate timezone (New York, London, Dubai, Tokyo)
Use text logo to label each clock with city name
Position: "0,-50" to place city name above clock center
Assign all modules to same position or create custom layout

Result: Visitors instantly see current time at all your locations.

Styling tip: Use consistent skin across all clocks for cohesive appearance. Consider modern or minimal for professional multi-timezone displays.

Corporate Branding

Scenario: Match clock to corporate brand identity.

Implementation:

Use Custom Skin Editor to match brand colors
Add company logo using Logo feature
Position logo at top of clock face: "0,-60"
For subtle branding, use semi-transparent logo (alpha: 0.6)
Enable smooth second hand for premium feel

Result: Branded timekeeping element that reinforces company identity.

Decorative Clock Faces

Scenario: Create unique, artistic clock displays.

Implementation:

Design custom clock face in graphics software (PNG with transparency)
Upload to server: /images/clockfaces/custom-design.png
Create clock with minimal skin (provides clean hands without distracting face elements)
Add URL logo pointing to your custom face image
Scale logo to cover clock area: width/height = 180-200% of radius
Position at center: "0,0"
Fine-tune hand colors to complement custom face

Result: Unlimited creative possibilities while maintaining functional analog clock.

Booking System Integration

Scenario: Show current time to prevent booking confusion.

Implementation:

Enable NTP Sync for accuracy
Position clock prominently near booking form
Use timezone matching booking system's configured timezone
Consider luxury or dark skin for sophistication
Add text logo indicating timezone: "EST" or "UTC"

Result: Users see accurate time in booking timezone, reducing errors and support requests.

Technical Reference

Browser Compatibility

Supported Browsers:

Chrome/Edge 90+
Firefox 88+
Safari 14+
Opera 76+

Technologies Used:

Canvas API (HTML5)
RequestAnimationFrame
IntersectionObserver (for performance)
ResizeObserver (for responsive sizing)

Performance Features

Intelligent Rendering Clock automatically pauses when not visible (using IntersectionObserver). Resumes when scrolled into view. Eliminates unnecessary rendering cycles.

Responsive Sizing Automatic DPI scaling for retina displays. Canvas resolution adjusts based on device pixel ratio for crisp rendering.

Smooth Animation Uses requestAnimationFrame for 60fps second hand animation when smooth mode enabled. Browser-optimized timing prevents jank.

Parameter Reference

Basic Parameters:

skin (string): Selected skin name or 'customSkin'
showSecondHand (boolean): Display second hand
showAMPM (boolean): Display AM/PM indicator
gmtOffset (float): Timezone offset in hours
smoothSecondHand (boolean): Enable smooth sweep animation
useNTP (boolean): Enable time synchronization

Custom Skin Parameters: All custom skin builder values stored in customSkin JSON parameter.

Logo Parameters:

logoType (string): 'text', 'url', 'svg', or empty
Logo-specific parameters based on type
All values stored in logo JSON parameter

Joomla Version Support

Fully Compatible:

Joomla 6.x
Joomla 5.x
Joomla 4.x
Joomla 3.x

Uses namespace-based architecture for Joomla 4+ while maintaining backward compatibility with Joomla 3.

Troubleshooting

Clock Not Displaying

Symptom: Module position shows but no clock appears

Solutions:

Verify canvas element rendered: Right-click → Inspect, look for <canvas> tag
Check browser console for JavaScript errors
Ensure module is published and assigned to visible position
Clear Joomla cache: System → Clear Cache
Verify JavaScript loaded: View page source, search for modernclock.js

Time Incorrect

Symptom: Clock shows wrong time

Solutions:

Check Joomla site timezone: System → Global Configuration → Server → Server Time Zone
Verify selected timezone in module configuration
If NTP enabled, check server time is correct: Contact hosting provider
Clear browser cookies (NTP sync cached in cookie)
Disable NTP temporarily to use visitor's local time

Custom Skin Not Saving

Symptom: Changes to custom skin don't persist

Solutions:

Ensure "customSkin" selected in Basic tab
Verify JSON is valid (check for syntax errors)
Save module after making custom skin changes
Clear Joomla cache after saving
Check browser console for JavaScript errors during save

Logo Not Appearing

Symptom: Logo configured but not visible on clock

Solutions:

Verify logo type selected (not empty)
For URL logos: Check image path is accessible (try opening in browser)
For SVG logos: Validate SVG markup (paste into text editor, look for errors)
Check logo position - may be outside visible area (try "0,0")
Verify logo dimensions - may be too small (increase width/height)
For remote URLs: Ensure CORS allows image loading

Performance Issues

Symptom: Clock causes lag or high CPU usage

Solutions:

Disable smooth second hand (reduces animation overhead)
Verify only one instance per page (multiple clocks multiply rendering)
Check if clock is in visible viewport (should auto-pause when hidden)
Update to latest browser version
Test in different browser to isolate browser-specific issues

Admin Preview Not Updating

Symptom: Changes in admin don't show in preview canvas

Solutions:

Hard refresh browser: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Clear browser cache
Check browser console for JavaScript errors
Ensure admin.js loaded properly
Try different browser to rule out browser-specific issues

NTP Sync Not Working

Symptom: Clock still shows incorrect time with NTP enabled

Solutions:

Verify server has accurate time (contact hosting provider)
Check AJAX requests successful: Open browser dev tools → Network tab
Clear cookies (NTP offset cached)
Ensure server allows Date header access
Check for JavaScript errors in console during sync

Support & Resources

Documentation: This file
Updates: Check Joomla Extension Directory for latest version
Issues: Report through RicheyWeb support channels

Tips for Best Results:

Test configuration changes in admin preview before saving
Use NTP sync for time-critical applications
Match skin to site design for cohesive appearance
Leverage logo feature for multi-timezone displays
Custom skin editor provides unlimited creative control

Documentation