Tagger
The tagger is a utility for generating HTML data attributes that the walkerOS browser source uses for event tracking. It provides a fluent interface to create properly formatted and escaped data attributes for your HTML elements.
Why Use the Tagger?
The tagger solves several challenges when working with walkerOS data attributes:
- Consistent formatting - Ensures data attributes follow walkerOS conventions
- Automatic escaping - Handles special characters in values (semicolons, colons, quotes, backslashes)
- Type safety - Provides TypeScript support for better development experience
- Fluent API - Chainable methods for building complex attribute sets
- Maintainability - Centralized logic for attribute generation
When to Use the Tagger
Use the tagger when you need to:
- Generate data attributes programmatically in JavaScript/TypeScript
- Handle dynamic values that may contain special characters
- Build complex attribute sets with multiple properties
- Ensure consistent tagging across your application
- Integrate walkerOS tracking into component-based frameworks (React, Vue, etc.)
Installation
Initialization
The tagger is initialized using the createTagger factory function:
Configuration
| Property | Type | Description | More |
|---|---|---|---|
prefix | string | Custom prefix for generated data attributes |
Usage Examples
Basic Data Tagging (Without Entity)
Entity Tagging
Action Mapping
Context and Global Properties
Multiple Entity Scopes
Order Matters
Value Escaping
Available Methods (API Reference)
tagger(scope?: string)
Creates a new tagger instance. The optional scope parameter sets the naming scope for data attributes without creating an entity attribute.
entity(name: string)
Sets the entity attribute and updates the naming scope for subsequent data calls.
data(key: string, value: Property) | data(object: Properties)
Adds data properties using the current naming scope.
action(trigger: string, action?: string) | action(object: Record<string, string>)
Adds action mappings for event triggers. Creates a data-elbaction attribute.
actions(trigger: string, action?: string) | actions(object: Record<string, string>)
Adds action mappings for event triggers. Creates a data-elbactions attribute.
context(key: string, value: Property) | context(object: Properties)
Adds context properties that apply to all events.
globals(key: string, value: Property) | globals(object: Properties)
Adds global properties that persist across page views.
link(id: string, type: string) | link(object: Record<string, string>)
Adds link relationships between elements.
get()
Generates the final HTML attributes object.
All methods return the tagger instance for method chaining, except get() which
returns the final attributes object.