Htmx.Net

Htmx.Net

Это пакет, предназначенный для добавления вспомогательных методов на стороне сервера для HttpRequest и HttpResponse . Это упрощает работу с концепциями серверной части HTML. Вам также следует прочитать о Hyperscript, дополнительном сопутствующем проекте для HTMX.

Если вы новичок в HTMX, ознакомьтесь с этой серией статей о начале работы с HTMX для разработчика ASP.NET Core, которая также включает пример проекта и шаблоны, которые могут оказаться вам полезными.

Методы расширения Htmx

Начиная

Установите пакет Htmx NuGet в свой проект ASP.NET Core.

 dotnet add package Htmx

HttpRequest

Используя HttpRequest , мы можем определить, был ли запрос инициирован Htmx на клиенте.

httpContext . Request . IsHtmx ( )

Это можно использовать либо для возврата полного ответа страницы, либо для частичного рендеринга страницы.

 // in a Razor Page
return Request . IsHtmx ( )
    ? Partial ( " _Form " , this )
    : Page ( ) ;

Мы также можем получить другие значения заголовков, которые может установить htmx.

Request . IsHtmx ( out var values ) ;

Подробнее о других значениях заголовков читайте на официальной странице документации.

Кэширование браузера

Обратите особое внимание: если ваш сервер может отображать разное содержимое для одного и того же URL-адреса в зависимости от некоторых других заголовков, вам необходимо использовать HTTP-заголовок ответа Vary. Например, если ваш сервер отображает полный HTML-код, когда Request.IsHtmx() имеет значение false, и отображает фрагмент этого HTML, когда Request.IsHtmx() имеет значение true, вам необходимо добавить Vary: HX-Request. Это приводит к тому, что ключ к кешу создается на основе комбинации URL-адреса ответа и заголовка запроса HX-Request, а не только на основе URL-адреса ответа.

 // in a Razor Page
if ( Request . IsHtmx ( ) )
{
  Response . Headers . Add ( " Vary " , " HX-Request " ) ;
  return Partial ( " _Form " , this )
}

return Page ( ) ;

HttpResponse

Мы можем установить заголовки ответа Http, используя метод расширения Htmx , который передает действие и объект HtmxResponseHeaders .

Response . Htmx ( h => {
    h . PushUrl ( " /new-url " )
     . WithTrigger ( " cool " )
} ) ;

Подробнее о заголовках HTTP-ответов читайте на официальном сайте документации.

Запуск событий на стороне клиента

Вы можете запускать события на стороне клиента с помощью HTMX, используя заголовок HX-Trigger . Htmx.Net предоставляет вспомогательный метод WithTrigger для настройки одного или нескольких событий, которые вы хотите инициировать.

Response . Htmx ( h => {
    h . WithTrigger ( " yes " )
     . WithTrigger ( " cool " , timing : HtmxTriggerTiming . AfterSettle )
     . WithTrigger ( " neat " , new { valueForFrontEnd = 42 , status = " Done! " } , timing : HtmxTriggerTiming . AfterSwap ) ;
} ) ; 

Политика CORS

По умолчанию все запросы и ответы Htmx будут заблокированы в контексте перекрестного происхождения.

Если вы настраиваете свое приложение в контексте перекрестного происхождения, то установка политики CORS в ASP.NET Core также позволяет вам определить конкретные ограничения на заголовки запросов и ответов, обеспечивая детальный контроль над данными, которыми можно обмениваться между вашими веб-сайтами. применение и различное происхождение.

Эта библиотека предоставляет простой подход к предоставлению заголовков Htmx вашей политике CORS:

 var  MyAllowSpecificOrigins = " _myAllowSpecificOrigins " ;

var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services . AddCors ( options =>
{
    options . AddPolicy ( name : MyAllowSpecificOrigins ,
                      policy  =>
                      {
                          policy . WithOrigins ( " http://example.com " , " http://www.contoso.com " )
                                   . WithHeaders ( HtmxRequestHeaders . Keys . All )  // Add htmx request headers
                                   . WithExposedHeaders ( HtmxResponseHeaders . Keys . All )  // Add htmx response headers
                      } ) ;
} ) ; 

Htmx.TagHelpers

Начиная

Установите пакет NuGet Htmx.TagHelpers в свой проект ASP.NET Core. Предназначен для проектов .NET Core 3.1+.

 dotnet add package Htmx.TagHelpers

Сделайте вспомогательные функции тегов доступными в вашем проекте, добавив следующую строку в файл _ViewImports.cshtml :

 @addTagHelper *, Htmx.TagHelpers

Обычно вам потребуются URL-адреса, указывающие на ваш сервер ASP.NET Core. К счастью, Htmx.TagHelpers имитирует генерацию URL-адресов, включенную в ASP.NET Core. Это упрощает связывание HTMX с вашим приложением ASP.NET Core.

 < div hx-target =" this " >
    < button hx-get
            hx-page =" Index "
            hx-page-handler =" Snippet "
            hx-swap =" outerHtml " >
        Click Me (Razor Page w/ Handler)
    </ button >
</ div >

< div hx-target =" this " >
    < button hx-get
            hx-controller =" Home "
            hx-action =" Index "
            hx-route-id =" 1 " >
        Click Me (Controller)
    </ button >
</ div >

< div hx-target =" this " >
    < button hx-post
            hx-route =" named " >
        Click Me (Named)
    </ button >
</ div >

Htmx.Config

Включен дополнительный вспомогательный тег тега htmx-config , который можно применить к meta элементу в head вашей страницы, что упрощает создание конфигурации HTMX. Например, ниже мы можем установить historyCacheSize , indicatorClass по умолчанию и указать, включать ли токены защиты от подделки ASP.NET Core в качестве дополнительного элемента в конфигурации HTMX.

 <!DOCTYPE html >
< html lang =" en " >
< head >
    < meta name =" htmx-config " 
          historyCacheSize =" 20 "
          indicatorClass =" htmx-indicator "
          includeAspNetAntiforgeryToken =" true "
          />
    <!-- additional elements... -->
</ head >

Результирующий HTML будет таким.

 <!DOCTYPE html >
< html lang =" en " >
< head >
    < meta name =" htmx-config " content =' {"indicatorClass":"htmx-indicator","historyCacheSize":20,"antiForgery":{"formFieldName":"__RequestVerificationToken","headerName":"RequestVerificationToken","requestToken":"<token>"}} ' />
    <!-- additional elements... -->
</ head >

HTMX и токены защиты от подделки

Вы можете установить атрибут includeAspNetAntiforgerToken в элементе htmx-config . Затем вам нужно будет включить этот дополнительный JavaScript в свое веб-приложение. Мы включаем атрибут __htmx_antiforgery , чтобы отслеживать, что прослушиватель событий уже добавлен. Это убережет нас от случайной перерегистрации прослушивателя событий.

 if ( ! document . body . attributes . __htmx_antiforgery ) {
    document . addEventListener ( "htmx:configRequest" , evt => {
        let httpVerb = evt . detail . verb . toUpperCase ( ) ;
        if ( httpVerb === 'GET' ) return ;
        let antiForgery = htmx . config . antiForgery ;
        if ( antiForgery ) {
            // already specified on form, short circuit
            if ( evt . detail . parameters [ antiForgery . formFieldName ] )
                return ;

            if ( antiForgery . headerName ) {
                evt . detail . headers [ antiForgery . headerName ]
                    = antiForgery . requestToken ;
            } else {
                evt . detail . parameters [ antiForgery . formFieldName ]
                    = antiForgery . requestToken ;
            }
        }
    } ) ;
    document . addEventListener ( "htmx:afterOnLoad" , evt => {
        if ( evt . detail . boosted ) {
            const parser = new DOMParser ( ) ;
            const html = parser . parseFromString ( evt . detail . xhr . responseText , 'text/html' ) ;
            const selector = 'meta[name=htmx-config]' ;
            const config = html . querySelector ( selector ) ;
            if ( config ) {
                const current = document . querySelector ( selector ) ;
                // only change the anti-forgery token
                const key = 'antiForgery' ;
                htmx . config [ key ] = JSON . parse ( config . attributes [ 'content' ] . value ) [ key ] ;
                // update DOM, probably not necessary, but for sanity's sake
                current . replaceWith ( config ) ;
            }
        }
    } ) ;
    document . body . attributes . __htmx_antiforgery = true ;
}

Вы можете получить доступ к фрагменту двумя способами. Первый — использовать статический класс HtmxSnippet в ваших представлениях.

 <script>
@Html.Raw(HtmxSnippets.AntiforgeryJavaScript)
</script>

Более простой способ — использовать класс HtmlExtensions , расширяющий IHtmlHelper .

 @Html.HtmxAntiforgeryScript()

Этот помощник html создаст тег <script> вместе с ранее упомянутым JavaScript. Примечание. Вы по-прежнему можете зарегистрировать несколько обработчиков событий для htmx:configRequest , поэтому можно использовать несколько обработчиков событий.

Обратите внимание: если атрибут hx-[get|post|put] находится в теге <form ..> и элемент <form> имеет атрибут method="post" (а также пустой или отсутствующий атрибут action="" ), Вспомогательные функции тегов ASP.NET добавят токен защиты от подделки в качестве input элемента, и вам не потребуется дополнительно настраивать запросы, как указано выше. Вы также можете использовать hx-include , указывающий на форму, но все зависит от предпочтений.

Кроме того, рекомендуемый подход — использовать HtmxAntiforgeryScriptEndpoint , который позволит вам сопоставить файл JavaScript с определенной конечной точкой, и по умолчанию это будет _htmx/antiforgery.js .

app . UseAuthorization ( ) ;
// registered here
app . MapHtmxAntiforgeryScript ( ) ;
app . MapRazorPages ( ) ;
app . MapControllers ( ) ;

Теперь вы можете настроить эту конечную точку с помощью кэширования, аутентификации и т. д. Что еще более важно, теперь вы можете использовать скрипт в теге head , применив тег defer , что предпочтительнее, чем наличие JavaScript в конце элемента body .

 < head >
    < meta charset =" utf-8 "/>
    < meta name =" viewport " content =" width=device-width, initial-scale=1.0 "/>
    < meta
        name =" htmx-config "
        historyCacheSize =" 20 "
        indicatorClass =" htmx-indicator "
        includeAspNetAntiforgeryToken =" true "/>
    < title > @ViewData["Title"] - Htmx.Sample </ title >
    < link rel =" stylesheet " href =" ~/lib/bootstrap/dist/css/bootstrap.min.css "/>
    < link rel =" stylesheet " href =" ~/css/site.css " asp-append-version =" true "/>
    < script src =" ~/lib/jquery/dist/jquery.min.js " defer > </ script >
    < script src =" ~/lib/bootstrap/dist/js/bootstrap.bundle.min.js " defer > </ script >
    < script src =" https://unpkg.com/htmx.org@@1.9.2 " defer > </ script >
    <!-- this uses the static value in a script tag -->
    < script src =" @HtmxAntiforgeryScriptEndpoints.Path " defer > </ script >
</ head > 

Лицензия

Copyright © 2022 Халид Абухакме

Настоящим бесплатно любому лицу, получившему копию этого программного обеспечения и связанных с ним файлов документации («Программное обеспечение»), предоставляется разрешение на работу с Программным обеспечением без ограничений, включая, помимо прочего, права на использование, копирование, изменение, объединение публиковать, распространять, сублицензировать и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставлено Программное обеспечение, делать это при соблюдении следующих условий:

Вышеупомянутое уведомление об авторских правах и настоящее уведомление о разрешении должны быть включены во все копии или существенные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ТОВАРНОЙ ЦЕННОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ОБЛАДАТЕЛИ АВТОРСКИХ ПРАВ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЕТЕНЗИИ, УБЫТКИ ИЛИ ДРУГУЮ ОТВЕТСТВЕННОСТЬ, БУДЬ В ДЕЙСТВИЯХ ПО КОНТРАКТУ, ПРАВОНАРУШЕНИЮ ИЛИ ДРУГИМ ОБРАЗОМ, ВОЗНИКАЮЩИЕ ОТ, ИЗ ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ДРУГИМИ СДЕЛКАМИ, ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ.