Drupal 模組介紹

Drupal 聯絡表單

Webform

安裝 webform
modi webform 
drush en webform_ui
modi token

在 <site>/admin/structure/webform/manage/contact 中增減元素 (Elements)，最重要的是 KEY 名稱可作為郵件內容。
另外可以修改是否顯示 Title 或 Placeholder (欄位中預先顯示該項目的文字)。

在 <site>/admin/structure/webform/manage/contact/handlers 中已內建 Email notification 為收到留言的電子郵件處理程序 ，Email confirmation 為自動回覆的電子郵件處理程序。
Email notification 或 Email confirmation 的項目中按下 Edit 後，在右邊的 Edit Email notification handler 窗格為主要設定的頁面。

Email notification (收到留言的電子郵件處理程序)
Edit Email confirmation handler
To email

[site:mail] (留言者傳送給網站郵件地址設定為 site:mail)

From email

Your Email (email) (contact 的 Elements 為留言者 email)

From name

Your Name (name) (郵件地址的前面的名稱為留言者姓名)

Subject (郵件主題)

Custom subject…

來自 [webform_submission:values:name] 的聯絡單 (1)
1 採用 [webform_submission:values:?] 的 token 格式來取得內容， 如 ? 為 name 是在 contact 的 Elements 中的 KEY。
Body (內容)

Custom body…

聯絡姓名:
[webform_submission:values:name]

聯絡信箱:
[webform_submission:values:email]

留言訊息:
[webform_submission:values:message]
Email confirmation (自動回覆的電子郵件處理程序)
Edit Email confirmation handler
To email

Your Email (email) (contact 的 Elements 為留言者 email)

From email

[site:mail] (網站傳送給留言者郵件地址設定為 site:mail)

From name

[site:name] (傳送給留言者郵件地址的前面的名稱為 site:name)

Subject (郵件主題)

Custom subject…

感謝您聯絡我們
Body (內容)

Custom body…

自行發揮

註：(E-mail 的) From email 已由 webform 中設定，在下列的模組中可忽略 From name。

Mail 模組

安裝 Mail 基本模組
modi mailsystem  (1)
modi mimemail  (2)
1 Mail System 可配置郵件格式及發送模組。
2 發送帶有嵌入式圖像和附件的 MIME 編碼的電子郵件。
Mail System 配置
<site>/admin/config/system/mailsystem
DEFAULT MAIL SYSTEM
Formatter (郵件格式)

Mime Mail mailer

Sender (郵件發送模組)

PHPMailer SMTP (支援 ssl 可發送至 Gmail)
SMTP Mailer (同上)
Maillog Mail-Plugin (用於測試發送的內容是否正確)

安裝 Mail 測試模組，可在不實際傳送郵件的情況，由記錄檔得知傳送情況
安裝 Mail 測試模組，取一安裝即可。
modi mail_safety  (1)
modi maillog
1 建議安裝 Mail Safety 可在傳送外送信件時一併記錄。
測試聯絡表單

如果是安裝 Maillog 在 <site>/admin/config/system/mailsystem 將 Sender 設為 Maillog Mail-Plugin，若安裝 mail_safety 則不需要更改。

Mail Safety 組態
<site>/admin/config/development/mail_safety/settings
Settings

  • Stop outgoing mails (停止外送郵件，要外送郵件時記得取消)

  • Send mail to dashboard (將外送郵件記錄儲存至 dashboard)

進入 <site>/webform/contact/test 網頁發送測試留言，在 <site>/admin/config/development/mail_safety 查看結果。

Maillog 組態
<site>/admin/config/development/maillog
Maillog Settings

  • Allow the e-mails to be sent.

  • Create table entries in maillog table for each e-mail.

  • Display the e-mails on page.

進入 <site>/webform/contact/test 網頁發送測試留言，在 <site>/admin/reports/maillog 查看結果。

安裝 SMTP 模組，以下取一即可。

PHPMailer SMTP
安裝 PHPMailer SMTP
modi phpmailer_smtp
PHPMailer SMTP 組態
<site>/admin/config/system/phpmailer-smtp
Configure the PHPMailer SMTP module
Primary SMTP server

smtp.gmail.com

SMTP port

465

Use secure protocol

SSL

SMTP AUTHENTICATION
Username

Gmail 帳號

Change password

Gmail 密碼

記得在 <site>/admin/config/system/mailsystem 將 Sender 設為 PHPMailer SMTP。

SMTP Authentication Support
安裝 SMTP Authentication Support
modi smtp
SMTP 組態
<site>/admin/config/system/smtp
SMTP Authentication Support
SMTP SERVER SETTINGS
SMTP server

smtp.gmail.com

SMTP port

465

Use encrypted protocol

Use SSL

Enable TLS encryption automatically

On

SMTP AUTHENTICATION
Username

Gmail 帳號

Password

Gmail 密碼

E-MAIL OPTIONS
E-mail from address

Gmail 帳號

註：本頁上方有 Disabled fields are overridden in site-specific configuration file 的訊息，可忽略它。

記得在 <site>/admin/config/system/mailsystem 將 Sender 設為 SMTP Mailer。

Gmail 組態
https://myaccount.google.com/security (登錄帳戶後，每個帳戶的網址都一樣)
低安全性應用程式存取權

開啟

如何將聯絡表單加入頁面

  1. 在 <site>/admin/structure/block 中，按下 Place block。

  2. 出現 Place block 窗格中選取 Webform 按下 Place block。

  3. 出現 Configure block 窗格中的 Webform 輸入 Contact。

另一個方法是直接採用 Webform 的預設連結。在 <site>/admin/structure/webform/manage/contact/settings 中 URL PATH SETTINGS 中的 Webform URL alias 已預設 /form/contact。

Captcha

modi recaptcha_v3 
# The following module(s) will be enabled: recaptcha_v3, captcha (1)
modi image_captcha (2)
1 自動加裝 captcha (CAPTCHA)
2 drupal 官方沒有 image_captcha 的網頁，只在上面的 CAPTCHA 網頁中提到了 Image CAPTCHA refresh ，網頁中：
Drupal 8

This module is going to be part of CAPTCHA module, see https://www.drupal.org/node/2608540 for updates.

https://www.drupal.org/node/2608540
Version:
8.x-1.x-dev
Component:
Image Captcha (image_captcha)

image_captcha 模組，在 Drupal 8 / 9 測試正常。
設定 reCAPTCHA v3
<site>/admin/config/people/captcha/recaptcha-v3
reCAPTCHA v3 settings Add to Default shortcuts
Site key

輸入註冊 reCAPTCHA v3 的金鑰

Secret key

輸入 reCAPTCHA v3 密鑰

Add reCAPTCHA v3 action
<site>/admin/config/people/captcha/recaptcha-v3-actions/add
Add reCAPTCHA v3 action
Label

Contact message

Threshold

1
0.5 至 1.0 表示可能是人類，人類分數為 1 的情況應該很少，會驗證失敗，可用來測試驗證失敗的情況。

Fallback challenge

Image (from module image_captcha)
驗證失敗時的備援機制，reCAPTCHA v3 驗證失敗除了 Image Captcha 亦可採用 reCAPTCHA (v2) 。

<site>/admin/config/people/captcha
CAPTCHA settings
Persistence
Always add a challenge

採用本選項，運作才會合乎預期，但缺點是在每次都會驗證，如在 reCAPTCHA v3 驗證失敗 (人類分數為 1) 的情況下；預覽 留言需輸入圖形碼， 上一頁 再次 預覽 時需再輸入一次。

Omit challenges in a multi-step/preview workflow once the user successfully responds to a challenge.

成功驗證後，可在多步驟 / 預覽工作流程中省略驗證。
但實測結果並不正常，在內部網段 reCAPTCHA 已提示下列：

網站擁有者請注意以下錯誤：
網站金鑰的網域無效

如果之前有 (以實際的外部網址) 成功驗證過，那麼將不會再執行圖形驗證。

測試時最好每次在 <site>/admin/config/people/captcha 執行 Clear the CAPTCHA placement cache 並且在 CLI 執行 drush cr 才不會誤判。

將 聯絡表單 (contact) 加入 Captcha 的功能
<site>/admin/structure/webform/manage/contact
Contact

+Add element

按下按鈕後出現 Select an element
Select an element

CAPTCHA Add element

再來選擇 recaptcha_v3
Add CAPTCHA element
Challenge type

contact_message (from module recaptcha_v3)

Save

按下按鈕 Save 後，會出現 [captcha] 的欄位，之後別忘了按下 Save elements 按鈕。

Save elements

Honeypot & Antibot

modi honeypot  (1)
modi antibot  (2)
1 設定時間限制，防止大量垃圾留言，若已採用 reCAPTCHA 應該不需要 Honeypot。
2 要求啟用 JavaScript 才能使用表單，Google reCAPTCHA 需要 JavaScript 應安裝。
Honeypot 配置
<site>/admin/config/content/honeypot
Honeypot configuration

  • Log blocked form submissions (如果想了解垃圾郵件機器人試圖提交多少，可啟用本功能)

    Honeypot element name

    myhoneypot (Honeypot 元素名稱，任意命名跟欄位名稱不會重複的名稱)

Honeypot time limit

5 seconds

將 聯絡表單 (contact) 啟用 Honeypot 及 Antibot 的功能
<site>/admin/structure/webform/manage/contact/settings
Contact
THIRD PARTY SETTINGS
ANTIBOT

  • Protect Contact webform with Antibot

HONEYPOT

  • Protect Contact webform with Honeypot

  • Add time restriction to Contact webform

Webform libraries

當瀏覽 Webform 的網頁時，可能會發現某些 css js 是存取外部的 cdn 如下
<link rel="stylesheet" media="all" href="https://cdn.jsdelivr.net/gh/NigelOToole/progress-tracker@v2.0.6/docs/styles/progress-tracker.css" />
另外在 <site>/admin/reports/status 中亦可發現 Drupal 已經警告
WEBFORM: EXTERNAL LIBRARIES 19 libraries (0 installed; 2 excluded; 17 CDN)
WEBFORM: PRIVATE FILES Private file system is not set.

Webform 模組附帶了一個 composer.libraries.json 檔案，其中包含有關模組本身所需的所有最新函式庫的資訊，可以通過合併 composer.libraries 來安裝。合併是通過 GitHub 上提供的 Composer Merge Plugin 的外掛來完成。

取得 Webform libraries 及安裝外掛
# 切換至站台的根目錄
cd /var/www/$site

drush webform:libraries:composer > composer.libraries.json (1)
composer require wikimedia/composer-merge-plugin (2)
1 下載檔案的模組版本比 <site>/modules/contrib/webform/composer.libraries.json 還新，而且版本跟 <site>/admin/reports/status 一致，這表示要更新該檔案。
2 安裝 Composer Merge Plugin 外掛。
編輯 <site>\composer.json
"extra": {
"merge-plugin": { (1)
            "include": [
                "composer.libraries.json" (2)
            ]
        }, (1)
        "drupal-scaffold": {
         ...
1 找出 "extra" 插入本段。
2 下載檔案的位置 (站台路徑的相對位置)，以本例而言下載位置為 /var/www/$site/composer.libraries.json。
更新函數庫
composer update --lock (1)
drush cr (2)
1 採用 --lock 參數，根據 composer.json 的修改情況來異動 composer.lock 檔案並安裝新模組 (不會更新現有模組)。
2 如果未執行，並不會使用函數庫，可發現 Webform 的網頁的 css js 存取外部的 cdn。

Private file system

進入網頁 <site>/admin/config/media/file-system 看一下內容

File system
Public file system path

sites/default/files

即然 sites/default/files 是公開目錄，那麼在其他目錄建立一個 private

mkdir sites/default/private

在 $site/sites/default/settings.php 檔案中加入下列

$settings['file_private_path'] = 'sites/default/private';
References

Webform Libraries
How to use composer to install libraries for the Webform module

Admin Toolbar

Admin Toolbar 

modi admin_toolbar
drush en admin_toolbar_tools -y
chwww .

Easy Breadcrumb

URL 的架構合乎 hierarchy (階層) Breadcrumb 就能正確運作。
root/cat
root/cat/content-page.html
index.html 的問題
root/cat/index.html (1)
root/cat/content-page.html
1 index.html 的架構可能比較完美，但 Drupal Breadcrumb 無法處理，「類別」的 URL 只能為路徑不能為頁面。

Drupal 內建的 Breadcrumb 會顯示 首頁 也沒有組態功能，加裝 Easy Breadcrumb 才能不顯示 首頁。

在 Configuration 點選 Easy Breadcrumb 進入
<site>/admin/config/user-interface/easy-breadcrumb
Easy Breadcrumb
GENERAL SETTINGS

  • Include the current page as a segment in the breadcrumb

  • Use the real page title when available

ADVANCED SETTINGS

Paths to be excluded while generating segments
若可以應採用 Block layout  Breadcrumbs (<site>/admin/structure/block/manage/bootstrap_custom_breadcrumbs) 中的 Pages 來限制顯示 Breadcrumb 頁面。

安裝 Easy Breadcrumb
modi easy_breadcrumb

Block Classes

安裝 Block Classes ，可在 Block 項目可設定 CSS class，多個 class 以空白字元分開。

<site>/admin/structure/block 選取任意 Block
Configure block
Title CSS class(es)

class1 class2

Content CSS class(es)

class1 class2

Block CSS class(es)

class1 class2

modi block_classes

Lazy-load

Lazy-load 可延遲加載 圖像 和 iframe，說明參閱： How to enable lazy-loading for inline-images and iframes?

<site>/admin/config/content/formats 選取一個要延遲加載 format

  • Lazy-load images and iframes

modi lazy
# mkdir -p /var/www/$site/libraries
cd /var/www/$site/libraries
sudo apt install git -y
git clone https://github.com/aFarkas/lazysizes.git lazysizes
chwww .

Advanced CSS/JS Aggregation

<site>/admin/config/development/performance/advagg
AdvAgg: Configuration
AdvAgg Cache Settings

High

CSS OPTIONS

  • Fix improperly set type

JS OPTIONS

  • Fix improperly set type

Advanced CSS/JS Aggregation 實測結果感覺比 Drupal 內建的 <site>/admin/config/development/performance 啟用 Aggregate CSS files / Aggregate JavaScript file 慢， 有空再測試吧。另外，會出現 Source Map 錯誤 bootstrap.min.css.map: HTTP error: status code 404，暫不處理。

composer require drupal/ctools drupal/token
modi advagg

Simple XML sitemap

<site>/admin/structure/types 選取 edit
Simple XML Sitemap
Sitemap variants (將 DEFAULT 展開 )

  • Index entities of type <Content type> in variant Default

採用 drush 產生 sitemap
drush simple-sitemap:generate

Simple XML sitemap 的 <site>/sitemap.xml 支援多國，sitemap.xml 出現了 en 可用 Disable language 來解決。

modi simple_sitemap

XML sitemap

modi xmlsitemap
<site>/admin/config/search/xmlsitemap/entities/settings
Custom Entities Settings
Custom sitemap entities settings

  • Content

  • Custom menu link …​

當選取了 Content 時，則畫面會增加 Content 的 CONTENT TYPE。

CONTENT TYPE

  • Article Config

  • Basic page

按下 Config 按鈕，設置 Included。

article XML sitemap settings
Inclusion

Included (預設是 Excluded)

Save configuration

<site>/admin/config/search/xmlsitemap
XML sitemap

已經預設了一個 XMLSITEMAP 按下 Edit

Edit XML sitemap
Label

http://default

Language

Chinese, Traditional

save

XML sitemap 沒有多國語言。

採用 drush 產生 sitemap
drush xmlsitemap:rebuild

Toc.js

Toc.js 可建立一個 Block 顯示文章中的 Toc，缺點是不區分 H2、H3…​，ToC 只有一層。

<site>/admin/structure/block 按下 Place block 選取 Toc.js block
Configure block

Title *
Toc.js block

  • Display title (取消 Toc.js block 標題)
    Title
    Table of content (英文標題，多國語言以 Translate block 修改)

  • Sticky

    Content types (選取要產生 ToC 的類型)

    • Article

cd /var/www/$site
mkdir -p libraries/toc
curl https://raw.githubusercontent.com/jgallen23/toc/greenkeeper/update-all/dist/toc.min.js > libraries/toc/toc.min.js
modi toc_js
目錄模組比較

Comparison of Table of Contents / TOC modules | Drupal.org

TOC filter

TOC filter 需在文章內容加入 [toc]，雖然可運作，但如果要在另一個 Block 顯示，卻跟 Block 的區域有關，如果要在文章之前的區塊，如 Sidebar First 顯示，那麼 ToC 的內容則不正確。
Drupal 8 - Table Of Contents From Headings - YouTube

Devel Kint

在 Drupal 8 使用 Kint (官方模組) 列出變數。 如在 page.html.twig ($site/core/themes/bartik/templates/page.html.twig) 中加入下列，可在網頁中顯示 page 變數內容。

Bartik page.html.twig
<div id="page-wrapper">
{{ kint(page) }} (1)
  <div id="page">
1 執行 kint 顯示 page 變數內容，在測試前應先啟用 偵錯模式。

偵錯 php 如在 $site/core/themes/bartik/bartik.theme 中的加入下列，可在管理頁面中顯示變數內容。

Bartik bartik.theme
function bartik_preprocess_html(&$variables) {
  // 原程式碼
  kint($variables); (1)
}
1 如果管理頁面顯示錯誤，可改為 ksm($variables);
Drupal 8 安裝 kint
modi kint
Drupal 9 安裝 kint
composer require kint-php/kint drupal/devel_kint_extras (1)
drush en devel_kint_extras
# The following module(s) will be enabled: devel_kint_extras, devel
1 參閱： Drupal 8 or Drupal 9 – how to enable Devel Kint again and display available methods

Web Profiler

composer require drupal/webprofiler
# - Installing symfony/stopwatch (v2.4.10): Loading from cache
# - Installing drupal/webprofiler (2.0.0-rc3): Loading from cache

drush en webprofiler
# 出錯，無法安裝

drush pmu webprofiler

Web Profiler
Web Profiler in Drupal 8