第二章：核心概念

在我們動手打造第一個 Skin 之前，理解 MoriForms 的三大核心支柱以及它們之間如何協同工作至關重要。這將為您後續的開發工作建立一個清晰的心智模型。

三大支柱 (The Three Pillars)

您可以將 MoriForms 的每一次表單運作，想像成三個緊密協作的元件：

1. Form Schema (表單藍圖 - The Blueprint)
   • 它的角色： 這是表單的「靈魂」與「大腦」。它是一份純粹的、結構化的資料藍圖，與外觀無關。
   • 它的實體： 一個遵循我們所定義的 Schema 2.0 規範的 JSON 檔案。
   • 它的職責：
     • 定義表單包含哪些欄位 (layout)。
     • 描述欄位的驗證規則 (validation)。
     • 設定所有複雜的顯示/隱藏條件 (conditions)。
     • 規劃提交成功後要執行的所有動作 (actions)。
   • 核心特性： 它具有絕佳的 可攜性 。您可以輕易地複製這份 JSON，在另一個同樣使用 MoriForms 的網站上建立一個一模一樣的表單，而無需遷移資料庫。
2. Skin (外觀與互動 - The Body)
   • 它的角色： 這是表單的「身體」與「面孔」，負責使用者看到和互動的一切。
   • 它的實體： 一個自給自足的檔案包，包含 template.html, main.css, main.js，以及圖片、字體等前端資源。
   • 它的職責：
     • 接收來自引擎的 Form Schema JSON 資料。
     • 根據 JSON 資料，動態地渲染出 HTML 介面。
     • 使用 CSS 和圖片資源為表單賦予獨特的視覺風格。
     • 透過 JavaScript 處理所有前端的互動邏輯，例如步驟切換、動畫效果、即時驗證回饋等。
   • 核心特性： Skin 本身是 無狀態的 (Stateless) 。它只是一個渲染器和互動處理器，直到被賦予一份 Form Schema JSON 後，它才知道自己該長什麼樣子、該如何運作。
3. Engine (後端引擎 - The Engine)
   • 它的角色： 這是連接「藍圖」與「身體」的「中樞神經系統」，是整個系統的無名英雄。
   • 它的實體： MoriForms 插件本身的核心 PHP 程式碼。
   • 它的職責：
     • 提供 WordPress 後台界面，讓您管理所有的 Form Schemas 和 Skins。
     • 解析頁面中的短代碼 [moriforms id="123"]。
     • 從資料庫中提取對應的 Form Schema JSON，並將其安全地注入到前端頁面。
     • 提供一個安全的 REST API 端點，用於接收前端 Skin 提交的資料。
     • 在伺服器端對提交的資料進行最終的、最嚴格的驗證。
     • 執行 Form Schema 中定義的提交後動作（如發送 Email）。
     • 將通過驗證的提交資料安全地存入資料庫。
   • 核心特性： 它是協調者與 守門員 ，確保資料在前後端之間順暢且安全地流動。

資料流程：從定義到提交的生命週期

了解這三大支柱後，我們可以將一次完整的表單互動串聯起來：

1. 定義階段 (Definition - 後台): 管理員在 WordPress 後台，透過以下兩種方式之一來賦予表單生命：

   • 主要流程 (推薦): 管理員在 MoriForms > Skins 中上傳一個捆綁了 schema.json 的 Skin 包。MoriForms Engine 會自動安裝 Skin，並根據附帶的 Schema 藍圖，建立一個無需額外設定、功能完整的「MoriForms 表單」。這個流程完美體現了 Skin 的可攜性與自給自足的特性。
   • 手動流程 (進階): 或者，管理員也可以在 MoriForms > 新增表單 中手動建立一個表單，將 Form Schema JSON 這個「唯一事實來源」貼入內容區。接著，從已安裝的 Skins 列表中，為這個表單手動選擇一個適用的外觀。這個流程提供了更高的彈性，適用於需要為單一 Schema 快速切換不同 Skin 的開發場景。

2. 渲染階段 (Rendering - 前端頁面載入):

   • 使用者訪問含有 [moriforms id="123"] 短代碼的頁面。
   • Engine 捕捉到短代碼，從資料庫讀取 ID 為 123 的表單定義 (JSON) 和其選擇的 Skin。
   • Engine 根據 Skin 的 manifest.json，將必要的 CSS 和 JS 檔案排入頁面佇列。
   • Engine 將完整的 Form Schema JSON 作為一個 JavaScript 物件，傳遞給 Skin 的主 JS 檔案。
   • Engine 讀取 Skin 的 template.html 檔案內容作為 HTML 骨架，並用動態資料（如表單容器 ID）替換掉模板中的佔位符，最後將完整的 HTML 渲染到頁面上。

3. 互動階段 (Interaction - 使用者操作):

   • 頁面載入完畢，Skin 的 main.js 開始執行。
   • main.js 讀取 Engine 傳遞過來的 JSON 物件。
   • main.js 開始動態地在 HTML 容器中建立表單欄位、按鈕和互動元素。
   • 使用者開始填寫表單，main.js 根據 conditions 規則即時更新 UI（例如顯示/隱藏相關欄位）。

4. 提交階段 (Submission - 前端發送資料):

   • 使用者點擊「送出」按鈕。
   • Skin 的 main.js 收集所有欄位的資料，打包成一個「提交資料 JSON」。
   • main.js 向 Engine 提供的 REST API 端點發起一個 POST 請求，並附上 Nonce 安全權杖和提交資料。

5. 處理階段 (Processing - 後端接收資料):

   • Engine 的 API 端點接收到請求。
   • 它首先進行安全檢查（Nonce、權限等）。
   • 接著，它根據儲存在資料庫中的原始 Form Schema JSON，對前端提交來的資料進行 伺服器端驗證 。
   • 如果驗證失敗，Engine 立刻回傳一個 400 錯誤，其中包含詳細的欄位錯誤資訊。
   • 如果驗證成功，Engine 將提交的資料存入資料庫，並執行 actions 中定義的動作（如發送 Email）。

6. 回應階段 (Response - 後端回傳結果):

   • 動作執行完畢後，Engine 回傳一個 200 OK 成功訊息。
   • 回應內容會告訴 Skin 下一步該做什麼（例如，顯示一段成功文字或重定向到感謝頁面）。
   • Skin 的 main.js 接收到成功回應，並據此更新使用者介面，完成整個流程。

下一步

現在，您已經對 MoriForms 的內部運作有了一個清晰的藍圖。在下一章，我們將不再紙上談兵，而是親自動手，一步步地帶您創建並安裝您的第一個功能完整的 Skin。