Configuration

Configure WildflowerJS behavior through script tag attributes and runtime options.

Script Tag Configuration

WildflowerJS can be configured at load time using attributes on the script tag:

<!-- Default: Both data-* and data-wf-* prefixes work -->
<script src="wildflower.js"></script>

<!-- Exclusive mode: Only data-wf-* prefixes are processed -->
<script src="wildflower.js" data-wf-prefix="true"></script>

<!-- Enable debug mode -->
<script src="wildflower.js" data-debug="true"></script>

<!-- Set error handling strategy -->
<script src="wildflower.js" data-error-handling="throw"></script>

<!-- Disable auto-initialization (call wildflower.init() manually) -->
<script src="wildflower.js" data-auto-init="false"></script>

Script Attribute	Values	Description
data-wf-prefix	"true"	Only process data-wf-* attributes (ignore data-*)
data-debug	"true"	Enable debug mode with verbose logging
data-error-handling	"log" | "throw" | "silent"	Error handling strategy (default: "log")
data-auto-init	"false"	Disable auto-initialization; call wildflower.init() manually

Exclusive Prefix Mode

By default, WildflowerJS recognizes both standard data-* attributes and data-wf-* prefixed attributes. This dual-mode allows flexibility but can conflict with third-party libraries that also use data-action, data-bind, or similar attributes.

The Problem

Libraries like Bootstrap, Alpine.js, or custom JavaScript may use:

• data-action - Common for delegated event handling
• data-bind - Used by various binding libraries
• data-toggle - Bootstrap modals, tooltips, etc.

When WildflowerJS processes these attributes, it may interfere with the intended third-party behavior.

The Solution: Exclusive Mode

Enable exclusive prefix mode to make WildflowerJS only process data-wf-* attributes:

<script src="wildflower.js" data-wf-prefix="true"></script>

With exclusive mode enabled:

• data-wf-bind - Processed by WildflowerJS
• data-wf-action - Processed by WildflowerJS
• data-wf-list - Processed by WildflowerJS
• data-bind - Ignored (available for third-party libraries)
• data-action - Ignored (available for third-party libraries)
• data-list - Ignored (available for third-party libraries)

Example: Using with Bootstrap

<!-- Enable exclusive mode to avoid conflicts with Bootstrap -->
<script src="wildflower.js" data-wf-prefix="true"></script>

<div data-wf-component="modal-example">
    <!-- Bootstrap uses data-toggle and data-target -->
    <button data-toggle="modal" data-target="#myModal">
        Open Bootstrap Modal
    </button>

    <!-- WildflowerJS uses data-wf-action -->
    <button data-wf-action="submitForm">
        Submit (WildflowerJS)
    </button>

    <!-- Display data with WildflowerJS binding -->
    <span data-wf-bind="username"></span>
</div>

Runtime Configuration

You can also toggle exclusive mode at runtime:

// Enable exclusive mode
wildflower.setWfPrefixMode(true);

// Disable exclusive mode (process both prefixes)
wildflower.setWfPrefixMode(false);

// Check current mode
console.log(wildflower.options.useWfPrefixOnly); // true or false

Attribute Reference

The following table shows all framework attributes and their data-wf-* equivalents:

Core

Standard Attribute	WF-Prefixed	Description
data-component	data-wf-component	Component definition
data-action	data-wf-action	Event handler
data-external	data-wf-external	Preserve element during component HTML updates
data-cloak	n/a	Hide element until framework initializes (add [data-cloak] { display: none !important; } to CSS). Do not use inside list <template> elements.

Data Binding

Standard Attribute	WF-Prefixed	Description
data-bind	data-wf-bind	Text binding
data-bind-html	data-wf-bind-html	HTML binding (renders raw HTML)
data-bind-class	data-wf-bind-class	Dynamic class binding
data-bind-style	data-wf-bind-style	Dynamic inline style binding
data-bind-attr	data-wf-bind-attr	Dynamic HTML attribute binding (object expression)

Forms

Standard Attribute	WF-Prefixed	Description
data-model	data-wf-model	Two-way form binding
data-model-lazy	data-wf-model-lazy	Update on blur instead of input
data-model-event	data-wf-model-event	Custom event for model sync (for web components)
data-validate	data-wf-validate	Form validation

Conditionals & Lists

Standard Attribute	WF-Prefixed	Description
data-show	data-wf-show	Conditional display (CSS visibility)
data-render	data-wf-render	Conditional render (DOM insertion/removal)
data-list	data-wf-list	List rendering
data-key	data-wf-key	List item key property for efficient reconciliation

Components & Templates

Standard Attribute	WF-Prefixed	Description
data-props	data-wf-props	Component props (JSON format)
data-prop-*	data-wf-prop-*	Individual component prop
data-slot	data-wf-slot	Named slot content
data-use-template	data-wf-use-template	Use a named template from parent component
data-with	data-wf-with	Data context for configurable templates

Event Modifiers

These attributes modify the behavior of data-action handlers. See Event Handling for details.

Standard Attribute	WF-Prefixed	Description
data-event-prevent	data-wf-event-prevent	Call preventDefault()
data-event-stop	data-wf-event-stop	Call stopPropagation()
data-event-once	data-wf-event-once	Execute handler only once
data-event-self	data-wf-event-self	Only fire if event target is the element itself
data-event-outside	data-wf-event-outside	Fire when clicking outside the element
data-event-capture	data-wf-event-capture	Use capture phase
data-event-passive	data-wf-event-passive	Mark as passive listener
data-event-debounce	data-wf-event-debounce	Debounce handler (value in ms, default 300)
data-event-throttle	data-wf-event-throttle	Throttle handler (value in ms, default 300)
data-event-key-*	data-wf-event-key-*	Key modifiers (ctrl, alt, shift, meta, enter, etc.)

Advanced

Standard Attribute	WF-Prefixed	Description
data-portal	data-wf-portal	Render content at a different DOM location
data-transition	data-wf-transition	Animation for show/render changes
data-error-fallback	data-wf-error-fallback	Fallback content selector for error boundaries
data-ssr	data-wf-ssr	Mark component as server-side rendered

Developer Tools

Application Inspector

Call wildflower.inspect() from the browser console to get a snapshot of your running application:

wildflower.inspect()

This prints:

• Components: a table of all active component types and their instance counts
• Stores: each named store with its current state (expandable in devtools)
• Summary: a one-line count, e.g. 3 components (14 instances), 2 stores

Example output:

[Wildflower] Application Inspector
  Components
┌─────────┬──────────────────┬───────────┐
│ (index) │    Component     │ Instances │
├─────────┼──────────────────┼───────────┤
│    0    │ 'product-card'   │    12     │
│    1    │ 'cart-drawer'    │     1     │
│    2    │ 'nav-bar'        │     1     │
└─────────┴──────────────────┴───────────┘
  Stores
    cart: {items: Array(3), total: 149.97}
    ui: {sidebarOpen: false, theme: 'dark'}
  Summary: 3 components (14 instances), 2 stores

The return value is an object you can work with:

const app = wildflower.inspect()
app.stores.cart         // { items: [...], total: 149.97 }
app.components          // { 'product-card': 12, 'cart-drawer': 1, ... }

Component Inspection

Pass a component name to inspect all instances of that type:

wildflower.inspect('kpi-widget')

This lists each instance with its DOM element and current state:

[Wildflower] Inspecting: kpi-widget (4 instances)
  #1 <div data-component="kpi-widget">
     state: {label: 'Revenue', value: 285644}
  #2 <div data-component="kpi-widget">
     state: {label: 'Orders', value: 1848}
  ...

The return value is the array of component instances, which you can use for further debugging:

const widgets = wildflower.inspect('kpi-widget')
widgets[0].element    // the DOM element
widgets[0].context    // the component's ContextProxy

Debug Mode

Enable verbose logging to see every binding, state change, and render cycle:

<script src="wildflower.js" data-debug="true"></script>

Debug mode outputs detailed information about:

• Component registration and initialization
• State mutations and computed recalculations
• DOM binding and update cycles
• Store subscriptions and notifications

Best Practices

• New projects: Use exclusive mode if you plan to integrate third-party libraries
• Existing projects: Continue using standard data-* attributes unless conflicts arise
• Migration: Both prefixes can be used simultaneously during gradual migration
• Consistency: Pick one prefix style and use it throughout your project