4.7 Les aides à la saisie

4.7.1 Présentation

Une aide à la saisie permet de compléter ou de remplir des zones de saisie lors de la modification d'un document, en proposant des suggestions à l'utilisateur.

Les suggestions sont calculées au moyen d'une fonction qui doit être définie dans un fichier php placé dans le répertoire /EXTERNALS/ du contexte.

Elle doit retourner un résultat sous la forme d'un tableau à 2 dimensions :

  • la première dimension correspond à la liste des suggestions ;

  • la seconde dimension correspond à la liste des valeurs à insérer dans le document lors du choix de cette suggestion.

    Elle est traitée de manière positionnelle :

    • La première valeur est affichée en tant que suggestion pour l'utilisateur ;
    • les valeurs suivantes sont dépilées et affectées dans l'ordre aux attributs cible.

Elle peut également retourner une chaîne de caractères, qui servira de message d'erreur.

4.7.2 Syntaxe

La syntaxe définissant les aides à la saisie est la suivante :

inputHelp:funcName(funcInputs):funcOutputsfuncInputs:funcInput,funcInputfuncInput:<spaces>sourceAttributeNamefamilyParameterNametextsourceKeyWordpropertyName{appParameterName}{familyName}<spaces>funcOutputs:funcOutput,funcOutputfuncOutput:targetAttributeNametargetKeyWordtext:'<text>'[^',]+'"[^",]+"sourceKeyWord:CTCT[relationAttributeName]DIKTAtargetKeyWord:CTCT[relationAttributeName]

Ce qui donne en BNF :

inputHelp       ::= funcName '(' ( funcInputs |  ) ')' ':' funcOutputs
 
funcInputs      ::= funcInput ( ',' funcInput )*
 
funcInput       ::= '<spaces>'* ( sourceAttributeName | familyParameterName | text | sourceKeyWord | propertyName | '{' appParameterName '}' | '{' familyName '}' ) '<spaces>'*
 
funcOutputs     ::= funcOutput ( ',' funcOutput )*
 
funcOutput      ::= ( targetAttributeName | targetKeyWord )
 
text            ::= ( "'" '<text>' ) | ( "'" "[^',]+" "'" ) | ( '"' '[^",]+' '"' )
 
sourceKeyWord   ::= ( 'CT' | 'CT' '[' relationAttributeName ']' | 'D' | 'I' | 'K' | 'T' | 'A' )
 
targetKeyWord   ::= ( 'CT' | 'CT' '[' relationAttributeName ']' )

avec les éléments suivants :

sourceAttributeName

Un nom d'attribut existant dans la famille.

La fonction de calcul recevra la valeur de l'attribut au moment de l'appel.

Lorsque attributeName est dans un array, alors la valeur passée est :

  • la valeur sur la même ligne si l'attribut sur lequel est définie l'aide à la saisie est dans le même tableau,
  • la valeur de la colonne (sous la forme d'un tableau php) si l'attribut sur lequel est définie l'aide à la saisie est en dehors du tableau
  • la valeur sur la même ligne si l'attribut est dans un autre tableau, ce qui peut conduire à des comportements surprenants.
familyParametername

Un nom de paramètre existant dans la famille.

La fonction de calcul recevra la valeur du paramètre au moment de l'appel.

sourceKeyWord

Un mot clé qui est remplacé par une valeur dynamique.

CT[relationAttributeName]

La valeur de l'input correspondant à la relation relationAttributeName.

Lorsque l'id est rempli, cela correspond au titre du document cible, sinon cela correspond au texte saisi dans cet input.

CT

Raccourci pour CT[currentAttributeName] (où currentAttributeName est le nom de l'attribut sur lequel est définie l'aide à la saisie).

Ne peut être utilisé que sur les attributs de type relation.

D
Accès à la base de données.
I
Id du document courant.
K

L'index de la ligne en cours si l'attribut est dans un tableau.

Si l'attribut n'est pas dans un tableau, la valeur passée est -1

T

L'objet php correspondant au document en cours.

L'objet récupéré est le document tel qu'il est en base de donnée.

A

L'action courante (un objet de la classe Action).

Cela permet, par exemple, de récupérer des informations sur l'utilisateur courant.

propertyName

Une propriété du document.

Elle sera remplacée par sa valeur.

appParameterName

Un paramètre applicatif.

Ce paramètre doit obligatoirement être global.

familyName

Un nom logique de famille.

Il sera remplacé par son id.

targetAttributeName

Un nom d'attribut existant dans la famille.

Lors du choix d'une des suggestions, les valeurs correspondant à ces suggestions sont insérées dans l'ordre dans les attributs désignés par targetAttributeName

targetKeyWord

Un mot clé désignant la cible de l'aide à la saisie.

CT[relationAttributeName]
L'input correspondant à la relation relationAttributeName.
CT
Raccourci pour CT[currentAttributeName] (où *currentAttributeName est le nom de l'attribut sur lequel est définie l'aide à la saisie).
?

permet de "sauter" une des valeurs de retour sans l'utiliser.

Est particulièrement utile dans le cas d'aides à la saisie génériques qui retournent plus de valeurs que d'attributs à compléter.

4.7.3 Exemples

4.7.3.1 Retour unique

attrid label type visibility phpfile phpfunc
city_name Ville text W cities.php getCities(city_name):city_name 
<?php
/**
 * EXTERNALS/cities.php
 */
 
function getCities($userInput=''){
    $suggestions = array();
    // Liste des villes utilisables
    $availableCities = array(
        "Paris",
        "Toulouse",
        "Souillac"
    );
    //teste si les villes correspondent à la saisie de l'utilisateur
    foreach($availableCities as $city){
        if( ''===$userInput || preg_match(strToLower($userInput), strToLower($city)) ){
            $suggestions[] = array(
                $city,      //le nom de la suggestion
                $city       //la valeur qui ira dans attr_city
            );
        }
    }
    return $suggestions;
}
 
?>

4.7.3.2 Retour multiple

attrid label type visibility phpfile phpfunc
city_name Ville text W cities.php getCities(city_name):city_name
city_cedex Code postal int W cities.php getCedex(city_cedex):city_cedex,city_name 
<?php
/**
 * EXTERNALS/cities.php
 */
 
function getCedex($userInput=''){
    $suggestions = array();
    // Liste des villes utilisables
    $availableCities = array(
        "75000" => "Paris",
        "31000" => "Toulouse",
        "46200" => "Souillac"
    );
    //teste si les villes correspondent à la saisie de l'utilisateur
    foreach($availableCities as $cedex => $city){
        if( ''===$userInput || preg_match($userInput, $cedex) ){
            $suggestions[] = array(
                sprintf("[%d] %s", $cedex, $city),      //le nom de la suggestion
                $cedex,                                 //la valeur qui ira dans attr_cedex
                $city                                   //la valeur qui ira dans attr_city
            );
        }
    }
    return $suggestions;
}
 
?>

4.7.4 Astuces

4.7.4.1 attributs relation

  • Lorsqu'une aide à la saisie remplit un attribut de type docid, il faut penser à remplir l'id et le titre affiché (attrid et CT[attrid]).
  • Lorsqu'un attribut est masqué (visibilité R ou H), alors le champ désigné par CT[attrid] n'existe pas, il est donc impossible de les désigner comme retour des aides à la saisie.

4.7.4.2 attributs htmltext

  • Lorsqu'un attribut de type htmltext est utilisé en entrée d'une aide à la saisie, la valeur reçue est encodée. il est donc nécessaire de la décoder (au moyen de html_entity_decode)
Source : famille/aides_a_la_saisie.md Dynacase Platform 3.2 | Core Manuel de référence, version 3.2 édition 13, © Anakeen Labs <labs@anakeen.com>
×
Publié sous licence CC (http://creativecommons.org/licenses/by-nc-sa/2.0/fr/) par Anakeen [www.anakeen.com]
Attribution Vous devez créditer l'Oeuvre, intégrer un lien vers la licence et indiquer si des modifications ont été effectuées à l'Oeuvre. Vous devez indiquer ces informations par tous les moyens possibles mais vous ne pouvez pas suggérer que l'Offrant vous soutient ou soutient la façon dont vous avez utilisé son Oeuvre.
Pas d’Utilisation Commerciale Vous n'êtes pas autoriser à faire un usage commercial de cette Oeuvre, tout ou partie du matériel la composant.
Partage dans les Mêmes Conditions Dans le cas où vous effectuez un remix, que vous transformez, ou créez à partir du matériel composant l'Oeuvre originale, vous devez diffuser l'Oeuvre modifiée dans les même conditions, c'est à dire avec la même licence avec laquelle l'Oeuvre originale a été diffusée.