SimpleTOC – Mein React WordPress Plugin


WordPress SimpleTOC Inhaltsverzeichnis

Damit die Tutorials im Blog für den geneigten Leser strukturierter zu erfassen sind, habe ich selber ein Inhaltsverzeichnis-Plugin programmiert: SimpleTOC. Es ist extrem einfach zu benutzen und hatte eine prominente Vorlage: Google Docs. Aber sei gewarnt: Es hat leider seine Schwächen.

„Sie baden gerade ihre Hände darin“

Genau so wie in der Spülmittelwerbung hast du das Plugin in Aktion bereits gesehen: Es ist natürlich in diesen Artikel eingebaut.

"Sie baden gerade ihre Hände darin" - Das Inhaltsverzeichnis ist natürlich hier im Artikel eingebaut. Einfach hochscrollen.
Das Schönheitsrezept für eingebildete Blöcke, die sich für ein Inhaltsverzeichnis halten

Hier die Einstellung mit verstecktem Inhaltsverzeichnis im Akkordeon-Menü. Natürlich ARIA konform.

Wozu selbermachen wenn es bereits Plugins gibt?

Es gibt sehr viele Table of Contents Plugins für WordPress. Allerdings unterstützen nur wenige den neuen Gutenberg Editor und stellen ihre Funktion als „Block“ bereit. Außerdem stellen mir die Plugins zu viele Fragen und bringen unnötigen Ballast für das Frontend und den Nutzer mit. Zu den unnötigen Funktionen zählen:

  • Verzichtbares Javascript für sanftes Scrolling verlangsamt das Frontend
  • Aufgeblasenes Markup verhindert Kompatibilität mit Google AMP und Dark Mode Plugins.
  • Überflüssige Einstellungen für die Darstellung. Es soll wie eine Auflistung im jeweiligen Theme aussehen

Zudem wollte ich schon lange einen eigenen Block entwickeln um Gutenberg besser zu verstehen und um das React JavaScript Framework auszuprobieren. Einen Build-Prozess um seinen Code zu erzeugen? Cool!

Bedienung ohne lästige Rückfragen

Gute Software stellt keine unnötigen Fragen sondern liefert eine befriedigende Antwort auf eine einfache Problemstellung: „Ich brauche ein Inhaltsverzeichnis in meinem Artikel“. Da SimpleTOC nur als Gutenberg-Block funktioniert, kann sie überall hin verschoben werden und zeigt das Ergebnis direkt an. Der Block erzeugt eine verschachtelte, unsortierte Liste (ul) mit einer übersetzten Überschrift (h2) namens „Table of Contents“.

<!-- Markup im Artikel -->
<h2 class="simpletoc-title">Inhaltsverzeichnis</h2>
<ul class="simpletoc">
  <li><a href="#slug">Überschrift</a></li>
</ul>

Dank Links springt man mit Sprungmarken direkt zu den Überschriften. Bei Änderungen an den Überschriften im Artikel, wird der Block aktualisiert. Diese Einfachheit sollte 90% aller Bedürfnisse in Bezug auf Inhaltsverzeichnisse befriedigen. Dabei bleibt der Code übersichtlich und klein.

So simpel fügt man mein SimpleTOC in Gutenberg ein

ServerSideRendering vs natives React JS

Gutenberg Blöcke werden in Modern JavaScript mit dem React JS Framework entwickelt. Statt alles mit JavaScript zu berechnen, zeige ich im Block letztendlich nur das Ergebnis einer php-Funktion an. Das nennt sich ServerSideRendering. Ich erlag dem Law of Instrument-Effekt und dachte nach ersten Erfolgen, dass ich React JS verstanden hätte. Obwohl ich über Ostern fast das komplette Plugin in php entwickelt habe, wollte ich es dann „mal schnell“ auf Modern JavaScript portieren.

I suppose it is tempting, if the only tool you have is a hammer, to treat everything as if it were a nail.

Abraham Maslow

Irgendwann nach drei Abenden sah es so aus, als ob es funktionieren würde. Jedoch bereitete mir eine Rekursion Kopfzerbrechen. Ich habe ihren Ursprung einfach nicht verstanden. Also fragte ich die Gutenberg-Entwickler selber. Nach der Antwort hatte die React-Reise ihr jähes Ende gefunden:

React usually has a reactive way of rendering, when changing some data, the render function is called again. So when calling setAttributes, the edit function is triggered, setAttributes again, ad infinitum… There’s also an in progress PR for a Table of Contents block that you can draw some inspiration from.

Daniel Richards am Gutenberg Issue auf Github

Übersetzt heißt das: „Du hast null verstanden, wie React funktioniert. Und übrigens: Wir bauen gerade einen eigenen Inhaltsverzeichnis-Block. Und zwar im Core von Gutenberg.“

Gerne würde ich weitermachen, wenn Nico Brünjes mir wie früher gegenüber sitzen würde und ihm doofe Fragen stellen dürfte. So ist die Hürde um mehr oder weniger eine neue Programmiersprache zu lernen, mir aktuell zu hoch und vor allem zeitaufwendig. Schließlich funktioniert SimpleTOC doch, oder?

Alleine die Entwicklungsumgebung ans Laufen zu bekommen war ein längerer Lernprozess
Alleine die Entwicklungsumgebung Node.js ans Laufen zu bekommen war ein interessanter Lernprozess

Die Nachteile von meinem SimpleTOC-Plugin

Warum ich unbedingt auf natives React JS ohne php wechseln wollte hat neben meiner Neugierde auch praktische Gründe. Zum einen aktualisiert sich mein Block nicht automatisch, wenn man den Post in WordPress verändert. Das bekommt man mit React geschenkt. React heißt ja nicht umsonst „React“. Zum anderen besitzt mein Ansatz kein Caching what-so-ever. Jeder Seitenaufruf des Frontends generiert das Inhaltsverzeichnis neu. Ich könnte das generierte Verzeichnis in einen transient cache stecken. Leider müssen für ein Inhaltsverzeichnis auch die Überschriften im Post manipuliert werden und mit einem Attribut namens „id“ als Sprungmarke ausgestattet werden. Das bekommt man wiederum in Gutenberg mehr oder weniger durch die Anchor-Attribute geschenkt.

Erfolgreicher als gedacht

Mittlerweile wurde das Plug-in über 4000 10.000 Mal heruntergeladen. Mehrere Webseiten haben SimpleTOC in seine Top-Listen aufgenommen. Zuletzt wurde SimpleTOC im AYS Pro WordPress Blog unter die Top 3 gewählt.

SimpleTOC runterladen

Für ein konzeptionellen Beweis der Machbarkeit hat SimpleTOC trotzdem gereicht. Und zumindest eine Person nutzt das Plugin erfolgreich: nämlich ich. Man findet SimpleTOC auf GitHub und im WordPress Repository:


Beitrag veröffentlicht

in

,

von

Kommentare

18 Antworten zu „SimpleTOC – Mein React WordPress Plugin“

  1. Avatar von Marc
    Marc

    SimpleTOC hat mittlerweile viele Reviews mit 5 von 5 Sternen und wird von mehr als 200 Leuten benutzt. =)

  2. Avatar von Marc
    Marc

    1000 irre Leute nutzen nun tatsächlich SimpleTOC. Ich freue mich.

  3. Avatar von NicoHood
    NicoHood

    Moin Marc,
    ich versuche gerade mir ein TOC Plugin rauszusuchen. Sehr cooler Blog Post, als Entwickler (wenn ich noch nicht fuer WordPress), finde ich solche Details immer wichtig. Hierzu ein paar Fragen:

    1. Kannst du das Github Issue verlinken? Gibt es eine Timeline, wann ein upstream TOC erscheint?
    2. Du hast dein Plugin geforkt. Was genau unterscheidet es vom Fork, anscheinend werden beide weiterentwickelt. So wie ich es verstanden habe, hast du einiges entschlackt. Haette man das nicht als Config Option via PR beim upstream posten koennen oder sehe ich das zu einfach?
    3. Unter diesem Post steht „Ja, füge mich zu der Mailingliste hinzu!“. Ich frage mich, ob das nur fuer diesen Post, oder fuer alle der Webseite gilt. Wenn sich das korrigieren laesst, wuerde ich es konkreter schreiben.

    1. Avatar von NicoHood
      NicoHood

      Achja und 4. wenn man bei den Blocks nach „Table of contents“ sucht, findet man deinen Block nicht. Sicher kann man das als Tag fuer die Block Suche definieren.

    2. Avatar von Marc
      Marc

      @Nico
      1) Ist im Artikel mehrfach drin
      2) Das alte Plug-In war tot und ich habe davon nur den Aufbau der nested list übernommen. Der Hinweis in den Credits reicht, denke ich
      3) Ja, ist ein Trick damit Du den Newsletter abonnierst. ;-)
      4) Meinst du als Tag in der Readme.txt für Google und wordpress.org? Steht aber drin. Das Plug-In verbreitet sich gerade hervorragend. Oder meinst Du innerhalb von Gutenberg?

  4. Avatar von Marc
    Marc

    Das Plugin hat nun über 2000 laufende Installationen zu verzeichnen. Unglaublich.

  5. Avatar von Jozsef Ver
    Jozsef Ver

    Hi Marc,
    I created Hungarian translation of your SimpleTOC plugin.
    If give me a reply, I will send you!
    Regards,
    Jozsef

    1. Avatar von Marc
      Marc

      Cool. Please use the WordPress Translate feature: Don’t sent it via GitHub or E-Mail. Use the WordPress repository.

  6. Avatar von Kenneth
    Kenneth

    Awesome simple TOC! Just what I was looking for. If I could just make a small request. If you could put in a section to set the offset? This way we get the section of the article to jump and stop before a sticky header and not under it.

    1. Avatar von Marc
      Marc

      Pro Tipp: this can be fixed in your theme and is not something that SimpleTOC cannot should fix. SimpleTOC does not use JavaScript.

    2. Avatar von Kenneth W Sim
      Kenneth W Sim

      No worries. I just added the following to my child theme and it works fine.

      // OnClick anchor to ID scroll
      $j('a[href^=\\#]').click(function(e){
      e.preventDefault();
      var $dest = $j(this).attr('href');
      var $destOb = $j($dest);
      var $destToTop = $destOb.offset().top;
      $j("html, body").animate({scrollTop:$destToTop-120},1000)
      });

  7. Avatar von Marc
    Marc

    SimpleTOC besitzt nun 5000 aktive Installationen laut offiziellem Repository.

  8. Avatar von Matthias
    Matthias

    Hi Marc, great plugin, absolutely easy to use!

    On my website I have some quite long headings like „FAQ – Häufig gestellte Fragen“. To create a cleaner hash link I manually assigned a short ID like „faq“ to those headings (HTML Anchor in Gutenberg).

    With two small changes your plugin could easily support such manually assigned IDs:

    function addAnchorAttribute($html)
    {

    foreach ($tags as $tag) {
    if ($tag->getAttribute(‚id‘)) {continue;}

    function generateToc($headings, $attributes)
    {

    $link = simpletoc_sanitize_string($title);
    if (isset($nodes[0]) && !empty($nodes[0]->ownerElement->getAttribute(‚id‘))) {
    $link = $nodes[0]->ownerElement->getAttribute(‚id‘);
    }

    1. Avatar von Marc
      Marc

      Cool. What about a pull request on github?

  9. Avatar von Opeyemi Quadri
    Opeyemi Quadri

    Hi Marc,

    Thanks for it available. Light and simple to use. The SimpleTOC was exactly what was looking for.

    But, is there a way to make the TOC appear on my sidebar?

    1. Avatar von Marc
      Marc

      Do you use full site editing?

  10. Avatar von Ralu
    Ralu

    I am using the Simple TOC for my blog posts, in the sidebar. Is there a way to make the TOC Sticky? Ideally something like this, but just sticky with no styling also works:

    1. Avatar von Marc
      Marc

      Hi and thanks for using SimpleTOC. I am afraid this is not within in scope of SimpleTOC at the moment.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert