Squashed merge of task/GH-310-breadcrumbs at commit 13276af

README.md

@@ -93,6 +93,28 @@ To support multiple instances of the CMS on one machine (i.e. local development)
     docker-compose -f docker-compose.custom.yml …
     ```
 
+### (Optional) Migrate Website from Older Version
+
+Some websites need static resources to supplement their migration.
+
+1. __If__ you did not [create your project by cloning `example-cms`](#custom-resources), __then__:
+    1. Copy `templates/fullwidth.html` from `taccsite_custom/example-cms/` to `taccsite_custom/name-of-project/`.
+    2. Copy `static/.../css/src/migrate.v1_v2.css` from `taccsite_custom/example-cms/` to `taccsite_custom/name-of-project/`.
+2. Update `taccsite_custom/name-of-project/templates/fullwidth.html` to load migration assets e.g.:
+    - Change
+
+    ```html
+      <!-- To style old CMS content on new CMS -->
+      <!-- <link rel="stylesheet" href="{% static 'example-cms/css/build/migrate.v1_v2.css' %}"> -->
+    ```
+
+    - To
+
+    ```html
+      <!-- To style old CMS content on new CMS -->
+      <link rel="stylesheet" href="{% static 'name-of-project/css/build/migrate.v1_v2.css' %}">
+    ```
+
 ## Run the CMS
 
 ### Prerequisites

taccsite_cms/static/site_cms/css/src/_imports/trumps/README.css

@@ -3,7 +3,7 @@
 /*
 Trumps
 
-Trump styles exist to overwrite other styles. They are added as necessary. Examples use cases are third-party styles, styles used only by JavaScript, modules that are not meant to extended as desired.
+Trump styles exist to overwrite other styles. They are added as necessary. Examples use cases are third-party styles, styles used only by JavaScript, modules that are not meant to be extended.
 
 Reference:
 
@@ -25,15 +25,24 @@ Styleguide Trumps
 /*
 Scopes
 
-Scope styles are overrides and styles that are scoped to a specific area. These are meant to be used sparingly. Examples of scopes are styles for third-party markup, WYSIWIG editor tags, form elements, components with a forced relationship.
+Scope styles are overrides and styles that are scoped to a specific area. These are meant to be used sparingly. Examples of scopes are styles for:
+- third-party markup, e.g.:
+    - social media widget
+    - external authentication form
+    - internal Bootstrap-dependent markup
+- enforcing internal markup (e.g. breadcrumbs, form elements, document pages)
+- WYSIWIG editor tags (e.g. CMS WYSIWIG content entry)
+- coupled components (i.e. components interwoven in unique situations), e.g.:
+    - Frontera homepage before all styling used plugins
+    - article previews within an article list
 
 Reference:
 
 - [BEM with Namespaces: Scope Namespaces](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/#scope-namespaces-s-)
 
 Guidelines:
 
-- Scopes are pretty rare, evaluate before creating.
+- Scopes should be rare; evaluate before creating.
 - A consistent way to author these in nested inside `.s-* {}`.
 
 Rules:

taccsite_cms/static/site_cms/css/src/_imports/trumps/s-breadcrumbs.css

@@ -0,0 +1,62 @@
+/*
+Breadcrumbs
+
+A list of links and to ancestor navigation (pages or sections that are a parent, grandparent, et cetera of the current page or section).
+
+Notice: A scope class is used to enforce appropriate semantic HTML.
+
+Markup:
+<!-- major navigation -->
+<nav class="s-breadcrumbs">
+  <ol>
+      <li><a href="/"><span>Home</span></a></li>
+      <li><a href="/"><span>Science</span></a></li>
+      <li><span>Publications</span></li>
+  </ol>
+</nav>
+<!-- minor navigation -->
+<ol class="s-breadcrumbs">
+    <li><a href="/"><span>Home</span></a></li>
+    <li><a href="/"><span>Science</span></a></li>
+    <li><span>Publications</span></li>
+</ol>
+
+Styleguide Trumps.Scopes.Breadcrumbs
+*/
+@import url("_imports/tools/x-truncate.css");
+
+
+
+
+
+/* Base i.e. Container */
+
+nav.s-breadcrumbs {
+  padding-top: 15px;
+
+  font-size: var(--global-font-size--x-small);
+
+  text-transform: uppercase;
+}
+
+
+
+/* Elements i.e. Content */
+
+nav.s-breadcrumbs ol {
+  list-style: none;
+}
+
+ol.s-breadcrumbs li,
+.s-breadcrumbs ol li {
+  display: inline-block;
+}
+
+ol.s-breadcrumbs li + li::before,
+.s-breadcrumbs ol li + li::before {
+  content: ' > ';
+}
+
+.s-breadcrumbs ol li:last-child span {
+  font-weight: var(--bold);
+}

taccsite_cms/static/site_cms/css/src/site.css

@@ -6,8 +6,8 @@
 /* SETTINGS */
 /* Shared with Portal */
 @import url("_imports/settings/border.css");
-@import url("_imports/settings/color.css");
 /* Unique to CMS */
+@import url("_imports/settings/color.css");
 @import url("_imports/settings/props.max-width.css");
 @import url("_imports/settings/props.space.css");
 @import url("_imports/settings/font.css");
@@ -41,6 +41,7 @@
 
 /* TRUMPS */
 @import url("_imports/trumps/s-article-list.css");
+@import url("_imports/trumps/s-breadcrumbs.css");
 @import url("_imports/trumps/s-footer.css");
 @import url("_imports/trumps/s-blockquote.css");
 @import url("_imports/trumps/u-empty.css");

taccsite_cms/templates/fullwidth.html

@@ -12,6 +12,7 @@
 {% endblock assets_custom %}
 
 {% block content %}
+{% include "nav_cms_breadcrumbs.html" %}
 {% placeholder "content" %}
 {% endblock content %}
 

taccsite_cms/templates/menu/breadcrumb.html

@@ -0,0 +1,24 @@
+{# SEE: https://github.com/django-cms/django-cms/blob/release/3.6.x/menus/templates/menu/breadcrumb.html #}
+{% for ance in ancestors %}
+
+  {# To support structured data, item* attributes are used #}
+  {# SEE: https://confluence.tacc.utexas.edu/x/5yMFDg #}
+  <li itemscope itemprop="itemListElement"
+      itemtype="https://schema.org/ListItem">
+
+  {% if not forloop.last %}
+
+    <a href="{{ ance.get_absolute_url }}" itemprop="item">
+      <span itemprop="name">{{ ance.get_menu_title }}</span>
+    </a>
+
+  {% else %}
+
+    <span itemprop="name">{{ ance.get_menu_title }}</span>
+
+  {% endif %}
+
+    <meta itemprop="position" content="{{ forloop.counter }}" />
+  </li>
+
+{% endfor %}

taccsite_cms/templates/nav_cms_breadcrumbs.html

@@ -0,0 +1,16 @@
+{# @var className #}
+{% load menu_tags %}
+
+<nav class="s-breadcrumbs  {{className}}">
+
+  {# To support structured data, item* attributes are used #}
+  {# SEE: https://confluence.tacc.utexas.edu/x/5yMFDg #}
+  <ol itemscope itemtype="https://schema.org/BreadcrumbList">
+
+    {# To include pages marked to not show in menu, attributes are added #}
+    {# SEE: https://docs.django-cms.org/en/release-3.6.x/reference/navigation.html#show-breadcrumb #}
+    {% show_breadcrumb 0 "menu/breadcrumb.html" 0 %}
+
+  </ol>
+
+</nav>

taccsite_cms/templates/snippets/README.md

@@ -8,7 +8,7 @@ _This directory can alleviate danger #1 of [Why a Snippet Is Dangerous](#why-a-s
 
 1. The Core CMS __must not__ use any snippets __for production__. _They __should only__ be for testing._
 2. A CMS project __should not__ use any snippets. _They __may only__ be temporarily._
-3. A CMS project snippet __must__ be saved into its respective snippets directory, `/code/taccsite_custom/name-of-project/static`.
+3. A CMS project snippet __must__ be saved into its respective snippets directory, `/code/taccsite_custom/name-of-project/templates/snippets`.
 4. Any snippet file __must__ be kept up to date with its snippet.[^1]
 
 [^1]: For now, maintain snippet source code via internal team process.
@@ -21,9 +21,9 @@ It allows an authorized CMS user to create a snippet of front-end web code (e.g.
 
 ## Why a Snippet Is Dangerous
 
-1. The code is dependent on the (unsynced) database, because it is not under:
+1. (Unless saved) The code is dependent on the (unsynced) database, because it is not under:
     - source/version control
-2. The code is independent of any other code control:
+2. The code may be authored independent of any other code control:
     - security
     - dependency management
     - style guide