cake htmx

bolo-htmx

Integração CakePHP para htmx.

Versões suportadas do CakePHP >= 4.xe 5.x.

Instalando usando o Composer

cd para a raiz da pasta do seu aplicativo (onde está o arquivo composer.json ) e execute o seguinte comando:

 composer require zunnu/cake-htmx

Em seguida, carregue o plugin usando o console do CakePHP:

 ./bin/cake plugin load CakeHtmx

Para instalar o htmx, consulte a documentação

Uso

A funcionalidade principal está atualmente envolvida no componente Htmx. Para carregar o componente você precisará modificar seu src/Controller/AppController.php e carregar o componente Htmx na função initialize()

 $ this -> loadComponent ( ' CakeHtmx.Htmx ' );

Solicitar

Você pode usar o detector para verificar se a solicitação é 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

Utilizando o componente você pode verificar detalhes mais específicos sobre a solicitação.

 $ 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

Resposta

• redirect

Htmx pode acionar um redirecionamento do lado do cliente quando recebe uma resposta com o cabeçalho HX-Redirect .

 $ this -> Htmx -> redirect ( ' /somewhere-else ' );

• clientRefresh

O Htmx acionará o recarregamento da página quando receber uma resposta com o cabeçalho HX-Refresh . clientRefresh é uma resposta personalizada que permite enviar tal resposta. Não são necessários argumentos, pois o Htmx ignora qualquer conteúdo.

 $ this -> Htmx -> clientRefresh ();

• stopPolling

Ao usar um gatilho de pesquisa, o Htmx interromperá a pesquisa quando encontrar uma resposta com o código de status HTTP especial 286. stopPolling é uma resposta personalizada com esse código de status.

 $ this -> Htmx -> stopPolling ();

Consulte a documentação para todos os cabeçalhos disponíveis restantes.

 $ 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

Além disso, você pode acionar eventos do lado do cliente usando os métodos addTrigger .

 $ this -> Htmx
    -> addTrigger ( ' myEvent ' )
    -> addTriggerAfterSettle ( ' myEventAfterSettle ' )
    -> addTriggerAfterSwap ( ' myEventAfterSwap ' );

Se quiser passar detalhes junto com o evento você pode usar o segundo argumento para enviar um corpo. Suporta strings ou arrays.

 $ this -> Htmx -> addTrigger ( ' myEvent ' , ' Hello from myEvent ' )
-> addTriggerAfterSettle ( ' showMessage ' , [
    ' level ' => ' info ' ,
    ' message ' => ' Here is a Message '
]);

Você pode chamar esses métodos várias vezes se quiser acionar vários eventos.

 $ this -> Htmx
    -> addTrigger ( ' trigger1 ' , ' A Message ' )
    -> addTrigger ( ' trigger2 ' , ' Another Message ' )

Token CSRF

Para adicionar token CSRF a todas as suas solicitações, adicione o código abaixo ao seu layout.

document.body.addEventListener( ' htmx:configRequest ' , (event) => {
    event.detail.headers[ ' X-CSRF-Token ' ] = " <?= $ this -> getRequest ()->getAttribute('csrfToken') ?> " ;
})

Blocos de renderização e troca OOB

A função setBlock() permite renderizar um bloco específico enquanto remove outros blocos que podem ser renderizados. Isto é particularmente útil quando você precisa atualizar apenas uma parte da sua visualização.

 $ this -> Htmx -> setBlock ( ' userTable ' );

A função addBlock() permite adicionar um bloco específico à lista de blocos que devem ser renderizados.

 $ this -> Htmx -> addBlock ( ' userTable ' );

A função addBlocks() permite adicionar vários blocos à lista de blocos que devem ser renderizados

 $ this -> Htmx -> addBlocks ([ ' userTable ' , ' pagination ' ]);

Troca OOB

Htmx oferece suporte à atualização de vários destinos retornando várias respostas parciais com hx-swap-oop . Veja o exemplo Users index search functionality with pagination update Observe se você estiver trabalhando com tabelas como no exemplo. Talvez seja necessário adicionar

 < script type = "text/javascript" >
    htmx.config.useTemplateFragments = true;
</ script >

No seu modelo ou layout.

Exemplos

Funcionalidade de pesquisa de índice de usuários

Neste exemplo, implementaremos uma funcionalidade de pesquisa para o índice de usuários usando Htmx para filtrar resultados dinamicamente. Colocaremos o corpo da nossa tabela dentro de um viewBlock chamado usersTable . Quando a página carregar, renderizaremos o viewBlock usersTable .

 // Template/Users/index.php

<?= $ this -> Form -> control ( ' search ' , [
    ' label ' => false , 
    ' placeholder ' => __ ( ' Search ' ),
    ' type ' => ' text ' , 
    ' required ' => false , 
    ' class ' => ' form-control input-text search ' ,
    ' value ' => ! empty ( $ search ) ? $ search : '' ,
    ' hx-get ' => $ this -> Url -> build ([ ' controller ' => ' Users ' , ' action ' => ' index ' ]),
    ' hx-trigger ' => " keyup changed delay:200ms " ,
    ' hx-target ' => " #search-results " ,
    ' templates ' => [
        ' inputContainer ' => ' <div class="col-10 col-md-6 col-lg-5">{{content}}</div> '
    ]
]); ?>

<table id="usersTable" class="table table-hover table-white-bordered">
    <thead>
        <tr>
            <th scope="col"> <?= ' id ' ?> </th>
            <th scope="col"> <?= ' Name ' ?> </th>
            <th scope="col"> <?= ' Email ' ?> </th>
            <th scope="col"> <?= ' Modified ' ?> </th>
            <th scope="col"> <?= ' Created ' ?> </th>
            <th scope="col" class="actions"> <?= ' Actions ' ?> </th>
        </tr>
    </thead>
    
    <tbody id="search-results">
        <?php $ this -> start ( ' usersTable ' ); ?>
            <?php foreach ( $ users as $ user ): ?>
                <tr>
                    <td> <?= $ user -> id ?> </td>
                    <td> <?= h ( $ user -> name ) ?> </td>
                    <td> <?= h ( $ user -> email ) ?> </td>
                    <td> <?= $ user -> modified ?> </td>
                    <td> <?= $ user -> created ?> </td>
                    <td class="actions">
                        <?= $ this -> Html -> link ( ' Edit ' ,
                            [
                                ' action ' => ' edit ' ,
                                $ user -> id
                            ],
                            [
                                ' escape ' => false
                            ]
                        ); ?>
                        <?= $ this -> Form -> postLink ( ' Delete ' ,
                            [
                                ' action ' => ' delete ' ,
                                $ user -> id
                            ],
                            [
                                ' confirm ' => __ ( ' Are you sure you want to delete user {0}? ' , $ user -> email ),
                                ' escape ' => false
                            ]
                        ); ?>
                    </td>
                </tr>
            <?php endforeach ; ?>
        <?php $ this -> end (); ?>

        <?php echo $ this -> fetch ( ' usersTable ' ); ?>
    </tbody>
</table>

No controlador externo verificaremos se a solicitação é Htmx e, em caso afirmativo, renderizaremos apenas o viewBlock usersTable .

 // src/Controller/UsersController.php

public function index ()
{
    $ search = null ;
    $ query = $ this -> Users -> find ( ' all ' );

    if ( $ this -> request -> is ( ' get ' )) {
        if (! empty ( $ this -> request -> getQueryParams ())) {
            $ data = $ this -> request -> getQueryParams ();

            if ( isset ( $ data [ ' search ' ])) {
                $ data = $ data [ ' search ' ];
                $ conditions = [
                    ' OR ' => [
                        ' Users.id ' => ( int ) $ data ,
                        ' Users.name LIKE ' => ' % ' . $ data . ' % ' ,
                        ' Users.email LIKE ' => ' % ' . $ data . ' % ' ,
                    ],
                ];
                $ query = $ query -> where ([ $ conditions ]);
                $ search = $ data ;
            }
        }
    }

    $ users = $ query -> toArray ();
    $ this -> set ( compact ( ' users ' , ' search ' ));

    if ( $ this -> getRequest ()-> is ( ' htmx ' )) {
        $ this -> viewBuilder ()-> disableAutoLayout ();

        // we will only render the usersTable viewblock
        $ this -> Htmx -> setBlock ( ' usersTable ' );
    }
}

Funcionalidade de pesquisa de índice de usuários com atualização de paginação

Neste exemplo, implementaremos uma funcionalidade de pesquisa dinâmica para o índice de usuários usando Htmx. Isso nos permitirá filtrar os resultados em tempo real e atualizar a paginação de acordo. Envolveremos o corpo da nossa tabela dentro de um viewBlock chamado usersTable e nosso bloco de paginação para pagination . Quando a página carregar, renderizaremos o usersTable e o viewBlock pagination .

 // Template/Users/index.php

<?= $ this -> Form -> control ( ' search ' , [
    ' label ' => false , 
    ' placeholder ' => __ ( ' Search ' ),
    ' type ' => ' text ' , 
    ' required ' => false , 
    ' class ' => ' form-control input-text search ' ,
    ' value ' => ! empty ( $ search ) ? $ search : '' ,
    ' hx-get ' => $ this -> Url -> build ([ ' controller ' => ' Users ' , ' action ' => ' index ' ]),
    ' hx-trigger ' => ' keyup changed delay:200ms ' ,
    ' hx-target ' => ' #search-results ' ,
    ' hx-push-url ' => ' true ' ,
    ' templates ' => [
        ' inputContainer ' => ' <div class="col-10 col-md-6 col-lg-5">{{content}}</div> '
    ]
]); ?>

<table id="usersTable" class="table table-hover table-white-bordered">
    <thead>
        <tr>
            <th scope="col"> <?= ' id ' ?> </th>
            <th scope="col"> <?= ' Name ' ?> </th>
            <th scope="col"> <?= ' Email ' ?> </th>
            <th scope="col"> <?= ' Modified ' ?> </th>
            <th scope="col"> <?= ' Created ' ?> </th>
            <th scope="col" class="actions"> <?= ' Actions ' ?> </th>
        </tr>
    </thead>
    
    <tbody id="search-results">
        <?php $ this -> start ( ' usersTable ' ); ?>
            <?php foreach ( $ users as $ user ): ?>
                <tr>
                    <td> <?= $ user -> id ?> </td>
                    <td> <?= h ( $ user -> name ) ?> </td>
                    <td> <?= h ( $ user -> email ) ?> </td>
                    <td> <?= $ user -> modified ?> </td>
                    <td> <?= $ user -> created ?> </td>
                    <td class="actions">
                        <?= $ this -> Html -> link ( ' Edit ' ,
                            [
                                ' action ' => ' edit ' ,
                                $ user -> id
                            ],
                            [
                                ' escape ' => false
                            ]
                        ); ?>
                        <?= $ this -> Form -> postLink ( ' Delete ' ,
                            [
                                ' action ' => ' delete ' ,
                                $ user -> id
                            ],
                            [
                                ' confirm ' => __ ( ' Are you sure you want to delete user {0}? ' , $ user -> email ),
                                ' escape ' => false
                            ]
                        ); ?>
                    </td>
                </tr>
            <?php endforeach ; ?>
        <?php $ this -> end (); ?>

        <?php echo $ this -> fetch ( ' usersTable ' ); ?>
    </tbody>
</table>

// pagination
<?php $ this -> start ( ' pagination ' ); ?>
    <nav aria-label="Page navigation" id="pagination">
        <ul class="pagination justify-content-center">
            <?php $ this -> Paginator -> setTemplates ([
                ' prevActive ' => ' <li class="page-item pagination-previous"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' prevDisabled ' => ' <li class="page-item disabled pagination-previous"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' number ' => ' <li class="page-item"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' current ' => ' <li class="page-item active"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' nextActive ' => ' <li class="page-item pagination-next"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' nextDisabled ' => ' <li class="page-item disabled pagination-next"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' first ' => ' <li class="page-item pagination-next"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
                ' last ' => ' <li class="page-item pagination-next"><a class="page-link" hx-get="{{url}}" hx-target="#search-results" hx-push-url="true" href="#">{{text}}</a></li> ' ,
            ]); ?>
            <?= $ this -> Paginator -> first ( ' <i class="fas fa-angles-left"></i> ' , [ ' escape ' => false ]) ?>
            <?= $ this -> Paginator -> prev ( ' <i class="fas fa-chevron-left"></i> ' , [ ' escape ' => false ]) ?>
            <?= $ this -> Paginator -> numbers ([ ' first ' => 1 , ' last ' => 1 , ' modulus ' => 3 ]) ?>
            <?= $ this -> Paginator -> next ( ' <i class="fas fa-chevron-right"></i> ' , [ ' escape ' => false ]) ?>
            <?= $ this -> Paginator -> last ( ' <i class="fas fa-angles-right"></i> ' , [ ' escape ' => false ]) ?>
        </ul>
    </nav>
<?php $ this -> end (); ?>

<?= $ this -> fetch ( ' pagination ' ); ?>

No controlador externo verificaremos se a solicitação é Htmx e, em caso afirmativo, renderizaremos apenas o viewBlock usersTable .

 // src/Controller/UsersController.php

public function index ()
{
    $ search = null ;
    $ query = $ this -> Users -> find ( ' all ' );

    if ( $ this -> request -> is ( ' get ' )) {
        if (! empty ( $ this -> request -> getQueryParams ())) {
            $ data = $ this -> request -> getQueryParams ();

            if ( isset ( $ data [ ' search ' ])) {
                $ data = $ data [ ' search ' ];
                $ conditions = [
                    ' OR ' => [
                        ' Users.id ' => ( int ) $ data ,
                        ' Users.name LIKE ' => ' % ' . $ data . ' % ' ,
                        ' Users.email LIKE ' => ' % ' . $ data . ' % ' ,
                    ],
                ];
                $ query = $ query -> where ([ $ conditions ]);
                $ search = $ data ;
            }
        }
    }

    $ this -> paginate [ ' limit ' ] = 200 ;
    $ users = $ this -> paginate ( $ query );
    $ this -> set ( compact ( ' users ' , ' search ' ));

    if ( $ this -> getRequest ()-> is ( ' htmx ' )) {
        $ this -> viewBuilder ()-> disableAutoLayout ();

        // render users table and pagination blocks
        $ this -> Htmx -> addBlock ( ' usersTable ' )-> addBlock ( ' pagination ' );
    }
}

Licença

Licenciado sob a licença MIT.