zunnu / cake-htmx
Htmx plugin for CakePHP
Installs: 1
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Type:cakephp-plugin
Requires
- php: >=7.2
- cakephp/cakephp: ^4.0
Requires (Dev)
- phpunit/phpunit: ^8.5 || ^9.3
README
CakePHP integration for htmx.
Supported CakePHP Versions >= 4.x.x. 5.x support will be added later.
Installing Using Composer
cd
to the root of your app folder (where the composer.json
file is) and run the following command:
composer require zunnu/cake-htmx
Then load the plugin by using CakePHP's console:
./bin/cake plugin load CakeHtmx
To install htmx please browse their documentation
Usage
Main functionality is currently wrapped inside Htmx component.
To load the component you will need to modify your src/Controller/AppController.php
and load the Htmx component in the initialize()
function
$this->loadComponent('CakeHtmx.Htmx');
Request
You can use detector to check if the request is Htmx.
$this->getRequest()->is('htmx') // Always true if the request is performed by Htmx $this->getRequest()->is('boosted') // Indicates that the request is via an element using hx-boost $this->getRequest()->is('historyRestoreRequest') // True if the request is for history restoration after a miss in the local history cache
Using the component you can check more specific details about the request.
$this->Htmx->getCurrentUrl(); // The current URL of the browser $this->Htmx->getPromptResponse(); // The user response to an hx-prompt $this->Htmx->getTarget(); // The id of the target element if it exists $this->Htmx->getTriggerName(); // The name of the triggered element if it exists $this->Htmx->getTriggerId(); // The id of the triggered element if it exists
Response
redirect
Htmx can trigger a client side redirect when it receives a response with the HX-Redirect
header.
$this->Htmx->redirect('/somewhere-else');
clientRefresh
Htmx will trigger a page reload when it receives a response with the HX-Refresh
header. clientRefresh
is a custom response that allows you to send such a response. It takes no arguments, since Htmx ignores any content.
$this->Htmx->clientRefresh();
stopPolling
When using a polling trigger, Htmx will stop polling when it encounters a response with the special HTTP status code 286. stopPolling
is a custom response with that status code.
$this->Htmx->stopPolling();
See the documentation for all the remaining available headers.
$this->Htmx->location($location) // Allows you to do a client-side redirect that does not do a full page reload $this->Htmx->pushUrl($url) // pushes a new url into the history stack $this->Htmx->replaceUrl($url) // replaces the current URL in the location bar $this->Htmx->reswap($option) // Allows you to specify how the response will be swapped $this->Htmx->retarget($selector); // A CSS selector that updates the target of the content update to a different element on the page
Additionally, you can trigger client-side events using the addTrigger
methods.
$this->Htmx ->addTrigger('myEvent') ->addTriggerAfterSettle('myEventAfterSettle') ->addTriggerAfterSwap('myEventAfterSwap');
If you want to pass details along with the event you can use the second argument to send a body. It supports strings or arrays.
$this->Htmx->addTrigger('myEvent', 'Hello from myEvent') ->addTriggerAfterSettle('showMessage', [ 'level' => 'info', 'message' => 'Here is a Message' ]);
You can call those methods multiple times if you want to trigger multiple events.
$this->Htmx ->addTrigger('trigger1', 'A Message') ->addTrigger('trigger2', 'Another Message')
CSRF token
To add CSRF token to all your request add below code to your layout.
document.body.addEventListener('htmx:configRequest', (event) => { event.detail.headers['X-CSRF-Token'] = "<?= $this->getRequest()->getAttribute('csrfToken') ?>"; })
License
Licensed under The MIT License.