Dieser Artikel gilt für viele Entwickler und Themenschöpfer, die die von Ghost (https://ghost.org/docs/themes/helpers/) unzureichenden Helfer finden. Es ist völlig normal, nach Möglichkeiten zu suchen, um die Fähigkeiten unserer Themen zu erweitern, die von Ghost bereitgestellte Lenker verwenden. Bevor ich diesen Artikel veröffentlichte und eine Lösung für mein Thema fand, suchte ich das gesamte Internet und führte selbst eine Analyse von Ghosts Quellcode durch.

Methode 1 (Änderung des Kerncodes)

Ich habe festgestellt, dass es möglich ist, den Quellcode von Ghost mit zusätzlichen Helfern zu erweitern. Ich habe dies erreicht, indem ich ein neues Verzeichnis in aktuellen/Core/Frontend/Apps hinzugefügt habe. Ich habe das Beispiel einer vorhandenen „App“ namens AMP verwendet, deren Code sehr einfach ist, um einen neuen Helfer zu erstellen, der im Thema verfügbar ist. In diesen vorhandenen Apps ist die Struktur unkompliziert, da Helfer in LIB/Helpers registriert sind. Am Ende des Prozesses müssen Sie den Namen Ihres Verzeichnisses in Apps zu aktuellen/core/Shared/config/overrides.json in den Apps.internal JSON hinzufügen.

Ein Beispielinhalt der Index.js -Datei in unserer App wäre:

const path = require('path');

module.exports = {
    activate: function activate(ghost) {
        ghost.helperService.registerDir(path.resolve(__dirname, './lib/helpers'));
    }
};

Als nächstes erstellen wir im Lib -Verzeichnis dieser App einen Ordner namens Helpers. Im Inneren erstellen wir eine neue Datei, die der Name des Helfers ist, der in einer Lenkervorlage aufgerufen werden soll. Nennen wir es beispielsweise UPRACE.js.

unten finden Sie ein Beispiel für einen solchen Helfer -Code, der einfach die Buchstaben des angegebenen Textes im Helferargument in Großbuchstaben umwandelt:

const {SafeString, escapeExpression} = require('../../../../services/handlebars');

module.exports = function uppercase(text) {
    return `${text.toUpperCase()}`;
};

Vergessen Sie nicht, den Namen des Anwendungsverzeichnisses zu aktuellen/core/Shared/config/overrides.json hinzuzufügen. Nach dem Neustart des Ghost sollte alles fertig sein.

Methode 2 (ohne den Kerncode zu ändern)

Ich habe kürzlich diese Methode entwickelt, und Sie können sie nicht nur auf selbst gehostete Geister anwenden, sondern auch auf Ghost-Instanzen, die von Hosting-Anbietern angeboten werden. Im letzteren Fall erfordert es eine angemessene architektonische Planung und den Kauf eines kleinen Servers, der als Proxy für Ihre endgültige Geisterinstanz fungiert.

Die Architektur, die wir in dieser Methode verwenden:
Nginx Server ← node.js Middleware ← Ghostinstance

Der Browser des Benutzers sendet eine Anfrage an den Nginx -Server, der den vorgelagerten Middleware enthält. Alle Anfragen, unabhängig vom Ort, werden in die Middleware verwickelt.

Die Middleware ist ein Express-Server, der in node.js mit dem hinzugefügten Express-http-Proxy (https://github.com/villadora/express-http-Proxy) läuft, was die Arbeit erheblich vereinfacht. Wir konfigurieren den Proxy, um mit der Ghost -Instanz zu kommunizieren. Die Express-HTTP-Proxy-Bibliothek verfügt über eine USERRESDeCorator-Eigenschaft, mit der wir "die Antwort des Proxied-Servers dekorieren" können. Einfach ausgedrückt können wir die Antwort von Ghost ändern, bevor wir sie an den Browser des Benutzers senden.

Unser UserresDecorator ist asynchron, um den Haupt -Thread nicht zu blockieren. Beim Erstellen von Helfern werden wir zum Thema asynchroner Verarbeitung zurückkehren. Im Moment müssen Sie wissen, dass nicht alles, was die Browseranfragen des Benutzers dekorieren müssen, nicht alles ist. Daher besteht der erste Schritt darin, den Inhalts-Header der Antwort von Ghost zu überprüfen. Sie können dies wie folgt tun und dann vergleichen, ob es sich um Text/HTML handelt, um nur HTML -Dokumente zu dekorieren, die an den Benutzer zurückgegeben wurden:

// Where 'proxyRes' is your proxy response inside 'userResDecorator'
const contentType = proxyRes.headers['content-type'] || '';
if (!contentType.includes('text/html')) {
    // Return original content if response is not 'text/html'
    return proxyResData;
}

let htmlContent = proxyResData.toString('utf8');
// Do something with 'htmlContent' and return
return htmlContent;

In dieser bedingten Aussage können wir anfangen, htmlContent zu ändern, aber warum brauchen wir es? Beginnen wir damit, die Grundlage für unseren benutzerdefinierten Helfer im Ghost -Thema aufzubauen!

In diesem Artikel erstelle ich einen benutzerdefinierten Helfer in der Index.hbs -Datei (Homepage) meines Themas. In einem sichtbaren Ort in der Lenkervorlage füge ich einen benutzerdefinierten Helfer hinzu, der ihn benenne, {{hello_world}}.

⚠️ Dann platziere ich es an einer sichtbaren Stelle auf der Homepage - aber merke, was passiert, wenn ich die Geisterseite aktualisiere!

{{!



After refreshing, I get an error message from Ghost because the {{hello_world}} helper doesn’t exist in Ghost's default helpers. For our logic to work, we must escape this helper so that it’s not treated as a helper by Ghost’s built-in Handlebars.

The correct way is to write this helper as \{{hello_world}}. This way, Ghost treats it as plain text. After refreshing the Ghost homepage, you should see the plain text {{hello_world}}. If this happens, you are on the right track. Let’s now return to the middleware server file, where we will use the response decorator.

⚠️ Remember to escape custom helpers in your theme! Don’t forget to add the \ character.



let htmlContent = proxyResData.toString('utf8');




 In dieser Variablen haben wir die Antwort aus der Ghost -Instanz als vollständige HTML der Seite. Stellen Sie sich vor, diese Antwort ist die Homepage Ihrer Ghost -Instanz. Der HTML -Inhalt enthält auch unseren einfachen Text {{hello_world}}, der als einfacher Text angezeigt wird. Wenn sich unser benutzerdefinierter Helfer in diesem Formular befindet, können wir ihn mit Ladebars.js (https://handlebarsjs.com/) in unserer Middleware kompilieren. Denken Sie daran, die Bibliothek zuerst über einen Paketmanager zu installieren, z. B. NPM: NPM -Lenker und fügen Sie sie Ihrem Code hinzu: const talbars = fordert ("Lenker"); 



// Compile response HTML with Handlebars, and return rendered template
let htmlContent = proxyResData.toString('utf8');
const template = handlebars.compile(htmlContent);
htmlContent = template({});




Wow! Wir haben jetzt HTML mit Lenker zusammengestellt und gemacht - aber wir sind noch nicht fertig. Wir müssen noch unseren benutzerdefinierten Helfer {{Hello_world}} registrieren. Fügen Sie den folgenden Code hinzu, vorzugsweise nach der Initialisierung von Lenker. Js: 



// Returns 'Hello from middleware!' with the current timestamp
handlebars.registerHelper('hello_world', function (options) {
   return `Hello from middleware! ${new Date().toISOString()}`;
});




 Nach dem Neustart des Middleware -Servers und der Registrierung des oben genannten Helfer sollten Sie den gerenderten Helfer im Browser mit dem von unserem Helfer zurückgegebenen Text und dem aktuellen Datum und der aktuellen Zeit sehen. 

 In diesem Stadium können Sie Ihr Ghost -Thema mit zusätzlichen benutzerdefinierten Helfern erweitern, die Sie dem Middleware Server -Code hinzufügen. 


  
  
  Sicherheit


 Irgendwann möchten Sie vielleicht mit Ihren Helfern verschiedene Dinge zurückgeben. Standardmäßig schützt die Bibliothek vor XSS -Angriffen, aber wenn Sie die Safestring -Methode verwenden, funktioniert dieser Schutz nicht mehr. Vermeiden Sie es, wenn möglich zu verwenden. 

 eine andere Sache! Stellen Sie sich vor, ein Benutzer fügt einen solchen Helfer im Kommentarbereich unter einem Beitrag hinzu und fügt im Parameter böswillige Inhalte hinzu. Achten Sie auf die Sicherheit. Wenn Sie beispielsweise jede HTML vollständig rendern, können Sie für XSS -Angriffe anfällig sein. Es wird empfohlen, Lenker in bestimmten, geschlossenen Bereichen zu kompilieren und zu rendern. Sie können die Bibliothek von Cheerio (https://cheerio.js.org/) verwenden, um HTML zu analysieren und bei Bedarf Lenker zu rendern. Hier ist ein Beispiel dafür, wie Sie sich sicherstellen können, indem Sie den vorherigen Rendering -Code ändern: 



// Render handlebars only inside 
 with>



In this code, our custom helpers and Handlebars are rendered only within a 
 container with>


  
  
  Asynchronous Processing


If you intend to create dynamic helpers that return more complex data, you’ll probably need to implement asynchronous helpers in Handlebars over time. This is useful in cases like:


Fetching values from a database (e.g., Ghost database)
Sending API requests and processing their responses


You can use an extension called handlebars-async-helpers (https://www.npmjs.com/package/handlebars-async-helpers) for this purpose. It enables asynchronous operations in Handlebars.js, making potentially lengthy and dynamic tasks possible. Here’s a simple example of how you can implement asynchronous processing in your middleware:



// Register async helpers with Handlebars
const hb = asyncHelpers(handlebars);

hb.registerHelper('hello_world', async function (options) {
  // You can use await's here!
  // ...
});




 Denken Sie daran, die Bibliotheksinitialisierung zu Beginn Ihres Skripts hinzuzufügen: const asynchelpers = required ('landbars-async-helpers');. Wenn Sie auf Probleme stoßen, die es aufgrund von Versionskonflikten zwischen Lenker-Async-Helpern und Lenker installieren, stufen Sie einfach den Lenker auf ^4.7.6 herab. Leider ist die asynchrische Helferbibliothek seit einiger Zeit nicht mehr aufrechterhalten, aber es funktioniert immer noch in der Praxis. 


  
  
  Datenbankkommunikation und Objekte


 Wenn Sie Datenbankabfragen in Ghost erstellen möchten, um beispielsweise den aktuellen Beitrag zu holen, ist dies möglich und nicht schwierig. Sie können eine Bibliothek wie Knex (https://knexjs.org/) verwenden, ein klarer und schneller SQL -Query -Builder. Denken Sie daran, dass Sie dafür Lenker-Async-Helpers benötigen. Konfigurieren Sie Knex ordnungsgemäß, um eine Verbindung zur Datenbank von Ghost herzustellen. 

 Knex initialisieren Sie als DB -Variable und probieren Sie den folgenden Code aus: 



// Return current post title from database
hb.registerHelper('post_title', async function (options) {
  const uuid = options.hash.uuid;
  try {
    const { title } = await db("posts")
      .select("title")
      .where("uuid", uuid)
      .limit(1)
      .first();
    return title;
  } catch (error) { return `Error: ${error.message}`; }
});




 Dann fügen Sie in der Vorlage post.hbs des Ghost -Themas den folgenden Helfer hinzu: \ {{post_title uUid = "{{uUid}}"}}. In diesem Beispiel wird {{uUid}} abgerufen und als Helfer in Ghost übergeben, wodurch das UUID -Feld unseres Helfers füllt und den Posttitel vom benutzerdefinierten Helfer angezeigt wird. 

 Sie können auch Axios verwenden, um HTTP -Anfragen an die Ghost -Inhalts -API zu stellen, aber dies ist deutlich langsamer als die direkte Datenbankkommunikation. 


  
  
  Leistung


 Ich weiß, dass eine mittelwarebasierte Lösung in Bezug auf Geschwindigkeit möglicherweise nicht die beste ist, aber ich persönlich diese Lösung verwende und keinen signifikanten Rückgang der Seitenladungszeiten bemerkt habe. Die durchschnittliche Reaktionszeit für eine einzige Anfrage lag unter 100 ms (gemäß Express-Status-Monitor), und ich verwende einen benutzerdefinierten Helfer, der einige Werte aus der Datenbank auf jeder Seite abruft. 

 Sie können natürlich Caching-Mechanismen hinzufügen, um die Middleware-Leistung zu verbessern oder alternative Lösungen anstelle von Express-Http-Proxy zu verwenden. 


  
  
  Implementierung der Architektur


 Verwenden Sie Docker oder einen anderen Containerisierungsmechanismus. Ich habe es in meinem Projekt verwendet und es funktioniert großartig. Fügen Sie Ghost- und Datenbankbilder für Ghost, Nginx und ein Node.js -Bild hinzu. Verbinden Sie sie mit einem gemeinsam genutzten Netzwerk (Treiber: Bridge), konfigurieren Sie Nginx und den Node.js -Server entsprechend - alles ist sehr einfach!