Modulen Avansert hjelp tilbyr et rammeverk som gjør det mulig for modul- og theme-utviklere å integrere hjelpetekster i et Drupal-nettsted. Selv om Avansert hjelp ikke selv inneholder generell hjelp tilbyr den et kraftig og enkelt rammeverk som prosjekter kan benytte for å tilby egen hjelp.

Prosjekter som benytter Avansert hjelp må ha en underkatalog med navnet help i sin rotkatalog I denne katalogen opprettes filen MODULNAVN.help.ini (evt. THEMENAVN.help.ini). Formatet på denne fila framgår av følgende eksempel:

[about-php]
title = About PHP
file = about-php
weight = -10

[history]
title = History of PHP
parent = about-php

[usage]
title = Usage of PHP
weight = 1

[security] 
title = Security of PHP
weight = 2

[syntax]
title = PHP syntax
parent = usage

Lag alltid den engelske versjonen av disse temaene først. Ønsker du å ha temaene oversatt til et annet språk følger du anvisningene i Oversettelse av Avansert hjelp.

Denne fila definerer fem hjelpe-emner (i firkant-parenteser), og noen innstillinger for dem. Se: Avansert hjelp .ini-filformat for en liste over definerte innstillinger.

Alle emner er beskrevet av det prosjektet som tilbyr emnet, og av emne-id. For å produsere en themet lenke til et sprettopp-vindu om et emne, bruk et format etter mønster fra følgende eksempel:

$output = theme('advanced_help_topic', array(
  'module' => 'help_example',
  'topic' => 'about-php',
));
$output .= ' ' . t('Click the help icon.');

Ikke oversett strengen inne i t(). Bruk alltid engelsk, og benytt Drupals lokaliserings-modul til å oversette.

Forutsatt at strengene er korrekt oversatt (ved hjelp av Drupals lokaliserings-modul) genererer dette følgende markeringer:

<a class="advanced-help-link" title="Om PHP"
  onclick="var w=window.open(this.href, 'advanced_help_window',
  'width=500,height=500,scrollbars,resizable');
  w.focus(); return false;"
  href="/help/help_example/about-php?popup=1">
<span>Hjelp</span>
</a>
 Klikk på hjelpe-ikonet.
</div>

Dette produserer et klikkbart hjelpe-ikon lik det som vises under:

Inne i en hjelpe-fil kan du lenke til andre hjelpe-emner ved å bruke dette formatet:

<a href="&topic:module/topic&">topic</a>

Ved å bruke dette formatet i stedet for standard-lenker vil sprettopp-status være konsistent når man trykker på lenker.

For å referere til andre elementer som befinner seg i hjelpe-katalogen, som bilder som du ønsker å bake inn i teksten, bruk:

<img src="&path&example.png"/>
<img src="&trans_path&example.png"/>

Nøkkelordet trans_path vil peke på en oversatt versjon av bildet i oversettelse-katalogen og kan benyttes dersom du ønsker å vise et bilde med oversatt tekst i stedet for originalen.

For å peke på en normal sti på nettstedet, bruk:

<a href="&base_url&admin/settings/site-configuration">anchor text</a>

NB: I tidligere versjoner av Advanced help var det ikke nødvendig å benytte &-tegn rundt topic:, path, og base_url. Dette fungerer fortsatt, men kan bli fjernet i en senere versjon. Ved å bruke &-tegn for å markere disse nøkkelordene kan de brukes overalt, og ikke bare som parametere til href="" og src="".

Adgangskontroll

Når denne modulen er installert vil brukere med tillatelsen view advanced help index se indeks-siden for Avansert hjelp ved å gå til Administrasjon → Advanced Help (sti: admin/advanced_help). Øvrige tillatelser view advanced help topic og view advanced help popup gir brukere adgang til de aktuelle hjelpe-sidene og sprettopp-vinduer.

Hjelpeteksten er lagret som vanlige .html-filer og kan, med mindre de beskyttes, bli sett av alle som kjenner deres URL. Dersom du ønsker å beskytte dem kan du beskytte dem mot innsyn ved å plassere følgende fire linjer i en fil med navn .htaccess i katalogen help i prosjektkatalogen:

<Files *\.html>
Order Allow,Deny
Deny from all
</Files>

Det er nettstedsansvarlig som har ansvaret for at denne typen beskyttelse er på plass dersom nettstedet har hjelpe-filer som må beskyttes fra direkte innsyn.

Se også denne tråden i prosjektets sporings-kø: #1980936 Typing complete path to .html help files in module bypasses user permissions.

Søk

For å skru på søk for Avansert hjelp, naviger til Administrasjon → Oppsett → Søk og metadata → Søkeinnstillinger. Rull ned til feltet Aktive søkemoduler og kryss av feltet til venstre for “Advanced help”. Søkefeltet vil deretter dukke opp på toppen av indekssidene for Avansert hjelp.

Dersom modulen Search i core er skrudd på, vil alt innhold på hjelpesidene bli indeksert av cron. Dersom du installerer og skrur på nye prosjekter og ønsker å indeksere deres hjelpetekster umiddelbart kan du navigere til Administrasjon → Rapporter → Status og klikke på lenken for å “kjøre cron manuelt.”.