[en] Paligo components and helpers

[en] Paligo gives templates ready-made components for common parts of a page, and a few helper functions and filters. A component produces complete, accessible HTML that you style with your own CSS. You can also build the same parts yourself from the [en] Template variables.

[en] Components

[en] Function	[en] Produces	[en] Produces nothing when
[en] `paligo_search_box()`	[en] A search box. See [en] Search in a theme.	[en] The layout has no search engine.
[en] `paligo_breadcrumbs()`	[en] A breadcrumb trail.	[en] The page is at the top level.
[en] `paligo_toc()`	[en] A list of the headings on the page.	[en] The page has no headings.
[en] `paligo_pager()`	[en] Links to the previous and next pages.	[en] There are no previous or next pages.
[en] `paligo_language_switcher()`	[en] Links to the site in its other languages.	[en] The site has one language.

<header>{{ paligo_search_box() }}</header>
<aside>{{ paligo_toc() }}</aside>
<main>
    {{ paligo_breadcrumbs() }}
    {{ page.content }}
    {{ paligo_pager() }}
</main>

[en] The class names to style:

[en] Component	[en] Markup
[en] `paligo_breadcrumbs()`	[en] `<nav class="paligo-breadcrumbs">` containing an `<ol>`. The current page is the last `<li>`, with `aria-current="page"`.
[en] `paligo_toc()`	[en] `<nav class="paligo-toc">` containing nested `<ul>` lists of links.
[en] `paligo_pager()`	[en] `<nav class="paligo-pager">` containing `<a class="paligo-pager-prev">` and `<a class="paligo-pager-next">`.
[en] `paligo_language_switcher()`	[en] `<nav class="paligo-language-switcher">` containing a `<ul>`. The current language's link has `aria-current="true"`.

Anmerkung

[en] The texts in paligo_pager() and the accessible names of these components are in English. For a site in other languages, build the pager from page.prevPage and page.nextPage with site.strings.navPrev and site.strings.navNext, as shown in [en] Template variables.

[en] Write your own language menu

[en] paligo_language_switcher() produces a plain list. To show the languages in your own way, such as a dropdown in the header, build the menu from site.languages. This example shows the current language's name, and opens to a list of every language:

[en] templates/partials/language-menu.html.twig:

{% if site.languages|length > 1 %}
  {% set current = site.languages|filter(l => l.code == site.lang)|first %}
  <details class="language-menu">
    <summary aria-label="{{ theme.strings.changeLanguage|default('Change language') }}">
      {{ current.label|default(site.lang|upper) }}
    </summary>
    <ul>
      {% for language in site.languages %}
        <li>
          {% if language.code == site.lang %}
            <a href="#" aria-current="true" lang="{{ language.code }}" hreflang="{{ language.code }}">{{ language.label }}</a>
          {% else %}
            <a href="../{{ page.translations[language.code]|default(language.code ~ '/') }}" lang="{{ language.code }}" hreflang="{{ language.code }}">{{ language.label }}</a>
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </details>
{% endif %}

[en] Include it where the menu goes:

{% include 'partials/language-menu.html.twig' %}

[en] How the example works:

[en] The menu is shown only when the site has more than one language.
[en] site.languages has each language's code, and its label, the language's name in that language, such as Deutsch. The current page's language is site.lang.
[en] The current language is marked with aria-current. The lang attribute lets screen readers say each name in its own language.
[en] Each other language links to the same page in that language when Paligo knows it, from page.translations, and otherwise to that language's front page. This is what paligo_language_switcher() does too.

[en] Use <details> and <summary> as in the example, and the menu opens and closes without a script.

[en] Helper functions

[en] asset(path) gives the link to a file in the theme's assets/ folder. See [en] Theme assets.

[en] paligo_contrast_color(background, dark, light) returns whichever of dark and light is easier to read on background, using the WCAG contrast ratio. dark defaults to #161617 and light to #ffffff. Use it to pick a text color that works with a color chosen in a theme option:

<div class="hero" style="background: {{ theme.options.accent }}; color: {{ paligo_contrast_color(theme.options.accent) }}">

[en] All three colors must be hex colors, such as #3a46e8. If one isn't, the function returns an empty value.

[en] Filters

[en] excerpt(length) turns HTML into plain text and shortens it to at most length characters, at the end of a word, adding "…" when it shortens it. The default length is 160.

<meta property="og:description" content="{{ page.content|excerpt(200) }}">