Schritt für Schritt: Eine Tag-Wolke als Python-Makro

Ein Python-Makro in bDS ist ein kleines Skript, das beim Rendern eines Beitrags automatisch eigenen HTML-Inhalt erzeugt. In diesem Beitrag bauen wir gemeinsam ein Makro, das eine farbige Tag-Wolke erzeugt — Schritt für Schritt, vom ersten „Hallo Welt" bis zur fertigen Visualisierung.

Was wir bauen

Eine Tag-Wolke, die alle Tags des Blogs anzeigt. Jeder Tag wird mit der Anzahl seiner Beiträge beschriftet. Die Farbe richtet sich nach der Häufigkeit: selten verwendete Tags erscheinen in Blau, häufig verwendete in Rot — dazwischen liegen Grün und Gelb.

Schritt 1: Ein neues Skript anlegen

In der Seitenleiste von bDS findest du den Bereich Skripte. Klicke dort auf Neues Skript.

Im Editor siehst du nun mehrere Felder:

• Titel — Gib deinem Skript einen Namen, z.B. Tolle-Tag-Wolke
• Slug — Wird automatisch erzeugt, z.B. tolle_tag_wolke. Unter diesem Namen rufst du das Makro später im Beitrag auf
• Typ — Wähle hier macro aus
• Einstiegspunkt — Wähle main (wird automatisch erkannt, sobald du eine Funktion main im Code hast)
• Aktiviert — Setze den Haken, damit das Makro beim Rendern auch ausgeführt wird

Schritt 2: Ein minimales Makro

Trage im Bereich Skriptinhalt folgenden Code ein:

async def main(context, post_data):
    return {
        'html': '<p>Hallo aus dem Makro!</p>'
    }

Klicke auf Skript speichern. Du kannst mit Syntax prüfen testen, ob der Code fehlerfrei ist.

Um das Makro in einem Beitrag zu verwenden, schreibe einfach an die gewünschte Stelle:

[[tolle_tag_wolke]]

Beim Rendern wird dieser Platzhalter durch den HTML-Text ersetzt — in diesem Fall einfach „Hallo aus dem Makro!".

Schritt 3: Tags und Beitragszahlen ermitteln

Jetzt erweitern wir das Skript. Über die eingebaute Schnittstelle bds_api kann das Makro auf alle Daten des Blogs zugreifen. Wir laden alle Tags und alle Beiträge und zählen, wie oft jeder Tag verwendet wird:

from bds_api import bds

async def main(context, post_data):
    # Alle Tags laden
    tags = await bds.tags.get_all()

    # Alle Beiträge laden
    result = await bds.posts.get_all()
    posts = result['items']

    # Zählen, wie oft jeder Tag vorkommt
    zaehler = {}
    for post in posts:
        for tag in post.get('tags', []):
            zaehler[tag] = zaehler.get(tag, 0) + 1

    # Zur Kontrolle als Text ausgeben
    zeilen = []
    for tag in tags:
        name = tag['name']
        anzahl = zaehler.get(name, 0)
        zeilen.append(f'{name}: {anzahl} Beitrag/Beiträge')

    return {
        'html': '<br>'.join(zeilen)
    }

Nach dem Speichern zeigt das Makro beim Rendern eine einfache Liste: jeden Tag mit der Anzahl seiner Beiträge.

Schritt 4: Die Tag-Wolke als farbige Darstellung

Im letzten Schritt bauen wir die Ausgabe zu einer richtigen Tag-Wolke um. Die Tags werden unterschiedlich groß und farbig dargestellt — je nach Häufigkeit. Die Farbskala reicht von Blau (wenige Beiträge) über Grün und Gelb bis Rot (viele Beiträge).

from bds_api import bds

async def main(context, post_data):
    tags = await bds.tags.get_all()
    result = await bds.posts.get_all()
    posts = result['items']

    zaehler = {}
    for post in posts:
        for tag in post.get('tags', []):
            zaehler[tag] = zaehler.get(tag, 0) + 1

    # Bereich der Häufigkeiten ermitteln
    werte = [zaehler.get(t['name'], 0) for t in tags]
    if not werte or max(werte) == 0:
        return {'html': '<p>Keine Tags mit Beiträgen gefunden.</p>'}

    min_val = min(werte)
    max_val = max(werte)
    spanne = max_val - min_val if max_val != min_val else 1

    # Farbe auf der Skala Blau → Grün → Gelb → Rot berechnen
    def farbe_fuer(anteil):
        if anteil < 0.33:
            # Blau → Grün
            t = anteil / 0.33
            r = 0
            g = int(128 + 127 * t)
            b = int(200 * (1 - t))
        elif anteil < 0.66:
            # Grün → Gelb
            t = (anteil - 0.33) / 0.33
            r = int(255 * t)
            g = 220
            b = 0
        else:
            # Gelb → Rot
            t = (anteil - 0.66) / 0.34
            r = 220
            g = int(200 * (1 - t))
            b = 0
        return f'rgb({r},{g},{b})'

    # HTML zusammenbauen
    elemente = []
    for tag in tags:
        name = tag['name']
        anzahl = zaehler.get(name, 0)
        anteil = (anzahl - min_val) / spanne
        groesse = 0.8 + anteil * 1.6  # 0.8em bis 2.4em
        farbe = farbe_fuer(anteil)
        elemente.append(
            f'<span style="font-size:{groesse:.1f}em;color:{farbe};'
            f'padding:4px 8px;display:inline-block;cursor:default" '
            f'title="{anzahl} Beitrag(e)">'
            f'{name} <sup style="font-size:0.6em">({anzahl})</sup></span>'
        )

    html = (
        '<div style="line-height:2.2;text-align:center;'
        'padding:16px;border:1px solid #e0e0e0;border-radius:8px">'
        + ' '.join(elemente)
        + '</div>'
    )

    return {'html': html}

So funktioniert die Farbgebung

Die Farbe wird anhand des Anteils berechnet — also wie die Häufigkeit eines Tags im Vergleich zu allen anderen liegt:

Tags mit wenigen Beiträgen sind also eher kühl (blau), vielgenutzte Tags eher warm (rot). Zusätzlich wird die Schriftgröße angepasst: seltene Tags erscheinen kleiner, häufige größer.

Zusammenfassung

Das Makro wird bei jeder Vorschau und bei jeder Veröffentlichung neu ausgeführt — die Tag-Wolke ist also immer aktuell.