Utilisation des formulaires dans l'administration de Dotclear

Dotclear intègre une classe PHP pour créer des formulaires, c'est la classe form que nous allons utiliser.

On placera les champs des formulaires dans une balise <form> :

<form method="post" action="<?php echo($p_url); ?>">
	...
	<p><?php echo $core->formNonce(); ?></p>
	<p><input type="submit" name="save"
	value="<?php echo __('Save'); ?>" /></p>
</form>

En englobant un champ et le texte qui l'accompagne dans une balise <label> </label>, on peut avoir des champs accessibles sans avoir à gérer les correspondances entre les attributs for="" des <label> </label> et les id="" des balises cibles.

Exemple :

<p><label><?php echo(__('Title:').
	form::field('field_maximal',40,255,
	__('default value'),'maximal')); ?></label></p>

La balise <fieldset> </fieldset> permet de grouper des éléments et de leur donner un intitulé grâce à la balise <legend> </legend> :

<fieldset>
	<legend><?php echo(__('Hello World!')); ?></legend>
	...
</fieldset>

Exemple :

<fieldset>
	<legend><?php echo(__('Hello World!')); ?></legend>
	<p><label class="classic"><?php echo(
			form::checkbox('example_active','1',$settings->example_active).
			' '.__('Enable')); ?></label></p>
 
	<p><label><?php echo(__('Title:').
		form::combo('combo',$combo_values,'2')); ?>
		</label></p>
	<p class="form-note">
		<?php echo(__('Hello World!')); ?>
</fieldset>
 
<fieldset>
	<legend><?php echo(__('Hello World!')); ?></legend>
	<p>
		<?php echo __('Title:'); ?>
		<label class="classic"><?php echo(
			form::radio(array('radio'),html::escapeHTML('1'),false).
			__('one')); ?></label>
		<label class="classic"><?php echo(
			form::radio(array('radio'),html::escapeHTML('2'),true).
			__('two')); ?></label>
	</p>
</fieldset>

Toutes les fonctions de cette classe utilisent le même premier paramètre : nid, il sert à définir les attributs name="" et id="", il accepte deux types de valeurs :

• un tableau avec une ou deux valeurs :
  • une valeur : name="" est le premier élément du tableau et id="" est vide, c'est utile quand on définit des éléments radio pour éviter d'utiliser plusieurs fois le même id
  • deux valeurs : name="" est le premier élément du tableau et id="" le second
• une chaîne de caractères, name="" et id="" prennent sa valeur

Les derniers paramètres sont aussi communs, ils sont tous facultatifs et sont vides par défaut :

• class : la classe CSS (une chaîne de caractères)
• tabindex : l'index du champ, pour la navigation au clavier (un nombre entier)
• disabled : désactiver (un booléen) (valeur par défaut : non)
• extra_html : un attribut supplémentaire pour la balise (une chaîne de caractères)

C'est la fonction form::field(), qui prend les arguments suivants :

• nid
• la taille du champ, en nombre de caractères
• la taille maximale du texte, en nombre de caractères
• la valeur par défaut, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML() (une chaîne de caractères)
• class (avec la classe maximal, le champ occupe toute la largeur disponible, indépendamment de sa taille)
• tabindex
• disabled
• extra_html

Exemple :

<p>
	<label for="field_maximal">
	<?php echo(__('A field with the maximal class:')); ?></label>
	<?php echo(form::field('field_maximal',40,255,__('default value'),'maximal')); ?>
</p>

Pour un champ obligatoire, il est nécessaire d'ajouter la classe required à l'élément <label> et une abréviation :

<p>
	<label class="required" for="field_maximal">
	<abbr title="<?php echo(__('Required field')); ?>">*</abbr>
	<?php echo(__('A field with the maximal class:')); ?></label>
	<?php echo(form::field('field_maximal',40,255,__('default value'),'maximal')); ?>
</p>

C'est la fonction form::password(), qui prend les mêmes arguments que la fonction form::field(),

Exemple :

<p><label><?php echo(__('A field with the maximal class:').
	form::password('password',20,255)); ?></p>

C'est la fonction form::textarea(), qui prend les arguments suivants :

• nid
• le nombre de colonnes
• le nombre de lignes
• la valeur par défaut, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML() (une chaîne de caractères)
• class (avec la classe maximal, le champ occupe toute la largeur disponible, indépendamment de sa taille)
• tabindex
• disabled
• extra_html

Exemple :

<p class="area"><label><?php echo(__('Title:').
	form::textarea('textarea',80,20,
	__('default value'))); ?></label></p>

C'est la fonction form::checkbox(), qui prend les arguments suivants :

• nid
• la valeur de la case, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML()
• cocher ou non la case (un booléen) (valeur par défaut : non) (facultatif)
• class
• tabindex
• disabled
• extra_html

Exemple :

<p><label class="classic"><?php echo(form::checkbox('checkbox','1',
	false).' '.__('Title')); ?></label></p>

C'est la fonction form::radio(), qui prend les arguments suivants :

• nid
• la valeur de la case, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML()
• cocher ou non la case (un booléen) (valeur par défaut : non) (facultatif)
• class
• tabindex
• disabled
• extra_html

Exemple :

<p>
	<?php echo __('Title:'); ?>
	<label class="classic"><?php echo(
		form::radio(array('radio'),html::escapeHTML('1'),false).
		__('one')); ?></label>
	<label class="classic"><?php echo(
		form::radio(array('radio'),html::escapeHTML('2'),true).
		__('two')); ?></label>
</p>

C'est la fonction form::combo(), qui prend les arguments suivants :

• nid
• un tableau de valeur
• la valeur par défaut, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML() (facultatif)
• class
• tabindex
• disabled
• extra_html

Exemple d'un tableau de valeur :

$combo_values = array(
	# un groupe de valeurs
	__('Numbers') => array(
		__('one') => 1,
		__('two') => 2
	),
	# une valeur seule
	__('Hello World!') => 'hello_world'
);

Utilisation de la fonction :

<p><label><?php echo(__('Title:').
	form::combo('combo',$combo_values,'2')); ?>
	</label></p>

C'est la fonction form::hidden(), qui ne prend que deux arguments :

• nid
• la valeur, on prendra soin de l'échapper en utilisant la fonction html::escapeHTML()

Exemple :

<p><?php echo(form::hidden('hidden',
	html::escapeHTML(__('value')))); ?></p>

Les boutons servent à valider les formulaires

<p><input type="submit" name="lorem_ipsum"
	value="<?php echo __('Lorem ipsum'); ?>" /></p>

Ajouter ceci dans la balise <head> de la page :

<script type="text/javascript">
//<![CDATA[
	<?php echo(dcPage::jsVar('dotclear.msg.confirm_lorem_ipsum',
	__('Lorem ipsum?'))); ?>
	$(document).ready(function () {
		$('input[@name="lorem_ipsum"]').click(function() {
			return window.confirm(dotclear.msg.confirm_lorem_ipsum);
		});
	});
//]]>
</script>