{{{pagetoc
.:forms
}}}

====== 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>'' :

<code html>
<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>
</code>

<note important>
Tous les formulaires doivent intégrer ''<?php echo $core->formNonce(); ?>''.
</note>

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 :

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

===== Groupe d'éléments =====

{{:2.6:resources:plugins:admin:form:fieldset.png|}}

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

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

Exemple :

<code html>
<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>
</code>

===== Les paramètres communs =====

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)

===== Champ textuel =====

{{:2.6:resources:plugins:admin:form:field.png|}}

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 :

<code html>
<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>
</code>

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

<code html>
<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>
</code>

===== Champ d'un mot de passe =====

{{:2.6:resources:plugins:admin:form:password.png|}}

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

Exemple :

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

===== Zone de texte =====

{{:2.6:resources:plugins:admin:form:textarea.png|}}

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 :

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

===== Case à cocher =====

{{:2.6:resources:plugins:admin:form:checkbox.png|}}

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 :

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

===== Cases d'option =====

{{:2.6:resources:plugins:admin:form:radio.png|}}

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 :

<code html>
<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>
</code>

===== Menu déroulant =====

{{:2.6:resources:plugins:admin:form:combo.png|}}

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 :

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

Utilisation de la fonction : 

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

===== Valeur cachée =====

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 : 

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

===== Bouton =====

{{:2.6:resources:plugins:admin:form:input_submit.png|}}

Les boutons servent à valider les formulaires

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

<note tip>L'utilisation de plusieurs ''<input type="submit" ... />'' avec différents valeurs de ''name=""'' permet de réaliser plusieurs actions avec le même formulaire, par exemple avec plusieurs cases à cocher et 2 boutons : //Désactiver// et //Supprimer//.</note>

==== Afficher un message de confirmation lors de l'appui sur le bouton ====

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

<code html>
<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>
</code>