The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-Plugin-HTMX-1.02
River stage zero No dependents
6 ++
/ Mojolicious::Plugin::HTMX

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>

  <button hx-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

  %= htmx->asset
  %= htmx->asset(src => '/assets/js/htmx.min.js')
  %= htmx->asset(ext => debug)

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

htmx->is_htmx_request

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

Based on HX-Request header.

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.

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

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.

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);

Register plugin in Mojolicious application.

SEE ALSO

Mojolicious, Mojolicious::Guides, https://mojolicious.org.

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

Copyright (c) 2022-2023, Giuseppe Di Terlizzi

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