Helpteksten in de rechterkolom

Uitleg hoort bij het scherm waar je hem nodig hebt, niet in een losse handleiding die niemand opslaat. Elk scherm kan daarom een rechterkolom met uitleg tonen, gevuld vanuit een beheerscherm.

• Een helptekst heeft een titel, inhoud en een status (actief/inactief), en wordt toegewezen aan een of meer pagina's. Dezelfde uitleg kan immers op meerdere schermen van pas komen — hoe de scores werken is even relevant bij het aanmaken van een taak als bij het bekijken ervan.
• Een pagina kan meerdere teksten tonen; een volgordegetal bepaalt welke bovenaan staat.
• De kolom verschijnt alleen als er voor die pagina teksten zijn ingesteld, en is in te klappen. Die keuze wordt in de browser onthouden, zodat je hem niet op elk scherm opnieuw hoeft weg te klikken.
• Welke pagina's er zijn, staat vast in de code en niet in de database: een pagina bestaat pas als er een scherm voor gebouwd is.

Opmaak. De inhoud is platte tekst met een handvol regels — alinea's, vet, code, opsommingen en links binnen de applicatie. Bewust geen editor en geen markdown-bibliotheek: de behoefte is een paar alinea's uitleg, niet een documentatiesysteem. Alles wordt geëscaped voordat de opmaak wordt toegepast, en links zijn beperkt tot interne paden.

Technische werking. Een scherm hoeft niets te doen om uitleg te tonen behalve zichzelf benoemen: de controller geeft één paginasleutel mee aan de view, en die haalt daarmee de actieve teksten voor dat scherm op en zet ze in de lay-out. Een nieuw scherm van uitleg voorzien is dus één regel in de paginalijst plus diezelfde sleutel in de controller — geen apart mechanisme per scherm. Omdat die lijst een constante in de code is, kan hij ook als controle dienen: bij het opslaan van een toewijzing wordt elke sleutel die er niet in staat weggegooid, zodat een verwijzing naar een scherm dat niet bestaat de database nooit haalt. De toewijzingen zelf staan in een koppeltabel (help_text_page, Datamodel), omdat de relatie aan beide kanten meervoudig is. Bij het tonen wordt de inhoud eerst geëscaped en pas daarna opgemaakt — die volgorde is het hele veiligheidsmechanisme, want HTML uit de invoer is op dat moment al onschadelijk gemaakt — en een reguliere expressie laat alleen links door waarvan het pad met een schuine streep begint. Of de kolom ingeklapt is, is geen instelling maar een browsergegeven: dat staat in localStorage en niet in de database, want het is een voorkeur van dit apparaat en niet van deze helptekst. Mislukt het opslaan daarvan — in een privévenster bijvoorbeeld — dan blijft de knop gewoon werken, alleen zonder geheugen.