template commentary and variable clean-up

templates/block--menu-block--main.html.twig

@@ -1,54 +1,21 @@
 {#
 /**
  * @file
- * Theme override for a menu block.
+ * Theme override for any menu block placement of "main" menu.
+ * IRL: This template is only used by cwd_*_mainnavigation (on CD Demo), but it
+ * works fine for any instance of "main" menu placed in sidebar_primary.
  *
- * Available variables:
- * - plugin_id: The ID of the block implementation.
- * - label: The configured label of the block if visible.
- * - configuration: A list of the block's configuration values.
- *   - label: The configured label for the block.
- *   - label_display: The display settings for the label.
- *   - provider: The module or other provider that provided this block plugin.
- *   - Block plugin specific settings will also be stored here.
- * - content: The content of this block.
- * - attributes: HTML attributes for the containing element.
- *   - id: A valid HTML ID and guaranteed unique.
- * - title_attributes: HTML attributes for the title element.
- * - content_attributes: HTML attributes for the content element.
- * - title_prefix: Additional output populated by modules, intended to be
- *   displayed in front of the main title tag that appears in the template.
- * - title_suffix: Additional output populated by modules, intended to be
- *   displayed after the main title tag that appears in the template.
- *
- * Headings should be used on navigation menus that consistently appear on
- * multiple pages. When this menu block's label is configured to not be
- * displayed, it is automatically made invisible using the 'visually-hidden' CSS
- * class, which still keeps it visible for screen-readers and assistive
- * technology. Headings allow screen-reader and keyboard only users to navigate
- * to or skip the links.
- * See http://juicystudio.com/article/screen-readers-display-none.php and
- * http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.
+ * See @cwd_base/block--system-menu-block.html.twig for available variables and other info.
  */
 #}
-{%
-  set classes = [
-    'block',
-    'block-menu',
-    'navigation',
-    'menu--' ~ derivative_plugin_id|clean_class,
-  ]
-%}
-{% set heading_id = attributes.id ~ '-menu'|clean_id %}
-{# title_prefix #}
+{# Label. #}
 {% if label %}
 <h2{{ title_attributes.addClass('menu-block-title') }}>{{ label }}</h2>
 {% endif %}
-{# title_suffix #}
 <nav class="secondary-navigation drupal-section-navigation mobile-expander" aria-label="Section Navigation">
-{# Menu. #}
-{% block content %}
-  {{ content }}
-{% endblock %}
+  {# Menu. #}
+  {% block content %}
+    {{ content }}
+  {% endblock %}
 </nav>
 

templates/block--menu-block--utility-navigation.html.twig

@@ -1,48 +1,15 @@
 {#
 /**
  * @file
- * Theme override for a menu block.
+ * Theme override for any menu block placement of "utility-navigation" menu.
+ * IRL: This template is only used by cwd_*_utilitynavigation (on CD Demo).
  *
- * Available variables:
- * - plugin_id: The ID of the block implementation.
- * - label: The configured label of the block if visible.
- * - configuration: A list of the block's configuration values.
- *   - label: The configured label for the block.
- *   - label_display: The display settings for the label.
- *   - provider: The module or other provider that provided this block plugin.
- *   - Block plugin specific settings will also be stored here.
- * - content: The content of this block.
- * - attributes: HTML attributes for the containing element.
- *   - id: A valid HTML ID and guaranteed unique.
- * - title_attributes: HTML attributes for the title element.
- * - content_attributes: HTML attributes for the content element.
- * - title_prefix: Additional output populated by modules, intended to be
- *   displayed in front of the main title tag that appears in the template.
- * - title_suffix: Additional output populated by modules, intended to be
- *   displayed after the main title tag that appears in the template.
- *
- * Headings should be used on navigation menus that consistently appear on
- * multiple pages. When this menu block's label is configured to not be
- * displayed, it is automatically made invisible using the 'visually-hidden' CSS
- * class, which still keeps it visible for screen-readers and assistive
- * technology. Headings allow screen-reader and keyboard only users to navigate
- * to or skip the links.
- * See http://juicystudio.com/article/screen-readers-display-none.php and
- * http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.
+ * See @cwd_base/block--system-menu-block.html.twig for available variables and other info.
  */
 #}
-{%
-  set classes = [
-    'block',
-    'block-menu',
-    'navigation',
-    'menu--' ~ derivative_plugin_id|clean_class,
-  ]
-%}
-{% set heading_id = attributes.id ~ '-menu'|clean_id %}
 <nav id="utility-navigation" aria-label="Supplementary Navigation">
-{# Menu. #}
-{% block content %}
-  {{ content }}
-{% endblock %}
+  {# Menu. #}
+  {% block content %}
+    {{ content }}
+  {% endblock %}
 </nav>

templates/block--system-menu-block--main.html.twig

@@ -1,45 +1,14 @@
 {#
 /**
  * @file
- * Theme override for a menu block.
+ * Theme override for any menu block placement of "main" menu.
+ * IRL: Only meant for cwd_*_main_menu block.
+ * 💬 This menu block is a core menu block, not a menu_block module menu block, so there's no theme hook suggestion setting to target it more specifically. Should we redo the main menu block with the menu_block module? Maybe! Not sure it's worth the trouble it would cause, but I think it's worth considering.
+ * Related: https://github.com/CU-CommunityApps/CD-demo/issues/79
  *
- * Available variables:
- * - plugin_id: The ID of the block implementation.
- * - label: The configured label of the block if visible.
- * - configuration: A list of the block's configuration values.
- *   - label: The configured label for the block.
- *   - label_display: The display settings for the label.
- *   - provider: The module or other provider that provided this block plugin.
- *   - Block plugin specific settings will also be stored here.
- * - content: The content of this block.
- * - attributes: HTML attributes for the containing element.
- *   - id: A valid HTML ID and guaranteed unique.
- * - title_attributes: HTML attributes for the title element.
- * - content_attributes: HTML attributes for the content element.
- * - title_prefix: Additional output populated by modules, intended to be
- *   displayed in front of the main title tag that appears in the template.
- * - title_suffix: Additional output populated by modules, intended to be
- *   displayed after the main title tag that appears in the template.
- *
- * Headings should be used on navigation menus that consistently appear on
- * multiple pages. When this menu block's label is configured to not be
- * displayed, it is automatically made invisible using the 'visually-hidden' CSS
- * class, which still keeps it visible for screen-readers and assistive
- * technology. Headings allow screen-reader and keyboard only users to navigate
- * to or skip the links.
- * See http://juicystudio.com/article/screen-readers-display-none.php and
- * http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.
+ * See @cwd_base/block--system-menu-block.html.twig for available variables and other info.
  */
 #}
-{%
-  set classes = [
-    'block',
-    'block-menu',
-    'navigation',
-    'menu--' ~ derivative_plugin_id|clean_class,
-  ]
-%}
-{% set heading_id = attributes.id ~ '-menu'|clean_id %}
 <nav class="dropdown-menu dropdown-menu-on-demand" id="main-navigation" aria-label="Main Navigation">
   <div class="container-fluid">
     <a id="mobile-home" href="/"><span class="sr-only">Home</span></a>

templates/block--system-menu-block.html.twig

@@ -1,7 +1,11 @@
 {#
 /**
  * @file
- * Theme override for a menu block.
+ * "Fallback" theme override for menu blocks.
+ * Based on @classy/block/block--system-menu-block.html.twig.
+ * IRL: Not in use (on CD Demo), just a starting place for menu block templates
+ * on child sites, if needed. (Works with core and menu_block menu blocks.)
+ * ~ Removed redundant role="navigation" from <nav> element.
  *
  * Available variables:
  * - plugin_id: The ID of the block implementation.

templates/block--views-block--spotlight-block-1.html.twig

@@ -1,48 +1,11 @@
 {#
 /**
  * @file
- * Default theme implementation to display a block.
+ * Theme override to display spotlights view block.
+ * LEGACY TEMPLATE, only keeping around in case it's used by older child sites -- spotlights view
+ * no longer has a display called block_1.
  *
- * Available variables:
- * - $block->subject: Block title.
- * - $content: Block content.
- * - $block->module: Module that generated the block.
- * - $block->delta: An ID for the block, unique within each module.
- * - $block->region: The block region embedding the current block.
- * - $classes: String of classes that can be used to style contextually through
- *   CSS. It can be manipulated through the variable $classes_array from
- *   preprocess functions. The default values can be one or more of the
- *   following:
- *   - block: The current template type, i.e., "theming hook".
- *   - block-[module]: The module generating the block. For example, the user
- *     module is responsible for handling the default user navigation block. In
- *     that case the class would be 'block-user'.
- * - $title_prefix (array): An array containing additional output populated by
- *   modules, intended to be displayed in front of the main title tag that
- *   appears in the template.
- * - $title_suffix (array): An array containing additional output populated by
- *   modules, intended to be displayed after the main title tag that appears in
- *   the template.
- *
- * Helper variables:
- * - $classes_array: Array of html class attribute values. It is flattened
- *   into a string within the variable $classes.
- * - $block_zebra: Outputs 'odd' and 'even' dependent on each block region.
- * - $zebra: Same output as $block_zebra but independent of any block region.
- * - $block_id: Counter dependent on each block region.
- * - $id: Same output as $block_id but independent of any block region.
- * - $is_front: Flags true when presented in the front page.
- * - $logged_in: Flags true when the current user is a logged-in member.
- * - $is_admin: Flags true when the current user is an administrator.
- * - $block_html_id: A valid HTML ID and guaranteed unique.
- *
- * @ingroup templates
- *
- * @see bootstrap_preprocess_block()
- * @see template_preprocess()
- * @see template_preprocess_block()
- * @see bootstrap_process_block()
- * @see template_process()
+ * TO DO: Maybe we can remove this, right? We don't guarantee backwards-compatability with cwd_base, so it's just clutter, right...?
  */
 #}
 {%

templates/menu--main.html.twig

@@ -1,7 +1,10 @@
 {#
 /**
  * @file
- * Theme override to display a menu.
+ * Theme override to display any instance of "main" menu.
+ * Based on @classy/navigation/menu.html.twig.
+ * IRL: Only meant for cwd_*_main_menu block. (See block--system-menu-block--main.html.twig for additional commentary.)
+ * ~ Add .list-menu.links classes to <ul>.
  *
  * Available variables:
  * - menu_name: The machine name of the menu.
@@ -30,6 +33,7 @@
 {% macro menu_links(items, attributes, menu_level) %}
   {% import _self as menus %}
   {% if items %}
+    {# TO DO: why even have this conditional if the markup is the same either way?... #}
     {% if menu_level == 0 %}
       <ul class="menu list-menu links">
     {% else %}

templates/menu--section-navigation.html.twig

@@ -1,21 +1,14 @@
 {#
 /**
  * @file
- * Theme override to display a menu.
+ * Theme override for "Section navigation" instance of "main" menu (usually
+ * placed in sidebar_primary region) (named based on theme hook suggestion in
+ * block config).
  *
- * Available variables:
- * - menu_name: The machine name of the menu.
- * - items: A nested list of menu items. Each menu item contains:
- *   - attributes: HTML attributes for the menu item.
- *   - below: The menu item child items.
- *   - title: The menu link title.
- *   - url: The menu link url, instance of \Drupal\Core\Url
- *   - localized_options: Menu link localized options.
- *   - is_expanded: TRUE if the link has visible children within the current
- *     menu tree.
- *   - is_collapsed: TRUE if the link has children within the current menu tree
- *     that are not currently visible.
- *   - in_active_trail: TRUE if the link is in the active trail.
+ * ~ (ALMOST) A direct copy of @classy/navigation/menu.html.twig.
+ *   See code comments below for related wonderings... (and maybe resolve the differences and update this code comment!)
+ *
+ * See @cwd_base/menu--main for available variables.
  */
 #}
 {% import _self as menus %}
@@ -24,6 +17,7 @@
   We call a macro which calls itself to render the full tree.
   @see http://twig.sensiolabs.org/doc/tags/macro.html
 #}
+{# TO DO: what is this line is for? 👇 git says it's been here since the initial repo commit, so, idk, but it looks like an accident to me #}
 {% set content_attributes = content_attributes.addClass(list_classes) %}
 {{ menus.menu_links(items, attributes, 0) }}
 
@@ -32,6 +26,9 @@
   {% if items %}
     {% if menu_level == 0 %}
       <ul class="menu">
+        {# TO DO: why even have this conditional if the markup is the same either way?...
+        ...FWIW, in @classy, the "if menu_level == 0" version looks like this, which also seems silly, right? --
+        <ul{{ attributes.addClass('menu') }}> #}
     {% else %}
       <ul class="menu">
     {% endif %}

templates/menu--utility-navigation.html.twig

@@ -1,21 +1,12 @@
 {#
 /**
  * @file
- * Theme override to display a menu.
+ * Theme override to display any instance of "utility-navigation" menu.
+ * ~ A direct copy of @cwd_base/menu--main.html.twig.
  *
- * Available variables:
- * - menu_name: The machine name of the menu.
- * - items: A nested list of menu items. Each menu item contains:
- *   - attributes: HTML attributes for the menu item.
- *   - below: The menu item child items.
- *   - title: The menu link title.
- *   - url: The menu link url, instance of \Drupal\Core\Url
- *   - localized_options: Menu link localized options.
- *   - is_expanded: TRUE if the link has visible children within the current
- *     menu tree.
- *   - is_collapsed: TRUE if the link has children within the current menu tree
- *     that are not currently visible.
- *   - in_active_trail: TRUE if the link is in the active trail.
+ * TO DO: Maybe clear out this template and "include" ^^that one?
+ *
+ * See @cwd_base/menu--main.html.twig for available variables.
  */
 #}
 {% import _self as menus %}