Htmx.Net
1.8.0
Dies ist ein Paket, das zum Hinzufügen serverseitiger Hilfsmethoden für HttpRequest und HttpResponse entwickelt wurde. Dies vereinfacht die Arbeit mit serverseitigen Htmx-Konzepten. Sie sollten auch über Hyperscript lesen, ein optionales Begleitprojekt für HTMX.
Wenn Sie neu bei HTMX sind, schauen Sie sich diese Serie über die ersten Schritte mit HTMX für ASP.NET Core-Entwickler an, die auch ein Beispielprojekt und Muster enthält, die für Sie hilfreich sein könnten.
Installieren Sie das Htmx NuGet-Paket in Ihrem ASP.NET Core-Projekt.
dotnet add package Htmx Mithilfe von HttpRequest können wir feststellen, ob die Anfrage von Htmx auf dem Client initiiert wurde.
httpContext . Request . IsHtmx ( )Dies kann verwendet werden, um entweder eine vollständige Seitenantwort oder ein teilweises Seitenrendering zurückzugeben.
// in a Razor Page
return Request . IsHtmx ( )
? Partial ( " _Form " , this )
: Page ( ) ;Wir können auch die anderen Header-Werte abrufen, die htmx möglicherweise festlegt.
Request . IsHtmx ( out var values ) ;Weitere Informationen zu den anderen Header-Werten finden Sie auf der offiziellen Dokumentationsseite.
Beachten Sie bitte besonders, dass Sie den HTTP-Header „Vary Response“ verwenden müssen, wenn Ihr Server je nach anderen Headern unterschiedliche Inhalte für dieselbe URL rendern kann. Wenn Ihr Server beispielsweise den vollständigen HTML-Code rendert, wenn Request.IsHtmx() „false“ ist, und ein Fragment dieses HTML-Codes, wenn Request.IsHtmx() „true“ ist, müssen Sie Vary: HX-Request hinzufügen. Dies führt dazu, dass der Cache auf der Grundlage einer Kombination aus der Antwort-URL und dem HX-Request-Anforderungsheader verschlüsselt wird – und nicht nur auf der Antwort-URL.
// in a Razor Page
if ( Request . IsHtmx ( ) )
{
Response . Headers . Add ( " Vary " , " HX-Request " ) ;
return Partial ( " _Form " , this )
}
return Page ( ) ; Wir können HTTP-Antwortheader mithilfe der Htmx Erweiterungsmethode festlegen, die eine Aktion und ein HtmxResponseHeaders -Objekt übergibt.
Response . Htmx ( h => {
h . PushUrl ( " /new-url " )
. WithTrigger ( " cool " )
} ) ;Weitere Informationen zu den HTTP-Antwortheadern finden Sie auf der offiziellen Dokumentationsseite.
Sie können clientseitige Ereignisse mit HTMX mithilfe des HX-Trigger Headers auslösen. Htmx.Net bietet eine WithTrigger Hilfsmethode zum Konfigurieren eines oder mehrerer Ereignisse, die Sie auslösen möchten.
Response . Htmx ( h => {
h . WithTrigger ( " yes " )
. WithTrigger ( " cool " , timing : HtmxTriggerTiming . AfterSettle )
. WithTrigger ( " neat " , new { valueForFrontEnd = 42 , status = " Done! " } , timing : HtmxTriggerTiming . AfterSwap ) ;
} ) ; Standardmäßig werden alle Htmx-Anfragen und -Antworten in einem Cross-Origin-Kontext blockiert.
Wenn Sie Ihre Anwendung in einem Cross-Origin-Kontext konfigurieren, können Sie durch das Festlegen einer CORS-Richtlinie in ASP.NET Core auch spezifische Einschränkungen für Anforderungs- und Antwortheader definieren und so eine differenzierte Kontrolle über die Daten ermöglichen, die zwischen Ihrem Web ausgetauscht werden können Anwendung und unterschiedliche Herkunft.
Diese Bibliothek bietet einen einfachen Ansatz zum Offenlegen von Htmx-Headern für Ihre CORS-Richtlinie:
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
} ) ;
} ) ; Installieren Sie das NuGet-Paket Htmx.TagHelpers in Ihrem ASP.NET Core-Projekt. Zielt auf .NET Core 3.1+-Projekte ab.
dotnet add package Htmx.TagHelpers Machen Sie die Tag-Hilfsprogramme in Ihrem Projekt verfügbar, indem Sie die folgende Zeile zu Ihrer _ViewImports.cshtml hinzufügen:
@addTagHelper *, Htmx.TagHelpers Im Allgemeinen benötigen Sie URL-Pfade, die auf Ihr ASP.NET Core-Backend verweisen. Glücklicherweise ahmt Htmx.TagHelpers die in ASP.NET Core enthaltene URL-Generierung nach. Dadurch wird die Verknüpfung von HTMX mit Ihrer ASP.NET Core-Anwendung zu einem nahtlosen Erlebnis.
< 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 > Ein zusätzlicher htmx-config Tag-Helfer ist enthalten, der auf ein meta im head Ihrer Seite angewendet werden kann und das Erstellen der HTMX-Konfiguration einfacher macht. Im Folgenden können wir beispielsweise den historyCacheSize und die Standard- indicatorClass festlegen und festlegen, ob die Fälschungsschutztoken von ASP.NET Core als zusätzliches Element in die HTMX-Konfiguration einbezogen werden sollen.
<!DOCTYPE html >
< html lang =" en " >
< head >
< meta name =" htmx-config "
historyCacheSize =" 20 "
indicatorClass =" htmx-indicator "
includeAspNetAntiforgeryToken =" true "
/>
<!-- additional elements... -->
</ head >Der resultierende HTML-Code wird sein.
<!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 > Sie können das Attribut includeAspNetAntiforgerToken für das htmx-config Element festlegen. Dann müssen Sie dieses zusätzliche JavaScript in Ihre Webanwendung einbinden. Wir fügen das Attribut __htmx_antiforgery hinzu, um zu verfolgen, dass der Ereignis-Listener bereits hinzugefügt wurde. Dies verhindert, dass wir den Ereignis-Listener versehentlich erneut registrieren.
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 ;
} Sie können auf zwei Arten auf das Snippet zugreifen. Die erste besteht darin, die statische Klasse HtmxSnippet in Ihren Ansichten zu verwenden.
<script>
@Html.Raw(HtmxSnippets.AntiforgeryJavaScript)
</script>
Eine einfachere Möglichkeit besteht darin, die HtmlExtensions -Klasse zu verwenden, die IHtmlHelper erweitert.
@Html.HtmxAntiforgeryScript()
Dieser HTML-Helfer führt zu einem <script> -Tag zusammen mit dem zuvor erwähnten JavaScript. Hinweis: Sie können weiterhin mehrere Event-Handler für htmx:configRequest registrieren, daher ist es in Ordnung, mehr als einen zu haben.
Beachten Sie Folgendes: Wenn sich das hx-[get|post|put] -Attribut auf einem <form ..> -Tag befindet und das <form> -Element ein method="post" -Attribut (und auch ein leeres oder fehlendes action="" )-Attribut hat, Die ASP.NET-Tag-Hilfsprogramme fügen das Anti-Forgery-Token als input hinzu und Sie müssen Ihre Anforderungen nicht wie oben beschrieben weiter konfigurieren. Sie könnten auch hx-include verwenden, um auf ein Formular zu verweisen, aber das hängt alles von Ihren Vorlieben ab.
Darüber hinaus besteht der empfohlene Ansatz darin, HtmxAntiforgeryScriptEndpoint zu verwenden, mit dem Sie die JavaScript-Datei einem bestimmten Endpunkt zuordnen können. Standardmäßig ist dies _htmx/antiforgery.js .
app . UseAuthorization ( ) ;
// registered here
app . MapHtmxAntiforgeryScript ( ) ;
app . MapRazorPages ( ) ;
app . MapControllers ( ) ; Sie können diesen Endpunkt jetzt mit Caching, Authentifizierung usw. konfigurieren. Noch wichtiger ist, dass Sie das Skript jetzt in Ihrem head -Tag verwenden können, indem Sie das defer -Tag anwenden, das besser ist als JavaScript am Ende eines body -Elements.
< 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 > Urheberrecht © 2022 Khalid Abuhakmeh
Hiermit wird jeder Person, die eine Kopie dieser Software und der zugehörigen Dokumentationsdateien (die „Software“) erhält, kostenlos die Erlaubnis erteilt, mit der Software ohne Einschränkung zu handeln, einschließlich und ohne Einschränkung der Rechte zur Nutzung, zum Kopieren, Ändern und Zusammenführen , Kopien der Software zu veröffentlichen, zu verteilen, unterzulizenzieren und/oder zu verkaufen und Personen, denen die Software zur Verfügung gestellt wird, dies zu gestatten, vorbehaltlich der folgenden Bedingungen:
Der obige Urheberrechtshinweis und dieser Genehmigungshinweis müssen in allen Kopien oder wesentlichen Teilen der Software enthalten sein.
DIE SOFTWARE WIRD „WIE BESEHEN“ ZUR VERFÜGUNG GESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF DIE GEWÄHRLEISTUNG DER MARKTGÄNGIGKEIT, EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND NICHTVERLETZUNG. IN KEINEM FALL SIND DIE AUTOREN ODER COPYRIGHT-INHABER HAFTBAR FÜR JEGLICHE ANSPRÜCHE, SCHÄDEN ODER ANDERE HAFTUNG, WEDER AUS EINER VERTRAGLICHEN HANDLUNG, AUS HANDLUNG ODER ANDERWEITIG, DIE SICH AUS, AUS ODER IN VERBINDUNG MIT DER SOFTWARE ODER DER NUTZUNG ODER ANDEREN HANDELN IN DER SOFTWARE ERGEBEN SOFTWARE.
