README

Mr. Spicy（表单）的目标是在不到2分钟内让您创建一个表单。这可能感觉就像您正在烈火中！这是一个API，它利用TacoWordPress创建表单配置帖子类型，允许您作为开发人员以及客户管理员进行设置。

基本示例

<?php
$contact_form_config = new \Taco\MrSpicy(
  array(
    'conf_name' => 'General Contact Form Configuration',
    'fields' => array(
      'first_name' => array('type' => 'text'),
      'email' => array('type' => 'email'),
      'message' => array('type' => 'textarea')
    )
  )
);

echo $contact_form_config->render();

这里发生了什么？

首先，我们创建一个新的MrSpicy对象
然后我们传递一个设置数组
定义一些要在表单中使用的字段
最后，使用对象的render方法渲染表单。

所有这些都为您提供了一个前端表单，访客可以填写并记录为WordPress中的条目帖子类型。它还允许管理员访问重写常见设置，如管理员电子邮件（用于通知）、成功消息和错误消息。

Mr. Spicy需求

Mr. Spicy目前需要位于这里的"taco-2016-boilerplate"。这很快就会得到修复。
PHP >=5.4.0
TacoWordPress

设置

请确保首先安装TacoWordPress的依赖项。 https://github.com/tacowordpress/tacowordpress/
在composer.json文件中将MrSpicy添加到TacoWordPress之后

{
  "require": {
    "tacowordpress/tacowordpress: "dev-master",
    "tacowordpress/mr-spicy": "dev-master"
  }
}

Mr. Spicy API配置设置

以下是可以用于设置表单配置的属性和值（以下显示默认值）。

    array(
      'form_unique_key' => '',
      'fields' => array(),
      'css_class' => '',
      'id' => '',
      'method' => 'post', // currently only works with POST
      'action' => null,
      'lock' => (ENVIRONMENT == 'prod') // set this to true in production environments
      'novalidate' => false,
      'use_ajax' => false, // coming soon
      'hide_labels' => false,
      'column_classes' => 'small-12 columns',
      'exclude_post_content' => false,
      'submit_button_text' => 'submit',
      'success_message' => null,
      'error_message' => null,
      'success_redirect_url' => null,
      'label_field_wrapper' => '\Taco\MrSpicy::rowColumnWrap',
      'use_honeypot' => true,
      'honeypot_field_name' => 'your_website_url',
      'use_recaptcha' => false,
      'google_recaptcha_site_key' => null,
      'google_recaptcha_secret_key' => null
    );

每个属性/值的详细信息即将推出。

自定义表单的渲染方式

Mr. Spicy的简洁性不仅仅如此。自定义表单的渲染也非常简单，并提供了一些不同的选项。

示例 1

<?php

echo (new \Taco\MrSpicy(
  array(
    'conf_name' => 'General Contact Form Configuration',
    'novalidate' => true,
    'fields' => array(
      'first_name' => array(),
      'email' => array('type' => 'email'),
      'message' => array('type' => 'textarea')
    ),
  )
))->render(function($form_conf) { ?>

  <div class="row">
    <div class="small-12 columns">
      %first_name%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %email%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %message%
    </div>
  </div>

   <div class="row">
    <div class="small-12 columns">
      <button type="submit">Submit</button>
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %edit_link%
    </div>
  </div>

<?php }); ?>

示例 1展示了如何使用HTML和模板标签使用自己的模板。使用%my_field_name%将根据配置设置渲染该字段。假设您想要隐藏字段的标签并使用占位符代替。在您的配置设置中，只需设置"hide_labels" => true。您会在上面的示例中注意到"%edit_link%"。这渲染了一个链接到WordPress管理员，客户管理员可以前往配置以编辑成功/错误消息和管理员电子邮件。

示例 2 更改表单消息

以下示例演示了一些事情：自定义表单的一般成功/错误消息及其位置。注意：WordPress管理员可以覆盖这些字段，这是设计的一部分。

<?php

echo (new \Taco\MrSpicy(
  array(
    'conf_name' => 'General Contact Form Configuration',
    'novalidate' => true,
    'success_message' => 'Success! Thanks for your inquiry.',
    'error_message' => 'Oops! Looks like there was an error in the form. Please correct and try again.',
    'fields' => array(
      'first_name' => array(),
      'last_name' => array(),
      'email' => array('type' => 'email'),
      'message' => array('type' => 'textarea')
    ),

  )
))->render(function($form_conf) { ?>

  <div class="row">
    <div class="small-12 columns">
      %form_messages% //This is where success or error messages will print
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %first_name%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %last_name%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %email%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %message%
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      <button type="submit">Submit</button>
    </div>
  </div>


<?php }); ?>

为什么模板语法不典型？

您会注意到如何关闭php以开始定义您的自定义模板。如果您已经使用php一段时间，您可能已经猜到我在使用输出缓冲区捕获html并用渲染的html替换%template_tags%。这发生在幕后。在我看来，如果您能克服奇怪之处，这是一个非常优雅的自定义方式。

<?php $contact_form = new \Taco\MrSpicy(
  array(
    'form_unique_key' => 'Contact Form Configuration',
    'fields' => 'auto', // don't define the fields here
  )
); ?>

<?php
echo $contact_form->render(function($form_conf) { ?>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %post_content%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %form_messages%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %first_name|required=true%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %last_name%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %email|required=true%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %message|type=textarea|required=true%
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
     <button type="submit">Submit</button>
    </div>
  </div>

  <div class="row">
    <div class="small-12 medium-8 medium-centered columns">
      %edit_link%
    </div>
  </div>
<?php }); ?>

是的，我们在模板中定义字段。

回调（事件）

在表单的配置设置中将"on_success"的值设置为闭包可以触发表单成功后的函数/方法。

$my_contact_form = new \Taco\MrSpicy(
  array(
    'form_unique_key' => 'contact-form-configuration',
    'on_success' => function($entry_object, $form_conf) {

      // send mail on the form's success
      $to = 'info@yourwebsite.com';
      $subject = 'A message from the site\'s general contact form';
      $message = '';
      mail($to, $subject, $message, $headers);
    }
  )
);
...

请注意，您必须定义您的回调具有2个参数，即（Object $entry, Object $form_conf）。如果您不想使用这些，请将它们设置为null。

重要：与指定的 "success_redirect_url" 一起使用闭包将会引发错误。为了解决这个问题，您必须指定一个字符串回调。请参见以下内容。

// the right way
...
'success_redirect_url' => 'http://mywebsite.com/thankyou-message',
'on_success' => 'MyClass::myMethod'

// and then define your class method (must be static)
class MyClass {
  public static function myMethod($entry, $form_conf) {}
}
...

// the wrong way - this will throw an error
...
'success_redirect_url' => 'http://mywebsite.com/thankyou-message',
'on_success' => function($entry, $form_conf) { }
...

表单状态

使用 MrSpicy 开发的表单具有数据属性 "data-form-status"。您可以使用它来告诉自定义 JavaScript 脚本表单的状态。以下是有三种状态。

data-form-status="idle" – 表单空闲且尚未提交

data-form-status="has_errors" – 表单包含无效值

data-form-status="success" – 表单提交成功

表单安全

Spicy先生的表单具有后端验证，但如果您需要额外的帮助，可以使用蜜罐和 Google Recaptcha 选项。只需在设置中传递即可

    array(
      ...
      'use_honeypot' => true,
      'honeypot_field_name' => 'your_website_url'
    );

目前蜜罐字段没有自定义错误消息。可能最好不要让它太明显。

Google reCAPTCHA

在使用 Google 的 reCAPTCHA 与 Mr. Spicy 表单之前，您需要有一个 Google 账户并注册您的网站。

https://www.google.com/recaptcha/

请注意，Google 提供的网站密钥和密钥，您将需要在表单设置中使用它们。

    array(
      ...
      'use_recaptcha' => true,
      'google_recaptcha_site_key' => $google_recaptcha_site_key,
      'google_recaptcha_secret_key' => $google_recaptcha_secret_key
      
      // let's also keep the honeypot
      'use_honeypot' => true,
      'honeypot_field_name' => 'your_website_url'
    );

进一步自定义

字段自动

当字段自动定义和渲染时，可能仍然需要覆盖某些元素。

%email|type=textarea|required=true%

如果您想自定义自动渲染的标签，您可以这样操作。

%email|type|label=false% // don't show it
// or
%email|type|label=email (required)% // to customize the text

字段自定义（非自动）

也许您不希望为字段定义和渲染使用任何 "%%" 模板语法，只想做自己的事情。请随意。您可以像平时那样键入表单字段。只需保持字段名与配置相同。如果想在提交后填充错误消息和值，您仍然需要使用 "%%" 语法。

<?php

echo (new \Taco\MrSpicy(
  array(
    'form_unique_key' => 'general-contact-form-configuration',
      'first_name' => array('type' => 'text', 'required' => true),
      'last_name' => array(),
      'email' => array('type' => 'email', 'required' => true),
      'message' => array('type' => 'textarea', 'required' => true)
    ),
  )
))->render(function($form_conf) { ?>

  ...

  <div class="row">
    <div class="small-12 columns">
      %error_first_name%
      <label for="first-name">first name *</label>
      <input type="text" name="first_name" id="first-name" value="%value_first_name%">
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      <label for="last-name">last name</label>
      <input type="text" name="last_name" id="last-name" value="%value_last_name%">
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %error_email%
      <label for="email">email</label>
      <input type="text" name="email" id="email" value="%value_email%">
    </div>
  </div>

  <div class="row">
    <div class="small-12 columns">
      %error_message%
      <label for="message">message</label>
      <input type="text" name="message" id="message" value="%value_message%">
    </div>
  </div>

  ...

覆盖全局配置

您可能希望自定义一些设置。然而，这些属性是全局的，将影响所有表单配置。您可以在 "vendor/tacowordpress/mr-spicy/src/forms-defaults.php" 中找到这些设置。请勿编辑此文件。相反，将其复制到 vendor 外部的文件夹中，以免在未来 composer 更新时被覆盖。完成此操作后，您需要告诉 Mr. Spicy 此文件的位置。

// add this line after the composer autoload include
\Taco\MrSpicy::setDefaultsPath(get_template_directory().'/forms-defaults.php'); // this can be changed

您可以通过以下方式覆盖当前的全球设置

return array(
  'form_action' => null, // This is set automatically, but you can override it.
  'error_message' => 'There were some errors with your form submission. Please correct and try again.',
  'success_message' => 'Thanks for your message',
  'shared_configuration_extra_fields' => [] // use this if you need common (shared across all form configurations) admin columns like "email" or "name" to be added
);

更多内容即将到来...

tacowordpress / mr-spicy

维护者

详情