【翻译】Drupal 8 webform 教程(一)

原文链接:https://www.webwash.net/getting-started-webform-drupal-8/

Drupal 8 的webform模块可以让你快速创建复杂的表单,基础的知识非常容易学习掌握,但是如果挖掘更深层的东西,那么webform模块更强大的功能就会显现出来。

虽然Drupal8核心里面的Contact模块允许你创建简单的个人和网站的联系表单,但是功能非常受限,这就是webform模块要介入的地方。

在这个教程的第一部分,我们将要使用webform的创建一个简单的但是功能齐全的表单,并且向你展示如何处理表单结果和添加一些其他功能。同时,我们也会演示其中一个内置的javascript库如何美化表单元素。

教程的第二部分,我们将会添加page到我们的webform里面,并且应用条件逻辑和展示如何创建layout以及其他更多功能。

起飞

安装webform最简单的方法就是使用Drush。下面的三条命令就能下载并且开启webform模块,并且会下载所以的依赖包,这个教程是基于webform 8.x-5.0-beta15讲解的。

drush dl webform
drush en webform webform_ui
drush webform-libraries-download

如果安装过程你看到“unable to unzip”的错误提示,那么你需要先在系统上安装解压工具,如果使用centos的话,那么需要安装unzip包。

或者换一种方式安装,不用drush的话,也可以下载这个模块,并且放到你的drupal模块的安装目录,注意,最好是能够下载依赖库(js,css),但是如果本地不存在对应类库的话,webform会使用cdn的方式加载他们。

如果想要查看当前网站使用到了哪些类库和检查他们的状态的话,点击管理员工具条的“Report”,然后再点击“Status Report”,可以搜索“webform library”开头的条目,如果需要的话,可以在webform的配置栏处关闭特定的类库。

status-libraries.jpeg

Screenshot showing the status of Webform libraries.

如果你计划允许用户使用wbform上传文件的话,那么需要了解一下如何配置私有文件,不正确的配置会导致非常严重的安全漏洞。

快速浏览webform

点击管理工具栏的“structure”,然后点击webform来创建和管理webform,类似于下面截图的样子:

interface.jpeg

Screenshot highlighting six different areas in the Webform interface.

图中标记的点如下说明:

  1. 顶部栏一目了然,我们将会在这个教程里面介绍他们

  2. 你可以点击“watch video”按钮获取webform的视频,这些视频对于了解webform的功能很有帮助。

  3. 添加一个webform表单

  4. 点击“how can we help you”按钮能快速找到关于webform模块的信息还有被报出来的一些问题,这个链接到drupal 社区。

  5. “filter webform”可以过滤搜索webform

   6. 每个webform都允许你下载webform的提交结果,或者编辑表单

创建简单的表单

这个教程我们创建一个简单的通讯注册表单,然后在添加一些复杂的元素。先初始化两个元素 - 姓名和邮箱。有两种方法创建表单,一个是复制contact表单,另外一种方法是从头开始创建表单,我们选择第二种方法。

  1. 点击“add webform” 按钮

  2. 给表单取个名字,例如“Newsletter signup”,也可以加上简短的介绍

  3. 可以给表单设置分类,我们这里选择“other”

  4. 点击“save”创建表单

add-webform.jpeg

Screenshot of the add Webfrom screen.

下一步我们添加表单元素:

 1.  点击“add element” 

 2. 搜索“text field”,然后点击“add element”

add-text-field.jpeg

3. title那一栏输入“first name”,其余的选项使用默认的配置

4. 同样的方式选择“email”类型的元素创建email,然后点击“save”

注意,如果想要验证用户输入的邮箱是否正确的话,可以选择“email confirm”元素类型。有些其他元素也会有变化,所以值得回顾审核下创建的元素,确保选择的是最适合你的。

newsletter-signup-1.jpeg

Screenshot of the edit tab after two elements have been added.

点击“view”按钮浏览表单。

newsletter-signup-view-1.jpeg

Screenshot of the view tab after two elements have been added.

简单起见,我们配置元素的时候使用了很多的默认配置,虽然这些配置可以满足大部分的场景,但是还是值得了解一下每个元素类型的不同选项配置,其中有很多方法可以自定义表单元素。

在我们这个场景下,有两个地方是可以优化的。首先,我们最好能够修改下表单提交按钮的文字,其次是设置一下两个元素为必填。

  1. 点击“Edit”按钮(现在应该是叫“Build”)

  2. 在“Submit buttons(s)”的右边,点击“Customize”按钮

customize-signup.jpeg

Screenshot showing that the customize button is below the other elements.

  1. 在“Submit button label”下方输入“Signup”,我们把title也修改成Signup

  2. 点击“Save”

  3. 勾选email和first name元素的“require”复选框,设置为必填,点击“save element”

newsletter-signup-2.jpeg

Screenshot highlighting the required checkboxes next to each element.

注意,使用自定义提交按钮,你可以按照你的需求调整按钮相对其他元素的位置。

现在,你查看这个表单的时候,你应该能够看到两个filed都是必填的,并且提交按钮的标签设置成“Signup”。

newsletter-signup-view-2.jpeg

Screenshot showing that the elements are now required and the submit button is now labelled Signup.

测试表单并且查看结果

如果想要测试刚刚创建的表单,你可以手动添加数据并且提交表单,也可以使用“test”按钮生成数据。如果安装了“Devel”生成模块的话,还可以使用它自动生成表单数据。

test-tab.jpeg

Screenshot of the test tab with information automatically added.

提交表单多次,然后点击“Result”标签。如果需要的话,你可以点击“customize”按钮改变显示列。你也可以使用“star”标记一些特殊的提交结果或者添加管理员笔记,我们对number为5的那条数据演示这两种操作。看到我们自动生成的表单列表,webform的维护者似乎很喜欢披头士。

webform-results.jpeg

Screenshot of the webform submissions with first names of John, Paul, George and Ringo.

每个表单结果后面都有个“edit”按钮,点击的时候会去到几个选项,分别是编辑,查看和删除表单结果。点击“Download”子标签,页面上允许你使用多种方式导出表单结果,同时你也可以基于时间或者submission id来导出你想要的数据。

download-results.jpeg

Screenshot of the download sub-tab.

邮件发送结果

因为我们可以查看表单的提交结果,所以,如果能够在表单被提交的时候通过邮件发送提交数据将会是一个非常有用的功能。

  1. 去到“Edit”tab(最新的应该是settings),点击“Email / Handlers”

  2. 点击“Add email”

  3. “send to”和“send from”部分我们使用默认的配置,那么邮箱地址和名字将会使用到网站的配置(Configuration下面的“Basic site settings”)。

  4. 如果需要的话,邮箱可以自定义,但是我们继续使用默认的配置来演示例子

   5. 点击“save”保存配置

email-handler.jpeg

Screenshot after the email handler added.

添加复选框和单选按钮

在这一部分,我们添加复选框和单选按钮,并且使用jquery icheck库来优化UI。如果添加元素的时候,你通过“checkbox”单次过滤,你会发现有五个结果:

checkbox - 这个是单个复选框

checkboxes - 这个表示一组复选框,使用自定义的或者预定义的列表(比如星期,月份)做为选项

checkboxes other - 这个表示一组复选框,但是有个“other...”选项,用户选择这个的时候,会有一个输入框给用户自定义输入内容

entity checkboxes - 这个表示选项使用实体的复选框

term checkboxed - 这个表示选项使用taxonomy terms的复选框

我们决定使用checkboxes来询问用户他们的兴趣爱好。

  1. 点击“Edit”(最新的叫Build),点击“Add Element”

  2. 使用过滤器搜索“checkboxes”,并且在结果选项后面点击“Add Element”

  3. title下面输入“what are your main interests?”

  4. 对于长标题,通常会简写关联的key,因为这个key会被用来做为css类或者在webform的其他地方用到。点击title右边的“edit”链接,把key改成main_interests。

add-checkboxes-1.jpeg

Screenshot of title and key for checkboxes other element.

 5. 定位到“Element options”部分

 6. 向下滚动到“lelment options”,该选项可以选择预定义的列表,比如星期,在我们这个例子里面,我们需要自己输入这些值,所以我们设置为“Custom...”

 7. 每个选项我们都需要设置健值对。“option value”是用来内部使用的,用来生成值,css id和class。“option text”是用来呈现给用户看的。我们这里设置 html/HTML,css/CSS,js/JavaScript。

checkbox-options-1.jpeg

Screenshot of value - text pairs.

  1. 向下滚动到“other options settings”,这里的配置提供了其他的配置选项。如果选择“checkboxes other”的话,那么这个位置会出现一些文本输入框让你配置“other”。这些选项都可以自己定义,但是在我们这个教程里面,我们都是用默认配置。

  2. 点击“Save”保存配置

注意,在“Element options”配置项里面,复选框选项的每行数量是可以调整的,我们这里选择单列,然后在下一部分教程说明如何配置多列显示。

使用同样的方法,可以添加其他的元素,例如单选和下拉列表。我们这里继续添加单选按钮。

1. 添加Radio元素

2. 起一个标题“Which Javascript library are you most interested in?”

3. 把关联key改为js_library

4. 添加选项为jQuery,AngularJS,React

5. 其它选项使用默认的配置,点击Save保存

checkbox-options-2.jpeg

Screenshot of value - text pairs.

在教程第二部分我们将会通过条件逻辑来控制隐藏这些选项,除非用户在“What are youre main interests”中选择Javascript选项的时候才显示该单选按钮。

点击view tab可以展示这些元素。

newsletter-signup-view-3.jpeg

Screenshot of Webform view tab with checkboxes and radio buttons.

优化复选框和单选按钮

正如你见到的,复选框和单选按钮都是默认的样式,但是,webform引入了jQuery iCheck库,所以我们很容易来优化这些元素的样式,你可以单独配置单个元素,也可以全局配置。(注意,最新的webform要先去admin/structure/webform/config/libraries开启icheck library,然后才会有icheck选项配置)

1.从管理员菜单点击“Structure->Webform->settings(最新版是configuration)

  1. 展开“Element Settings”,(最新版直接找到“Element”子菜单的配置)

  2. 可以在页面上看到“Checkbox/radio settings”

4.在“Enhance checkboxes/radio buttons using iCheck”下拉列表里面选择一种符合你的主题的选项,你可以尝试配置不同的样式风格看看效果

  1. 滚到到底部点击“Save Configuration”保存配置 Now our Webform has greatly enhanced checkboxes and radio buttons. 现在,我们已经优化了webform的checkboxes和redio的样式了。

newsletter-signup-view-4.jpeg

Screenshot with enhanced checkboxes and radio buttons.

其他元素

我们只讨论了webform元素列表中的几个,但是很值得花点时间去尝试一下其他的webform元素。

如果你添加了file类型的元素,要确保你已经合理配置了文件上传,允许不信任的用户上传文件到public目录会带来非常严重的安全问题,当使用private目录的时候,确保你已经正确安全配置并且建议大家只允许信任的用户上传文件。下面这篇文章值得阅读: Drupal file upload by anonymous or untrusted users into public file systems – PSA-2016-003

小结

教程的这一部分,我们演示了如何创建简单的表单以及查看表单结果,并且讨论了webform的元素以及如何优化checkbox和radio的样式。

在教程的第二部分,我们将演示如何创建多个page的表单,并且使用条件逻辑来显示或者隐藏表单元素,以及创建layout等。