Documentatie- en helpmodule
Sommige modules vereisen eigenlijk geen enkele actie van jou — ze doen gewoon hun werk achter de schermen. Zulke modules hebben waarschijnlijk geen configureerbare instellingen of dienen enkel als afhankelijkheden voor andere modules.
Meestal is de module waarin je geïnteresseerd bent er een waarvoor je machtigingen en instellingen kunt configureren. Sommige projecten zijn eenvoudig te gebruiken — hun gebruik is ‘intuïtief’, en het zal je vrij duidelijk zijn wat je kunt instellen en wat je moet doen om te bereiken wat je wilt doen.
Als je alle details wilt weten die nodig zijn om de pas geïnstalleerde module op een verstandige manier te gebruiken, zijn er verschillende bronnen en plaatsen waar je kunt kijken.
De volgende suggesties zijn geordend op gebruiksgemak.
Helaas voor beginnende eindgebruikers zoals wij, is Drupal voortdurend in ontwikkeling. En hoewel we het geluk hebben om te profiteren van al het geweldige werk van ontwikkelaars, is hun tijd beperkt, en het is veilig te zeggen dat de beste ontwikkelaars niet altijd de meest toegewijde documentatieschrijvers zijn. Anders zouden jij en ik hier nu niet zitten.
Ik raad je aan om je ervaringen — je successen én frustraties — te documenteren en te delen wanneer je leert om met Drupal te werken, ten behoeve van de duizenden mensen die zich de komende dagen, maanden en jaren in jouw positie zullen bevinden.
Ik beschouw dit als het uiteindelijke doel van het schrijven van deze documentatie, ondanks (of juist vanwege) de eindeloze irritaties en frustraties — zowel door het gebruik van de nieuwe documentatiesectie op Drupal.org als door de leercurve van Drupal zelf. Vooral ben ik blij dat jij, mijn vriend, hier voordeel uit zult halen.
Net als ik hoef je niets te weten over ‘ontwikkeling’ of programmeren om te delen wat je hebt geleerd.
Probeer-en-fout-methode
Je kunt gewoon beginnen met het gebruiken van de module of spelen met de instellingen ervan.
Wanneer je na enig onderzoek niet kunt achterhalen wat een bepaalde optie doet of wat de mogelijke gevolgen van een instelling zijn, kun je gerust alles uitproberen wat je nieuwsgierige geest het proberen waard vindt.
Elke keer dat je in een situatie belandt waarin een module enig giswerk vereist, hoef je je daar niet druk om te maken — zolang je regelmatig een back-up van je site maakt, kun je altijd terugkeren naar een eerdere versie. Je maakt toch back-ups van je site, nietwaar?
Aangezien het niet altijd meteen duidelijk is welke effecten een module of specifieke optie op je site heeft, raad ik aan om slechts één module tegelijk te proberen. Verken vervolgens elke hoek van je site en test alles — maak nieuwe pagina’s aan, probeer verschillende configuratieopties — voordat je een andere contrib-module toevoegt.
Als je meerdere nieuwe modules tegelijk inschakelt en daarna vreemde problemen tegenkomt, weet je immers niet welke module daarvoor verantwoordelijk is.
Inhoud van de projectpagina
Elke projectpagina van een module is zijn startpagina op drupal.org. De projectpagina is meestal de eerste plek waar ik naartoe ga wanneer ik overweeg een module uit te proberen, of wanneer ik problemen of vragen heb over een module die ik net heb ingeschakeld.
Als je de hele projectpagina zorgvuldig leest, kun je er vrij zeker van zijn dat je alle belangrijke informatie hebt. Bijvoorbeeld: als een module andere modules vereist om te werken, zullen deze elders op de projectpagina vermeld staan.
De projectpagina kan ook andere nuttige links bevatten die relevant zijn voor de module.
De inhoud van een projectpagina kan gericht zijn op beginnende Drupal-gebruikers of juist op gevorderde gebruikers en ontwikkelaars.
Link naar de projectpagina “Documentatie lezen” (indien aanwezig)
In de rechterkolom (die op mobiele apparaten of smalle vensters naar beneden schuift) vind je altijd de sectie “Bronnen”. Daar kun je soms een link “Documentatie lezen” vinden.
Niet alle projectpagina’s hebben echter zo’n link. Hopelijk vind je in dat geval nuttige documentatielinks in de hoofdinhoud van de projectpagina.
Wanneer de link “Documentatie lezen” wel bestaat, verwijst deze naar de door de ontwikkelaars aanbevolen bron voor meer informatie.
De inhoud van elke projectpagina wordt bepaald en beheerd door de oorspronkelijke maker van het project en mogelijk enkele andere personen met bewerkingsrechten.
Andere leden van drupal.org zonder schrijfrechten maken vaak aanvullende pagina’s met uitstekende informatie over een module, maar helaas worden deze zelden gelinkt vanaf de officiële projectpagina.
Hoe je zulke niet-gelinkte pagina’s kunt vinden, wordt hieronder uitgelegd in de sectie over Google-zoekopdrachten beperkt tot drupal.org ⤵
Het “README.txt”-bestand van de module
Het bestand “README.txt” was historisch gezien de officiële plek waar alle belangrijke en noodzakelijke informatie over een module (of thema) werd gedocumenteerd, inclusief informatie over updates naar nieuwere versies.
Het bestand README.txt bevindt zich in de hoofdmap van de contrib-module (of het thema) na het uitpakken, als het bestaat.
Om het README.txt-bestand te bekijken zonder iets te downloaden, ga je naar:
http://cgit.drupalcode.org/project/PROJECT_MACHINE_NAME.git/blob/HEAD:/README.txt
Vervang PROJECT_MACHINE_NAME in de bovenstaande URL door de korte ‘machinenaam’ van het project.
De machinenaam staat in de URL van de browser wanneer je een projectpagina bezoekt, bijvoorbeeld in een adres als:
https://www.drupal.org/project/PROJECT_MACHINE_NAME
Als er geen README.txt-bestand bestaat, is het waarschijnlijk een module zonder instellingen — een module die achter de schermen werkt en vereist is voor andere contrib-modules.
Als er geen README.txt-bestand is of als je alle overige projectbestanden wilt bekijken, gebruik dan de volgende URL (vervang “PROJECT_MACHINE_NAME”):
http://cgit.drupalcode.org/PROJECT_MACHINE_NAME/tree/?id=HEAD
Rechtsboven op deze “drupalcode.org”-pagina kun je eventueel overschakelen naar de Drupal-coreversie die je wilt bestuderen.
Google-zoekopdracht beperkt tot drupal.org
Als je een zoekopdracht wilt uitvoeren die beperkt is tot de hele drupal.org-site, kun je dit doen zoals ik dat vaak doe. Ik gebruik deze methode regelmatig om te zoeken op drupal.org of een ander domein naar keuze.
Ga naar google.com ⎘ en typ:
site:drupal.org
Let op dat er geen spatie staat na de dubbele punt (":") vóór de domeinnaam. En gebruik geen “www.” aan het begin van een domeinnaam.
Voeg vervolgens een spatie toe en typ de trefwoorden die je zoekt — in dit geval de naam van de module.
Soms is het nuttig om de zoekopdracht te beperken tot “Drupal 8” (in plaats van resultaten van D6 of D7 te krijgen) door “Drupal 8” tussen aanhalingstekens toe te voegen aan je zoekterm. Google toont dan alleen pagina’s die die exacte woordgroep bevatten. (Meestal.)
Als je informatie over een module wereldwijd wilt zoeken, zowel binnen als buiten drupal.org, laat dan site:drupal.org weg.
Om 100 Google-zoekresultaten per pagina te krijgen in plaats van 10, klik op het tandwielicoon rechtsboven op de resultatenpagina, selecteer “Zoekinstellingen”, zet “Google Instant voorspellingen” op “Nooit tonen”, en schuif onder “Resultaten per pagina” de schuifbalk helemaal naar rechts. Je zoekopdrachten duren nu een fractie van een seconde langer.
Een persoonlijke mening: je kunt overwegen om de zoekfunctie bovenaan drupal.org te gebruiken. Ik heb dat meerdere keren geprobeerd, en raad je aan het zelf te ervaren — als je van zinloze oefeningen houdt.
“Help”-knoppen of links op de “Uitbreiden”-pagina van je site (indien aanwezig)
Op de “Uitbreiden”-pagina van je site zie je, rechts van de modulenaam, de eerste regel van de beschrijving als het venster breed genoeg is.
Als je op die eerste regel klikt, klapt de rest van de beschrijving open, samen met knoppen of links voor “Help”, “Machtigingen” en “Instellen”, indien beschikbaar.
Als je de beschrijvingsregel niet ziet en deze toch wilt bekijken, volg dan de instructies op de configuratiepagina van de module.
Helaas kun je de helppagina van een module pas bekijken nadat je de module op je site hebt geïnstalleerd en ingeschakeld. En niet alle core- of contrib-modules hebben een “Help”-link. Je weet dus pas of deze beschikbaar is nadat je de module hebt ingeschakeld.
Om deze redenen heb ik nooit sterk vertrouwd op de “Help”-knoppen, hoewel ik nu zie dat ze vaak naar nuttige informatie leiden.