# Module - Cool Clock Documentation
- Extension Page: [Module - CoolClock](/software/joomla/modules/module-coolclock)
## Quick Start
**Get a clock running in under 2 minutes:**
1. Install mod\_coolclock through Joomla's extension manager
2. Create a new module: Extensions → Modules → New → CoolClock
3. Select a skin from the dropdown (default: swissRail)
4. Assign to a module position
5. 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](#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](#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)
## 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:
1. Make changes using visual controls to generate base JSON
2. Copy JSON from the Custom Skin textarea
3. Modify values directly (colors, positions, alpha values)
4. Paste back into Custom Skin textarea
5. 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:
1. Create or source a decorative clock face image (circular, 400x400px recommended)
2. Set logo type to URL or SVG
3. Set width and height to cover entire clock (e.g., 200,200)
4. Position at center: "0,0"
5. Use transparent or semi-transparent background
6. 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:
1. Module makes AJAX request to your Joomla server
2. Extracts `Date` header from HTTP response
3. Calculates offset between server time and browser time
4. Applies offset to all time calculations
5. 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:**
1. Create one clock module per timezone
2. Configure each with appropriate timezone (New York, London, Dubai, Tokyo)
3. Use text logo to label each clock with city name
4. Position: "0,-50" to place city name above clock center
5. 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:**
1. Use Custom Skin Editor to match brand colors
2. Add company logo using Logo feature
3. Position logo at top of clock face: "0,-60"
4. For subtle branding, use semi-transparent logo (alpha: 0.6)
5. 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:**
1. Design custom clock face in graphics software (PNG with transparency)
2. Upload to server: `/images/clockfaces/custom-design.png`
3. Create clock with `minimal` skin (provides clean hands without distracting face elements)
4. Add URL logo pointing to your custom face image
5. Scale logo to cover clock area: width/height = 180-200% of radius
6. Position at center: "0,0"
7. 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:**
1. Enable NTP Sync for accuracy
2. Position clock prominently near booking form
3. Use timezone matching booking system's configured timezone
4. Consider `luxury` or `dark` skin for sophistication
5. 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:**
1. Verify canvas element rendered: Right-click → Inspect, look for `