Merge pull request #18 from IATI/design-system-upgrade

New header and footer

docs/conf.py

@@ -9,6 +9,7 @@
 project = "IATI Sphinx Theme"
 copyright = "2024 IATI Secretariat"
 author = "IATI Secretariat"
+language = "en"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -26,4 +27,11 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "iati_sphinx_theme"
+html_theme_options = {
+    "github_repository": "https://github.com/IATI/sphinx-theme",
+    "languages": {
+        "en": "English",
+    },
+}
+
 todo_include_todos = True

docs/index.rst

@@ -2,11 +2,6 @@
 IATI Sphinx Theme
 =================
 
-.. toctree::
-   :hidden:
-
-   Home <self>
-
 .. toctree::
    :titlesonly:
    :maxdepth: 1
@@ -35,9 +30,25 @@ Installation
 Configuration
 =============
 
-Plausible Analytics
+This theme has multiple options, which can be configured using the :code:`html_theme_options` object in your :code:`conf.py` file.
+
+.. code-block:: python
+
+  html_theme_options = {
+    "github_repository": "https://github.com/organisation/repository",
+    "plausible_domain": "example.com"
+  }
+
+There is more information on each option below.
+
+:code:`github_repository`
 -------------------
 
+This should be a link to the Github repository for the documentation site, and is used to link to the source code in the footer of the site.
+
+:code:`plausible_domain`
+------------------------
+
 To integrate with Plausible Analytics, add the :code:`plausible_domain` option in your project's :code:`conf.py` file.
 
 If your docs site is a subdomain for the site it is documenting, use the top level domain for cross-subdomain tracking.

iati_sphinx_theme/__init__.py

@@ -9,3 +9,6 @@ def setup(app: sphinx.application.Sphinx) -> None:
     app.add_html_theme("iati_sphinx_theme", path.abspath(path.dirname(__file__)))
     app.config["html_permalinks_icon"] = "#"
     app.config["html_favicon"] = "static/favicon-16x16.png"
+    app.config["html_context"]["language"] = app.config["language"]
+    app.add_js_file("header.js")
+    app.add_js_file("language-switcher.js")

iati_sphinx_theme/footer.html

@@ -0,0 +1,55 @@
+<footer class="iati-footer iati-brand-background">
+  <div class="iati-brand-background__content">
+
+    <div class="iati-footer__section iati-footer__section--first">
+      <div class="iati-footer__container">
+        <div class="iati-footer-block">
+          <h2 class="iati-footer-block__title">Additional information</h2>
+          <div class="iati-footer-block__content">
+            <p>Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.</p>
+            {% if theme_github_repository %}
+              <p>Source code on <a href="{{ theme_github_repository }}">GitHub</a>.</p>
+            {% endif %}
+            <p>Documentation licensed under <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>.</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="iati-footer__section iati-footer__section--last">
+      <div class="iati-footer__container">
+        <nav>
+          <ul class="iati-piped-list iati-footer__legal-nav">
+            <li><a href="https://iatistandard.org/en/privacy-policy/">Privacy Policy</a></li>
+            <li>
+              <span>
+                {{ copyright_block() }}
+              </span>
+            </li>
+          </ul>
+        </nav>
+
+        {%- include "language-switcher.html" %}
+
+        <div class="iati-footer__social">
+          <a
+            href="https://www.linkedin.com/company/international-aid-transparency-initiative/"
+            aria-label="LinkedIn"
+          >
+            <i class="iati-icon iati-icon--linkedin"></i>
+          </a>
+          <a href="https://twitter.com/IATI_aid" aria-label="Twitter">
+            <i class="iati-icon iati-icon--twitter"></i>
+          </a>
+          <a
+            href="https://www.youtube.com/channel/UCAVH1gcgJXElsj8ENC-bDQQ"
+            aria-label="YouTube"
+          >
+            <i class="iati-icon iati-icon--youtube"></i>
+          </a>
+        </div>
+      </div>
+    </div>
+
+  </div>
+</footer>

iati_sphinx_theme/header.html

@@ -0,0 +1,85 @@
+{% set general_nav_items = [
+  {"text": "About IATI", "link": "https://iatistandard.org/en/about/"},
+  {"text": "Use Data", "link": "https://iatistandard.org/en/using-data/"},
+  {"text": "Publish Data", "link": "https://iatistandard.org/en/guidance/publishing-data/"},
+  {"text": "Contact", "link": "https://iatistandard.org/guidance/get-support/"},
+] %}
+
+<div class="iati-mobile-nav js-iati-mobile-nav">
+  <div class="iati-mobile-nav__overlay js-iati-mobile-overlay"></div>
+    <nav class="iati-mobile-nav__menu">
+      <div class="iati-mobile-nav__header">
+        <h2 class="iati-mobile-nav__label">Menu</h2>
+        <button class="iati-menu-toggle iati-menu-toggle--close js-iati-menu-toggle-close">
+          <span>Close</span>
+        </button>
+      </div>
+      <ul>
+          <li class="iati-mobile-nav__item">
+            <a href="/"  class="iati-mobile-nav__link">{{ _(project) }}</a>
+          </li>
+      </ul>
+      <ul>
+        {% for nav_item in general_nav_items %}
+          <li class="iati-mobile-nav__item">
+            <a href="{{ nav_item['link'] }}" class="iati-mobile-nav__link">{{ nav_item["text"] }}</a>
+          </li>
+        {% endfor %}
+      </ul>
+    </nav>
+</div>
+
+<header class="iati-header">
+
+  <div class="iati-header__section iati-header__section--first">
+    <div class="iati-header__container">
+      <a href="https://iatistandard.org/" aria-label="Go to IATI homepage">
+        <img class="iati-header__logo" alt="" src="{{ pathto('_static/logo-colour.svg', 1) }}">
+      </a>
+      <nav class="iati-header__general-nav">
+        <ul class="iati-piped-list">
+          {% for nav_item in general_nav_items %}
+            <li>
+              <a href="{{ nav_item['link'] }}">{{ nav_item["text"] }}</a>
+            </li>
+          {% endfor %}
+        </ul>
+      </nav>
+    </div>
+  </div>
+
+  <div class="iati-header__section iati-header__section--last iati-brand-background">
+    <div class="iati-header__container iati-brand-background__content">
+
+      <div class="iati-header__actions">
+
+        {%- include "language-switcher.html" %}
+
+        <a href="{{ pathto('search') }}" class="iati-button iati-button--light">
+          <span>Search</span>
+          <img class="iati-button__icon" alt="" src="{{ pathto('_static/icon-search.svg', 1) }}">
+        </a>
+
+        <button class="iati-menu-toggle iati-menu-toggle--open js-iati-menu-toggle-open">
+          <span class="iati-menu-toggle__label">Menu</span>
+        </button>
+      </div>
+
+      <div class="iati-header-title">
+        <p class="iati-header-title__eyebrow">IATI Tools</p>
+        <p class="iati-header-title__heading">{{ _(project) }}</p>
+      </div>
+
+      <div class="iati-header__nav">
+        <nav>
+          <ul class="iati-tool-nav">
+              <li>
+                <a href="/"  class="iati-tool-nav-link">{{ _(project) }}</a>
+              </li>
+          </ul>
+        </nav>
+      </div>
+    </div>
+  </div>
+
+</header>

iati_sphinx_theme/language-switcher.html

@@ -0,0 +1,10 @@
+<div class="iati-country-switcher">
+  <label for="iati-country-switcher" class="iati-country-switcher__label">Choose your language</label>
+  <select id="iati-country-switcher" class="iati-country-switcher__control">
+    {% for language_code in theme_languages %}
+      <option value="{{ language_code }}" {% if language_code == language %}selected{% endif %}>
+        {{- theme_languages[language_code] -}}
+      </option>
+    {% endfor %}
+  </select>
+</div>

iati_sphinx_theme/layout.html

@@ -4,29 +4,15 @@
   {% if theme_plausible_domain %}
     <script defer data-domain="{{ theme_plausible_domain }}" src="https://plausible.io/js/script.js"></script>
   {% endif %}
+  <style>
+    .iati-brand-background {
+      --background-image: url("{{ pathto('marque-white.svg', 1) }}");
+    }
+  </style>
 {% endblock %}
 
 {%- block header %}
-  <div class="iati-title-bar">
-    <header class="iati-header">
-      <div>
-        <a href="https://iatistandard.org/">
-          <img
-            src="http://styles.iatistandard.org/assets/svg/source/logo-colour.svg"
-            class="iati-header__logo"
-          />
-        </a>
-      </div>
-      <ul class="iati-header__nav">
-        <li class="iati-header__nav-item">
-          <a href="{{ pathto('search') }}">Search</a>
-        </li>
-      </ul>
-    </header>
-    <div class="iati-title-bar__title">
-      {{ _(project) }}
-    </div>
-  </div>
+  {%- include "header.html" %}
 {% endblock %}
 
 {%- block relbar1 %}{% endblock %}
@@ -49,45 +35,5 @@
 {% endblock %}
 
 {%- block footer %}
-  <footer class="iati-footer" role="contentinfo">
-    <div>
-      <a href="https://iatistandard.org/">
-        <img
-          src="http://styles.iatistandard.org/assets/svg/source/logo-white.svg"
-          class="iati-footer__logo"
-        />
-      </a>
-      <div class="iati-footer__list">
-          <span class="iati-footer__list-title">Useful Links</span>
-          <ul>
-            <li><a href="https://iatistandard.org/en/contact/">Contact</a></li>
-            <li><a href="https://iatistandard.org/en/privacy-policy/">Privacy Policy</a></li>
-          </ul>
-        </div>
-    </div>
-    <hr />
-    <div>
-      <div>
-        {{- copyright_block() -}}
-        Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.
-      </div>
-      <div class="iati-footer__social-icons">
-        <a href="https://twitter.com/IATI_aid" aria-label="Twitter">
-          <i class="iati-icon iati-icon--twitter"></i>
-        </a>
-        <a
-          href="https://www.youtube.com/channel/UCAVH1gcgJXElsj8ENC-bDQQ"
-          aria-label="YouTube"
-        >
-          <i class="iati-icon iati-icon--youtube"></i>
-        </a>
-        <a
-          href="https://www.linkedin.com/company/international-aid-transparency-initiative/"
-          aria-label="LinkedIn"
-        >
-          <i class="iati-icon iati-icon--linkedin"></i>
-        </a>
-      </div>
-    </div>
-  </footer>
+  {%- include "footer.html" %}
 {%- endblock %}

iati_sphinx_theme/static/header.js

@@ -0,0 +1,69 @@
+(function () {
+  /**
+   * @param {Object} container DOM element, which will be hidden\displayed (required)
+   * @param {string} options the class to be toggled.
+   */
+  class IatiMobileNav {
+    constructor(wrapper, openClass) {
+      this.wrapper = wrapper;
+      this.openClass = openClass;
+      const focusableElements = this.wrapper.querySelectorAll("a, button");
+      this.firstElement = focusableElements[0];
+      this.lastElement = focusableElements[focusableElements.length - 1];
+    }
+
+    show = () => {
+      this.wrapper.removeAttribute("hidden");
+      const reflow = this.wrapper.offsetHeight;
+      document.addEventListener("keydown", (e) => this.handleKeyDown(e));
+      this.wrapper.classList.add(this.openClass);
+      setTimeout(() => {
+        this.firstElement.focus();
+      }, 500);
+    };
+
+    hide = (closeCallBack) => {
+      this.wrapper.classList.remove(this.openClass);
+      document.removeEventListener("keydown", (e) => this.handleKeyDown(e));
+      setTimeout(() => {
+        this.wrapper.setAttribute("hidden", "hidden");
+        closeCallBack();
+      }, 500);
+    };
+
+    handleKeyDown(event) {
+      if (event.key === "Tab") {
+        if (document.activeElement === this.firstElement && event.shiftKey) {
+          this.lastElement.focus();
+          event.preventDefault();
+        }
+        if (document.activeElement === this.lastElement && !event.shiftKey) {
+          this.firstElement.focus();
+          event.preventDefault();
+        }
+      }
+      if (event.key == "Escape") {
+        this.hide();
+      }
+    }
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    const iatiMobileNav = new IatiMobileNav(
+      document.querySelector(".js-iati-mobile-nav"),
+      "iati-mobile-nav--open"
+    );
+
+    const overlay = document.querySelector(".js-iati-mobile-overlay");
+    const menuOpenBtn = document.querySelector(".js-iati-menu-toggle-open");
+    const menuCloseBtn = document.querySelector(".js-iati-menu-toggle-close");
+    const restoreFocus = () => {
+      menuOpenBtn.focus();
+    };
+    menuOpenBtn.addEventListener("click", iatiMobileNav.show);
+    menuCloseBtn.addEventListener("click", () =>
+      iatiMobileNav.hide(restoreFocus)
+    );
+    overlay.addEventListener("click", () => iatiMobileNav.hide(restoreFocus));
+  });
+})();