NAME

Mojolicious::Plugin::HTMX - Mojolicious Plugin for htmx

SYNOPSIS

# Mojolicious
$self->plugin('Mojolicious::Plugin::HTMX');

# Mojolicious::Lite
plugin 'Mojolicious::Plugin::HTMX';

get '/trigger' => 'trigger';
post '/trigger' => sub ($c) {

    state $count = 0;
    $count++;

    $c->htmx->res->trigger(showMessage => 'Here Is A Message');
    $c->render(text => "Triggered $count times");

};

@@ template.html.ep
<html>
<head>
    %= app->htmx->asset
</head>
<body>
    %= content
</body>
</html>

@@ trigger.html.ep
% layout 'default';
<h1>Trigger</h1>

<!-- Common -->
<button hx-post="/trigger">Click Me</button>

<!-- Use "hx" helper -->
%= tag 'button', hx(post => '/trigger'), 'Click Me'

<!-- Use "hx_attr" helper -->
<button <%= hx_attr(post => '/trigger') %>>Click Me</button>

<script>
document.body.addEventListener("showMessage", function(e){
    alert(e.detail.value);
});
</script>

DESCRIPTION

Mojolicious::Plugin::HTMX is a Mojolicious plugin to add htmx in your Mojolicious application.

HELPERS

Mojolicious::Plugin::HTMX implements the following helpers.

GENERIC HELPERS

htmx->asset

# Load htmx from "https://unpkg.com/htmx.org"
%= htmx->asset

# Load htmx from a provided URL
%= htmx->asset(src => '/assets/js/htmx.min.js')

# Load an extension from "/dist/ext" directory
%= htmx->asset(ext => 'debug')

Generate script tag for include htmx script file in your template.

htmx->stop_polling

Sets the HTTP status code to 286 which is used by HTMX to halt polling requests.

$c->htmx->stop_polling;

is_htmx_request

if ($c->is_htmx_request) {
  # ...
}

Based on HX-Request header.

hx

%= tag 'button', hx(get => '/confirm', confirm => 'Confirm The Action'), 'Click For Confirm'
%= button_to Save => 'some_route', hx(patch => url_for('some_route'), swap => 'outerHTML', target => 'body')

hx helper convert the provided HASH attributes in "hx-" format. hx helper is useful when use Mojolicious::Plugin::TagHelpers helpers.

hx_attr

Alias for hx.

hx_attr helper convert the HASH atteibutes in "hx-" format and generate a well-format string.

<button <%= hx_attr(get => '/confirm', confirm => 'Confirm The Action') %>>Click For Confirm</button>

is equivalent to:

<button hx-get="/confirm" hx-confirm="Confirm The Action">Click For Confirm</button>

REQUEST HELPERS

htmx->req->boosted

Indicates that the request is via an element using hx-boost.

Based on HX-Boosted header.

htmx->req->current_url

The current URL of the browser.

Based on HX-Current-URL header.

htmx->req->history_restore_request

true if the request is for history restoration after a miss in the local history cache.

Based on HX-History-Restore-Request header.

htmx->req->prompt

The user response to an hx-prompt.

Based on HX-Prompt header.

htmx->req->request

Always true.

Based on HX-Request header.

htmx->req->target

The id of the target element if it exists.

Based on HX-Target header.

htmx->req->trigger_name

The name of the triggered element if it exists.

Based on HX-Trigger-Name header.

htmx->req->trigger

The id of the triggered element if it exists.

Based on HX-Trigger header.

htmx->req->to_hash

Turn htmx request into a hash reference.

RESPONSE HELPERS

htmx->res->location

Allows you to do a client-side redirect that does not do a full page reload.

Based on HX-Location header.

htmx->res->push_url

Pushes a new url into the history stack.

Based on HX-Push-Url header.

htmx->res->redirect

Can be used to do a client-side redirect to a new location.

Based on HX-Redirect header.

htmx->res->refresh

Full refresh of the page.

Based on HX-Refresh header.

htmx->res->replace_url

Replaces the current URL in the location bar.

Based on HX-Replace-Url header.

htmx->res->reswap

Allows you to specify how the response will be swapped.

The possible values of this attribute are:

innerHTML The default, replace the inner html of the target element
outerHTML Replace the entire target element with the response
beforebegin Insert the response before the target element
afterbegin Insert the response before the first child of the target element
beforeend Insert the response after the last child of the target element
afterend Insert the response after the target element
delete Deletes the target element regardless of the response
none Does not append content from response (out of band items will still be processed).

Based on HX-Reswap header.

htmx->res->reselect

A CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing hx-select on the triggering element

Based on HX-Reselect header.

htmx->res->retarget

A CSS selector that updates the target of the content update to a different element on the page.

Based on HX-Retarget header.

htmx->res->trigger

Allows you to trigger client side events, see https://htmx.org/headers/hx-trigger for more info.

To trigger a single event with no additional details you can simply send the event name like so:

if ($c->is_htmx_request) {
  $c->htmx->res->trigger('myEvent');
}

If you want to pass details along with the event, you can use HASH for the value of the trigger:

if ($c->is_htmx_request) {
  $c->htmx->res->trigger( showMessage => 'Here Is A Message' );
}

if ($c->is_htmx_request) {
  $c->htmx->res->trigger(
    showMessage => {
      level   => 'info',
      message => 'Here Is A Message'
    }
  );
}

If you wish to invoke multiple events, you can simply add additional keys to the HASH:

if ($c->is_htmx_request) {
  $c->htmx->res->trigger(
      event1 => 'A message',
      event2 => 'Another message'
  );
}

You may also trigger multiple events with no additional details by sending event names in ARRAY:

if ($c->is_htmx_request) {
  $c->htmx->res->trigger(['event1', 'event2']);
}

Based on HX-Trigger header.

htmx->res->trigger_after_settle

Allows you to trigger client side events, see https://htmx.org/headers/hx-trigger for more info.

Based on HX-Trigger-After-Settle header.

htmx->res->trigger_after_swap

Allows you to trigger client side events, see https://htmx.org/headers/hx-trigger for more info.

Based on HX-Trigger-After-Swap header.

METHODS

Mojolicious::Plugin::HTMX inherits all methods from Mojolicious::Plugin and implements the following new ones.

register

$plugin->register(Mojolicious->new);

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/giterlizzi/perl-Mojolicious-Plugin-HTMX/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/giterlizzi/perl-Mojolicious-Plugin-HTMX

git clone https://github.com/giterlizzi/perl-Mojolicious-Plugin-HTMX.git

AUTHORS

Giuseppe Di Terlizzi <gdt@cpan.org>

COPYRIGHT AND LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

To install Mojolicious::Plugin::HTMX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mojolicious::Plugin::HTMX

CPAN shell

perl -MCPAN -e shell
install Mojolicious::Plugin::HTMX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

HELPERS

GENERIC HELPERS

htmx->asset

htmx->stop_polling

is_htmx_request

hx

hx_attr

REQUEST HELPERS

htmx->req->boosted

htmx->req->current_url

htmx->req->history_restore_request

htmx->req->prompt

htmx->req->request

htmx->req->target

htmx->req->trigger_name

htmx->req->trigger

htmx->req->to_hash

RESPONSE HELPERS

htmx->res->location

htmx->res->push_url

htmx->res->redirect

htmx->res->refresh

htmx->res->replace_url

htmx->res->reswap

htmx->res->reselect

htmx->res->retarget

htmx->res->trigger

htmx->res->trigger_after_settle

htmx->res->trigger_after_swap

METHODS

register

SEE ALSO

SUPPORT

Bugs / Feature Requests

Source Code

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions