ClickTracker Documentation

Overview

The ClickTracker component provides a seamless way to intercept mouse click coordinates on any specific UI element. It bridges the gap between standard browser click events and OutSystems logic, offering high-precision decimal values.

🔧 Technical Implementation

1. The Logic Flow

The component uses a JavaScript Event Listener attached to the target DOM element.

1. The OnReady event initializes the listener.
2. The JavaScript Tool calculates coordinates using getBoundingClientRect() to ensure sub-pixel accuracy.
3. A Private Client Action acts as a bridge, receiving data from JS and triggering the Public Event OnClicked.
4. The OnDestroy event cleans up the listener to ensure zero memory impact.

2. Parameters & Properties

Input Parameters

• TargetElementId(Text, Mandatory): The unique runtime ID of the widget you want to track.
  • Usage: Pass MyWidget.Id.
• IsRelative(Boolean):
  • True: Coordinates are calculated relative to the top-left corner of the target element (0,0 is the element's origin).
  • False: Coordinates are relative to the browser's viewport.

Events

• OnClicked: Triggered every time a user clicks inside the target area.
  • X (Decimal): The horizontal coordinate.
  • Y (Decimal): The vertical coordinate.

💡 Implementation Guide (Step-by-Step)

Standard Setup

1. Name your target widget (e.g., ImageContainer).
2. Place the ClickTracker block on your screen.
3. Bind TargetElementId to ImageContainer.Id.
4. Create a handler for the OnClicked event.
5. In the handler, use the X and Y decimals to update your application state.

Dynamic Elements

If your target element is inside a List or Block, ensure you are passing the correct Id for that specific instance. The component is designed to be instantiated multiple times on the same page without conflicts.

⚠️ Troubleshooting & FAQ

Q: The coordinates are always 0 or it's not triggering.

• Check ID: Ensure you are passing WidgetName.Id and not just a hardcoded string like "WidgetName".
• Z-Index: Ensure no other transparent element is "covering" your target, preventing the click from reaching it.
• Container Size: Verify if your container has a defined height. Empty containers often collapse to 0px height.

Q: Why use Decimal instead of Integer?

• Modern browsers and High-DPI (Retina) screens report mouse positions in fractions of pixels. Using Decimal prevents "jumpy" behavior when positioning elements like pins or tooltips based on the click.

Q: Does it work on Mobile?

• Yes. While it listens for click events, mobile browsers typically map a "tap" to a click event. For specific multi-touch requirements, a future update may include touchstart support.

🗑️ Cleanup and Performance

The component automatically manages its lifecycle. When the screen changes or the block is removed from the DOM via an If widget, the JavaScript listener is explicitly removed using removeEventListener to prevent Memory Leaks.

ClickTracker Documentation

Overview

The ClickTracker component provides a seamless way to intercept mouse click coordinates on any specific UI element. It bridges the gap between standard browser click events and OutSystems logic, offering high-precision decimal values.

🔧 Technical Implementation

1. The Logic Flow

The component uses a JavaScript Event Listener attached to the target DOM element.

1. The OnReady event initializes the listener.
2. The JavaScript Tool calculates coordinates using getBoundingClientRect() to ensure sub-pixel accuracy.
3. A Private Client Action acts as a bridge, receiving data from JS and triggering the Public Event OnClicked.
4. The OnDestroy event cleans up the listener to ensure zero memory impact.

2. Parameters & Properties

Input Parameters

• TargetElementId (Text, Mandatory): The unique runtime ID of the widget you want to track.
  • Usage: Pass MyWidget.Id.
• IsRelative (Boolean):
  • True: Coordinates are calculated relative to the top-left corner of the target element (0,0 is the element's origin).
  • False: Coordinates are relative to the browser's viewport.

Events

• OnClicked: Triggered every time a user clicks inside the target area.
  • X (Decimal): The horizontal coordinate.
  • Y (Decimal): The vertical coordinate.

💡 Implementation Guide (Step-by-Step)

Standard Setup

1. Name your target widget (e.g., ImageContainer).
2. Place the ClickTracker block on your screen.
3. Bind TargetElementId to ImageContainer.Id.
4. Create a handler for the OnClicked event.
5. In the handler, use the X and Y decimals to update your application state.

Dynamic Elements

If your target element is inside a List or Block, ensure you are passing the correct Id for that specific instance. The component is designed to be instantiated multiple times on the same page without conflicts.

⚠️ Troubleshooting & FAQ

Q: The coordinates are always 0 or it's not triggering.

• Check ID: Ensure you are passing WidgetName.Id and not just a hardcoded string like "WidgetName".
• Z-Index: Ensure no other transparent element is "covering" your target, preventing the click from reaching it.
• Container Size: Verify if your container has a defined height. Empty containers often collapse to 0px height.

Q: Why use Decimal instead of Integer?

• Modern browsers and High-DPI (Retina) screens report mouse positions in fractions of pixels. Using Decimal prevents "jumpy" behavior when positioning elements like pins or tooltips based on the click.

Q: Does it work on Mobile?

• Yes. While it listens for click events, mobile browsers typically map a "tap" to a click event. For specific multi-touch requirements, a future update may include touchstart support.

🗑️ Cleanup and Performance

The component automatically manages its lifecycle. When the screen changes or the block is removed from the DOM via an If widget, the JavaScript listener is explicitly removed using removeEventListener to prevent Memory Leaks.