Panini

平面檔案編譯器，為我們的原型範本提供動力。輕鬆建立具有相容版面和可重複使用部分的網頁。

如果您曾經建立過靜態網站，或許您有五個網頁都共用同一個頁首和頁尾。您建立第一個網頁，然後複製並貼上共用元素到下一個網頁。但現在，如果您需要變更頁首，則必須在多個檔案中進行變更。您也可以在活動中的電子郵件中執行此操作！

Panini 是一個平面檔案編譯器，它使用範本、網頁和部分的概念，並由 Handlebars 範本語言提供動力，以簡化建立靜態原型的流程。

我們的原型範本使用 Panini，以及其他處理 Sass 和影像的工具，讓建立最佳化的範本變得容易。它已經設定好使用以下所有功能，但如果您想了解如何設定函式庫的詳細資訊，請前往 Panini GitHub 頁面。

基礎：範本和網頁

範本是設計中每個網頁共用的共用版面。可以有多個範本，但通常您只需要一個，而且一個網頁只能使用一個範本。在原型範本中，預設版面位於 src/layouts/default.html 下。

以下是一個基本範本的範例

<html>
  <head>
    <title>Definitely an Email!</title>
  </head>
  <body>
    <header class="header"><!-- ... --></header>
    {{> body}}
    <footer class="footer"><!-- ... --></footer>
  </body>
</html>

HTML 中間有一點 Handlebars 程式碼：{{> body}}。這是當 Panini 執行時，您編寫的網頁會插入的地方，最後會提供一系列完整的 HTML 檔案。

網頁構成版面的主體。這些檔案只會有設計的中間部分，因為版面已經涵蓋頂部和底部。原型範本包含一個空白網頁讓您開始，位於 src/pages/index.html 下。

一個基本網頁可能如下所示

<h1>Page Title</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Praesentium ducimus eligendi, reiciendis corporis quam facere quaerat qui, aspernatur molestiae velit, vero ea quisquam laborum corrupti repudiandae totam, at aliquam esse.</p>

請注意，沒有 <html> 或 <body> 標籤，也沒有頁首或頁尾。當 Panini 組合您的網頁時，此程式碼會插入到 {{> body}} 宣告中。

在原型模板中，這些完成的文件會編譯成一個獨立資料夾，稱為 dist（「distribution」的縮寫），其中也包含處理過的 CSS、JavaScript 和圖片。這個資料夾可以輕鬆上傳到任何 ESP（電子郵件服務供應商）。

部分

部分是 Handlebars 的一個功能，允許你在頁面或版面中的任何地方插入 HTML。當你需要在頁面中重複某些程式碼區塊，或防止個別檔案因 HTML 而過於雜亂時，它們非常有用。

以下是將其關鍵部分分為部分的版面檔案範例

<html>
  <head>
    <title>Definitely STILL an Email!</title>
  </head>
  <body>
    {{> header}}
    {{> body}}
    {{> footer}}
  </body>
</html>

{{> }} 語法告訴 Handlebars 尋找具有該名稱的 HTML 檔案，並將其插入該位置。在此範例中，我們有稱為 header.html、navigation.html 和 footer.html 的檔案。在原型模板中，這些檔案都存在於 src/partials 中。

頁面變數

頁面有幾個內建變數，可以在頁面模板本身中使用，或與頁面串用的版面或部分中使用。

page

列印目前頁面的名稱，不含其原始檔案副檔名。在以下範例中，如果頁面是 index.html，{{page}} 將會變成 index。

<p>You are here: {{page}}</p>

root

在檔案路徑前使用 {{root}}，以確保它在目前頁面所在的資料夾中都能正常運作。

例如，如果目前頁面位於網站的根目錄或子資料夾中，則外部 CSS 檔案的路徑將需要有所不同。

以下是使用 <link> 標籤的方式

<link rel="stylesheet" href="{{root}}assets/css/app.css">

如果頁面是 index.html，路徑將如下所示

<link rel="stylesheet" href="assets/css/app.css">

如果頁面是 folder/page.html，路徑將如下所示

<link rel="stylesheet" href="../assets/css/app.css">

../ 僅新增在子資料夾中的頁面，因此 CSS 仍可以正確載入。

輔助函式

輔助函式是處理頁面內容的特殊函式。除了 Handlebars 的內建輔助函式之外，Panini 還包含一些自訂輔助函式，而且你可以新增自己的輔助函式。

ifpage

僅在特定頁面上顯示輔助函式內的 HTML。在以下範例中，輔助函式內的 HTML 將只會顯示在 index.html 頁面上。

{{#ifpage 'index'}}
  <p>This is definitely the Index page.</p>
{{/ifpage}}

你也可以檢查多個頁面。如果清單中的任何名稱與目前頁面相符，HTML 將會顯示。

{{#ifpage 'index' 'about'}}
  <p>This is definitely either the Index or About page.</p>
{{/ifpage}}

unlesspage

#ifpage 的相反，#unlesspage 僅會在目前頁面不在參數中時顯示其內的 HTML。

{{#unlesspage 'index'}}
  <p>This is definitely <em>not</em> the Index page.</p>
{{/unlesspage}}

repeat

重複其內部的內容 n 次。在原型中使用此功能可以輕鬆列印大量重複的 HTML。

<ul>
  {{#repeat 5}}
  <li>Five hundred ninety-nine US dollars</li>
  {{/repeat}}
</ul>

markdown

將 Markdown 轉換為 HTML。

{{#markdown}}
# Heading 1
Lorem ipsum [dolor sit amet](https://html5zombo.com), consectetur adipisicing elit. Nam dolor, perferendis. Mollitia aut dolorum, est amet libero eos ad facere pariatur, ullam dolorem similique fugit, debitis impedit, eligendi officiis dolores.
{{/markdown}}

自訂輔助函式

如果您找不到合適的輔助函式，您可以自行撰寫。將 JavaScript 檔案新增至「src/helpers」，重新啟動 npm，然後在範本中呼叫它。

// Example file src/helpers/bold.js
module.exports = function(options) {
  // options.fn(this) = Handlebars content between {{#bold}} HERE {{/bold}}
  var bolder = '<strong>' + options.fn(this) + '</strong>';
  return bolder;
}

然後在您的專案中呼叫自訂的 {{#bold}} 輔助函式

{{#bold}}ideas{{/bold}}

自訂資料

可以將自訂資料新增至您的網頁。然後，您可以透過 Handlebars 將這些資料插入 HTML 中。有兩種方式可以將資料新增至專案。

若要僅將變數新增至特定網頁，請將其新增至網頁 HTML 的最上方，作為 Front Matter 區塊。假設以下內容位於 src/pages/index.html 內。

---
title: Page Title
description: Lorem ipsum.
---

<!-- The rest of your HTML is down here. -->

現在，您可以將這些變數的值插入 index.html 網頁或default.html 版面。若要插入變數，請將變數名稱用雙大括號括起來，如下所示

<h1>{{ title }}</h1>

也可以透過建立外部 JSON 或 YML 檔案，並將其新增至專案中的 src/data 資料夾，來全域新增變數。我們來建立一個名為 breakfast.yml 的檔案

- eggs
- bacon
- toast

Panini 會將此 YML 檔案的內容載入為名為 {{ breakfast }} 的變數。由於它是一個陣列，因此我們可以使用 Handlebars 的 {{#each}} 輔助函式來迴圈瀏覽它

<ul class="breakfast-items">
  {{#each breakfast}}
    <li>{{ this }}</li>
  {{/each}}
</ul>

這段程式碼會列印三個 <li>，每個檔案中的項目一個。

教學課程

保持 D.R.Y. 的 Panini Panini 內建許多 Handlebars 輔助函式，例如重複輔助函式或 Markdown 解析器，但在本課程中，我們將了解如何為 HTML 電子郵件建立自訂的月份/年份輔助函式。