README

目前该项目已 停止开发。不过，欢迎将其分叉并继续其开发！

Craft CMS 3 是基于 Yii 2 框架构建的。此插件使得可以使用与 Yii 2 框架相同的方式使用表单。这包括

• 使用模型中的规则进行易于实现的客户端和服务器端验证。
• 将模型中的字段标签分配到多个区域使用。

除了 Yii 2 框架的逻辑外，我们还增加了

• 在设置中轻松启用/禁用表单。
• 在设置中轻松启用/禁用将表单条目记录到数据库中。
• 在插件设置中按表单控制联系请求电子邮件的收件人和主题。
• Twig 扩展，表单示例和电子邮件示例。

注意：当 Craft 插件商店可用时，此插件可能成为付费插件。

要求

• Craft 3.0 (beta 28)+
• PHP 7.0+

安装

1. 使用 Composer 安装

   composer require dolphiq/craft3-forms
   

2. 在 Craft 控制面板的“设置”>“插件”下安装插件

3. 在您的 craft 项目根目录下添加一个名为 forms 的新目录（在您的 config 和模板目录旁边），或将插件目录中的 examples 文件夹中的 forms 目录复制到该目录

目录结构

下面您将找到联系表和招聘表单的示例目录结构

如您所见，每个表单都有自己的目录。最少的文件是联系目录中的文件。当使用此插件的所有功能时，您将拥有与招聘目录中一样多的文件。

forms/
    contact/
        contactForm.php
        contactView.php
    vacancy/
        vacancyForm.php
        vacancyView.php
        vacancyMailOwner.php
        vacancyCustomerMail.php
        vacancyThanks.php
    thanks.php       

创建新的表单

假设我们要创建一个联系表单。

1. 在 forms 目录内创建一个以您的表单名称命名的目录。此名称将作为您的表单处理程序。在此情况下，它将被命名为 contact

2. 在此目录内创建两个文件

   • contactForm.php 此文件是一个模型，用于定义表单的字段和规则。文件名由处理程序附加 Form.php 组成。

     此文件是一个模型，如：https://yiiframework.cn/doc-2.0/guide-start-forms.html#creating-model 所述。确保类扩展插件中的 Form 模型并使用 app\forms 命名空间，如果不这样做，则插件无法工作。

     示例 contactForm.php

     namespace app\forms;
              
     use Craft;
     use plugins\dolphiq\form\models\Form;
     
     class contactForm extends Form {
     
      public $firstname = "";
      public $lastname = "";
      public $phone = "";
      public $email = "";
      public $message = "";
     
      public function rules()
      {
          return [
              [['firstname', 'lastname', 'email', 'message'], 'required'],
              ['email', 'email'],
              ['phone', 'safe']
          ];
      }
     
      public function attributeLabels()
      {
          return [
              'firstname' => Craft::t('site', 'Firstname'),
              'lastname' => Craft::t('site', 'Lastname'),
              'phone' => Craft::t('site', 'Phone'),
              'email' => Craft::t('site', 'Email'),
              'message' => Craft::t('site', 'Message'),
          ];
      }
     }

   • contactView.php 此文件是一个视图，用于显示您的表单。文件名由处理程序附加 View.php 组成。

     文件是一个视图文件，如：https://yiiframework.cn/doc-2.0/guide-start-forms.html#creating-views 所述。重要的是要保持 activeform 的动作和 pjax 小部件的 id 不变，否则您的表单将无法工作。

     示例 contactView.php

     <?php
     
     /**
       * @var $model app\forms\contactForm
       * @var $handle string
       */
     
     use yii\widgets\ActiveForm;
     use yii\widgets\Pjax;
     
     // Start ajax handling of the form
     Pjax::begin(['enablePushState' => false, 'id' => 'pjax-'.$handle]);
     
     // Start active form
     $form = ActiveForm::begin([
         'action' => \craft\helpers\UrlHelper::actionUrl('dolphiq-craft3-forms/main/index', ['handle' => $handle]),
         'method' => 'POST',
         'options' => [
             'data-pjax' => true,
         ],
     ]);
     
     ?>
     
     <?= $form->field($model, 'firstname')->textInput(); ?>
     <?= $form->field($model, 'lastname')->textInput(); ?>
     <?= $form->field($model, 'phone')->textInput(); ?>
     <?= $form->field($model, 'email')->textInput(); ?>
     
     <?= $form->field($model, 'message')->textarea(); ?>
     
     <div>
       <button type="submit">
           <?= Craft::t('site', 'Send request'); ?>
       </button>
     </div>
     
     
     <?php 
       
       // End active form
       ActiveForm::end();
       
       // End ajax handling
       Pjax::end(); 
     
     ?>

3. 在您的模板中，您现在可以使用以下标签使用表单。将 contact 替换为您的表单处理程序。

   {{ dolphiqForm('contact') }}

感谢信息

当表单提交并正确验证时，它将被替换为感谢信息。有两种类型的感谢信息

1. 默认感谢信息。

   该插件自带默认的感谢信息。您可以通过在 forms/ 目录下创建一个 thanks.php 文件来覆盖此信息。这将然后成为您所有表单使用的默认感谢信息。您可以使用表单模型在这里个性化感谢信息。

   默认感谢信息的示例

   <p>Thank you! We will contact you soon.</p>

2. 每个表单的个性化感谢信息

   您可以创建每个表单的感谢信息，这样它就不会使用默认的感谢信息。如果您想通过使用表单模型来个性化感谢信息，这将非常有用。

   每个表单的个性化感谢信息的示例

   <?php
   /**
    * @var $model \app\forms\contactForm
    */
   ?>
   
   <p>Thank you <?= $model->firstname ?>, we will contact you soon</p>

邮件

您可以将插件启用以向表单所有者和填写表单的人发送电子邮件。为此，您可以创建两个文件

1. contactMailOwner.php 此文件包含将发送给表单所有者的电子邮件。

   您可以使用 $model 变量从填写好的表单中获取属性。

   示例

   <?php
   
   use yii\widgets\DetailView;
   
   /* @var $this \yii\web\View view component instance */
   /* @var $message \yii\mail\BaseMessage instance of newly created mail message */
   /* @var $model \app\forms\contactForm */
   
   ?>
   <h2>A contact request has been filled in</h2>
   <p>
     We received the following details:<br>
       <?= DetailView::widget([
           'model' => $model,
           'attributes' => [
               'firstname',
               'lastname',
               'email',
               'phone',
               'message:ntext'
           ]
       ]); ?>
   </p>

2. contactMailCustomer.php 此文件包含将发送给填写表单的人的电子邮件（如果存在 email 属性并且已填写）。

   您可以使用 $model 变量从填写好的表单中获取属性。这样您就可以个性化电子邮件。

   <?php
       
   /* @var $this \yii\web\View view component instance */
   /* @var $message \yii\mail\BaseMessage instance of newly created mail message */
   /* @var $model app\forms\contactForm */
   
   ?>
   <h2>Thank you for your message <?= $model->lastname; ?></h2>
   <p>
       We will contact you as soon as possible
   </p>

这两封邮件将被包裹在由插件文件夹中定义的邮件布局中。您不能更改此布局。

CP 设置

在控制面板中，您可以按表单设置设置。您可以按以下选项设置每个表单：

• 启用 当禁用时，表单将不会显示
• 日志记录 当启用时，表单的结果将记录到数据库中
• 所有者邮件 当表单填写时，将发送此电子邮件。您可以填写以下选项：
  • 邮件地址 将发送电子邮件的电子邮件地址
  • 邮件主题 将发送到上述电子邮件地址的电子邮件的主题
• 客户邮件 这将发送给填写表单的人的电子邮件。这仅在表单包含 email 属性并且填写人可以填写他的电子邮件地址时才有效。您可以填写以下选项：
  • 邮件主题 将发送到客户电子邮件地址的电子邮件的主题。

贡献者 & 开发者

Lucas Weijers - info@dolphiq.nl 由 Dolphiq 提供