learning-website-django1-6  Exercise 1: The Global Bar, the Site Menu and Readable Labels
=====================================================================================

Build the first two layers of navigation (Learning Website: Framework &
Architecture 5), and make sure the labels read well. Django 6.1.2.

Every layer is DERIVED, so none can drift: the global bar from the site map, the
site menu from the pages that really exist in the database, the labels from the
folder names.

Save as apps/navigation/labels.py:

"""Readable labels for folder names, so a menu says "Data Science and ML", not "Data Science And Ml".

The live site's helper capitalises every word, which gave "Data Science And Ml" and "Cloud And Devops"
(found in Learning Website: Framework & Architecture 5). This one lower-cases small joining words and
knows the acronyms and a few product names."""
import re

SMALL_WORDS = {"a", "an", "and", "of", "for", "the", "in", "on", "to", "with", "vs"}

ACRONYMS = {
    "ai", "css", "html", "js", "php", "sql", "api", "seo", "tls", "https", "ssh", "vpn", "rdp", "vnc",
    "grub", "awk", "sed", "iis", "obs", "vfx", "pdf", "k8s", "llm", "nlp", "gpu", "cpu", "os", "ui",
    "ux", "cli", "sdk", "ide", "json", "xml", "yaml", "rest", "grpc", "cicd", "iot", "orm", "jwt",
    "oauth", "cdn", "ml", "dns", "aws", "gcp", "usa", "uk",
}

OVERRIDES = {
    "devops": "DevOps", "ios": "iOS", "macos": "macOS", "nextjs": "Next.js", "nodejs": "Node.js",
    "javascript": "JavaScript", "typescript": "TypeScript", "graphql": "GraphQL", "mysql": "MySQL",
    "postgresql": "PostgreSQL", "sqlite": "SQLite", "mongodb": "MongoDB", "wordpress": "WordPress",
    "web3": "Web3", "youtube": "YouTube", "linkedin": "LinkedIn", "github": "GitHub",
}


def humanize(segment):
    """'data-science-and-ml' -> 'Data Science and ML'"""
    stem = re.sub(r"\.[a-z0-9]+$", "", segment, flags=re.I)
    words = [w for w in re.split(r"[-_]+", stem) if w]
    out = []
    for i, word in enumerate(words):
        low = word.lower()
        if low in OVERRIDES:
            out.append(OVERRIDES[low])
        elif low in ACRONYMS:
            out.append(low.upper())
        elif i > 0 and low in SMALL_WORDS:
            out.append(low)
        else:
            out.append(low[:1].upper() + low[1:])
    return " ".join(out)

Save as apps/navigation/menus.py:

"""The three layers of navigation (Learning Website: Framework & Architecture 5): the global bar, the
site menu and the page's own breadcrumb and previous/next links. All of them are DERIVED, so none can drift."""
from django.conf import settings
from django.core.cache import cache

from apps.content.models import Course, Page
from config.sites_config import SIDEBAR_ROUTES, SITE_STYLE, SITES

from .labels import humanize

CACHE_SECONDS = 3600


def site_url(site, path="/"):
    """Absolute address of a path on a site, from one template in the settings."""
    return settings.SITE_URL_TEMPLATE.format(site=site) + path


def global_bar(current):
    """Layer 1: every site, the same on every page, with the current one marked."""
    return [{"name": name, "title": info["title"], "url": site_url(name), "current": name == current}
            for name, info in SITES.items()]


def _menu_cache_key(site):
    return f"nav:menu:{site}"


def invalidate_menus():
    """Call after an import: the menus are rebuilt from the database on the next request."""
    cache.delete_many([_menu_cache_key(site) for site in SITES])


def site_menu(site):
    """Layer 2: this site's subject folders that really have pages, in the site map's order."""
    def build():
        present = {path.split("/")[0] for path in Page.objects.filter(site=site).values_list("path", flat=True)}
        items = [{"label": humanize(folder), "href": f"/{folder}/", "folder": folder}
                 for folder in SITES[site]["folders"] if folder in present]
        # a site only gets a Sidebar entry if some sidebar/<subject>/ is routed to it AND has pages
        if "sidebar" in present and site in SIDEBAR_ROUTES.values():
            items.append({"label": "Sidebar", "href": "/sidebar/", "folder": "sidebar"})
        return items
    return cache.get_or_set(_menu_cache_key(site), build, CACHE_SECONDS)


def breadcrumbs(site, folder_path, last_label=None):
    """Layer 3: Site > folder > folder > ... > this page. folder_path is the page's folder, "" for the site home.

    A course folder is labelled with the course's real name; any other folder with its readable name."""
    parts = [p for p in folder_path.split("/") if p]
    prefixes = ["/".join(parts[:i + 1]) for i in range(len(parts))]
    names = dict(Course.objects.filter(folder__in=prefixes).values_list("folder", "name"))
    trail = [{"label": SITES[site]["title"], "href": "/"}]
    for prefix in prefixes:
        trail.append({"label": names.get(prefix) or humanize(prefix.rsplit("/", 1)[-1]), "href": f"/{prefix}/"})
    if last_label:
        trail.append({"label": last_label, "href": None})
    elif trail[-1]["href"] != "/":
        trail[-1]["href"] = None                       # the folder you are on is not a link
    return trail


def neighbours(page):
    """The previous and next chapter of the same course, by chapter NUMBER (so 10 follows 9, not 1)."""
    if page.course_id is None or page.chapter_no is None:
        return None, None
    chapters = Page.objects.light().filter(course_id=page.course_id)
    before = chapters.filter(chapter_no__lt=page.chapter_no).order_by("-chapter_no").first()
    after = chapters.filter(chapter_no__gt=page.chapter_no).order_by("chapter_no").first()
    return before, after


def listing(site, folder_path):
    """What is directly inside a folder: sub-folders and pages. Returns None if the folder has no pages."""
    prefix = folder_path.strip("/") + "/"
    pages = list(Page.objects.light().filter(site=site, path__startswith=prefix).order_by("chapter_no", "path"))
    if not pages:
        return None
    folders, here = {}, []
    for p in pages:
        rest = p.path[len(prefix):]
        if "/" in rest:
            name = rest.split("/", 1)[0]
            folders[name] = folders.get(name, 0) + 1
        else:
            here.append(p)
    return {
        "folders": [{"label": humanize(n), "href": f"/{prefix}{n}/", "count": c} for n, c in sorted(folders.items())],
        "pages": here,
        "course": Course.objects.filter(folder=prefix.rstrip("/")).first(),
    }

Save as apps/navigation/links.py:

"""Links between sites, built from the one site map (Learning Website: Framework & Architecture 5)."""
from urllib.parse import urlsplit, urlunsplit

from config.sites_config import site_for_path


def resolve_link(current_site, href, url_template):
    """Turn an old-style root-relative link into the right link from current_site.

    - external links, anchors and relative paths are returned unchanged
    - a link into the current site stays root-relative (the trailing slash, query and fragment are kept)
    - a link into another site becomes an absolute URL on that site
    - a root-relative path that belongs to no site raises NoSiteError: a broken link should fail, not be guessed"""
    parts = urlsplit(href)
    if parts.scheme or parts.netloc or not href.startswith("/") or parts.path.lower().endswith(".txt"):
        return href
    if parts.path == "/":
        return href
    target = site_for_path(parts.path)
    if target == current_site:
        return href
    base = urlsplit(url_template.format(site=target))
    return urlunsplit((base.scheme, base.netloc, parts.path, parts.query, parts.fragment))

Save as apps/theme/context_processors.py:

from apps.navigation.menus import global_bar, site_menu
from config.sites_config import SITE_STYLE


def site(request):
    """Make the current site's name, title, colours and navigation available to every template."""
    name = getattr(request, "site", None)
    if name is None:                                   # error pages for hosts that are not a site
        return {"site_name": None, "site_title": "Learning Notes", "site_family": "technical",
                "site_accent": "#44b78b", "global_bar": [], "site_menu": []}
    style = SITE_STYLE[name]
    return {"site_name": name, "site_title": request.site_info["title"],
            "site_family": style["family"], "site_accent": style["accent"],
            "global_bar": global_bar(name), "site_menu": site_menu(name)}

Add the address template to the settings (the global bar uses it):

  config/settings/dev.py:   SITE_URL_TEMPLATE = "http://{site}.localhost:" + os.environ.get("LW_DEV_PORT", "8000")
  config/settings/prod.py:  SITE_URL_TEMPLATE = "https://{site}.osztromok.com"

Tell the importer to clear the cached menus when it finishes (so a new import
shows up in the menus at once). In apps/content/importer.py:

  from apps.navigation.menus import invalidate_menus
  ...
      invalidate_menus()          # just before "return result"

Save the base template that shows the layers:

Save as apps/theme/templates/theme/base.html:

{% load static %}<!DOCTYPE html>
<html lang="en-GB" data-site="{{ site_name|default:'none' }}" data-family="{{ site_family }}" style="--accent: {{ site_accent }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{% block title %}{{ site_title }}{% endblock %} | Philip's Learning Notes</title>
  {# load order matters: tokens, then base, then components. A page fragment's own <style> comes later, in the body, so it wins ties. #}
  <link rel="stylesheet" href="{% static 'theme/tokens.css' %}">
  <link rel="stylesheet" href="{% static 'theme/base.css' %}">
  <link rel="stylesheet" href="{% static 'theme/components.css' %}">
  <script src="{% static 'theme/copy-code.js' %}" defer></script>
</head>
<body>
  <a class="skip-link" href="#main">Skip to the content</a>

  {# layer 1: every site, the same on every page #}
  {% if global_bar %}
  <nav class="global-bar" aria-label="Sites">
    {% for s in global_bar %}<a href="{{ s.url }}"{% if s.current %} aria-current="true" class="is-current"{% endif %}>{{ s.title }}</a>{% endfor %}
  </nav>
  {% endif %}

  {# layer 2: this site's subjects #}
  <header class="site-bar">
    <a class="site-bar__name" href="/">{{ site_title }}</a>
    {% if site_menu %}
    <nav class="site-menu" aria-label="{{ site_title }} subjects">
      {% for item in site_menu %}<a href="{{ item.href }}"{% if item.folder == active_folder %} aria-current="true" class="is-current"{% endif %}>{{ item.label }}</a>{% endfor %}
    </nav>
    {% endif %}
  </header>

  <main id="main">
    {# layer 3: where you are on this site #}
    {% if breadcrumbs %}
    <nav class="breadcrumb" aria-label="Breadcrumb">
      <ol>{% for crumb in breadcrumbs %}
        <li>{% if crumb.href %}<a href="{{ crumb.href }}">{{ crumb.label }}</a>{% else %}<span aria-current="page">{{ crumb.label }}</span>{% endif %}</li>{% endfor %}
      </ol>
    </nav>
    {% endif %}
    {% block content %}{% endblock %}
  </main>
  <footer class="site-footer">Philip Osztromok &middot; generated with Claude</footer>
</body>
</html>

and the stylesheet additions at the end of apps/theme/static/theme/base.css:

/* navigation (Chapter 6): three layers */
.global-bar {
  display: flex; gap: 1.1rem; padding: .4rem 1.25rem; overflow-x: auto; white-space: nowrap;
  background: var(--bg); border-bottom: 1px solid var(--border); font-size: .8rem;
}
.global-bar a { color: var(--muted); text-decoration: none; }
.global-bar a:hover { color: var(--text); }
.global-bar a.is-current { color: var(--accent); font-weight: 700; }

.site-menu { display: flex; flex-wrap: wrap; gap: .25rem 1rem; font-size: .88rem; }
.site-menu a { color: var(--text); text-decoration: none; padding: .15rem 0; border-bottom: 2px solid transparent; }
.site-menu a:hover, .site-menu a.is-current { border-bottom-color: var(--accent); }
.site-bar { flex-wrap: wrap; }

.breadcrumb ol { list-style: none; display: flex; flex-wrap: wrap; gap: .25rem; margin: 0 0 1rem; padding: 0; font-size: .82rem; color: var(--muted); }
.breadcrumb li + li::before { content: "\203A"; margin-right: .25rem; }
.breadcrumb a { color: var(--muted); }

.page-nav { display: flex; justify-content: space-between; gap: 1rem; margin-top: 2.5rem; border-top: 1px solid var(--border); padding-top: 1rem; }
.page-nav a { text-decoration: none; padding: .6rem .9rem; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text); max-width: 48%; }
.page-nav a span { display: block; font-size: .7rem; text-transform: uppercase; letter-spacing: .08em; color: var(--accent); }
.page-nav__next { margin-left: auto; text-align: right; }

.listing-heading { font-size: 1rem; color: var(--accent); text-transform: uppercase; letter-spacing: .08em; margin: 1.5rem 0 .5rem; }
.listing { padding-left: 1.4rem; }
.listing--plain { list-style: none; padding-left: 0; }
.listing li { margin: .3rem 0; }
.listing__count { color: var(--muted); font-size: .8rem; margin-left: .4rem; }

@media print { .global-bar, .breadcrumb, .page-nav { display: none; } }

Design points
-------------
- The labels fix a flaw found on the live site: "Data Science And Ml" and
  "Cloud And Devops". Small joining words are lower case, ML and AI are
  acronyms, and product names (DevOps, iOS, JavaScript, YouTube) have their own
  capitals. The tests cover each.
- The site menu lists a folder only if the database has pages in it, in the site
  map's order. A Sidebar entry appears only for a site that receives sidebar pages.
- The menu is cached for an hour in Django's cache and cleared by the importer,
  so a page view reads it with no query. A test proves the second call makes 0
  queries and that it only changes after invalidate_menus().
- The global bar is the same on every page; the current site is marked with
  aria-current, so a screen reader announces it.
- resolve_link() is the Chapter 5 link resolver from the framework course: a
  same-site link stays root-relative, a cross-site link becomes absolute, and a
  path in no site raises an error. Content has no cross-site links today, so it is
  not applied to page bodies; it is here for the day one is added.

WHY THIS WORKS AS AN ANSWER
---------------------------
Hand-written menus drift (13 of the live site's 49 folders were missing from its
top menu). Menus derived from the data cannot, and one check later in this
chapter proves it on the real pages.