add section on navigation

corehq/apps/styleguide/context.py

@@ -53,6 +53,12 @@ def get_navigation_context(current_page):
                     Page("Tables", 'styleguide_organisms_tables_b5'),
                 ],
             ),
+            NavigationGroup(
+                name="Pages",
+                pages=[
+                    Page("Navigation", 'styleguide_pages_navigation_b5'),
+                ],
+            ),
         ],
     }
 

corehq/apps/styleguide/templates/styleguide/bootstrap5/code_html_non_working.html

@@ -0,0 +1 @@
+{% include 'styleguide/bootstrap5/partials/readable_code_block.html' with content=content language="HTML" %}

corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/navs_cards.html

@@ -0,0 +1,27 @@
+<div class="card mb-3">
+  <div class="card-body">
+    <h5 class="card-title">Winter</h5>
+    December, January, February
+  </div>
+</div>
+
+<div class="card mb-3">
+  <div class="card-body">
+    <h5 class="card-title">Spring</h5>
+    March, April, May
+  </div>
+</div>
+
+<div class="card mb-3">
+  <div class="card-body">
+    <h5 class="card-title">Summer</h5>
+    June, July, August
+  </div>
+</div>
+
+<div class="card mb-3">
+  <div class="card-body">
+    <h5 class="card-title">Autumn</h5>
+    September, October, November
+  </div>
+</div>

corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/navs_tabs.html

@@ -0,0 +1,29 @@
+<ul class="nav nav-tabs" id="seasons" role="tablist">
+  <li class="nav-item" role="presentation">
+    <button class="nav-link active" id="winter-tab" data-bs-toggle="tab" data-bs-target="#winter-tab-pane" type="button" role="tab" aria-controls="winter-tab-pane" aria-selected="true">Winter</button>
+  </li>
+  <li class="nav-item" role="presentation">
+    <button class="nav-link" id="spring-tab" data-bs-toggle="tab" data-bs-target="#spring-tab-pane" type="button" role="tab" aria-controls="spring-tab-pane" aria-selected="false">Spring</button>
+  </li>
+  <li class="nav-item" role="presentation">
+    <button class="nav-link" id="summer-tab" data-bs-toggle="tab" data-bs-target="#summer-tab-pane" type="button" role="tab" aria-controls="summer-tab-pane" aria-selected="false">Summer</button>
+  </li>
+  <li class="nav-item" role="presentation">
+    <button class="nav-link" id="autumn-tab" data-bs-toggle="tab" data-bs-target="#autumn-tab-pane" type="button" role="tab" aria-controls="autumn-tab-pane" aria-selected="false">Autumn</button>
+  </li>
+</ul>
+
+<div class="tab-content" id="seasonsContent">
+  <div class="tab-pane fade show active" id="winter-tab-pane" role="tabpanel" aria-labelledby="winter-tab" tabindex="0">
+    December, January, February
+  </div>
+  <div class="tab-pane fade" id="spring-tab-pane" role="tabpanel" aria-labelledby="spring-tab" tabindex="0">
+    March, April, May
+  </div>
+  <div class="tab-pane fade" id="summer-tab-pane" role="tabpanel" aria-labelledby="summer-tab" tabindex="0">
+    June, July, August
+  </div>
+  <div class="tab-pane fade" id="autumn-tab-pane" role="tabpanel" aria-labelledby="autumn-tab" tabindex="0">
+    September, October, November
+  </div>
+</div>

corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/page_header.html

@@ -0,0 +1,11 @@
+<h1 class="h4">
+  Mobile Workers
+</h1>
+<p>
+  Mobile workers' activity and form submissions can be monitored in the Reports section of this CommCare HQ project space.
+  <br>
+  Read more about managing mobile workers on our
+  <a href="https://confluence.dimagi.com/display/commcarepublic/Create+and+Manage+CommCare+Mobile+Workers" target="_blank">
+    Help Site
+  </a>.
+</p>

corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/page_title_block.html

@@ -0,0 +1,3 @@
+{% block page_title %}
+  {{ current_page.title }}
+{% endblock %}

corehq/apps/styleguide/templates/styleguide/bootstrap5/pages/navigation.html

@@ -0,0 +1,164 @@
+{% extends 'styleguide/bootstrap5/base.html' %}
+{% load hq_shared_tags %}
+
+{% block intro %}
+  <h1 class="sg-title mb-0" id="content">Navigation</h1>
+  <p class="sg-lead">
+    Users should always know where they are and how to get back where they came from.
+  </p>
+{% endblock intro %}
+
+{% block toc %}
+  <h5 class="my-2 ms-3">On this page</h5>
+  <hr class="my-2 ms-3">
+  <nav id="TableOfContents">
+    <ul>
+      <li><a href="#overview">Overview</a>
+        <ul>
+          <li><a href="#top-navigation">Top Navigation</a></li>
+          <li><a href="#side-navigation">Side Navigation</a></li>
+          <li><a href="#breadcrumbs">Breadcrumbs</a></li>
+        </ul>
+      </li>
+      <li><a href="#page-headers">Page Headers</a></li>
+      <li><a href="#in-page-nav">In-page Navigation</a>
+        <ul>
+          <li><a href="#nav-tabs">Tabs</a></li>
+          <li><a href="#nav-cards">Cards</a></li>
+        </ul>
+      </li>
+    </ul>
+  </nav>
+{% endblock toc %}
+
+{% block content %}
+  <h2 id="overview">Overview</h2>
+  <p>
+    These standard navigation elements should be present on almost every page. The following assumes
+    that the page descends from <code>hqwebapp/bootstrap5/base_section.html</code>, which virtually all pages should.
+  </p>
+
+  <h3 id="top-navigation" class="pt-3">
+    Top Navigation
+  </h3>
+  <div class="card mb-3">
+    <div class="p-1">
+      <img src="{% static "styleguide/images/navigation/top_navigation.png" %}" width="100%" alt="top navigation example" />
+    </div>
+  </div>
+  <p>
+    The top navigation should <strong>always</strong> be visible to users. Individual tabs are defined in
+    <a href="https://github.com/dimagi/commcare-hq/blob/master/corehq/tabs/tabclasses.py" target="_blank">tabclasses.py</a>.
+    Which tab is highlighted depends on the <code>url_prefix_formats</code> defined for each tab. Which items
+    appear in a tab's dropdown is determined by <code>dropdown_items</code>.
+  </p>
+
+  <h3 id="side-navigation" class="pt-3">
+    Side Navigation
+  </h3>
+  <div class="card mb-3">
+    <div class="p-1">
+      <img src="{% static "styleguide/images/navigation/side_navigation.png" %}" width="100%" alt="top navigation example" />
+    </div>
+  </div>
+  <p>
+    The side navigation appears almost everywhere. Major exceptions are the dashboard,
+    which has no navigation, and app manager, which has a custom sidebar corresponding to the app's structure.
+    Other pages should almost certainly have a sidebar.
+  </p>
+  <p>
+    The sidebar is also defined in
+    <a href="https://github.com/dimagi/commcare-hq/blob/master/corehq/tabs/tabclasses.py" target="_blank">tabclasses.py</a>,
+    controlled by the <code>sidebar_items</code> class methods.
+  </p>
+  <p>
+    Temporary sub-items that appear only when on a specific page, such as the "Create Form Data Export" item that
+    appears under the main "Export Form Data" item only when you're creating a new export, can be added using
+    the <code>subpages</code> property.
+  </p>
+  <p>
+    Dynamic item names, such as displaying the username when editing a web user, can be enabled by passing a
+    function to the menu item's <code>title</code>.
+  </p>
+
+  <h3 id="breadcrumbs" class="pt-3">
+    Breadcrumbs
+  </h3>
+  <div class="card mb-3">
+    <div class="p-1">
+      <img src="{% static "styleguide/images/navigation/breadcrumbs.png" %}" width="100%" alt="top navigation example" />
+    </div>
+  </div>
+  <p>
+    Breadcrumbs are defined by the <code>parent_pages</code> class method in a class-based view.
+    Standard pages should have a breadcrumb for the top nav section (e.g., "Data"), for the left sidebar section
+    if there is one (e.g., "Edit Data"), and for the page itself. Multi-step workflows such as case import should
+    also be reflected in breadcrumbs. All items in the breadcrumbs should be links, except for the last
+    (the current page).
+  </p>
+  <p>
+    A few pages override the page_breadcrumbs block defined in the template:
+    <code>hqwebapp/bootstrap5/base_section.html</code>. This should only be done in exceptional circumstances.
+  </p>
+  <div class="alert alert-primary">
+    <strong>Usage Notes:</strong> See <a href="https://commcare-hq.readthedocs.io/class_views.html#hierarchy" target="_blank">this example</a> for
+    how to implement breadcrumbs on a class-based view.
+  </div>
+
+  <h2 id="page-headers" class="pt-4">
+    Page Headers
+  </h2>
+  <p>
+    A page header at the top of the page's main content helps the user stay oriented, and this is a good place to
+    briefly introduce the user to the page and link to documentation.
+  </p>
+  <p>
+    This is an area where the technical implementation isn't well-standardized. When possible, make sure you
+    <code>page_title</code> attribute is defined if using a class-based view
+    (<a href="https://commcare-hq.readthedocs.io/class_views.html#a-basic-centered-page" target="_blank">see this example</a>)
+    or passed into the template context if using a functional view.
+  </p>
+  <p>
+    For a class-based view, you would then (ideally) set the <code>page_title</code> block this way:
+    {% include 'styleguide/bootstrap5/code_html_non_working.html' with content=examples.page_title_block %}
+  </p>
+  <p>
+    Otherwise, you can set the page header manually with the following bit of HTML at the beginning of
+    <code>{% verbatim %}{% block page_content %}{% endverbatim %}</code>:
+  </p>
+  {% include 'styleguide/bootstrap5/code_example.html' with content=examples.page_header %}
+
+  <h2 id="in-page-nav" class="pt-4">
+    In-page Navigation
+  </h2>
+  <p>
+    If a page has multiple sections, you have a few options to visually separate them:
+  </p>
+  <ul>
+    <li>
+      Split into multiple pages.
+    </li>
+    <li>
+      Set each section up as a <code>tab</code> (<a href="https://getbootstrap.com/docs/5.3/components/navs-tabs/#tabs" target="_blank">see docs</a>).
+      Please avoid using <code>pill</code>s for navigation as they look similar to
+      <a href="{% url "styleguide_molecules_selections_b5" %}#select-toggle">select toggles</a> used in forms.
+    </li>
+    <li>
+      Enclose each section in a <code>card</code> (<a href="https://getbootstrap.com/docs/5.3/components/card/" target="_blank">see docs</a>).
+    </li>
+  </ul>
+  <h3 id="nav-tabs" class="pt-3">
+    Tabs
+  </h3>
+  <p>
+    Below is an example of sectioning a page with tabs. This is the most preferred method of sectioning a page in HQ.
+  </p>
+  {% include 'styleguide/bootstrap5/code_example.html' with content=examples.navs_tabs %}
+  <h3 id="nav-cards" class="pt-3">
+    Cards
+  </h3>
+  <p>
+    Below is an example of sectioning a page with cards.
+  </p>
+  {% include 'styleguide/bootstrap5/code_example.html' with content=examples.navs_cards %}
+{% endblock content %}

corehq/apps/styleguide/urls.py

@@ -80,4 +80,6 @@
         name="styleguide_organisms_forms_b5"),
     url(r'^b5/organisms/tables/$', bootstrap5.styleguide_organisms_tables,
         name="styleguide_organisms_tables_b5"),
+    url(r'^b5/pages/navigation/$', bootstrap5.styleguide_pages_navigation,
+        name="styleguide_pages_navigation_b5"),
 ]

corehq/apps/styleguide/views/bootstrap5.py

@@ -310,3 +310,17 @@ def styleguide_organisms_tables(request):
         },
     })
     return render(request, 'styleguide/bootstrap5/organisms/tables.html', context)
+
+
+@use_bootstrap5
+def styleguide_pages_navigation(request):
+    context = get_navigation_context("styleguide_pages_navigation_b5")
+    context.update({
+        'examples': {
+            'page_title_block': get_example_context('styleguide/bootstrap5/examples/page_title_block.html'),
+            'page_header': get_example_context('styleguide/bootstrap5/examples/page_header.html'),
+            'navs_cards': get_example_context('styleguide/bootstrap5/examples/navs_cards.html'),
+            'navs_tabs': get_example_context('styleguide/bootstrap5/examples/navs_tabs.html'),
+        },
+    })
+    return render(request, 'styleguide/bootstrap5/pages/navigation.html', context)