第十章：後端擴充性：Add-ons 與進階 Skin

雖然 MoriForms 的核心是透過 JSON 和前端 Skin 來運作，但我們深知，在真實的專案中，總會有一些需求是僅靠前端技術無法或不應解決的。例如，與其他 WordPress 插件的資料庫進行安全交互、執行複雜的伺服器端運算、或是在資料儲存的生命週期中注入自訂邏輯。

為此，MoriForms 提供了兩種層級分明、功能強大的後端擴充機制。理解它們各自的適用場景，是成為 MoriForms 專家的關鍵一步。

1. Add-on 插件 (推薦方式): 用於建立可重用、與外觀無關的通用功能。這是最專業、最安全的擴充方式。
2. Skin 的 functions.php (進階方式): 用於實現與特定 Skin 外觀強烈綁定的輔助性功能。

本章將深入探討這兩種機制，並指導您何時以及如何使用它們。

1. 主要擴充方式：建立 Add-on 插件

當您需要的功能是通用的、可以和任何 Skin 搭配使用的，那麼建立一個獨立的 Add-on 插件是官方推薦的最佳實踐。

適用情境：

• 將提交的資料同步到第三方 CRM 或電子報服務 (如 Mailchimp)。
• 整合進階的垃圾訊息過濾器 (如 Akismet)。
• 在表單提交後，自動在另一個自訂文章類型中建立一篇文章。
• 實現任何與特定外觀無關的商業邏輯。

Add-on 的核心是利用 MoriForms 引擎提供的一系列全域勾點 (Hooks)，這些勾點在您專案的內部開發規格文件中有詳細定義。

實戰範例：建立一個「簡易 CRM 同步」Add-on

讓我們來建立一個簡單的 Add-on。當一個特定的「聯絡我們」表單被提交後，它會模擬一次 API 呼叫，將使用者姓名和 Email 傳送到外部 CRM 系統。

1. 建立插件檔案： 在您的 wp-content/plugins 目錄下，建立一個名為 moriforms-simple-crm 的資料夾，並在其中建立一個檔案 moriforms-simple-crm.php。

2. 撰寫插件程式碼： 打開 moriforms-simple-crm.php 並貼上以下內容：

   PHP

   <?php
   /**
    * Plugin Name: MoriForms - Simple CRM Sync
    * Description: An add-on for MoriForms that syncs new submissions to a fake CRM.
    * Version: 1.0.0
    * Author: Your Name
    */
   
   // 防止直接存取
   if (!defined('ABSPATH')) {
       exit;
   }
   
   // 1. 先檢查 MoriForms 主插件是否存在並啟用
   add_action('plugins_loaded', 'moriforms_simple_crm_init');
   
   function moriforms_simple_crm_init() {
       if (!class_exists('MoriForms_Engine')) {
           // 如果主插件未啟用，則不執行任何操作
           return;
       }
   
       // 2. 將我們的核心邏輯掛載到 MoriForms 最重要的 Action Hook 上
       add_action('moriforms_after_submission_saved', 'moriforms_sync_to_crm', 10, 3);
   }
   
   /**
    * 將提交的資料同步到 CRM。
    *
    * @param int    $submission_id  新建立的提交紀錄 ID。
    * @param array  $validated_data 已通過伺服器驗證的表單資料。
    * @param object $form_schema    該表單的完整 Schema 物件。
    */
   function moriforms_sync_to_crm($submission_id, $validated_data, $form_schema) {
   
       // 3. 檢查是否為我們感興趣的表單，避免所有表單都觸發
       if ($form_schema->formName !== '極簡聯絡表單') {
           return;
       }
   
       // 4. 從驗證後的資料中取得姓名和 Email
       $name = $validated_data['customer_name'] ?? null;
       $email = $validated_data['customer_email'] ?? null;
   
       if (!$name || !$email) {
           return; // 如果缺少必要資料，則中止
       }
   
       // 5. 模擬一次對外部 CRM API 的呼叫
       $crm_endpoint = 'https://api.fake-crm.com/leads';
       $response = wp_remote_post($crm_endpoint, [
           'method'    => 'POST',
           'headers'   => ['Content-Type' => 'application/json'],
           'body'      => json_encode([
               'name'  => $name,
               'email' => $email,
               'source'=> 'MoriForms Submission #' . $submission_id
           ]),
       ]);
   
       // (可選) 根據回應結果，在 MoriForms 的日誌中記錄操作
       if (is_wp_error($response)) {
           error_log('MoriForms CRM Sync Failed: ' . $response->get_error_message());
       }
   }
   

3. 啟用與測試： 到 WordPress 後台的「外掛」頁面啟用 "MoriForms - Simple CRM Sync"。現在，每當「極簡聯絡表單」被成功提交後，上述的 moriforms_sync_to_crm 函數就會被自動觸發。

2. 進階擴充方式：使用 Skin 的 functions.php

這是一個可選的、專為進階 Skin 設計的便利工具，它允許 Skin 捆綁一些與自身外觀或功能強烈相關的 PHP 邏輯。

安全性第一 (Security First) MoriForms 引擎會對 Skin 包中的 functions.php 檔案執行嚴格的安全掃描。任何可疑的程式碼，如 eval()、file_put_contents() 或直接存取 $_POST 等，都會導致 Skin 安裝失敗。此檔案只應用於實現與外觀相關的輔助功能。

適用情境：

• 動態產生一個 select 欄位的選項（例如，從 WordPress 的文章分類中讀取）。
• 為您的 template.html 提供自訂的、僅此 Skin 使用的模板佔位符 (Tokens)。

實戰範例：為模板新增一個「問候語」佔位符

我們在第九章中介紹過，可以使用 moriforms_template_tokens 這個 Filter 來新增自訂佔位符。這正是 functions.php 的完美應用場景。

1. 在 Skin 中建立 functions.php： 在您的 minimalist-contact Skin 資料夾中，建立 functions.php 檔案。

   PHP (functions.php)

   <?php
   if (!defined('ABSPATH')) exit;
   
   /**
    * 為模板提供一個動態的問候語。
    * @return string
    */
   function minimalist_contact_get_greeting() {
       if (is_user_logged_in()) {
           $user = wp_get_current_user();
           return '歡迎回來，' . esc_html($user->display_name) . '！';
       }
       return '歡迎訪客！';
   }
   
   /**
    * 將問候語註冊為一個模板佔位符。
    */
   add_filter('moriforms_template_tokens', function($tokens, $form_id) {
       // 我們將 {{greeting_message}} 這個佔位符，賦值為上面函數的執行結果
       $tokens['{{greeting_message}}'] = minimalist_contact_get_greeting();
       return $tokens;
   }, 10, 2);
   

2. 在 template.html 中使用它： 現在，您可以直接在您的 template.html 中使用這個新的佔位符。

   HTML (template.html)

   <div id="{{container_id}}" class="minimalist-contact-wrapper">
       <h2>{{greeting_message}}</h2>
       <div class="form-messages" role="alert"></div>
       </div>
   

MoriForms 引擎在渲染模板時，會自動找到並替換這個佔位符。

總結：如何選擇正確的擴充路徑

下一步

恭喜您完成了 MoriForms 開發者文件的核心學習部分！從核心理念、Schema 設計、Skin 開發，到前後端的互動與擴充，您已經掌握了使用 MoriForms 打造專業級表單所需的全方位知識。