Buat Pembantu Bar Hendal Tersuai dalam Ghost!

Artikel ini adalah untuk ramai pembangun dan pencipta tema yang mendapati pembantu standard yang ditawarkan oleh Ghost (https://ghost.org/docs/themes/helpers/) tidak mencukupi. Adalah perkara biasa untuk mencari cara untuk melanjutkan keupayaan tema kami yang menggunakan Handlebars yang disediakan oleh Ghost. Sebelum menerbitkan artikel ini dan mencari penyelesaian untuk tema saya, saya mencari seluruh internet dan menjalankan analisis kod sumber Ghost sendiri.

Kaedah 1 (mengubah suai kod teras)

Saya mendapati bahawa adalah mungkin untuk melanjutkan kod sumber Ghost dengan pembantu tambahan. Saya mencapai ini dengan menambah direktori baharu dalam semasa/teras/depan/apl. Saya menggunakan contoh "apl" sedia ada yang dipanggil amp, yang kodnya sangat mudah, untuk mula mencipta pembantu baharu yang tersedia dalam tema. Dalam apl sedia ada ini, strukturnya adalah mudah kerana pembantu didaftarkan dalam lib/pembantu. Pada penghujung proses, anda perlu menambah nama direktori anda dalam apl pada current/core/shared/config/overrides.json dalam bahagian JSON apps.internal.

Contoh kandungan fail index.js dalam apl kami ialah:

const path = require('path');

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

Seterusnya, dalam direktori lib apl ini, kami mencipta folder bernama pembantu. Di dalam, kami mencipta fail baharu, yang akan menjadi nama pembantu yang akan dipanggil dalam templat Handlebars. Contohnya, mari namakan huruf besar.js.

Di bawah ialah contoh kod pembantu sedemikian, yang hanya menukar huruf teks yang diberikan dalam hujah pembantu kepada huruf besar:

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

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

Jangan lupa tambahkan nama direktori aplikasi pada current/core/shared/config/overrides.json. Selepas memulakan semula Ghost, semuanya harus sedia.

Kaedah 2 (tanpa mengubah suai kod teras)

Saya baru-baru ini membangunkan kaedah ini dan anda boleh menggunakannya bukan sahaja pada Ghost yang dihoskan sendiri tetapi juga pada contoh Ghost yang ditawarkan oleh penyedia pengehosan. Dalam kes kedua, ia memerlukan perancangan seni bina yang sesuai dan membeli pelayan kecil yang akan bertindak sebagai proksi untuk contoh Ghost terakhir anda.

Seni bina yang akan kami gunakan dalam kaedah ini:
Pelayan Nginx ← Perisian tengah Node.js ← Contoh hantu

Pelayar pengguna menghantar permintaan kepada pelayan Nginx, yang mengandungi huluan perisian tengah. Semua permintaan, tanpa mengira lokasi, akan diproksikan kepada perisian tengah.

Perisian tengah ialah pelayan Ekspres yang dijalankan dalam Node.js dengan pustaka express-http-proxy (https://github.com/villadora/express-http-proxy) tambahan, yang memudahkan kerja dengan ketara. Kami mengkonfigurasi proksi untuk berkomunikasi dengan contoh Ghost. Pustaka ekspres-http-proksi mempunyai sifat userResDecorator yang boleh kami gunakan untuk "menghiasi respons pelayan yang diproksi." Ringkasnya, kami boleh mengubah suai respons daripada Ghost sebelum menghantarnya ke penyemak imbas pengguna.

PenggunaResDecorator kami akan menjadi tidak segerak supaya tidak menyekat utas utama. Kami akan kembali kepada topik pemprosesan tak segerak semasa membuat pembantu. Buat masa ini, anda perlu tahu bahawa tidak semua permintaan pelayar pengguna perlu dihias. Oleh itu, langkah pertama ialah menyemak pengepala jenis kandungan respons daripada Ghost. Anda boleh melakukan ini seperti berikut dan kemudian bandingkan jika ia adalah teks/html untuk menghiasi hanya dokumen HTML yang dikembalikan kepada pengguna:

const path = require('path');

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

Dalam pernyataan bersyarat ini, kita boleh mula mengubah suai htmlKandungan, tetapi mengapa kita memerlukannya? Mari mulakan dengan membina asas untuk pembantu tersuai kami dalam tema Hantu!

Dalam artikel ini, saya akan mencipta pembantu tersuai dalam fail index.hbs (laman utama) tema saya. Di lokasi yang boleh dilihat dalam templat Handlebars, saya menambah contoh pembantu tersuai, menamakannya {{hello_world}}.

⚠️ Kemudian, saya meletakkannya di tempat yang boleh dilihat pada halaman utama — tetapi perhatikan apa yang berlaku apabila saya memuat semula halaman Hantu!

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

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

Dalam pembolehubah ini, kami mempunyai respons daripada contoh Ghost sebagai HTML penuh halaman. Bayangkan bahawa respons ini ialah halaman utama contoh Ghost anda. Kandungan HTML juga akan termasuk teks biasa kami {{hello_world}}, yang dipaparkan sebagai teks biasa. Jika pembantu tersuai kami ada dalam borang ini, kami boleh menyusunnya menggunakan Handlebars.js (https://handlebarsjs.com/) dalam middleware kami. Ingat untuk memasang perpustakaan terlebih dahulu melalui pengurus pakej, cth., npm: npm install hendal dan tambahkannya pada kod anda: const handlebars = require("handlebars");.

// 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;

Wah! Kami kini telah menyusun dan memberikan HTML menggunakan Handlebars.js — tetapi kami belum selesai lagi. Kami masih perlu mendaftarkan pembantu tersuai kami {{hello_world}}. Tambahkan kod berikut, sebaik-baiknya selepas memulakan Handlebars.js:

{{!< default}}
<div>



<p>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.</p>

<p>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.</p>

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

<pre class="brush:php;toolbar:false">let htmlContent = proxyResData.toString('utf8');

Selepas memulakan semula pelayan perisian tengah dan mendaftarkan pembantu di atas, anda seharusnya melihat pembantu yang diberikan dalam penyemak imbas dengan teks yang dikembalikan oleh pembantu kami serta tarikh dan masa semasa.

Pada peringkat ini, anda boleh melanjutkan tema Hantu anda dengan pembantu tersuai tambahan, yang akan anda tambahkan pada kod pelayan perisian tengah.

Keselamatan

Pada satu ketika, anda mungkin mahu memulangkan pelbagai perkara dengan pembantu anda. Secara lalai, pustaka melindungi daripada serangan XSS, tetapi apabila anda menggunakan kaedah SafeString, perlindungan ini berhenti berfungsi. Elakkan menggunakannya apabila boleh.

Perkara lain! Bayangkan pengguna menambah pembantu sedemikian di bahagian komen di bawah siaran dan menambah kandungan berniat jahat dalam parameter. Berhati-hati dengan keselamatan. Contohnya, jika anda memaparkan setiap HTML sepenuhnya, anda mungkin terdedah kepada serangan XSS. Adalah disyorkan untuk menyusun dan memaparkan Handlebars.js dalam kawasan tertutup yang khusus. Anda boleh menggunakan pustaka cheerio (https://cheerio.js.org/) untuk menghuraikan HTML dan memaparkan Handlebars jika perlu. Berikut ialah contoh cara anda boleh melindungi diri anda dengan mengubah suai kod pemaparan sebelumnya:

const path = require('path');

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

Ingat untuk menambah permulaan perpustakaan pada permulaan skrip anda: const asyncHelpers = require('handlebars-async-helpers');. Jika anda menghadapi masalah memasangnya disebabkan konflik versi antara hendal-async-helpers dan hendal, hanya turun taraf hendal kepada ^4.7.6. Malangnya, pustaka pembantu async telah lama tidak diselenggara, tetapi ia masih berfungsi dalam amalan.

Komunikasi Pangkalan Data dan Objek

Jika anda ingin membuat pertanyaan pangkalan data dalam Ghost untuk diambil, sebagai contoh, siaran semasa, ia mungkin dan tidak sukar. Anda boleh menggunakan perpustakaan seperti knex (https://knexjs.org/), yang merupakan pembina pertanyaan SQL yang jelas dan pantas. Ingat bahawa anda memerlukan bar hendal-async-helpers untuk ini. Konfigurasikan knex dengan betul untuk menyambung ke pangkalan data Ghost.

Mulakan knex sebagai pembolehubah db dan cuba kod berikut:

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

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

Kemudian, dalam templat post.hbs tema Hantu, tambahkan pembantu berikut: {{post_title uuid="{{uuid}}"}}. Dalam contoh ini, {{uuid}} akan diambil dan diluluskan sebagai pembantu yang tersedia dalam Ghost, mengisi medan uuid pembantu kami dan menyebabkan tajuk siaran dipaparkan oleh pembantu tersuai.

Anda juga boleh menggunakan axios untuk membuat permintaan HTTP kepada Ghost Content API, tetapi ini jauh lebih perlahan daripada komunikasi pangkalan data langsung.

Prestasi

Saya tahu bahawa penyelesaian berasaskan perisian tengah mungkin bukan yang terbaik dari segi kelajuan, tetapi saya secara peribadi menggunakan penyelesaian ini dan tidak menyedari penurunan ketara dalam masa muat halaman. Purata masa tindak balas untuk satu permintaan adalah di bawah 100ms (mengikut express-status-monitor), dan saya menggunakan pembantu tersuai yang mengambil beberapa nilai daripada pangkalan data pada setiap halaman.

Anda boleh, sudah tentu, menambah mekanisme caching untuk meningkatkan prestasi perisian tengah atau menggunakan penyelesaian alternatif dan bukannya proksi-http-ekspres.

Pelaksanaan Seni Bina

Gunakan Docker atau mekanisme kontena lain. Saya telah menggunakannya dalam projek saya, dan ia berfungsi dengan baik. Tambahkan Ghost dan imej pangkalan data untuk Ghost, Nginx dan imej Node.js. Sambungkan mereka ke rangkaian kongsi (pemandu: jambatan), konfigurasikan Nginx dan pelayan Node.js dengan sewajarnya — semuanya sangat mudah!

Atas ialah kandungan terperinci Buat Pembantu Bar Hendal Tersuai dalam Ghost!. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!