Merge pull request #2154 from GSA/2119-clean-up-best-practices-folders-and-components

2119 clean up best practices folders and components

app/assets/sass/uswds/_uswds-theme-custom-styles.scss

@@ -676,28 +676,28 @@ details form {
    margin-top: 0;
 }
 
-ol.best-practices-list {
+ol.guides-list {
    counter-reset: item;
    list-style-type: none;
    padding-left: 0;
 }
 
-ol.best-practices-list.set-two {
+ol.guides-list.set-two {
    counter-reset: item 6;
 }
 
-ol.best-practices-list.set-three {
+ol.guides-list.set-three {
    counter-reset: item 10;
 }
 
-ol.best-practices-list li {
+ol.guides-list li {
    counter-increment: item;
    margin-bottom: 15px;
    position: relative;
    padding-left: 40px;
 }
 
-ol.best-practices-list li::before {
+ol.guides-list li::before {
    content: counter(item);
    background-color: #005ea2;
    color: white;
@@ -713,11 +713,11 @@ ol.best-practices-list li::before {
    top: 0;
 }
 
-li.best-practices {
+li.guides {
    padding-bottom: 50px;
 }
 
-div.best-practices {
+div.guides {
    height: 400px
 }
 
@@ -820,7 +820,7 @@ $do-dont-top-bar-width: 1;
 }
 
 @media (max-width: 758px) {
-   .best-practices-flex-container {
+   .guides-flex-container {
       flex-direction: column;
    }
 }

app/main/views/index.py

@@ -25,7 +25,7 @@ from app.utils.user import user_is_logged_in
 # Hook to check for feature flags
 @main.before_request
 def check_feature_flags():
-    if request.path.startswith("/guides/best-practices") and not current_app.config.get(
+    if request.path.startswith("/guides") and not current_app.config.get(
         "FEATURE_BEST_PRACTICES_ENABLED", False
     ):
         abort(404)
@@ -207,61 +207,61 @@ def trial_mode_new():
 @user_is_logged_in
 def best_practices():
     return render_template(
-        "views/best-practices/best-practices.html",
+        "views/guides/best-practices.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/clear-goals")
+@main.route("/guides/clear-goals")
 @user_is_logged_in
 def clear_goals():
     return render_template(
-        "views/best-practices/clear-goals.html",
+        "views/guides/clear-goals.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/rules-and-regulations")
+@main.route("/guides/rules-and-regulations")
 @user_is_logged_in
 def rules_and_regulations():
     return render_template(
-        "views/best-practices/rules-and-regulations.html",
+        "views/guides/rules-and-regulations.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/establish-trust")
+@main.route("/guides/establish-trust")
 @user_is_logged_in
 def establish_trust():
     return render_template(
-        "views/best-practices/establish-trust.html",
+        "views/guides/establish-trust.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/write-for-action")
+@main.route("/guides/write-for-action")
 @user_is_logged_in
 def write_for_action():
     return render_template(
-        "views/best-practices/write-for-action.html",
+        "views/guides/write-for-action.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/multiple-languages")
+@main.route("/guides/multiple-languages")
 @user_is_logged_in
 def multiple_languages():
     return render_template(
-        "views/best-practices/multiple-languages.html",
+        "views/guides/multiple-languages.html",
         navigation_links=best_practices_nav(),
     )
 
 
-@main.route("/guides/best-practices/benchmark-performance")
+@main.route("/guides/benchmark-performance")
 @user_is_logged_in
 def benchmark_performance():
     return render_template(
-        "views/best-practices/benchmark-performance.html",
+        "views/guides/benchmark-performance.html",
         navigation_links=best_practices_nav(),
     )
 

app/templates/components/nav_breadcrumb.html

@@ -1,8 +1,12 @@
+{% macro breadcrumb(title, parent_menu_title, url) %}
 <nav class="navigation-service usa-breadcrumb padding-top-0">
   <ol class="usa-breadcrumb__list">
     <li class="usa-breadcrumb__list-item">
-      <span class="usa-breadcrumb__label"><a href="{{ url_for('.best_practices') }}"
+      <span class="usa-breadcrumb__label">
-          class="usa-link navigation-organization-link">Best Practices</a></span>
+        <a href="{{ url_for(url) }}" class="usa-link navigation-organization-link">
+          {{ parent_menu_title }}
+        </a>
+      </span>
     </li>
     {% if title %}
     <li class="usa-breadcrumb__list-item">
@@ -11,3 +15,4 @@
     {% endif %}
   </ol>
 </nav>
+{% endmacro %}

app/templates/views/about/about.html

@@ -7,7 +7,6 @@
 {% endblock %}
 
 {% block content_column_content %}
-<!-- {% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %} -->
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p>Notify.gov is a text messaging service built by and for the government. We help agencies communicate more

app/templates/views/about/security.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
 
 {% set page_title = "Security" %}
 
@@ -7,7 +8,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-<!-- {% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %} -->
+{{ breadcrumbs.breadcrumb(page_title, "About", "main.about_notify") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base">Notify.gov is built for the needs of government agencies with fundamental system

app/templates/views/about/why-text-messaging.html

@@ -1,4 +1,6 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
+
 {% set page_title = "Why text messaging" %}
 
 {% block per_page_title %}
@@ -6,8 +8,7 @@
 {% endblock %}
 
 {% block content_column_content %}
-<!-- {% with title=page_title, parent_title="About", url="main.why_text_messaging" %}{% include
+{{ breadcrumbs.breadcrumb(page_title, "About", "main.about_notify") }}
-"components/best-practices/nav_breadcrumb.html" %}{% endwith %} -->
 
 <section class="usa-prose">
   <h1>{{page_title}}</h1>

app/templates/views/guides/benchmark-performance.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
 
 {% set page_title = "Measuring performance with benchmarking" %}
 
@@ -7,7 +8,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base">Learn how effective your texting program can be.</p>
@@ -19,7 +21,7 @@
   </p>
   <h2>What other texting studies have found</h2>
   <p>
-    When the <a
+    When the <a class="use-link usa-link--external"
       href="https://www.cbpp.org/research/food-assistance/targeted-text-message-outreach-can-increase-wic-enrollment-pilots-show"
       target="_blank">Center on Budget and Policy Priorities</a> studied WIC, they found key learnings about the
     quantity of messages delivered, how people engage with messages, and how they take action.
@@ -78,7 +80,8 @@
   </div>
 
   <p>
-    The <a href="https://codeforamerica.org/resources/texting-playbook/" target="_blank">Code for America’s Texting
+    The <a class="use-link usa-link--external" href="https://codeforamerica.org/resources/texting-playbook/"
+      target="_blank">Code for America’s Texting
       Playbook</a>
     reported specific learnings around appointment reminders, completing
     document submission, and maintenance reminders.

app/templates/views/guides/best-practices.html

@@ -1,11 +1,12 @@
 {% extends "base.html" %}
 
+{% set page_title = "Best Practices" %}
+
 {% block per_page_title %}
-Best Practices
+{{page_title}}
 {% endblock %}
 
 {% block content_column_content %}
-
 <section class="usa-prose">
   <h1>Best Practices</h1>
   <p class="font-sans-lg text-base">For texting the public</p>
@@ -23,41 +24,41 @@ Best Practices
   "svg_src": "goal",
   "card_heading": "Establish clear goals",
   "p_text": "Start with a singular purpose. Make explicit what you want to achieve.",
-  "link": "/guides/best-practices/clear-goals"
+  "link": "/guides/clear-goals"
   },
   {
   "svg_src": "compliant",
   "card_heading": "Follow rules & regulations",
   "p_text": "Understand what is required when texting the public.",
-  "link": "/guides/best-practices/rules-and-regulations"
+  "link": "/guides/rules-and-regulations"
   },
   {
   "svg_src": "trust",
   "card_heading": "Establish trust",
   "p_text": "Help your audience anticipate and welcome your texts.",
-  "link": "/guides/best-practices/establish-trust"
+  "link": "/guides/establish-trust"
   },
   {
   "svg_src": "runner",
   "card_heading": "Write texts that provoke action",
   "p_text": "Help your audience know what to do with the information you send.",
-  "link": "/guides/best-practices/write-for-action"
+  "link": "/guides/write-for-action"
   },
   {
   "svg_src": "language",
   "card_heading": "Send texts in multiple languages",
   "p_text": "What to know as you plan translated texts.",
-  "link": "/guides/best-practices/multiple-languages"
+  "link": "/guides/multiple-languages"
   },
   {
   "svg_src": "chart",
   "card_heading": "Measure performance with benchmarking",
   "p_text": "Learn how effective your texting program can be.",
-  "link": "/guides/best-practices/benchmark-performance"
+  "link": "/guides/benchmark-performance"
   }
   ] %}
 
-  {% with card_contents=card_contents %}{% include "components/best-practices/cards.html" %}{%
+  {% with card_contents=card_contents %}{% include "components/guides/cards.html" %}{%
   endwith %}
 
 </section>

app/templates/views/guides/clear-goals.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
 
 {% set page_title = "Establish clear goals" %}
 
@@ -7,7 +8,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base">Start with a singular purpose. Make explicit what you want to achieve.</p>
@@ -160,7 +162,7 @@
   </div>
   <p>
     Review your drafted hypothesis with your team to make sure everyone is aligned on your desired goals. A clear and
-    concise hypothesis can help you decide how to <a href="../best-practices/write-for-action">write text message
+    concise hypothesis can help you decide how to <a href="../guides/write-for-action">write text message
       content
       that provokes action</a>.
   </p>

app/templates/views/guides/establish-trust.html

@@ -1,5 +1,7 @@
 {% extends "base.html" %}
-{% from "components/best-practices/circle_number.html" import circle_number %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
+
+{% from "components/guides/circle_number.html" import circle_number %}
 
 {% set page_title = "Establish trust" %}
 
@@ -8,7 +10,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base">Help your audience anticipate and welcome your texts.</p>
@@ -38,7 +41,7 @@
     <li class="flex-1 width-full height-full padding-bottom-2">
       <div class="usa-card__container border-0">
         <p>To reinforce legitimacy, include these key messages in your outreach:</p>
-        <ol class="best-practices-list">
+        <ol class="guides-list">
           <li><b>Introduce yourself</b> – Give people time to get to know your texting communications before you need
             direct action from them</li>
           <li><b>Phone number</b> – Note the sending phone number your texts will come from</li>
@@ -79,7 +82,7 @@
   <ul class="usa-card-group flex-1 flex-wrap padding-top-2">
     <li class="flex-1 width-full height-full padding-bottom-2">
       <div class="usa-card__container border-0">
-        <ol start="7" class="best-practices-list set-two">
+        <ol start="7" class="guides-list set-two">
           <li>Identify yourself in the text message. Use a consistent and familiar <b>program name</b> to precede each
             text you send.</li>
           <li>Personalize with <b>first name</b>. Through A/B testing, Code for America saw an increase in
@@ -98,7 +101,7 @@
           <p class="sms-message-wrapper text-left">
             {{circle_number(7) }}<b>Dept. of Social Services:</b> Hi {{circle_number(8) }}<b>Julie,</b> Your Medicaid
             renewal is closing December 31, 2023. You can renew online at {{circle_number(9) }}<a
-              href="https://www.application.yourstate.gov" target="_blank"
+              class="use-link usa-link--external" href="https://www.application.yourstate.gov" target="_blank"
               rel="application.yourstate.gov">https://www.application.yourstate.gov</a> or {{circle_number(10) }}
             <b>call the number on the back</b> of your Medicaid card.
           </p>
@@ -114,14 +117,14 @@
         <p>If you're sending one-way notifications, phone carriers allow a single auto-response message that will be
           generated if a recipient tries to text a response to your message. Use the auto-response to reaffirm your key
           messages around legitimacy and communicate to recipients that texts are coming from an automated system.</p>
-        <ol class="best-practices-list set-three">
+        <ol class="guides-list set-three">
           <li>Provide <b>a way to contact a human</b> in any auto-response text</li>
           <li>Provide <b>information on how to opt out</b> and opt back in</li>
         </ol>
       </div>
     </li>
     <li class="usa-card flex-1 usa-card--media-right width-full padding-top-3">
-      <div class="usa-card__container border-0 width-full overflow-hidden best-practices">
+      <div class="usa-card__container border-0 width-full overflow-hidden guides">
         <img class="width-full" src="{{ asset_url('images/phone_grey.svg') }}" role="img" alt="Phone" />
         <div class="position-absolute flex text-center padding-5 padding-top-15">
           <p class="sms-message-wrapper text-left">
@@ -167,7 +170,7 @@
   },
   ] %}
 
-  {% with card_contents=card_contents %}{% include "components/best-practices/cards.html" %}{%
+  {% with card_contents=card_contents %}{% include "components/guides/cards.html" %}{%
   endwith %}
   <h3 class="padding-bottom-2">Prepare your team</h3>
   {% set card_contents = [
@@ -187,7 +190,7 @@
   pages or within case management notes.",
   },
   ] %}
-  {% with card_contents=card_contents %}{% include "components/best-practices/cards.html" %}{%
+  {% with card_contents=card_contents %}{% include "components/guides/cards.html" %}{%
   endwith %}
 </section>
 {% endblock %}

app/templates/views/guides/multiple-languages.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
 
 {% set page_title = "Text in multiple languages" %}
 
@@ -7,7 +8,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base"> What to know as you plan translated texts.</p>

app/templates/views/guides/rules-and-regulations.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
 
 {% set page_title = "Rules and regulations" %}
 
@@ -7,7 +8,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base">Understand what is required when texting the public.</p>
@@ -20,7 +22,7 @@
     If you do need expressed consent, consider including a pre-checked plain language opt-in (i.e. “It’s OK to text
     me.”) on
     digital forms. Be sure to ask for an up-to-date phone number and include a question about the recipient’s preferred
-    language for text messages if you expect to <a href="../best-practices/multiple-languages">translate your text
+    language for text messages if you expect to <a href="../guides/multiple-languages">translate your text
       messages</a> in
     languages other than English.
   </p>
@@ -79,7 +81,7 @@
   <h3>Opting out</h3>
   <p>
     There is no policy requirement for senders to communicate opt-out options, but <a
-      href="../best-practices/establish-trust#as-people-receive-texts"> including instructions in introductory and/or
+      href="../guides/establish-trust#as-people-receive-texts"> including instructions in introductory and/or
       auto-response texts </a> on how to opt out and opt back in are effective ways to establish trust with your
     audience.
   </p>

app/templates/views/guides/write-for-action.html

@@ -1,5 +1,6 @@
 {% extends "base.html" %}
-{% from "components/best-practices/circle_number.html" import circle_number %}
+{% import "components/nav_breadcrumb.html" as breadcrumbs %}
+{% from "components/guides/circle_number.html" import circle_number %}
 
 {% set page_title = "Write texts that provoke action" %}
 
@@ -8,7 +9,8 @@
 {% endblock %}
 
 {% block content_column_content %}
-{% with title=page_title %}{% include "components/best-practices/nav_breadcrumb.html" %}{% endwith %}
+{{ breadcrumbs.breadcrumb(page_title, "Guides", "main.best_practices") }}
+
 <section class="usa-prose">
   <h1>{{page_title}}</h1>
   <p class="font-sans-lg text-base"> Help your audience know what to do with the information you send.</p>
@@ -40,11 +42,11 @@
     <li>Use a neutral, direct, and professional tone. This works better than a friendly or overly casual tone.</li>
   </ul>
   <h2>Build conditions for action</h2>
-  <ul class="usa-card-group flex-1 flex-wrap padding-top-2 best-practices-flex-container">
+  <ul class="usa-card-group flex-1 flex-wrap padding-top-2 guides-flex-container">
     <li class="flex-1 width-full height-full padding-bottom-2">
       <div class="usa-card__container border-0">
         <p>For example, getting a person to update their mailing address:</p>
-        <ol class="best-practices-list">
+        <ol class="guides-list">
           <li>Clearly state the information and the response you want the recipient to take.</li>
           <li>Point directly to where the action can be completed, not to more information.</li>
           <li>Make sure the action can be completed via mobile phone, like calling a person or going to a
@@ -78,7 +80,8 @@
     </li>
   </ul>
   <h2>What provoking action looks like</h2>
-  <p class="padding-bottom-2"><a href="https://www.ncbi.nlm.nih.gov/pmc/articles/PMC10002044/" target="_blank">Evidence
+  <p class="padding-bottom-2"><a class="use-link usa-link--external"
+      href="https://www.ncbi.nlm.nih.gov/pmc/articles/PMC10002044/" target="_blank">Evidence
       shows</a> that employing
     behavioral science is an effective way to increase the
     likelihood of a recipient
@@ -100,7 +103,7 @@
   internet services <b>that belong to you</b>.",
   },
   ] %}
-  {% with card_contents=card_contents, text_align='left' %}{% include "components/best-practices/cards.html" %}{%
+  {% with card_contents=card_contents, text_align='left' %}{% include "components/guides/cards.html" %}{%
   endwith %}
 </section>
 {% endblock %}

tests/app/main/views/test_index.py

@@ -125,6 +125,7 @@ def test_static_pages(client_request, mock_get_organization_by_domain, view, moc
             "write_for_action",
             "multiple_languages",
             "benchmark_performance",
+            "guidance_index"
         ]
         return (
             not current_app.config["FEATURE_BEST_PRACTICES_ENABLED"]

tests/end_to_end/test_best_practices_content_pages.py

@@ -11,7 +11,7 @@ E2E_TEST_URI = os.getenv("NOTIFY_E2E_TEST_URI")
 def test_best_practices_side_menu(authenticated_page):
     page = authenticated_page
 
-    page.goto(f"{E2E_TEST_URI}/guides/best-practices")
+    page.goto(f"{E2E_TEST_URI}")
 
     page.wait_for_load_state("domcontentloaded")
     check_axe_report(page)
@@ -58,7 +58,7 @@ def test_best_practices_side_menu(authenticated_page):
 def test_breadcrumbs_best_practices(authenticated_page):
     page = authenticated_page
 
-    page.goto(f"{E2E_TEST_URI}/guides/best-practices")
+    page.goto(f"{E2E_TEST_URI}")
 
     page.wait_for_load_state("domcontentloaded")
     check_axe_report(page)

urls.js

@@ -14,23 +14,23 @@ const sublinks = [
   { label: 'Security', path: '/features/security' },
   { label: 'Support', path: '/support' },
   { label: 'Best Practices', path: '/guides/best-practices' },
-  { label: 'Clear Goals', path: '/guides/best-practices/clear-goals' },
+  { label: 'Clear Goals', path: '/guides/clear-goals' },
   {
     label: 'Rules And Regulations',
-    path: '/guides/best-practices/rules-and-regulations',
+    path: '/guides/rules-and-regulations',
   },
-  { label: 'Establish Trust', path: '/guides/best-practices/establish-trust' },
+  { label: 'Establish Trust', path: '/guides/establish-trust' },
   {
     label: 'Write For Action',
-    path: '/guides/best-practices/write-for-action',
+    path: '/guides/write-for-action',
   },
   {
     label: 'Multiple Languages',
-    path: '/guides/best-practices/multiple-languages',
+    path: '/guides/multiple-languages',
   },
   {
     label: 'Benchmark Performance',
-    path: '/guides/best-practices/benchmark-performance',
+    path: '/guides/benchmark-performance',
   },
   // Add more links here as needed
 ];