Les conditions vous permettent d’afficher de manière sélective tout élément d’Oxygen en fonction d’une condition ou d’un ensemble de conditions. Par exemple, si un utilisateur est connecté ou pas, si il a un certain rôle ou une certaine capacité qui lui sont attribués, etc.
Lorsque les conditions d’un élément sont définies sur True (vrai), l’élément est affiché. Si les conditions sont définies sur False (faux) l’élément est masqué. Par défaut, toutes les conditions d’un élément doivent être définies sur la valeur True pour pouvoir être affichées, car le type de condition définie par défaut est réglé sur AND (et).
Si vous modifiez le type de condition en OR (ou), une seule des conditions doit être évaluée comme étant True (vrai) pour que l’élément soit affiché.
Pour affecter une condition à un élément, sélectionnez-le et cliquez sur l’icône Condition en haut du volet Propriétés.
Vous aurez alors accès au menu Condition.
Set Conditions – Définir des conditions
Ce bouton lance le module Condition, dans lequel vous allez définir les conditions pour l'élément sélectionné.
Condition Type – Type de Condition
Choisissez si la condition doit être évaluée comme étant AND (toutes les conditions doivent être vraies) ou OR (une des conditions doit être vraie).
In-Editor Behavior – Comportement interne
Spécifie comment la visibilité de l’élément doit être restituée dans l'aperçu du builder.
En cliquant sur Set Conditions (Définir les conditions), vous lancez le module Conditions.
Vous pouvez y définir les conditions de l’élément.
Pour commencer, cliquez sur le bouton Add your first condition situé au centre du module.
Désormais, trois champs vous sont présentés: Condition, Operator, et Value.
Tout d’abord, utilisez le menu déroulant le plus à gauche pour choisir votre condition.
Oxygen inclut un certain nombre de conditions intégrées, mais les conditions enregistrées via l’API Conditions seront également répertoriées ici.
Une fois la condition sélectionnée,, choisissez un opérateur dans la liste déroulante du milieu.
Les opérateurs sont utilisés pour évaluer la condition (par exemple, l’ID de la publication en cours) par rapport à la valeur saisie.
Plusieurs opérateurs sont disponibles selon la condition choisie. Certains opérateurs, tels que contains (contient) ou does not contain (ne contient pas), sont des abstractions de fonctions de comparaison de chaînes de caractères et fonctionnent comme leur nom l’indique. Certaines conditions peuvent ne pas nécessiter d’opérateur, auquel cas le seul opérateur disponible sera deux tirets (––).
Enfin, indiquez une valeur dans le champ de droite. Ce champ peut être une liste déroulante, un champ de saisie ou les deux, selon la condition choisie. Lorsque vous entrez une valeur, tenez compte du type de données que vous comparez. Par exemple, vous ne devez pas utiliser du texte comme valeur pour une condition portant sur un Post ID car, dans ce cas, la valeur à comparer doit un nombre (ici, le numéro d'identification unique du Post).
Une fois qu’une condition a été définie à un élément, vous pouvez voir l’icône d’indicateur de condition en regard du nom de cet élément dans le volet Structure.
Cette icône vous aidera à repérer les éléments qui peuvent se retrouver masqués par une condition dans l’aperçu du builder (cf. les options Always Hide ou Show/Hide Based on Conditions).
L’API Conditions vous permet d’enregistrer vos propres conditions dans Oxygen. Cela peut être fait à partir d’un plugin personnalisé ou via le plugin Code Snippets.
Tout d’abord, il est important de s'assurer que la fonction oxygen_vsb_register_condition existe avant de l’utiliser.
if( function_exists('oxygen_vsb_register_condition') ) { }
Si Oxygen était désactivé, la fonction oxygen_vsb_register_condition le serait également.
Dans ce cas, appeler cette fonction via un plugin personnalisé (ou via Code Snippets) provoquerait l'affichage d'un message d’erreur PHP.
Ensuite, nous devons utiliser la fonction oxygen_vsb_register_condition() pour enregistrer notre condition. La fonction oxygen_vsb_register_condition accepte les arguments obligatoires suivants :
Condition Name
[string] Le nom de la condition telle qu’elle apparaîtra dans la liste des conditions dans Oxygen.
Values
[array] Le tableau de valeurs prédéfinies que l’utilisateur peut choisir.
Utilisez la touche Options pour lister les valeurs par défaut. Définissez la valeur de la clé personnalisée sur true pour permettre aux utilisateurs de saisir des valeurs personnalisées. Exemple : array('options'=>array('option 1', 'option 2', 'true', 'false'), 'custom'=>true)..
Operators
[array] Tableau d’opérateurs pouvant être utilisés dans la condition. Exemple: array (’==’, ’!=‘).
Callback Function
[string] Nom de la fonction de rappel qui sera utilisée pour gérer la condition.
Condition Category
[string] Nom de la catégorie sous laquelle la condition apparaîtra dans la liste déroulante Conditions.
Dans cet exemple, nous allons enregistrer une condition qui vérifie l’ID de la publication en cours.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'condition_post_id_callback', 'Post');
}
Comme nous souhaitons que l’utilisateur entre sa propre valeur personnalisée, nous avons laissé le tableau Options vide et nous avons paramétré Custom sur true.
Ensuite, nous devons simplement créer la fonction de rappel pour évaluer la condition et renvoyer true ou false en fonction de l’évaluation.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
switch ($operator) {
case '==':
return ($current_post_id == $value) ? true : false;
break;
case '!=':
return ($current_post_id == $value) ? true : false;
break;
case '>=':
return ($current_post_id == $value) ? true : false;
break;
case '<=':
return ($current_post_id == $value) ? true : false;
break;
case '>':
return ($current_post_id == $value) ? true : false;
break;
case '<':
return ($current_post_id == $value) ? true : false;
break;
}
}
}
Notez que la fonction accepte deux arguments : $value et $operator. Les valeurs possibles pour celles-ci sont déterminées par les valeurs définies dans oxygen_vsb_register_condition et sont choisies par l’utilisateur. Ensuite, les arguments sont passés à la fonction et utilisés pour évaluer la condition.
Premièrement, nous définissons une variable avec la valeur à comparer. Dans ce cas, nous devons connaître l’ID de publication de la publication actuelle. Nous avons donc défini $current_post_id sur get_the_ID(). Ensuite, nous nous assurons que la valeur transmise par l’utilisateur est un entier en définissant $valeur sur intval($ valeur).
Enfin, nous configurons une instruction switch qui compare l’opérateur que l’utilisateur a choisi et évalue $current_post_id par rapport à $value pour déterminer le résultat. Notez que l’instruction switch doit prendre en charge tous les opérateurs possibles déclarés dans oxygen_vsb_register_condition_call. Nous devons renvoyer la valeur true si la condition est évaluée comme vraie (par exemple, $current_post_id == $value, dans le cas où $operator est ==) et renvoyer la valeur false dans le cas où la condition est fausse. Lorsque true est renvoyé par la fonction de rappel, l’élément utilisant cette condition sera visible. Si false est renvoyé par la fonction de rappel, l’élément sera masqué.
Maintenant que votre condition a été enregistrée, elle apparaîtra dans le menu déroulant des conditions pour tous les éléments de votre site.
Pour faciliter la création des conditions d’Oxygen, nous avons également inclus quelques fonctions d’assistance et variables.
Dans l’exemple ci-dessus, nous pouvons remplacer l’intégralité de l’instruction switch en renvoyant la fonction d’assistance oxy_condition_eval_int().
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
return oxy_condition_eval_int($current_post_id, $value, $operator);
}
}
Si nous devions évaluer une chaîne, nous pourrions utiliser la fonction oxy_condition_eval_string(). Pour utiliser l’une ou l’autre fonction, retournez-la simplement après avoir déclaré les variables de condition et transmettez-lui en paramètres : la valeur à comparer ($current_post_id), la valeur choisie par l’utilisateur ($value) et l'opérateur ($operator).
De plus, lors de l’enregistrement de conditions, nous pouvons utiliser la variable globale $oxy_condition_operators pour insérer rapidement des ensembles d’opérateurs prédéfinis à utiliser dans notre condition.
if( function_exists('oxygen_vsb_register_condition') ) {
global $oxy_condition_operators;
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), $oxy_condition_operators['int'], 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
return oxy_condition_eval_int($current_post_id, $value, $operator);
}
}
Premièrement, nous devons rendre la variable $oxy_condition_operators accessible avec la ligne globale $oxy_condition_operators.
Ensuite, nous remplaçons notre argument d’opérateurs dans oxygen_vsb_register_condition() par cette variable, puis nous ciblons l’ensemble des opérateurs du tableau que nous souhaitons utiliser.
Il existe trois ensembles: int, string et simple.
Greg C. / Ph. Reskator
