De functie charger() van een CVT-formulier

Hoe definieer je de functie

De functie charger() van een formulier XXX (wat in een skelet wordt weergegeven met #FORMULAIRE_XXX) wordt gedefinieerd in het bestand formulaires/xxx.php of in het bestand formulaires/xxx/charger.php. De map formulaires/ moet zich bevinden in de map van een plugin, of in de map squelettes/.

De functie moet worden genoemd function formulaires_xxx_charger_dist(). De suffix _dist laat een ontwikkelaar toe zijn gedrag aan te passen door het maken van een functie function formulaires_xxx_charger().

De argumenten van de functie

De functie charger() ontvangt automatisch in dezelfde volgorde de waarde van ieder argument dat aan het baken #FORMULAIRE_XXX werd doorgegeven. Door bijvoorbeeld te schrijven:

#FORMULAIRE_XXX{#ID_ARTICLE,#ID_RUBRIQUE}

met de functie:

formulaires_xxx_charger_dist($arg1,$arg2){
...
}

zal $arg1 de waarde van #ID_ARTICLE en $arg2 die van #ID_RUBRIQUE krijgen.

Wat moet de functie doen

De functie charger() moet een tabel met standaardwaardes voor elk veld van het invoerformulier doorgeven. Deze tabel heeft een tweeledige functie:

• de lijst van invoervelden declareren (de lijst van iedere «name» van de invoervelden);
• een standaardwaarde voor ieder veld aangeven.

De standaardwaardes worden bij de eerste weergave van het formulier getoond, maar kunnen vervolgens door de gebruiker worden aangepast of verdwijnen na een foute invoer.

Voorbeeld van de functie charger()
Bekijk dit voorbeeld

function formulaires_xxx_charger_dist() {
  $valeurs = array();
  $valeurs['nom'] = 'Voer je naam in';
  $valeurs['prenom'] = '';
  $valeurs['email'] = '';
  return $valeurs;
}

Hier stuurt functie charger() een tabel met drie velden ’nom’, ’prenom’, ’email’ met hun standaardwaarde.

Zelfs als die standaardwaarde leeg is, moet het veld in de tabel zijn opgenomen. SPIP gebruikt de tabel om te bepalen wat de invoervelden zijn.

Je hoeft velden van waarden niet van aanhalingstekens te voorzien, dat doet SPIP voor je.

In de HTML van het skelet van het formulier kan je de waarde van ieder veld terug vinden, zoals: #ENV{nom}, #ENV{prenom}, #ENV{email}

Speciale velden

De functie charger() kan enkele specifieke waardes in de tabel zetten:

editable
Deze waarde bepaalt of de inhoud van het formulire mag worden aangepast. Na de verwerking van een formulier komt «editable» op «false» te staan en wordt alleen de succesmelding getoond.

Voor speciale toepassingen kan een waarde voor «editable» worden aangegeven.

message_ok
Normaal gesproken is het de functie traiter() die dit veld vult. Toch kan deze functie dit veld ook gebruiken.

message_erreur
Normaal gesproken is het de functie traiter() die dit veld vult. Toch kan deze functie dit veld ook gebruiken.

action
Deze waarde geeft de URL waarop het formulier is gepost. Standaard is het de huidige pagina, wat ook de voorkeur geniet, zodat bij een fout weer het originele formulier kan worden getoond.

_forcer_request
SPIP controleert standaard of het formulier het juiste is (bijvoorbeeld bij meerdere formulieren op dezelfde pagina). De verificatie wordt gebaseerd op de lijst van argumenten die aan het baken #FORMULAIRE_XXX worden meegegeven.

Als die argumenten door de invoer veranderen, kan SPIP zich vergissen en denken dat het om een ander formulier gaat.
Door het geven van waarde true aan _forcer_request vertel je hem deze verificatie niet te doen en de invoer gewoon te behandelen.

_action
Wanneer de verwerking van formulier xxx een functie uit de map actions/ vereist dat is beschermd met securiser_action(), kan je door de naam van die actie aan te geven SPIP automatisch de hash-code laten doorgeven.

_hidden
De waarde van dit veld wordt direct in de HTML van het formulier opgeomen. Ze wordt gebruikt voor verborgen (hidden) invoervelden:

$valeurs['_hidden'] = "<input type='hidden' name='secret' value='hop' />";

_pipeline
Dit veld geeft aan dat het resultaat van de berekening van het formulier via deze pipeline wordt doorgegeven, waardoor een plugin ermee kan werken.
Het kan een eenvoudige tekst zijn die de naam van de pipeline aangeeft:

$valeurs['_pipeline'] = "mijnpipeline";

of een tabel met twee waardes, om door te geven argumenten te vermelden:

$valeurs['_pipeline'] = array("mijnpipeline", array('arg1' => 'eenwaarde', ...));

Markering en bescherming van invoervelden
Standaard zijn alle waardes in een tabel beschermd om veilig in de attributen value van een input in het skelet van een formulier te worden opgenomen. Omdat de waarde zlef een tabel is, is ieder van zijn waardes beschermd.

Velden die een prefix _ (underscore) hebben worden niet automatisch beveiligd door SPIP. Wanneer waardes aan een skelet moeten worden doorgegeven, maar deze niet als invoer worden gebruikt, wordt aangeraden systematisch deze prefix te gebruiken.

Omgekeerd moet je geen prefix _ (underscore) gebruiken voor invoervelden, want de waarde zal worden genegeerd wanneer het formulier na een fout opnieuw moet worden getoond.

Personalisatie

De functie charger() van een formulier ka nvia twee mechanismes worden gepersonaliseerd

Surcharge
Zoals hierboven aangegeven, kan de standaardfunctie charger() worden overschreven met een eigen functie function formulaires_xxx_charger() die zal worden aangeroepen in plaats van de standaardfunctie, die de toevoeging _dist heeft.
Deze overschrijvende functie kan worden gedefinieerd in het bestand formulaires/xxx/charger.php, of in een bestand options.php dat wordt aangeroepen bij elke hit.

Pipeline
De pipeline formulaire_charger kan het resultaat van de standaardfunctie charger() aanpassen, ongeacht het CVT-formulier.

Dit is de methode die de voorkeur heeft in een plugin.

De pipeline ontvangt als argument een tabel in deze vorm:

array(
	'args'=>array('form'=>$form,'args'=>$args),
	'data'=>$res)
)

Door de functie pipeline als volgt te schrijven

function mijnplugin_formulaire_charger($flux){
...
}

Zul je in $flux de volgende elementen terugvinden:

Alle formulieren passeren dezelfde pipeline. Je moet dus de waarde van $flux['args']['form'] testen om te zorgen dat je uitsluitend het gedrag van formulier xxx beïnvloedt.

Bekijk ook de functies verifier() en traiter()