{"id":8058,"date":"2025-06-24T10:37:36","date_gmt":"2025-06-24T08:37:36","guid":{"rendered":"https:\/\/swissmakers.ch\/?p=8058"},"modified":"2025-07-07T12:43:25","modified_gmt":"2025-07-07T10:43:25","slug":"dynamic-landingpages-wikijs","status":"publish","type":"post","link":"https:\/\/swissmakers.ch\/en\/dynamische-landingpages-wikijs\/","title":{"rendered":"Dynamic landing pages with Wiki.js v2"},"content":{"rendered":"\n

Wer mit Wiki.js v2<\/a> produktiv arbeitet, bemerkt schnell eine L\u00fccke: Es gibt keine eingebaute M\u00f6glichkeit, auf einer Seite automatisch alle Unterseiten aufzulisten. Jede Landingpage, ob f\u00fcr Team-Wikis, Projektbereiche oder Dokumentationen, muss heute manuell gepflegt werden. Sobald eine neue Unterseite angelegt, verschoben oder gel\u00f6scht wird, besteht die Gefahr, dass das zentrale Inhaltsverzeichnis veraltet. In einem lebendigen Unternehmens-Wiki wie unserem ist das nicht tragbar: Wir haben \u00fcber 800 Eintr\u00e4ge und t\u00e4glich kommen welche dazu.<\/p>\n\n\n\n

F\u00fcr Swissmakers GmbH<\/strong> war klar: Eine dynamische Landingpage, die sich ohne manuellen Aufwand aktualisiert, ist essenziell f\u00fcr konsistente Dokumentation und effizientes Auffinden von Informationen.<\/p>\n\n\n\n

Warum Wiki.js das nicht von Haus aus mitliefert<\/h2>\n\n\n\n

Die Wiki.js-Version 2 basiert intern auf einem Vue.js Single-Page-Application-Ansatz<\/strong>. Alle Seiteninhalte werden clientseitig nachgeladen; serverseitig generierte Platzhalter wie \u201e[children]\u201c (bekannt aus anderen Markdown-Plugins) existieren nicht. Das Entwicklerteam von Wiki.js hat zwar f\u00fcr Version 3 ein modulares Blocks-System angek\u00fcndigt, doch f\u00fcr v2-Instanzen bleibt nur der Weg \u00fcber die \u00f6ffentliche GraphQL-API<\/a><\/strong> oder ein Upgrade. Letzteres ist jedoch im produktiven Umfeld definitiv nicht empfohlen da die v3 seit nun fast zwei Jahren lediglich als Alpha Version verf\u00fcgbar ist und bis heute als «unstable» gilt. Zudem sind die meisten Features noch gar nicht oder nicht richtig implementiert.<\/p>\n\n\n\n

Unsere L\u00f6sung: Ein leichtgewichtiger GraphQL-Client im Frontend<\/h2>\n\n\n\n

Um das Feature umzusetzen, haben wir ein JavaScript-Snippet<\/strong> entwickelt, das wir in jeder gew\u00fcnschten Landingpage oder \u00fcbergeordnete «Tech-Page» einbinden k\u00f6nnen. Der Code wird dabei in die jeweilige Seite unter den «Page Properties» im Tab «Script» eingef\u00fcgt:<\/p>\n\n\n\n

\"JavaScript-Snippet\"<\/figure>\n\n\n\n

Der Code folgt beim Aufruf der jeweiligen Seite dem folgendem Ablauf:<\/p>\n\n\n\n

    \n
  1. holt einmalig alle Seiten aus der GraphQL-API (Standartlimit bis 1000 gesetzt),<\/li>\n\n\n\n
  2. filtert ausschliesslich jene, deren Pfad unterhalb des automatisch erkannten Seitenpfads liegt (also unterhalb der aktuell ge\u00f6ffneten Seite),<\/li>\n\n\n\n
  3. entfernt die Landingpage selbst aus der Ausgabe,<\/li>\n\n\n\n
  4. rendert das Ergebnis als \u00fcbersichtliche Link-Liste mit dem bereits eingebauten links-list<\/code>-Styling von Wiki.js.<\/li>\n<\/ol>\n\n\n\n

    In der wiki-Seite selbst wird dann der gerenderte HTML-content innerhalb des
    <div id=\"pageTree\">Loading pages \u2026<\/div><\/code> mit dem generierten Menu ersetzt.<\/p>\n\n\n\n

    \"Verwendung<\/figure>\n\n\n\n

    Die Page kann dabei beliebig gestaltet oder erweitert werden, wichtig ist nur, dass das erw\u00e4hnte Div am gew\u00fcnschten Ort innerhalb der Seite platziert wird, wo die dynamische Sub-\u00dcbersicht gew\u00fcnscht ist.<\/p>\n\n\n\n

    JavaScript Code<\/h2>\n\n\n\n

    Achtung<\/strong>: F\u00fcr alle, die diese Seite auf Englisch lesen. Bitte kopiert den Code aus der deutschen Original-Seite. Unsere Deepl-\u00dcbersetzungsapp hat momentan einen Bug und l\u00f6scht teils Code aus Codebl\u00f6cken oder Newlines heraus. Ein Bugreport ist erstellt. Besten Dank und Sorry f\u00fcr die Umst\u00e4nde.<\/em><\/p>\n\n\n\n

    <script>\n(() => {\n  const debug = false;               \/\/ auf true setzen, falls etwas nicht wie gew\u00fcnscht funktioniert.\n  const MAX_ATTEMPTS = 30;           \/\/ bis zu 30 \u00d7 200 ms auf #pageTree warten (timeout)\n  let attempts = 0;\n\n  const log   = (...a) => debug && console.log(...a);\n  const warn  = (...a) => debug && console.warn(...a);\n  const error = (...a) => debug && console.error(...a);\n\n  function init() {\n    const container = document.getElementById('pageTree');\n    if (!container) {\n      attempts++;\n      warn(`#pageTree not found, attempt ${attempts}`);\n      if (attempts < MAX_ATTEMPTS) return setTimeout(init, 200);\n      error('Gave up waiting for #pageTree');\n      return;\n    }\n\n    \/** Pfad der aktuellen Seite ohne f\u00fchrenden Locale-Teil *\/\n    const selfPath = location.pathname\n      .replace(\/^\\\/[^\/]+\\\/\/, '')     \/\/ z.B.  \/en\/  entfernen\n      .replace(\/^\\\/|\\\/$\/g, '');      \/\/ f\u00fchrenden \/ und trailing \/ entfernen\n\n    \/** Pr\u00e4fix, das alle childs gemeinsam haben (selfPath + \"\/\") *\/\n    const childPrefix = selfPath.endsWith('\/') ? selfPath : selfPath + '\/';\n\n    log('[Wiki.js] selfPath:', selfPath);\n    log('[Wiki.js] childPrefix:', childPrefix);\n\n    const query = `\n      query {\n        pages {\n          list(limit: 1000, orderBy: PATH, orderByDirection: ASC) {\n            path\n            title\n            locale\n          }\n        }\n      }`;\n\n    fetch('\/graphql', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application\/json' },\n      body: JSON.stringify({ query })\n    })\n      .then(r => r.json())\n      .then(({ data }) => {\n        if (!data?.pages?.list) {\n          container.textContent = 'API-Fehler: keine Seitendaten.';\n          error('pages.list fehlt im Response', data);\n          return;\n        }\n\n        const pages = data.pages.list\n          .filter(p => p.path.startsWith(childPrefix)) \/\/ nur echte Unterseiten\n          .filter(p => p.path !== selfPath);           \/\/ Landingpage selbst soll raus\n\n        log('[Wiki.js] gefilterte Seiten:', pages);\n\n        if (!pages.length) {\n          container.textContent = 'Keine Unterseiten vorhanden.';\n          return;\n        }\n\n        const listHTML = pages.map(\n          p => `<li><a href=\"\/${p.locale}\/${p.path}\">${p.title}<\/a><\/li>`\n        ).join('');\n\n        container.innerHTML = `<ul class=\"links-list\">${listHTML}<\/ul>`;\n      })\n      .catch(err => {\n        container.textContent = 'Fehler beim Laden der Seitenliste.';\n        error(err);\n      });\n  }\n\n  init();\n})();\n<\/script><\/code><\/pre>\n\n\n\n
    Was passiert im Detail?<\/h3>\n\n\n\n
    Nachfolgend haben wir f\u00fcr jene, die sich f\u00fcr JavaScript interessieren oder einfach genauer wissen m\u00f6chten, was Zeile f\u00fcr Zeile genau passiert, das Ganze auf die einzelnen Zeilen aufgeschl\u00fcsselt. (Die Zeilennummern beziehen sich auf das komplette Snippet, inklusive <script><\/code>-Tag.)<\/em><\/p>\n\n\n\n
    Zeile(n)<\/th>Code<\/th>Technische Erkl\u00e4rung<\/th><\/tr><\/thead>
    1<\/strong><\/td><script><\/code><\/td>\u00d6ffnet einen HTML-Script-Block \u2013 der Browser interpretiert alles bis <\/script><\/code> als JavaScript.<\/td><\/tr>
    2<\/strong><\/td>(() => {<\/code><\/td>Start eines IIFE (Immediately Invoked Function Expression). Dadurch liegt der gesamte Code in einem eigenen Scope; globale Namens\u00adkollisionen werden vermieden.<\/td><\/tr>
    3<\/strong><\/td>const debug = true;<\/code><\/td>Schalter f\u00fcr ausf\u00fchrliche Konsolen\u00adausgabe. Bei false<\/code> werden alle Log-Aufrufe unterdr\u00fcckt.<\/td><\/tr>
    4<\/strong><\/td>const MAX_ATTEMPTS = 30;<\/code><\/td>Maximale Anzahl Wiederholungen beim Polling auf das DOM-Element.<\/td><\/tr>
    5<\/strong><\/td>let attempts = 0;<\/code><\/td>Z\u00e4hler f\u00fcr die bereits erfolgten Polling-Versuche.<\/td><\/tr>
    7 \u2013 9<\/strong><\/td>const log\u2026warn\u2026error\u2026<\/code><\/td>Drei Arrow Functions, die jeweils nur dann auf console.*<\/code> zugreifen, wenn debug<\/code> aktiv ist. So spart man if-Bl\u00f6cke in der Logik darunter.<\/td><\/tr>
    11<\/strong><\/td>function init() {<\/code><\/td>Hauptfunktion. Sie wird wiederholt aufgerufen, bis das Ziel-Element vorhanden ist.<\/td><\/tr>
    12<\/strong><\/td>const container = document.getElementById('pageTree');<\/code><\/td>Sucht das DIV, in dem sp\u00e4ter die Linkliste gerendert wird.<\/td><\/tr>
    13 \u2013 18<\/strong><\/td>if (!container) { \u2026 }<\/code><\/td>Polling-Logik:
    \u2022 Z\u00e4hler erh\u00f6hen
    \u2022 Warnung loggen
    \u2022 Wenn attempts < MAX_ATTEMPTS<\/code>, mit setTimeout(init, 200)<\/code> nach 200 ms erneut pr\u00fcfen.
    \u2022 Nach dem Limit Abbruch mit Fehlermeldung.<\/td><\/tr>
    22 \u2013 24<\/strong><\/td>const selfPath = location.pathname.replace\u2026<\/code><\/td>Ermittelt den Pfad der aktuellen Wiki-Seite, entfernt dabei:
    1. die Sprachpr\u00e4fix-Sektion (Regex ^\\\/[^\\\/]+\\\/<\/code>)
    2. evtl. f\u00fchrenden bzw. abschliessenden Slash.<\/td><\/tr>
    27<\/strong><\/td>const childPrefix = selfPath.endsWith('\/') ? selfPath : selfPath + '\/';<\/code><\/td>Stellt sicher, dass der Child-Pr\u00e4fix immer mit \/<\/code> endet. Beispiel: 07-internal-it\/it-services\/<\/code>.<\/td><\/tr>
    29 \u2013 30<\/strong><\/td>log('[Wiki.js] selfPath:' \u2026)<\/code><\/td>Debug-Ausgabe des aktuellen Pfades und des sub-Pr\u00e4fixes.<\/td><\/tr>
    32 \u2013 41<\/strong><\/td>const query = \\<\/code>\u2026`;`<\/td>Template Literal mit GraphQL-Query.
    \u2022 pages.list<\/code> liefert bis zu 1000 Seiten.
    \u2022 Sortiert nach Pfad, damit childs automatisch gruppiert sind.<\/td><\/tr>
    43 \u2013 47<\/strong><\/td>fetch('\/graphql', { \u2026 })<\/code><\/td>Stellt einen HTTP-POST an den Wiki.js-GraphQL-Endpunkt. Header Content-Type: application\/json<\/code> ist Pflicht.<\/td><\/tr>
    48<\/strong><\/td>}).then(r => r.json())<\/code><\/td>Erster Promise-Schritt: Die Antwort wird per Response.json()<\/code> geparst.<\/td><\/tr>
    49<\/strong><\/td>.then(({ data }) => {<\/code><\/td>Zweiter Promise-Schritt: ES6-Destrukturierung, um data<\/code> sofort herauszuziehen.<\/td><\/tr>
    50 \u2013 54<\/strong><\/td>if (!data?.pages?.list) { \u2026 }<\/code><\/td>Pr\u00fcfung auf Existenz der erwarteten Struktur unter Nutzung von Optional Chaining (?.<\/code>). Bei Fehler: Meldung f\u00fcr den Benutzer und Logging.<\/td><\/tr>
    56 \u2013 58<\/strong><\/td>const pages = data.pages.list.filter\u2026<\/code><\/td>Zweistufiger Filter:
    1. startsWith(childPrefix)<\/code> \u2192 nur echte Unterseiten
    2. !== selfPath<\/code> \u2192 eigene Seite ausschliessen.<\/td><\/tr>
    60<\/strong><\/td>log('[Wiki.js] gefilterte Seiten:', pages);<\/code><\/td>Debug-Ausgabe des Ergebnisses nach dem Filter.<\/td><\/tr>
    62 \u2013 65<\/strong><\/td>if (!pages.length) { \u2026 }<\/code><\/td>Fehlermeldung, falls keine Unterseiten existieren (z. B. nach Migration).<\/td><\/tr>
    67 \u2013 69<\/strong><\/td>const listHTML = pages.map(p => `<li>\u2026`).join('');<\/code><\/td>Baut f\u00fcr jede Unterseite ein <li><a \u2026><\/a><\/li><\/code> und verbindet alles zu einem HTML-String.<\/td><\/tr>
    71<\/strong><\/td>container.innerHTML = \\<\/code><ul class=»links-list»>${listHTML}<\/ul>`;`<\/td>Rendert die Linkliste. Die Klasse links-list<\/code> sorgt f\u00fcr das card-artige Styling, das Wiki.js mitliefert.<\/td><\/tr>
    73 \u2013 76<\/strong><\/td>.catch(err => { \u2026 })<\/code><\/td>Fehlerbehandlung der Fetch-Kette. Zeigt nutzerfreundliche Meldung und loggt das Exception-Objekt.<\/td><\/tr>
    79<\/strong><\/td>init();<\/code><\/td>Erster Aufruf der Init-Funktion \u2013 l\u00f6st das Polling aus.<\/td><\/tr>
    80<\/strong><\/td>})();<\/code><\/td>Schliesst das IIFE und ruft es sofort auf.<\/td><\/tr>
    81<\/strong><\/td><\/script><\/code><\/td>Ende des Script-Blocks.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Kleiner Zusatz: Alphabetisches Sortieren nach «Page-Titel» anstatt Pfad<\/h3>\n\n\n\n
    Im Standard GraphQL-Respond sind die jeweiligen Pages nach dem Pfad (PATH URL) sortiert. Diese kann sich aber vom eigentlichen Titel unterscheiden und so kann es auch Sinn machen, die Seiten nach ihrem Titel alphabetisch zu sortieren.<\/p>\n\n\n\n
    Daf\u00fcr wird im JavaScript-Code noch vor dem Rendern der Liste const listHTML = pages.map<\/code> (Zeile 67) das Array der Seiten mit der Funktion sort() und localeCompare() nachsortiert. Der ben\u00f6tigte Code sieht so aus:<\/p>\n\n\n\n
    pages.sort((a, b) => a.title.localeCompare(b.title));<\/code><\/pre>\n\n\n\n
    Die n\u00f6tige \u00c4nderung, respektive Erg\u00e4nzung im Code m\u00fcsste also wie folgt aussehen:<\/p>\n\n\n\n
    pages.sort((a, b) => a.title.localeCompare(b.title));\n\nconst listHTML = pages.map(\n  p => `<li><a href=\"\/${p.locale}\/${p.path}\">${p.title}<\/a><\/li>`\n).join('');<\/code><\/pre>\n\n\n\n
    Praxiserfahrungen nach der Integration<\/h2>\n\n\n\n
    Nach wenigen Minuten ist das Snippet in mehreren Bereichen aktiv. Seitdem<\/p>\n\n\n\n