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