michaelschiemer/docs/framework/data-attributes-reference.md

Data Attributes Reference

Complete reference for all data-* HTML attributes used in the framework, organized by feature area.

Overview

All data attributes are centrally managed through PHP Enums and JavaScript Constants to ensure:

• Type Safety: IDE autocomplete and compile-time checks
• Consistency: Unified naming conventions
• Refactoring: Easy renaming across the entire codebase
• Documentation: Central overview of all attributes

Structure

Attributes are organized into specialized Enums/Constants by feature area:

• LiveComponent Core (LiveComponentCoreAttribute / LiveComponentCoreAttributes)
• LiveComponent Features (LiveComponentFeatureAttribute / LiveComponentFeatureAttributes)
• LiveComponent Lazy Loading (LiveComponentLazyAttribute / LiveComponentLazyAttributes)
• Admin Tables (AdminTableAttribute / AdminTableAttributes)
• Bulk Operations (BulkOperationAttribute / BulkOperationAttributes)
• Action Handler (ActionHandlerAttribute / ActionHandlerAttributes)
• Form Data (FormDataAttribute / FormDataAttributes)
• State Management (StateDataAttribute / StateDataAttributes)
• UI Enhancements (UIDataAttribute / UIDataAttributes)
• Module System (ModuleDataAttribute / ModuleDataAttributes)

Usage

PHP Backend

use App\Framework\View\ValueObjects\LiveComponentCoreAttribute;
use App\Framework\View\Dom\ElementNode;

// Get attribute name
$attr = LiveComponentCoreAttribute::LIVE_COMPONENT->value();
// Returns: "data-live-component"

// Convert to CSS selector
$selector = LiveComponentCoreAttribute::LIVE_COMPONENT->toSelector();
// Returns: "[data-live-component]"

// Convert to JavaScript dataset key
$datasetKey = LiveComponentCoreAttribute::LIVE_COMPONENT->toDatasetKey();
// Returns: "liveComponent"

// Use directly in methods (no ->value() needed!)
$element = new ElementNode('div');
$element->setAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT, 'my-component');
$element->hasAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // true
$value = $element->getAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // "my-component"

// For array keys, ->value() is still required (PHP limitation)
$attributes = [
    LiveComponentCoreAttribute::LIVE_COMPONENT->value() => 'my-component',
    LiveComponentCoreAttribute::STATE->value() => '{}',
];

JavaScript Frontend

import { LiveComponentCoreAttributes, toDatasetKey } from '/assets/js/core/DataAttributes.js';

// Get attribute name
const attr = LiveComponentCoreAttributes.LIVE_COMPONENT;
// Returns: "data-live-component"

// Use in getAttribute
element.getAttribute(LiveComponentCoreAttributes.LIVE_COMPONENT);

// Use in dataset (with helper)
element.dataset[toDatasetKey(LiveComponentCoreAttributes.LIVE_COMPONENT)];

// Use in querySelector
document.querySelector(`[${LiveComponentCoreAttributes.LIVE_COMPONENT}]`);

LiveComponent Core Attributes

Core data-* attributes for component identification, state, security, and real-time communication.

Attribute	Enum Case	Description
data-live-component	LIVE_COMPONENT	Component root element identifier
data-component-id	COMPONENT_ID	Unique component instance ID
data-live-id	LIVE_ID	Alternative component ID
data-state	STATE	Component state (JSON)
data-live-state	LIVE_STATE	Alternative state attribute
data-live-content	LIVE_CONTENT	Component content container
data-live-action	LIVE_ACTION	Action name to trigger
data-csrf-token	CSRF_TOKEN	Component-specific CSRF token
data-sse-channel	SSE_CHANNEL	Server-Sent Events channel
data-poll-interval	POLL_INTERVAL	Polling interval in milliseconds
data-live-upload	LIVE_UPLOAD	File upload handler
data-live-dropzone	LIVE_DROPZONE	File dropzone handler
data-live-polite	LIVE_POLITE	Accessibility politeness level

LiveComponent Feature Attributes

Advanced feature attributes (data-lc-*) for data binding, fragments, URL management, transitions, and triggers.

Attribute	Enum Case	Description
data-lc-model	LC_MODEL	Two-way data binding
data-lc-fragment	LC_FRAGMENT	Fragment identifier
data-lc-fragments	LC_FRAGMENTS	Comma-separated fragment list
data-lc-key	LC_KEY	Element key for DOM matching
data-lc-boost	LC_BOOST	Progressive enhancement
data-lc-push-url	LC_PUSH_URL	Push URL to browser history
data-lc-replace-url	LC_REPLACE_URL	Replace URL without history entry
data-lc-target	LC_TARGET	Target element selector
data-lc-swap	LC_SWAP	DOM swap strategy
data-lc-swap-transition	LC_SWAP_TRANSITION	Transition animation
data-lc-keep-focus	LC_KEEP_FOCUS	Preserve focus after update
data-lc-scroll	LC_SCROLL	Enable scrolling
data-lc-scroll-target	LC_SCROLL_TARGET	Scroll target selector
data-lc-scroll-behavior	LC_SCROLL_BEHAVIOR	Scroll behavior (smooth/instant)
data-lc-indicator	LC_INDICATOR	Loading indicator selector
data-lc-trigger-delay	LC_TRIGGER_DELAY	Trigger delay in milliseconds
data-lc-trigger-throttle	LC_TRIGGER_THROTTLE	Trigger throttle in milliseconds
data-lc-trigger-once	LC_TRIGGER_ONCE	Trigger only once
data-lc-trigger-changed	LC_TRIGGER_CHANGED	Trigger only on value change
data-lc-trigger-from	LC_TRIGGER_FROM	Trigger from another element
data-lc-trigger-load	LC_TRIGGER_LOAD	Trigger on page load

LiveComponent Lazy Loading Attributes

Attributes for lazy loading and island rendering of LiveComponents.

Attribute	Enum Case	Description
data-live-component-lazy	LIVE_COMPONENT_LAZY	Lazy-loaded component ID
data-live-component-island	LIVE_COMPONENT_ISLAND	Island component ID
data-island-component	ISLAND_COMPONENT	Mark as island component
data-lazy-priority	LAZY_PRIORITY	Loading priority (high/normal/low)
data-lazy-threshold	LAZY_THRESHOLD	Intersection observer threshold
data-lazy-placeholder	LAZY_PLACEHOLDER	Placeholder text

Admin Table Attributes

Data attributes for admin table functionality including sorting, pagination, searching, and column configuration.

Attribute	Enum Case	Description
data-resource	RESOURCE	Resource name
data-api-endpoint	API_ENDPOINT	API endpoint URL
data-sortable	SORTABLE	Enable sorting
data-searchable	SEARCHABLE	Enable searching
data-paginated	PAGINATED	Enable pagination
data-per-page	PER_PAGE	Items per page
data-column	COLUMN	Column identifier
data-sort-dir	SORT_DIR	Sort direction (asc/desc)
data-page	PAGE	Page number
data-table-search	TABLE_SEARCH	Search container selector
data-table-pagination	TABLE_PAGINATION	Pagination container selector

Bulk Operation Attributes

Data attributes for bulk operations on admin tables.

Attribute	Enum Case	Description
data-bulk-operations	BULK_OPERATIONS	Enable bulk operations
data-bulk-toolbar	BULK_TOOLBAR	Toolbar container selector
data-bulk-count	BULK_COUNT	Selected count element selector
data-bulk-buttons	BULK_BUTTONS	Action buttons container selector
data-bulk-initialized	BULK_INITIALIZED	Initialization flag
data-bulk-select-all	BULK_SELECT_ALL	Select all checkbox
data-bulk-item-id	BULK_ITEM_ID	Item ID for bulk selection
data-bulk-action	BULK_ACTION	Bulk action name
data-bulk-method	BULK_METHOD	HTTP method for bulk action
data-bulk-confirm	BULK_CONFIRM	Confirmation message

Action Handler Attributes

Data attributes for the ActionHandler system.

Attribute	Enum Case	Description
data-action	ACTION	Action name
data-action-handler	ACTION_HANDLER	Handler name
data-action-url	ACTION_URL	Direct action URL
data-action-method	ACTION_METHOD	HTTP method
data-action-type	ACTION_TYPE	Action type (e.g., "window")
data-action-handler-container	ACTION_HANDLER_CONTAINER	Container selector
data-action-confirm	ACTION_CONFIRM	Confirmation message
data-action-loading-text	ACTION_LOADING_TEXT	Loading text
data-action-success-toast	ACTION_SUCCESS_TOAST	Success message
data-action-error-toast	ACTION_ERROR_TOAST	Error message

Note: data-action-param-* is a pattern (not an enum case) for dynamic parameters.

Form Data Attributes

Data attributes for form handling and validation.

Attribute	Enum Case	Description
data-field	FIELD	Form field identifier
data-selected-if	SELECTED_IF	Conditional selection
data-checked-if	CHECKED_IF	Conditional check

Note: data-param-* is a pattern (not an enum case) for dynamic parameters.

State Management Attributes

Data attributes for client-side state management and data binding.

Attribute	Enum Case	Description
data-bind	BIND	Bind to state key
data-bind-attr	BIND_ATTR	Bind attribute to state
data-bind-attr-name	BIND_ATTR_NAME	Attribute name for binding
data-bind-class	BIND_CLASS	Bind class to state
data-bind-input	BIND_INPUT	Two-way input binding
data-persistent	PERSISTENT	Persist state in localStorage

UI Enhancement Attributes

Data attributes for UI enhancements including loading states, optimistic updates, confirmations, modals, themes, and other UI features.

Attribute	Enum Case	Description
data-loading	LOADING	Enable loading state
data-loading-text	LOADING_TEXT	Loading text
data-original-text	ORIGINAL_TEXT	Original text (for restoration)
data-optimistic	OPTIMISTIC	Enable optimistic updates
data-rollback	ROLLBACK	Rollback flag
data-confirm-ok	CONFIRM_OK	Confirm OK button
data-confirm-cancel	CONFIRM_CANCEL	Confirm cancel button
data-close-modal	CLOSE_MODAL	Close modal button
data-tag	TAG	Tag identifier
data-theme	THEME	Theme name
data-theme-icon	THEME_ICON	Theme icon selector
data-mobile-menu-open	MOBILE_MENU_OPEN	Mobile menu state
data-section-id	SECTION_ID	Section identifier
data-tab	TAB	Tab identifier
data-view-mode	VIEW_MODE	View mode
data-asset-id	ASSET_ID	Asset identifier

Module System Attributes

Data attributes for the JavaScript module initialization system.

Attribute	Enum Case	Description
data-module	MODULE	Module name
data-options	OPTIONS	Module options (JSON)

Related Documentation

• LiveComponents API Reference
• Action Handler Guide
• Framework Architecture