/ 
Uniform-HTMX-0.15
/ Uniform::HTMX

NAME

Uniform::HTMX - Extensible, framework-agnostic base layer for htmx communication

SYNOPSIS

This is an abstract base module. It should not be used directly. Instead, implement or install a framework-specific driver subclass:

# Inside a subclass (e.g. Uniform::HTMX::PAGI)
package Uniform::HTMX::PAGI;
use parent 'Uniform::HTMX';

sub new {
    my ($class, $scope) = @_;
    my %raw_headers = ...; # Framework specific extraction

    my $self = bless { in => {}, out => {}, _ctx => $scope }, $class;
    $self->{in} = $self->_normalize_headers(\%raw_headers);
    return $self;
}

sub apply {
    my ($self) = @_;
    # Framework specific response injection using $self->{out}
}

DESCRIPTION

Uniform::HTMX provides a strict, unified interface for interacting with the htmx client-side library. By decoupling the htmx spec protocol from core web frameworks, it prevents backend platform locking and standardizes frontend interactions.

METHODS

Request Inspection

is_htmx()

Returns 1 if the incoming request was triggered by htmx (checks HX-Request header), otherwise returns 0.

is_boosted()

Returns 1 when HX-Boosted is true.

is_history_restore()

Returns 1 when HX-History-Restore-Request is true.

current_url()

Returns the browser URL supplied in HX-Current-URL, or undef.

prompt()

Returns the response to hx-prompt, including an intentionally empty string, or undef when HX-Prompt was not sent.

target()

Returns the string ID or CSS selector of the target element sent by the browser via the HX-Target header, if present.

trigger_id()

Returns the ID of the specific frontend DOM element that triggered the request via the HX-Trigger request header.

trigger_name()

Returns the name of the triggering element from HX-Trigger-Name, or undef.

trigger_event()

Inspects the incoming HX-Trigger request header and evaluates its contents.

Under the htmx specification, if a request is launched due to a client-side JavaScript event, the browser may send a JSON string containing the event name and its parameters instead of a simple element ID string.

This method checks the structural layout of the payload. If it detects a JSON string, it automatically decodes it and returns a native Perl data structure (hash reference or array reference). If it is a normal text string, it returns the raw scalar ID unchanged.

Returns undef if the header was not sent.

Response Manipulation

All modification methods return $self to support fluent method chaining.

res_retarget( $css_selector )

Overrides the client-side element target target for the incoming HTML swap. Maps to the outbound HX-Retarget HTTP header.

res_reswap( $strategy )

Overrides the layout swap strategy (e.g., 'outerHTML', 'innerHTML', 'none'). Maps to the outbound HX-Reswap HTTP header.

res_reselect( $css_selector )

Selects the portion of the response to swap via HX-Reselect.

res_location( $url_or_hashref )

Performs an htmx client-side navigation without a full reload. A scalar sets a URL; a hash reference is JSON encoded for the extended HX-Location form.

res_push_url( $url_or_false )

Sets HX-Push-Url. Pass a URL, or the literal string false to prevent a history entry.

res_replace_url( $url_or_false )

Sets HX-Replace-Url. Pass a URL, or the literal string false to prevent URL replacement.

res_redirect( $url )

Requests a full client-side redirect using HX-Redirect.

res_refresh( [$boolean] )

Sets HX-Refresh to true by default. Passing a false Perl value sets it to false.

res_trigger_name( $element_name )

Sets the HX-Trigger-Name outbound response header to specify the name of the target element to trigger client-side, if overriding standard target patterns.

res_trigger( $event_name [, $params_hashref_or_arrayref ] )

Instructs htmx to launch a custom client-side JavaScript event upon receiving the response fragment. If params are provided, they will be automatically serialized to valid JSON format as required by the htmx specification. Maps to the outbound HX-Trigger HTTP header.

res_trigger_after_settle( $event_name [, $params ] )

Like res_trigger, but emits HX-Trigger-After-Settle.

res_trigger_after_swap( $event_name [, $params ] )

Like res_trigger, but emits HX-Trigger-After-Swap.

EXTENDING UNIFORM::HTMX

To author a brand-new framework bridge distribution, construct your module namespace under the Uniform::HTMX::* hierarchy and declare Uniform::HTMX as your parent.

Subclasses gain access to _normalize_headers( \%hash ), which accepts normal HTTP names and common CGI/PSGI environment spellings such as HX-Target, hx_target, and HTTP_HX_TARGET. Names are matched case-insensitively. Malformed names and reference-valued fields are ignored; for array-valued duplicate fields, the last defined scalar is used. If both direct and environment forms are present, the direct HTTP spelling takes precedence.

Outbound values reject references and CR/LF characters to avoid accidental invalid headers and response-splitting vulnerabilities. JSON-capable methods serialize their structured values with JSON::MaybeXS, falling back to the core JSON::PP module when JSON::MaybeXS is unavailable.

SEE ALSO

Uniform

Uniform::HTMX::PSGI

Uniform::HTMX::Mojolicious

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Joshua S. Day.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)