Wiki - 1 output

La liste des valeurs possibles pour la propriété est filtrée en fonction de la valeur d’autres propriétés.

	/**
	 * @filters filter_property[=property|method|value][,other_filters...]
	 */

Cette annotation appliquée sur une propriété de type objet permet de réduire la liste des valeurs possibles pour l’objet en fonction de différents types de filtres.

Filtre par une propriété homonyme d’un autre objet

Exemple d’un objet article acceptant des caractéristiques, elles-même matérialisées par un code caractéristique et par des listes de valeurs possibles.

 
/**
 * @business
 */
class Item
{
	use Has_Code;
 
	/**
	 * @link Collection
	 * @var Characteristic_Item[]
	 */
	public $characteristics;
 
}
 
/**
 * @business
 */
class Characteristic
{
	use Has_Code;
 
	/**
	 * @link Collection
	 * @var Value[]
	 */
	public $values;
 
}
 
class Value
{
	use Component;
 
	/**
	 * @link Object
	 * @var Characteristic
	 */
	public $characteristic;
 
	/**
	 * @var string
	 */
	public $value;
 
/**
 * @business
 */
class Characteristic_Item
{
	use Component;
 
	/**
	 * @composite
	 * @getter
	 * @link Object
	 * @store false
	 * @var Characteristic
	 */
	public $characteristic;
 
	/**
	 * @composite
	 * @link Object
	 * @var Item
	 */
	public $item;
 
	/**
	 * @composite
	 * @filters characteristic
	 * @link Object
	 * @var Value
	 */
	public $value;
 
	/**
	 * @return ?Characteristic
	 */
	protected function getCharacteristic() : ?Characteristic
	{
		return $this->value->characteristic ?: $this->characteristic;
	}
 
}

Dans cet exemple tel quel, si l’on modifie un article avec le formulaire de modification standard, on peut saisir plusieurs caractéristiques en sélectionnant pour chacune :

• la caractéristique, parmi toutes les caractéristiques confondues
• la valeur associée, parmi toutes les valeurs possibles (associées à toutes les caractéristiques), et ce quelle que soit la caractéristique choisie.

Appliquer @filters permet de réduire dans le combo de sélection de l’objet valeur la liste de ces valeurs à la caractéristique, si elle a été sélectionnée dans la fiche article. L’utilisateur ne pourra choisir dans la combo que les valeurs de caractéristiques pour lequelles la caractéristique correspond à ce qui a été sélectionné dans l’article.

Note : ont été rajoutés ici @store false pour la caractéristique pour éviter de stocker une double référence à la caractéristique dans la base de données (car logiquement item.characteristic = item.value.characteristic). De même le @getter permet de s’assurer qu’on puisse consulter la caractéristique, qu’elle ait été définie ou non directement dans l’article, puisse qu’en principe elle doit correspondre à la caractéristique de la valeur associée.

Cette utilisation permet donc de filter les combo sur un objet avec une ou plusieurs autres propriétés de l’objet. La syntaxe présentée ci-dessus fonctionne si le nom de la propriété dans le sous-objet en référence est le même que le nom de la propriété locale.

Filtre par une propriété d’un autre objet qui porte un autre nom

Sur le même exemple que ci-dessus, la propriété peut avoir un autre nom dans la classe Characteristic_Item que dans Item :

/**
 * @business
 */
class Characteristic_Item
{
	use Component;
 
	/**
	 * @composite
	 * @getter
	 * @link Object
	 * @store false
	 * @var Characteristic
	 */
	public $value_characteristic;
 
	/**
	 * @composite
	 * @link Object
	 * @var Item
	 */
	public $item;
 
	/**
	 * @composite
	 * @filters characteristic=value_characteristic
	 * @link Object
	 * @var Value
	 */
	public $value;
 
	/**
	 * @return ?Characteristic
	 */
	protected function getCharacteristic() : ?Characteristic
	{
		return $this->value->characteristic ?: $this->characteristic;
	}
 
}

Dans ce cas @filters value_characteristic=characteristic fait correspondre pour le filtre la valeur de la propriété $value_characteristic de Characteristic_Item avec la propriété $characteristic la classe Value, type de la propriété objet $value.

Filtre par une valeur constante

Plutôt que filtrer la sélection d’un objet liée par la valeur d’une propriété de l’objet, les critères de filtre des objets de la sélection combo peuvent être des constantes. Exemple d’une sélection de fonctionnalités logicielles dont on ne veut voir que les fonctionnalités non-intégrées :

class Features_Set
{
 
	//------------------------------------------------------------------------------------- $features
	/**
	 * @filters status != 'built-in'
	 * @link Map
	 * @var Feature[]
	 */
	public $features;
 
}

Cet exemple fonctionne pour une classe Feature dont la propriété $status peut avoir comme valeur 'built-in' : on ne pourra sélectionner et attribué à cette propriété ici que des fonctionnalités qui n’ont pas cette valeur.

Format des constantes : elles sont reconnaissables si elles sont :

• encadrées par un guillemet simple ', comme dans l’exemple ci-dessus,
• encadrées par des guillemets doubles ",
• des valeurs numériques, par exemple 0.

Chemins de propriétés

Le filtre peut être appliqué dans un niveau plus profond de l’objet : les chemins de propriétés sont autorisés, mais uniquement du côté de la propriété de l’objet lié, pas dans la propriété de l’objet courant pris en référence.

- Est autorisé : @filters employee.date_of_entry<=date, où $date est une propriété de l’objet courant et employee.date_of_entry un chemin de propriété valide pour l’objet stocké dans la propriété sur laquelle porte l’annotation.
- N’est pas autorisé : @filters employee=company.employee_of_the_month@.

Opérateurs autorisés

Les opérateurs admis pour la concordance propriété de l’objet lié utilisée poru le filtre – valeur sont :

• = : égal
• != : différent
• <= : inférieur ou égal
• < : strictement inférieur
• >= : supérieur ou égal
• > : supérieur

Filtres multiples

Plusieurs filtres peuvent être demandés pour la valeur de la même propriété. Il suffit de les séparer par une virgule.

Vous en trouverez des exemples ci-dessous.

Filtre par une valeur retournée par une méthode

Au lieu d’une constante, on peut calculer la valeur via une méthode.
Attention : cette méthode n’est appelée qu’une seule fois au moment de générer la vue, elle ne tiendra donc pas compte de valeurs pouvant être modifiées directement ou indirectement par l’utilisateur pendant la saisie du formulaire. Pour se faire, il faudra plutôt considérer les méthodes proposées pour modifier les @filters dynamiquement dans votre formulaire, faisant appel à la méthode @user_change.

Exemple : Un objet contient la relation à un utilisateur, mais ne permet de sélectionner que des utilisateurs liés à un employé actif de la société (c’est à dire dans sa période de présence dans la société) :

	//----------------------------------------------------------------------------------------- $user
	/**
	 * @default User::current
	 * @feature allUsers Day output access to all users @user
	 * @filters employee.date_of_entry<=getEndDateFilter, employee.date_of_exit>=getBeginDateFilter
	 * @see Widget
	 * @user invisible
	 * @var User
	 * @widget Widget
	 */
	public $user;
 
	//---------------------------------------------------------------------------- getBeginDateFilter
	/**
	 * @return string
	 */
	public function getBeginDateFilter() : string
	{
		return ('Y-m-01');
	}
 
	//------------------------------------------------------------------------------ getEndDateFilter
	/**
	 * @return string
	 */
	public function getEndDateFilter() : string
	{
		return date('Y-m-31');
	}

Ici on peut imaginer que les deux méthodes utilisées en référence du filtre permettent de calculer une plage de date définissant le contexte dans lequel on souhaite ne pouvoir sélectionner que des utilisateurs présents à un moment donné de cette plage de date. Dans cet exemple on est resté sur le mois courant.

On rappelle qu’ici :

• employee.date_of_entry, à gauche de l’opérateur, fait référence au chemin de propriété dans la classe User de l’objet $user,
• getEndDateFilter, à droite de l’opérateur, fait référence à la valeur renvoyée par la méthode getEndDateFilter() de l’objet courant au moment de générer la vue.

A contrario, lorsque la valeur de droite est une propriété de l’objet, sa valeur est prise dynamiquement sur le formulaire généré par la vue : les modifications des utilisateurs seront prises en compte. Pour un appel à une méthode, le calcul de la méthode ne tient compte de l’objet qu’au moment de générer la vue.