Feat: Support for the facets_form module.

While rendering the facets_form_checkboxes facet widget provided by the
facets_form module, groups facet checkboxes according to their LocalGov
Directory facet type.  This is similar to how the existing `checkbox` facet
widget is rendered for LocalGov Directory facets.

Resolves #326

css/facets_form.css

@@ -0,0 +1,11 @@
+/**
+ * @file
+ * Style rules for facets widgets from the facets_form module.
+ */
+
+/**
+ * Hides the submit buttons on an empty facets form.
+ */
+.facet-empty ~ .form-actions {
+  display: none;
+}

localgov_directories.libraries.yml

@@ -8,3 +8,10 @@ localgov_directories_search:
   dependencies:
     - core/drupalSettings
     - core/once
+
+# Hides submit buttons when there are no facet checkboxes to display.
+facets_form_checkboxes_empty:
+  version: 1.x
+  css:
+    state:
+      css/facets_form.css: {}

localgov_directories.module

@@ -8,6 +8,7 @@
 use Drupal\Core\Entity\ContentEntityInterface;
 use Drupal\Core\Entity\Display\EntityFormDisplayInterface;
 use Drupal\Core\Entity\Display\EntityViewDisplayInterface;
+use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Render\Element;
 use Drupal\facets\FacetInterface;
 use Drupal\field\FieldConfigInterface;
@@ -53,6 +54,9 @@ function localgov_directories_theme() {
       'base hook' => 'facets_item_list',
       'template'  => 'facets-item-list--dropdown--localgov-directories-facets',
     ],
+    'checkboxes__localgov_directories_facets' => [
+      'base hook' => 'checkboxes',
+    ],
   ];
 }
 
@@ -218,6 +222,51 @@ function localgov_directories_preprocess_facets_item_list(array &$variables) {
   }
 }
 
+/**
+ * Implements hook_theme_suggestions_HOOK_alter() for hook_theme_suggestions_checkbox_alter().
+ */
+function localgov_directories_theme_suggestions_checkboxes_alter(array &$suggestions, array $variables) {
+
+  $is_dir_facet_checkbox = isset($variables['element']['#name']) ? ($variables['element']['#name'] === Directory::FACET_CONFIG_ENTITY_ID || $variables['element']['#name'] === Directory::FACET_CONFIG_ENTITY_ID_FOR_PROXIMITY_SEARCH) : FALSE;
+  if ($is_dir_facet_checkbox) {
+    $suggestions[] = 'checkboxes__localgov_directories_facets';
+  }
+}
+
+/**
+ * Preprocess for LocalGov Directory facet checkboxes.
+ *
+ * Groups facet checkboxes by their parent LocalGov Directory facet types.
+ */
+function template_preprocess_checkboxes__localgov_directories_facets(array &$variables) {
+
+  \Drupal::service('class_resolver')
+    ->getInstanceFromDefinition(DirectoryExtraFieldDisplay::class)
+    ->preprocessFacetCheckboxes($variables);
+}
+
+/**
+ * Implements hook_form_FORM_ID_alter() for hook_form_facets_form_alter().
+ *
+ * Hides form submit buttons for an empty LocalGov Directory facet form.
+ *
+ * @see Drupal\facets\FacetManager\DefaultFacetManager::build()
+ */
+function localgov_directories_form_facets_form_alter(array &$form, FormStateInterface $form_state) {
+
+  $has_empty_dir_facet = FALSE;
+  if (isset($form['facets'][Directory::FACET_CONFIG_ENTITY_ID][0]['#attributes']['class'][0])) {
+    $has_empty_dir_facet = $form['facets'][Directory::FACET_CONFIG_ENTITY_ID][0]['#attributes']['class'][0] === Directory::FACET_EMPTY_CLASS;
+  }
+  elseif (isset($form['facets'][Directory::FACET_CONFIG_ENTITY_ID_FOR_PROXIMITY_SEARCH][0]['#attributes']['class'][0])) {
+    $has_empty_dir_facet = $form['facets'][Directory::FACET_CONFIG_ENTITY_ID_FOR_PROXIMITY_SEARCH][0]['#attributes']['class'][0] === Directory::FACET_EMPTY_CLASS;
+  }
+
+  if ($has_empty_dir_facet) {
+    $form['#attached']['library'][] = 'localgov_directories/facets_form_checkboxes_empty';
+  }
+}
+
 /**
  * Prepares variables for directory facets templates.
  *

src/Constants.php

@@ -41,6 +41,8 @@ class Constants {
 
   const FACET_CONFIG_FILE_FOR_PROXIMITY_SEARCH = 'facets.facet.localgov_directories_facets_proximity_search';
 
+  const FACET_EMPTY_CLASS = 'facet-empty';
+
   const CHANNEL_VIEW = 'localgov_directory_channel';
 
   const CHANNEL_VIEW_DISPLAY = 'node_embed';

src/DirectoryExtraFieldDisplay.php

@@ -12,6 +12,7 @@
 use Drupal\Core\Form\FormBuilderInterface;
 use Drupal\Core\Form\FormState;
 use Drupal\Core\Plugin\PluginBase;
+use Drupal\Core\Render\Element;
 use Drupal\Core\Render\Markup;
 use Drupal\Core\Routing\RouteMatchInterface;
 use Drupal\Core\Security\TrustedCallbackInterface;
@@ -305,13 +306,47 @@ public function preprocessFacetList(array &$variables) {
       }
     }
 
+    $variables['items'] = $this->groupDirFacetItems($variables['items']);
+
+    if (!empty($show_reset_link)) {
+      // Add the reset link.
+      $variables['items']['show_reset_all']['items'][] = $show_reset_link;
+      $reset_all = $variables['items']['show_reset_all'];
+      // Place the reset link at the top of the facet filters.
+      array_unshift($variables['items'], $reset_all);
+      array_pop($variables['items']);
+    }
+  }
+
+  /**
+   * Groups facet checkboxes.
+   *
+   * Prepares variables for facet checkboxes grouped by LocalGov Directory facet
+   * types.
+   *
+   * @see templates/checkboxes--localgov-directories-facets.html.twig
+   * @see template_preprocess_checkboxes__localgov_directories_facets()
+   */
+  public function preprocessFacetCheckboxes(array &$variables): void {
+
+    $facet_id_list = Element::children($variables['element']);
+    $facet_options = array_filter($variables['element'], fn($facet_id) => in_array($facet_id, $facet_id_list), ARRAY_FILTER_USE_KEY);
+    $variables['grouped_options'] = $this->groupDirFacetItems($facet_options);
+  }
+
+  /**
+   * Groups facet items by LocalGov Directory facet types.
+   */
+  public function groupDirFacetItems(array $facet_items): array {
+
     $facet_storage = $this->entityTypeManager
       ->getStorage(Directory::FACET_CONFIG_ENTITY_ID);
     $group_items = [];
-    foreach ($variables['items'] as $key => $item) {
-      if ($entity = $facet_storage->load($item['value']['#attributes']['data-drupal-facet-item-value'])) {
-        assert($entity instanceof LocalgovDirectoriesFacets);
-        $group_items[$entity->bundle()]['items'][$key] = $item;
+    foreach ($facet_items as $key => $item) {
+      $facet_id = $item['value']['#attributes']['data-drupal-facet-item-value'] ?? $key;
+      if ($facet_entity = $facet_storage->load($facet_id)) {
+        assert($facet_entity instanceof LocalgovDirectoriesFacets);
+        $group_items[$facet_entity->bundle()]['items'][$key] = $item;
       }
     }
 
@@ -331,22 +366,14 @@ public function preprocessFacetList(array &$variables) {
     $type_storage = $this->entityTypeManager
       ->getStorage(Directory::FACET_TYPE_CONFIG_ENTITY_ID);
     foreach ($group_items as $bundle => $items) {
-      $entity = $type_storage->load($bundle);
-      assert($entity instanceof LocalgovDirectoriesFacetsType);
-      $group_items[$bundle]['title'] = Html::escape($this->entityRepository->getTranslationFromContext($entity)->label());
-      $group_items[$bundle]['weight'] = $entity->get('weight');
+      $facet_type_entity = $type_storage->load($bundle);
+      assert($facet_type_entity instanceof LocalgovDirectoriesFacetsType);
+      $group_items[$bundle]['title'] = Html::escape($this->entityRepository->getTranslationFromContext($facet_type_entity)->label());
+      $group_items[$bundle]['weight'] = $facet_type_entity->get('weight');
     }
     uasort($group_items, static::compareFacetBundlesByWeight(...));
-    $variables['items'] = $group_items;
 
-    if (!empty($show_reset_link)) {
-      // Add the reset link.
-      $variables['items']['show_reset_all']['items'][] = $show_reset_link;
-      $reset_all = $variables['items']['show_reset_all'];
-      // Place the reset link at the top of the facet filters.
-      array_unshift($variables['items'], $reset_all);
-      array_pop($variables['items']);
-    }
+    return $group_items;
   }
 
   /**

templates/checkboxes--localgov-directories-facets.html.twig

@@ -0,0 +1,40 @@
+{#
+/**
+ * @file
+ * Default theme template for directory facet checkboxes.
+ *
+ * These checkboxes are used within the facets_form_checkbox facet widget.
+ *
+ * Available variables:
+ * - title: Optional list title.
+ * - grouped_options: checkboxes grouped by their corresponding LocalGov Directory facet type.  Each group array contains:
+ *   - title: Label of the facet type.
+ *   - items: Checkbox element.
+ *   - weight: Sorting weight of the facet type.
+ * - attributes: HTML attributes to be applied to the list.
+ *
+ * @see template_preprocess_checkboxes__localgov_directories_facets()
+ */
+#}
+<div class="facets-widget facets-widget--facets-form-checkbox">
+
+  {%- if title is not empty -%}
+    <h3>{{ title }}</h3>
+  {%- endif -%}
+
+  {% if grouped_options %}
+    <ul{{ attributes }}>
+    {%- for group_id, group_record in grouped_options -%}
+      <li>
+        <h4 class="facet-group__title">{{ group_record.title }}</h4>
+
+        <ul{{ attributes.addClass('facet-filter-checkboxes') }}>
+        {%- for checkbox in group_record.items -%}
+          <li>{{ checkbox }}</li>
+        {%- endfor -%}
+        </ul>
+      </li>
+    {%- endfor -%}
+    </ul>
+  {%- endif %}
+</div>