spaghettify
1.0.0
Spaghettify verwandelt jede statische HTML-Site in eine Single-Page-Anwendung mit AJAX-gesteuerter Navigation und Funktionen zur Persistenz von DOM-Elementen. Zu diesem Zweck implementiert es einen DOM-Interceptor und einen Middleware-Funneling-Prozessor , der Link-Klick-Ereignisse erfasst, jedes angeforderte Dokument über XHR abruft und die Antwort verarbeitet, indem er sie durch eine Reihe von Middleware-Funktionen streamt, bevor das Browserdokument aktualisiert wird.
Bei diesen Middleware-Funktionen handelt es sich um steckbare I/O-Handler, die das Single-Responsibility-Prinzip befolgen und eine vollständige Pipeline von Schritten anpassen, die in onBeforeComplete -Middleware-Hooks, die das aktuelle Seiten-DOM NICHT mutieren, und onAfterComplete Middleware-Hooks, die ihre Änderungen anwenden, kategorisiert werden können (daher mutieren) direkt im aktuellen Seiten-DOM, nachdem es injiziert wurde.
Das gesamte Projekt basiert auf TypeScript und implementiert mehrere Polyfills und Codierungsstrategien, um die Unterstützung auf alte Legacy-Browser wie MSIE11 zu erweitern.
Die Mindestanforderungen für die Ausführung dieses Projekts, entweder im Entwicklungs- oder Produktionsmodus, und seiner Entwicklungsskripts sind node v12.16.0 und npm v.6.14.15 oder spätere Versionen. Wahrscheinlich läuft dieses Projekt problemlos auf älteren Versionen von node und npm wir empfehlen jedoch die Verwendung der neuesten LTS-Versionen.
Dieses Projekt basiert auf BabelJS und Webpack, um Code im Entwicklungsmodus zu kompilieren, Builds auszuführen, die die Demo-Site-Dateien bereitstellen und Codeoptimierungen durchführen.
Die gesamte Interaktion mit BabelJS und Webpack wurde zu Ihrer Bequemlichkeit in benutzerdefinierten NPM-Skripten abstrahiert.
Als ersten Schritt zum Erstellen einer Entwicklungsumgebung oder eines Produktions-Builds führen Sie bitte entweder yarn oder npm install aus, um alle erforderlichen Abhängigkeiten für dieses Projekt abzurufen.
Bitte führen Sie yarn build oder npm run build in Ihrem Terminalfenster aus.
Der Projektbündeler navigiert durch die gesamte Anwendungsstruktur und erstellt das JavaScript-Artefakt im Ordner /dist , gebündelt als spaghettify.js . Zu Ihrer Bequemlichkeit werden dort auch andere nützliche Pakete gespeichert.
Kann ich Spaghettify aus der npm-Registrierung abrufen? Zum Zeitpunkt des Schreibens dieses Artikels bestehen die Projektprioritäten darin, die Testabdeckung etwas weiter zu erhöhen und die API-Funktionen durch erweiterte Unterstützung für vom Benutzer bereitgestellte Middleware-Hooks zu erweitern. Spaghettify soll vorerst als Browser-Abhängigkeit genutzt werden, die Verteilung als NPM-Paket ist jedoch geplant. Bitte schauen Sie in Kürze noch einmal vorbei, um Updates zu erhalten.
Sie können Spaghettify über eine praktische API-Versorgung mit globalen Umschaltern, Routen-Interceptoren, Ausschlüssen und Status-Persistenz-Attributflags und nicht zuletzt Ladefortschrittsindikatoren und -handlern instanziieren und mit ihnen interagieren.
Sobald Sie Spaghettify erfolgreich kompiliert haben, können Sie es wie folgt in Ihre Anwendung importieren und instanziieren:
< script type =" text/javascript " src =" /dist/spaghettify.js " > </ script >
< script type =" text/javascript " >
new Spaghettify ( {
enabled : true ,
routes : [ '*.html' , 'content/*' ] ,
excludeByAttr : 'no-spa' ,
loadProgress : true ,
persistAttr : 'data-persist' ,
} ) ;
</ script >Wie Sie sehen, kann Spaghettify bei der Instanziierung ein Konfigurationsobjekt übernehmen. Bitte beachten Sie, dass alle Felder optional sind und auch das gesamte Konfigurationsobjekt selbst optional ist. Wenn nicht angegeben, wird Spaghettify mit den Standardoptionen instanziiert, wie in der folgenden Tabelle beschrieben.
Das Spaghettify-Konfigurationseinstellungsobjekt kann wie folgt zusammengefasst werden:
| Feld | Typ | Standard | Beschreibung |
|---|---|---|---|
enabled | Boolean | true | Aktiviert oder deaktiviert Spaghettify bei der Instanziierung |
routes | String[] | ['*'] | Definiert Muster für Routen, die über Spaghettify abgefangen und bereitgestellt werden sollen. Unterstützt Glob-Token. |
excludeByAttr | String | undefined | Definiert ein Ausschlussdatenattribut-Token (mit oder ohne das data- ). Mit diesem Attribut versehene Links werden von Spaghettify umgangen |
loadProgress | Boolean Function | false | Aktiviert einen integrierten Fortschrittsbalken oder nicht. Es kann auch ein Funktionshandler verwendet werden, der beim Laden eine prozentuale Fortschrittszahl erhält. |
persistAttr | String | undefined | Definiert ein UI-Zustandspersistenz-Flag-Datenattribut (mit oder ohne das data- ). Mit diesem Attribut versehene Elemente behalten ihren Status während der gesamten Seitennavigation bei. |
Bitte beachten Sie, dass alle Konfigurationsoptionen (und die Optionsnutzlast selbst) optional sind und den Standardwert annehmen, wenn sie nicht explizit deklariert werden.
Spaghettify interagiert mit Ihrem aktuellen Dokument, indem es Event-Handler intern an geeignete Links bindet. Um Speicherlecks zu verhindern oder wenn Sie Spaghettify stoppen möchten, bis es erneut gestartet wird, sollten Sie es wie folgt zerstören:
< script type =" text/javascript " >
// First, we instantiate Spaghettify
const spa = new Spaghettify ( ) ;
// Then we dispose it after use
spa . destroy ( ) ;
</ script > Alle Links werden von Spaghettify so konfiguriert, dass sie abgefangen werden können. Die interne Event-Manager-Maschinerie beurteilt, ob der Link als AJAX-Anfrage behandelt werden kann oder nicht, indem sie den Link-href-Wert mit den Glob-Tokens routes vergleicht.
Wir können diesen Schritt jedoch im Voraus umgehen, indem wir die Option excludeByAttr mit einem Attributwert konfigurieren, entweder mit dem Präfix data- oder nicht.
Aus Gründen der Semantik berücksichtigt Spaghettify dann jedoch nur Linkelemente, die mit dem vollwertigen Attribut konfiguriert sind.
< script type =" text/javascript " >
new Spaghettify ( {
excludeByAttr : 'skip-me' ,
} ) ;
</ script >
<!-- Spaghettify will disregard the following link -->
< a href =" foo.html " data-skip-me > Skip this link </ a >Das konfigurierte Attribut kann mit einem beliebigen oder gar keinem Wert gefüllt werden. Spaghettify wird diesen Wert sowieso ignorieren.
Wie wir bereits gesehen haben, kann die Konfigurationsoption loadProgress einen Boolean Grundwert oder einen Funktionshandler annehmen.
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : true ,
} ) ;
</ script > Wenn dies nicht explizit konfiguriert oder auf false gesetzt ist, wird keine Fortschrittsbalkenanzeige angezeigt. Wenn true angegeben wird, zeigt Spaghettify oben im Ansichtsfenster eine animierte rote Fortschrittsbalkenanzeige an. Der Fortschrittsbalken zeigt den tatsächlichen Download-Fortschritt.
Verbraucher möchten jedoch möglicherweise ihre eigenen visuellen Lösungen für die Darstellung von Download-Fortschrittsinformationen implementieren. Spaghettify deckt sie ab, indem es einen Ladefortschrittshandler bereitstellt, der in seiner Signatur einen ganzzahligen Wertparameter erwartet, der Werte von 0 bis 100 annimmt, wenn Seiten über HXR angefordert und heruntergeladen werden.
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : function onLoad ( progress ) {
console . log ( progress ) ; // Will log values from 0 to 100
} ,
} ) ;
</ script > Spaghettify implementiert eine experimentelle API zum Beibehalten des Status in ausgewählten, annotierten DOM-Knoten über die Seitennavigation hinweg. Dazu müssen Sie lediglich ein Werttoken in der Option persistAttr konfigurieren und dann die DOM-Elemente, deren Zustand beibehalten werden soll, mit dem entsprechenden data- mit jeweils einem eindeutigen Wert annotieren:
< script type =" text/javascript " >
new Spaghettify ( {
persistAttr : 'persist-id' ,
} ) ;
</ script >
< input type =" text " data-persist-id =" my-input " /> Sie können dem Wert explizit data- voranstellen oder nicht, aber Spaghettify verlangt von Ihnen, dass Sie die DOM-Elemente, die beibehalten werden sollen, mit der vollständigen Datenattributsyntax annotieren.
Bitte beachten Sie : Attributwerte sollen eindeutig sein. Spaghettify löst eine Ausnahme aus, wenn mehr als ein Element unterschiedlichen Typs mit demselben Attributwert konfiguriert ist.
Hervorzuheben ist, dass die Persistenz auf der Basis eines vollständigen DOM- Node angewendet wird, sodass sie nicht nur den inneren HTML-Code des Elements, sondern auch den nativen Berührungszustand für Eingabesteuerelemente umfasst. Und das alles unabhängig von den Änderungen im äußeren HTML.
Sie können eine Entwicklungsumgebung erstellen, indem Sie in der Konsole yarn dev oder npm run dev ausführen.
Das System generiert alle Artefakte und bedient die Sandbox-Site (weitere Details unten) von http://localhost:3000 (oder einem anderen Port Ihrer Wahl, wenn Sie den Parameter --port=PORT an den Befehl dev anhängen, wobei PORT ist der gewünschte Port) im Überwachungsmodus , sodass die Anwendung bei Änderungen im Quellcode neu kompiliert wird.
Die Sandbox-Site ist eine kleine, äußerst vereinfachte Webanwendung, die als Spielplatz und Testarena für das Debuggen von Spaghettify in einer Live-Umgebung dient. Es zeichnet sich durch ein ziemlich einfaches Design aus und besteht aus einer Reihe verschiedener, hierarchischer Seiten, die die folgenden Hauptfunktionen darstellen:
index.html enthält eine Inline-Instanz von Spaghettify zu Demozwecken. Alle anderen Dokumente implementieren eine solche Instanz als importiertes Skript. Sie müssen Spaghettify nicht für jedes Dokument importieren, sondern nur für das Eintragsdokument. Dies ermöglicht jedoch, Spaghettify aus jedem Dokument heraus zu starten, nachdem das Browserfenster zu Demozwecken neu geladen wurde. In einem realen Produktionsszenario kann (und sollte) Spaghettify nur einmal am Eingabeort importiert und instanziiert werden./sandbox und einem untergeordneten Unterordner /sandbox/content verteilt, sodass Mitwirkende bei Bedarf mit Link-Selektoren herumspielen können, die auf Unterordner verweisen./sandbox/content verfügen entweder über Inline- oder importiertes benutzerdefiniertes JavaScript, das Spaghettify bei Bedarf verarbeitet, erneut einfügt und ausführt. ESLint ist derzeit in der Spaghettify-Codebasis aktiviert und beim Erstellen des Projekts wird ein Linting-Audit ausgelöst. Sie können Ihre IDE so konfigurieren, dass beim Einführen von Änderungen automatisch eine Linting-Bewertung durchgeführt wird. Darüber hinaus können Sie Code-Linting jederzeit auslösen, indem Sie npm run lint oder yarn lint in Ihrer Terminalkonsole ausführen.
Sie können Tests in die Codebasis einführen oder die vorhandenen ausführen, indem Sie npm test oder yarn test in Ihrer Terminalkonsole ausführen. Codeabdeckungsdaten werden gesammelt und in einem bequem formatierten Dokument unter /coverage/lcov-report gespeichert. Für Abdeckungsberichte auf dem Bildschirm hängen Sie bitte den Parameter --coverage an den test an.
Sie können bei Coveralls auch online einen umfassenden Testabdeckungsbericht einsehen.
Copyright 2021 Pablo Deeleman
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.
