Drupal 11中使用HTMX实现级联选择表单的详细指南

Drupal 11中使用HTMX实现级联选择表单的详细指南

Drupal 11: Cascading Select Forms With HTMX

这是一系列探讨 Drupal 中 HTMX 的文章的第四部分。在过去的两篇文章中，我们探讨了以不同方式在控制器中使用 HTMX。这次，我将涉足 HTMX 和表单的领域。

几年前，我在这个网站上写了一篇关于 Drupal 中的级联 Ajax 选择表单 的文章，当我试图解决与选择表单和 Ajax 相关的问题时，我经常会参考这篇文章。在那篇文章中，我使用年、月和日选择字段，并将它们关联起来，以便在选择过程中相互影响。

我编写 Drupal 网站已经有很多年了，但在尝试在 Drupal 表单中实现 Ajax 之前，我仍然需要深吸一口气。为了让一切正常工作，我最终会在表单字段中添加包装元素或自定义属性。这似乎总是一个痛苦的过程。

当我学习 HTMX 和 Drupal 时，我坐下来重新实现这个级联选择表单，并在大约半小时内就完成了。大部分时间都花在了将表单元素添加到构建表单的方法中。这与在 Drupal 表单中添加 Ajax 的旧方法形成了鲜明对比。

在本文中，我们将探讨创建一个包含多个选择元素的表单，然后使用 HTMX（以及一点表单状态 API）将它们关联起来，以便选择一个元素时更新其他元素。

本文中包含的所有代码都可以在 GitHub 上的 Drupal HTMX 示例项目 中找到，但在这里我们将详细介绍代码的功能以及它执行哪些操作来生成内容。

就像关于 HTMX 的其他文章一样，我将从定义路由开始。

一、路由

我们这里需要的路由只需将路径 /htmx-examples/cascading-select 指向我们的表单类。

  
    drupal_htmx_examples_cascading_select_form:
      path: "/htmx-examples/cascading-select"
      defaults:
        _form: '\Drupal\drupal_htmx_examples\Form\CascadingSelectForm'
        _title: "HTMX Cascading Select Example Form"
      requirements:
        _permission: "access content"

这个路由没有什么特别之处，它只是一个普通的表单路由。

让我们为这个路由创建表单。

二、表单

表单类只是一个标准的 Drupal 表单，但在控制器中使用 HTMX 和在表单中使用 HTMX 有一个区别。当我们定义一个将使用 HTMX 的控制器时，我们（有时）需要将 request_stack 服务注入到表单中，以便我们可以使用它来检测任何传入的 HTMX 请求。对于表单来说，这不是必需的，因为 request_stack 服务是核心 FormBase 类的一部分，我们在 Drupal 中创建所有表单时都会扩展这个类。

这是表单类的大纲，它将包含我们的级联选择表单。

  
    <?php

    namespace Drupal\drupal_htmx_examples\Form;

    use Drupal\Core\Form\FormBase;
    use Drupal\Core\Form\FormStateInterface;
    use Drupal\Core\Htmx\Htmx;
    use Symfony\Component\DependencyInjection\ContainerInterface;

    /**
     * Form to show cascading selects using HTMX.
     */
    class CascadingSelectForm extends FormBase {

      /**
       * {@inheritDoc}
       */
      public function getFormId() {
        return 'htmx_cascade_select_form';
      }

      /**
       * {@inheritDoc}
       */
      public function buildForm(array $form, FormStateInterface $form_state) {}

      /**
       * {@inheritDoc}
       */
      public function submitForm(array &$form, FormStateInterface $form_state): void {
        $year = $form_state->getValue('year');
        $month = $form_state->getValue('month');
        $day = $form_state->getValue('day');

        $args = [
          '%year' => $year,
          '%month' => $month,
          '%day' => $day,
        ];
        $this->messenger()->addMessage($this->t('Submitted form with values year: %year, month: %month, day: %day', $args));
      }

    }

我还在这里添加了提交处理程序，它将把输入参数作为消息打印出来。

为了构建我们的表单，我们需要定义年、月和日选择字段，以便它们在用户交互过程中可以相互更新。

第一个元素是年份，它定义了一个从 2019 到 2050 的任意日期范围，并将其作为数组提供给一个选择字段。我们还从表单状态中获取当前年份的值，以防用户已经提交了表单，我们希望保持该状态。我们可以在这里对日期范围进行更细致的处理，但这只是一个测试表单。

  
    $years = range(2019, 2050);
    $years = array_combine($years, $years);
    $year = $form_state->getValue('year');

    $form['year'] = [
      '#title' => $this->t('Year'),
      '#type' => 'select',
      '#empty_option' => $this->t('- Select -'),
      '#options' => $years,
      '#default_value' => $year,
    ];

为了定义月份，我们只需创建一个小的月份数组（毕竟只有 12 个值），并将其提供给月份选择元素。我们还从表单状态中添加当前月份的值，然后在这里设置表单 '#states' API，以便只有当年份选择有值时才显示月份。

  
    $months = [
      1 => $this->t('Jan'),
      2 => $this->t('Feb'),
      3 => $this->t('Mar'),
      4 => $this->t('Apr'),
      5 => $this->t('May'),
      6 => $this->t('Jun'),
      7 => $this->t('Jul'),
      8 => $this->t('Aug'),
      9 => $this->t('Sep'),
      10 => $this->t('Oct'),
      11 => $this->t('Nov'),
      12 => $this->t('Dec'),
    ];
    $month = $form_state->getValue('month');

    $form['month'] = [
      '#title' => $this->t('Month'),
      '#type' => 'select',
      '#options' => $months,
      '#empty_option' => $this->t('- Select -'),
      '#default_value' => $month,
      '#states' => [
        '!visible' => [
          ':input[name="year"]' => ['value' => ''],
        ],
      ],
    ];

创建日期列表稍微复杂一些。有些月份的天数不同[需要引用来源]，所以我们不能简单地添加一个从 1 到 31 的范围就完事了。相反，我们需要监听年份和月份的值，然后使用 PHP 内置函数 cal_days_in_month() 来加载天数。这意味着如果月份是闰年的二月，我们仍然会在选择列表中显示正确的天数。我们还添加了 #states API 属性，以便只有当月份元素有值时才显示日期字段。

  
    $days = [];
    if ($month) {
      $number = cal_days_in_month(CAL_GREGORIAN, $month, $year);
      $days = range(1, $number);
      $days = array_combine($days, $days);
    }
    $day = $form_state->getValue('day');

    $form['day'] = [
      '#title' => $this->t('Day'),
      '#type' => 'select',
      '#options' => $days,
      '#empty_option' => $this->t('- Select -'),
      '#default_value' => $day,
      '#states' => [
        '!visible' => [
          ':input[name="month"]' => ['value' => ''],
        ],
      ],
    ];

最后，我们只需要添加一个提交按钮并返回表单。

  
    $form['submit'] = [
      '#type' => 'submit',
      '#value' => 'Submit',
    ];

    return $form;

这个表单将根据状态 API 显示和隐藏元素，但它不会用正确的天数填充日期字段。所以让我们在表单中添加重要的 HTMX。

三、添加 HTMX

这个表单的 HTMX 需要在选择元素定义之后、表单末尾的返回语句之前添加。

我们需要为表单中的两个字段添加 HTMX，以执行以下操作：

  • 当用户选择一个 月份 时，我们需要返回表单以计算该月的天数，并填充 日期 选择字段。
  • 当用户选择一个 年份 时，我们需要返回并重新填充 月份 和 日期 选择字段。这将涵盖选择闰年且用户恰好选择了 2 月 29 日的情况。

我们使用 Htmx Drupal 类来创建我们需要的属性，并将它们应用到月份选择元素上。

  
    (new Htmx())
      ->post()
      ->select('*:has(>select[name="day"])')
      ->target('*:has(>select[name="day"])')
      ->swap('outerHTML')
      ->applyTo($form['month']);

这会将以下 HTMX 属性添加到表单元素中。

  • data-hx-post - 这将向表单发送一个 POST 请求。由于我们没有为方法添加值，它将自动使用当前路由。
  • data-hx-select - 在处理 Drupal 中的 HTMX 表单时，选择属性至关重要。如果您读过我之前的文章，您会记得当我们发出 HTMX 请求时，我们会从服务器获取整个表单。因此，我们需要告诉 HTMX 从响应中只挑选出我们需要的元素。在这种情况下，我们使用选择器字符串 *:has(>select[name="day"]，它告诉 HTMX 我们要找到名称为 "day" 的选择元素的 父元素，也就是我们的日期选择元素。
  • data-hx-target - 这告诉 HTMX 将我们从响应中提取的元素放置在哪里。我们使用与 data-hx-select 属性相同的选择器字符串，我们想要替换页面上的日期选择元素。
  • data-hs-swap - 最后，我们将交换策略设置为 outerHTML，这告诉 HTMX 用响应中选择的值完全替换目标元素。

创建另一个 Htmx Drupal 对象，为年份选择元素添加我们需要的属性。

  
    (new Htmx())
      ->post()
      ->select('*:has(>select[name="month"])')
      ->target('*:has(>select[name="month"])')
      // We also target the edit-day ID (which is the select element) with a
      // out of bounds select to replace the day select. This catches edge
      // cases where te 29th Feb is selected and a non-leap year is selected.
      ->selectOob('#edit-day')
      ->swap('outerHTML')
      ->applyTo($form['year']);

年份表单元素的主要新增内容是添加了 selectOob() 方法。这会向年份字段添加一个 data-hx-select-oob 属性，该属性在年份触发的响应中针对日期字段。

如果您正在阅读本文并想知道为什么我不能重用月份字段 data-hx-select 和 data-hx-target 属性中的选择器字符串，那是因为当使用带外选择时，该选择器似乎会导致 HTMX 出现问题。HTMX 似乎希望属性中存在一个 ID，所以如果我们传递一个以 "*" 开头的字符串，它会尝试将其作为 ID 名称，如 "#*"，这对于选择器来说是无效的语法。

四、HTMX 工作流程

这些 HTMX 元素以以下方式工作。

请注意，我已经简化并删除了大量标记，以便于阅读和理解。

我们在这里要做的是选择日期 "2024 年 2 月 29 日"，这是一个闰年，然后选择年份 2023，这不是闰年。这会导致日期选择被取消选择，因为记录 29 不再存在。

表单被创建，其中包含以下元素。

  
    <div class="js-form-item form-item form-type-select js-form-type-select form-item-year js-form-item-year">
    <select data-hx-post="" data-hx-select="*:has(&gt;select[name=&quot;month&quot;])" data-hx-target="*:has(&gt;select[name=&quot;month&quot;])" data-hx-select-oob="edit-day" data-hx-swap="outerHTML ignoreTitle:true" data-drupal-selector="edit-year" id="edit-year" name="year" class="form-select form-element form-element--type-select">
      <option value="" selected="selected">- Select -</option>
      <option value="2019">2019</option>
      ...
      <option value="2024">2024</option>
      ...
      <option value="2050">2050</option>
    </select>
    </div>

    <div

联系我们

提供基于Drupal的门户网站、电子商务网站、移动应用开发及托管服务

联系电话
137-9572-6015
QQ
415066151
长按加微信
长风云微信
长按关注公众号
长风云公众号