# Contrôleur restreint

Le contrôleur restreint permet de modifier le fonctionnement du Smart Element.

# Objets internes du contrôleur

Le contrôleur de Smart Element possède quelques objets internes pour pouvoir identifier le Smart Element en cours et interagir avec le Smart Element. Ces objets se retrouvent notamment dans les événements et via l'api du widget.

# Smart Element

L'objet Smart Element décrit le Smart Element en cours. C'est un objet javascript contenant les propriétés suivantes :

id : identifiant du Smart Element
initid : identifiant initial du Smart element
title : titre du Smart Element
family : objet décrivant la Smart Structure en cours, et contenant les propriétés suivantes :
- title : titre de la Smart Structure
- name : nom logique de la Smart Structure
- id : identifiant de la Smart Structure
- icon : lien vers l'icône de la Smart Structure,
icon : lien vers l'icône du Smart Element
revision : numéro de révision du Smart Element,
status : statut du Smart Element (actif, supprimé, etc.)
viewId : rendu en cours
renderMode : mode de rendu en cours, parmi :
- edit : édition
- view : consultation.
isModified (booléen) : indique si le Smart Element contient des modifications non synchronisées.
hasUploadingFiles (booléen) : indique s'il y a des téléversements de fichier en cours. La sauvegarde d'un Smart Element ne peut être commencée que lorsque l'ensemble des téléversements sont finis.
controller (object) : référence vers le contrôleur restreint au Smart Element

# Smart Field

L'objet Smart Field décrit un Smart Field du Smart Element en cours. Il contient les propriétés et méthodes suivantes :

# Propriétés

id : identifiant du Smart Field

# Méthodes

getProperties() : {} : retourne l'ensemble des propriétés du Smart Field sous la forme d'un objet indexé par les noms des propriétés
getOptions() : {} : retourne l'ensemble des options du Smart Field sous la forme d'un objet indexé par les noms des options
getOption(optionId) : string|{} : retourne l'option optionId, retourne null, si l'option n'existe pas.
setOption(optiondId, value) : $ : modifie l'option optionId
getValue(type) : {value:, displayValue:} : retourne la valeur (typée) du Smart Field en cours. L'option facultative
type permet d'avoir les valeurs suivantes :
- current : valeur courante du Smart Field (valeur par défaut). La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée
- previous : valeur précédente du Smart Field avant modification. La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée
- initial : valeur initiale du Smart Field. La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée
- all (valeur par défaut) : retourne toutes les valeurs du Smart Field sous la forme d'un objet indexé par type de valeur.
setValue(newValue): $ : permet de modifier la valeur courante du Smart Field. La valeur en entrée est un object json contenant au moins value. La donnée displayValue est aussi nécessaire si celle-ci est différente de value. Pour les Smart Fields à valeurs multiple, le valeur doit être un tableau de valeur.
getLabel() : text : permet de récupérer le libellé du Smart Field.
setLabel(newLabel) : $ : permet de modifier le libellé du Smart Field. L'argument est du texte, le format HTML n'est pas accepté.
isModified() : bool : permet de savoir si la valeur du Smart Field a été modifiée depuis la dernière sauvegarde. Retourne true si la valeur a été modifiée.

# Types de Smart Field

# Énuméré

setEnumList(data) : void : permet de définir une nouvelle liste d'énuméré sur le Smart Field Enum.
- data : Tableau d'énuméré: Pour chaque ligne un objet avec les propriétés suivantes:
  - key : élément affiché dans la liste déroulante
  - label : message (optionnel)
  - originalLabel: Libéllé par défault (optionnel)
  - longLabel: Nom du label avec le nom des label parents (optionnel)
  - parentKey: clé de l'énuméré parent (optionnel)
  - path: chemin vers l'enuméré (optionnel) (regarder comment est le format de la variable (si possible mettre un tableau de KEY))
  - disabled: (Permette de disable chaque élément)

# Fenêtre de transition

Cet objet permet de piloter la fenêtre de transition. Il contient les propriétés et méthodes suivantes :

# Propriétés

$el : nœud DOM contenant la fenêtre de changement d'état, sous la forme d'un objet jQuery,
nextState : identifiant de l'état suivant visé
transition : identifiant de la transition empruntée (vide dans le cas de changement d'état forcé par l'administrateur).

# Méthodes

getValues() : retourne les valeurs collectées par la fenêtre de changement d'état
hide() : cache la fenêtre de changement d'état
show() : montre la fenêtre de changement d'état
close() : ferme la fenêtre de changement d'état.

L'objet menu décrit un menu du Smart Element en cours. Il permet de piloter le menu. Il contient les propriétés et méthodes suivantes :

# Propriétés

id (string) : identifiant du menu

Si l' `id` est `undefined`, alors le menu demandé n'existe pas.
type (string) : type de menu, parmi :
- itemMenu : entrée simple
- listMenu : sous-menu
- dynamicMenu : sous-menu dynamique (le contenu est demandé au serveur lors de son activation)
- callableMenu : menu avec fonction (l'appel à la fonction serveur est demandé lors de son activation)
- separatorMenu : séparateur de menu
label (string) : libellé brut textuel (pas html)
htmlLabel (string) : libellé textuel html, le libellé html est affiché avant le libellé brut
tooltipLabel : contenu du tooltip
tooltipHtml (boolean) : indique si le libellé du tooltip est html ou pas
htmlAttributes (object) : liste des attributs au sens DOM du terme,
visibility (string) : Visibilité du menu, parmi :
- visible : indique que le menu est visible
- hidden : indique que le menu est caché
- disabled : indique que le menu est désactivé
beforeContent (string) : html contenu affiché devant le libellé. Utilisé pour décrire une icône ou un symbole permettant d'identifier le menu
important (boolean) : indique si le menu est important. Lorsqu'un menu est marqué comme important, il ne sera jamais déplacé dans le menu "autres" lorsque la largeur de la page est faible.
iconUrl (string) : url de l'icône du menu
url (string) : url du menu
target (string) : nom de la fenêtre dans laquelle doit être ouverte l'url
targetOptions (object) : options de la target
confirmationText (string) : texte affiché à l'utilisateur lorsqu'il clique sur le menu dans une pop-up de confirmation
confirmationOptions (object) : options de la confirmation

TIP

Plus d'informations sur les propriétés peuvent être trouvées dans la configuration des menus.

# Méthodes

# `getProperties`

Cette méthode retourne la liste des propriétés du menu.

# Arguments

Pas d'arguments

# Retour

Un objet contenant les propriétés du menu.

# Exception

Pas d'exception

# `disable`

Cette méthode désactive le menu. Le menu reste visible mais il n'est plus actif.

WARNING

Si le menu a été masqué via hide, il sera ré-affiché, mais désactivé.

# Arguments

options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si le menu n'existe pas et que le mode strict est à true.

# `enable`

Cette méthode active le menu.

WARNING

Si le menu a été masqué via hide, il sera ré-affiché.

# Arguments

options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si le menu n'existe pas et que le mode strict est à true.

# `hide`

Cette méthode cache le menu.

WARNING

Pour ré-afficher le menu, il faut utiliser une des méthodes disable ou enable

# Arguments

options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si le menu n'existe pas et que le mode strict est à true.

# `setLabel`

Cette méthode modifie le label du menu.

# Arguments

label : Le label à utiliser. Le HTML est automatiquement échappé.
options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si le menu n'existe pas et que le mode strict est à true.

# `setHtmlLabel`

Cette méthode modifie le label du menu.

# Arguments

label : Le label à utiliser. Aucun échappement n'est effectué, le texte est inséré directement.
options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur si jamais le menu n'existe pas et le mode strict est à true.

# `setUrl`

Cette méthode modifie l'url menu.

# Arguments

url : nouvelle url du menu.
options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si jamais le menu n'existe pas et que le mode strict est à true.

# `setCssClass`

Cette méthode définit les classes css de l'élément de menu.

WARNING

Il ne faut jamais attribuer de classe directement sur le menu, car au redraw, seules les classes définies par setCssClass seront utilisées.

# Arguments

cssClass : La liste des classes séparées par un espace
options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si jamais le menu n'existe pas et que le mode strict est à true.

# Exemple

Ajout d'une classe à un menu

const menuId = "mon-menu",
  menu = controller.getMenu(menuId),
  currentClasses = menu.getProperties().cssClass.split(/\s+/),
  newClass = "menu-highlight";

if (-1 === currentClasses.indexOf(newClass)) {
  curentClasses.push(newClass);
  menu.setCssClass(currentClasses.join(" "));
}

# `setIconUrl`

Cette méthode définit une icône qui sera présentée avant le texte du menu.

C'est le pendant de la méthode php Anakeen\Ui\ItemMenu::setIcon.

WARNING

Attention, contrairement à Anakeen\Ui\ItemMenu::setIcon, la taille de l'image ne peut pas être précisée (l'image peut être retaillée par css, mais le client devra auparavant charger l'image complète).

# Arguments

iconUrl : L'url de l'image à afficher
options : Un objet contenant les propriétés suivantes :
- strict (boolean, false par défaut) : si true une erreur est déclenchée si le menu est non présent
- silent (boolean, false par défaut) : si true la modification est enregistrée mais pas rendue. L'appel à la méthode redraw permet de rendre le menu ensuite. Utile pour faire un unique rendu après plusieurs modifications.

# Retour

Pas de retour.

# Exception

Une erreur est levée si jamais le menu n'existe pas et que le mode strict est à true.

# `redraw`

Calcule et affiche le menu.

Dans le cas ou plusieurs des méthodes ci-dessus sont appelées avec l'option silent, cette méthode permet de re-dessiner le menu une unique fois en appliquant tous les changements.

# Arguments

Pas d'argument.

# Retour

Pas de retour.

# Exception

Une erreur est levée si jamais le menu n'existe pas et que le mode strict est à true.

# Carte des événements du contrôleur restreint

Cette section décrit l'ordre dans lequel les événements du Smart Element sont déclenchés.

# Ordonnancement des événements

Les événements suivants sont déclenchés de manière systématique durant le processus de rendu d'un Smart Element :

beforeRender
smartFieldBeforeTabSelect (uniquement pour les Smart Field de type tab)
smartFieldBeforeRender (pour chaque Smart Field)
smartFieldReady (pour chaque Smart Field)
smartFieldAfterTabSelect (uniquement pour les Smart Field de type tab)
ready

# Clic sur un élément du Smart Element (`docid`, élément de menu)

actionClick

# Modification

Les événements suivants sont déclenchés lors de la modification d'un Smart Element

smartFieldUploadFile (uniquement pour les Smart Field de type file)
smartFieldHelperSearch (uniquement pour les aides à la saisie)
smartFieldHelperResponse (uniquement pour les aides à la saisie) 4. smartFieldEnumSelect (uniquement pour les aides à la saisie)
smartFieldEnumSearch (uniquement pour les aides à la saisie)
smartFieldEnumResponse (uniquement pour les aides à la saisie)
smartFieldHelperSelect (uniquement pour les aides à la saisie)
smartFieldConstraintCheck
smartFieldUploadFileDone (uniquement pour les Smart Field de type file)
smartFieldChange
smartFieldArrayChange (uniquement pour les Smart Field de type array)

# Cas du Smart Field de type `docid` avec option de création

actionClick (lors du clic sur le bouton de création)
smartFieldCreateDialogSmartElementReady
smartFieldCreateDialogSmartElementBeforeSetFormValues
smartFieldCreateDialogSmartElementBeforeSetTargetValue
smartFieldCreateDialogSmartElementBeforeClose
smartFieldCreateDialogSmartElementBeforeDestroy

# Sauvegarde

Les événements suivants sont déclenchés lors de la sauvegarde d'un Smart Element :

beforeValidate
beforeSave
smartFieldConstraintCheck (pour chaque Smart Field)
afterSave
close

# Suppression

Les événements suivants sont déclenchés lors de la suppression d'un Smart Element :

# Restauration

Les événements suivants sont déclenchés lors de la restauration d'un Smart Element :

# Passage de transition

Les événements suivants sont déclenchés lors d'une transition (changement d'état) du Smart Element :

beforeDisplayTransition
afterDisplayTransition Si annulation
beforeTransitionClose (si annulation)

Si confirmation

beforeTransition(si confirmation)
successTransition/ failTransition
beforeTransitionClose
beforeClose
close

# Autres

# Affichage de message

displayMessage / displayError

# Changement du label d'un onglet ou contenu d'un onglet en erreur

smartFieldTabChange

# Méthodes du contrôleur restreint de Smart Element

# `addEventListener`

Cette méthode permet de charger un écouteur dans le widget du Smart Element.

WARNING

L’écouteur ajouté est déchargé automatiquement lors d’un rechargement des données widget Smart Element (changement de mode, d’identifiant ou de révision (passage de transition)).

# Arguments

type (String) : Le type d’événement. Vous pouvez vous référer aux événements émis par le Smart Element, les Smart Fields, les changements d’état ainsi que les événements spécialisés.
option (Object) : Optionnel. Il contient les propriétés suivantes :
- check (function, default: () => true) : Cette fonction permet d’indiquer pour quel type de Smart Element s’applique l’écouteur. Elle reçoit en entrée un objet Smart Element décrivant le Smart Element courant. Elle doit retourner true pour indiquer que l’écouteur est applicable pour ce type de Smart Element. Par défaut l’écouteur s’applique au rendu courant du Smart Element.
- name (String): Optionnel. Nom de l’écouteur. Ce nom est utilisé pour identifier l’écouteur et le supprimer. Le nom peut posséder un namespace. Par défaut un nom est calculé automatiquement. lorsque le nom correspond à un écouteur déjà enregistré sur ce widget, le nouvel écouteur remplace l’ancien, qui ne sera donc plus déclenché.
- once (Boolean, default: false) : si once est à true, l’écouteur n’est appliqué qu’une seule fois et ensuite supprimé.
- persistent (Boolean, default: false) : si persistent est à true, l’écouteur n’est pas supprimé lors du prochain fetchSmartElement.
callback (function) : cette fonction est appelée lorsque l’événement type est émis. Elle reçoit un tableau contenant les paramètres suivants dans cet ordre:
- event : Objet événement standard de jQuery.
- smartElement : l’objet Smart Element écouté.
- parameters : les paramètres de l’événement.

Annulation d’un comportement

Pour les événements annulables (par exemple les événements de type before), la callback permet d’annuler l’événement dans les cas où :

La méthode preventDefault() du paramètre event est appelée.
La callback retourne false

Asynchrone avec promesse

Il est possible de renvoyer un traitement asynchrone en retournant un objet Promise. Le traitement dans la promesse ne sera exécuté que lorsque la promesse sera résolue.

# Retour

Le nom de l’écouteur enregistré.

# Exceptions

Aucune exception.

# Exemple

localController.addEventListener(
  "actionClick",
  {
    name: "myActionClickListener",
    check: function(smartElement) {
      return smartElement.family.name === "DEVBILL";
    }
  },
  function(event, smartElement, parameters) {
    console.log(`On a enclenché l’action ${parameters.eventId} du smart element ${smartElement.initid}`);
  }
);

# `addConstraint`

Cette méthode permet de charger une contrainte dans le Smart Element. Une fois la contrainte chargée, elle est valide durant toute la vie du Smart Element.

WARNING

Une contrainte n’est pas déchargée automatiquement lors du changement d’état du Smart Element ( changement de Smart Element, d’état, etc.).

# Arguments

options (Object) : Objet décrivant la contrainte. Il contient les propriétés suivantes :
- check (function, default: () => true) : Fonction permettant d’indiquer sur quel type de Smart element la contrainte s’applique. Cette fonction reçoit en argument un objet Smart Element. La contrainte sera applicable à tous les Smart Elements pour lesquels la fonction retourne true. Par défaut, la contrainte s’applique à tous les Smart Elements.
- smartFieldCheck (function, default: () => true) : Fonction permettant d’indiquer pour quel Smart Field s’applique la contrainte. Cette fonction reçoit en argument un objet Smart Field. La contrainte sera applicable à tous les Smart Fields pour lesquels la fonction retourne true. Par défaut, la contrainte s’applique à tous les Smart Fields.
- name (String) : Le nom de la contrainte. Ce nom est utilisé pour identifier la contrainte et la supprimer. Le nom peut posséder un namespace. Par défaut un nom est calculé automatiquement. Obligatoire si l’argument callback n’est pas défini.
- once (Boolean, default: false) : Si à true, la contrainte n’est appliquée qu’une seule fois avant d’être supprimée.
callback (function): Fonction qui sera appelée lors de la modification d’un Smart Field du Smart Element. Si une chaîne de caractère est renvoyée alors la contrainte est déclenchée, dans ce cas la sauvegarde est annulée. Il est aussi possible de retourner un tableau d’objet avec une clef "message" et une clef "index". La fonction reçoit les paramètres suivants suivants :
- smartElement : Le Smart Element.
- smartField : Le Smart Field modifié.
- values : un objet décrivant les modifications en cours. Il possède les propriétés :
  - current : valeur courante du Smart Field
  - previous : valeur précédente du Smart Field
  - initial : valeur initiale du Smart Field

# Retour

La méthode retourne le nom de la contrainte.

# Exceptions

Une exception est levée dans le cas où ni callback ni la propriété name ne sont définis.

# Exemple

localController.addConstraint(
  {
    check: function(smartElement) {
      return smartElement.family.name === "DEVBILL";
    },
    name: "myConstraint"
  },
  function(smartElement, smartField, values) {
    console.log(`The smart field ${smartField.name} will be modified to :`, values.current);
  }
);

# `addCustomClientData`

Cette méthode permet d’enregistrer des données complémentaires transmises lors de la sauvegarde, suppression, rechargement du Smart Element. La donnée complémentaire est effacée lorsque la commande réussit (avant que les callback soient appelés). Pour les enregistrements (POST et PUT), la donnée est envoyée dans le contenu en json dans l’index "customClientData". Pour les consultations (GET) et suppressions (DELETE), la donnée est envoyée encodée en json dans l’url avec la variable "customClientData".

# Arguments

Il existe trois signatures pour cette méthode :

# `addCustomClientData(value: Object)`

value (Object) : Objet de données complémentaires à ajouter. Les données sont ajoutées à la liste des données à envoyer lors du prochain échange. Les données sont fusionnées avec celles déjà existantes. Si une clef existante est fournie, la nouvelle valeur remplace l’ancienne.

# `addCustomClientData(check: function, value: Object)`

check (Function) : fonction de vérification des données complémentaires. Les données ne sont envoyées que si cette fonction retourne true lors du prochain échange réseau. Cette contrainte reçoit en entrée les mêmes paramètres que les check.
value (Object) : Objet de données complémentaires à ajouter. Les données sont ajoutées à la liste des données à envoyer lors du prochain échange. Les données sont fusionnées avec celles déjà existantes. Si une clef existante est fournie, la nouvelle valeur remplace l’ancienne.

# `addCustomClientData(check: Object, value: Object)`

check (Function) : Objet contenant les propriétés :
- check (Function, default: () => true): optionnel. Fonction de vérification des données complémentaires. Les données ne sont envoyées que si cette fonction retourne true lors du prochain échange réseau. Cette contrainte reçoit en entrée les mêmes paramètres que les check. Par défaut, la fonction renvoie toujours true.
- once (Boolean, default: true) : si à false, alors le customClientData est persistent (il n’est pas effacé après une transaction réseau). Il n’est effacé qu’au moyen de la méthode removeCustomClientData.
value (Object) : Objet de données complémentaires à ajouter. Les données sont ajoutées à la liste des données à envoyer lors du prochain échange. Les données sont fusionnées avec celles déjà existantes. Si une clef existante est fournie, la nouvelle valeur remplace l’ancienne.

# Retour

Aucun retour.

# Exceptions

Aucune exception.

# Exemple

localController.addCustomClientData({
  myData: "myData"
});
console.log(JSON.stringify(localController.getCustomClientData()));

Retour de la console :

{ "myData": "myData" }

# `appendArrayRow`

Cette méthode permet d’ajouter une ligne à la fin d’un Smart Field de type tableau. Si une des colonnes du tableau n’est pas renseignée, la valeur par défaut sera utilisée.

# Arguments

smartFieldId (String) : l’identifiant du Smart Field de type tableau
values (Object) : un objet ayant pour clef la valeur d’un des Smart Fields du tableau et pour contenu de chaque clef un objet avec les propriétés :
- value (String) Obligatoire : valeur brute du Smart Field
- displayValue (String, default: value) : valeur du Smart Field présenté aux utilisateurs. Égal à value par défaut.

# Retour

Aucun retour.

# Exceptions

Une exception est levée dans le cas où :

Le Smart Field n’existe pas
Le Smart Field n’est pas un tableau
Sa valeur n’est pas un objet

# Exemple

localController.appendArrayRow("my_array_field", {
  newRow: { value: "newRow", displayValue: "This is a new row" }
});

# `changeStateSmartElement`

Cette méthode permet de demander le passage d’une transition pour effectuer un changement d’état pour le Smart Element en cours.

La demande de transition se déroule en trois temps :

Affichage d’une fenêtre de transition : cette fenêtre propose les ask ou demande un commentaire ou affiche juste le processus de transition, s’il n’y a ni ask, ni commentaire demandé. la fenêtre n’est pas affichée si le changement est unattented.
Demande de transition : une requête serveur est effectuée avec en référence l’état demandé et les valeurs des paramètres.
Si l’étape précédente peut-être effectuée (changement d’état valide, etc...), le Smart Element est rechargé (les deuxième et troisième paramètres sont donc similaires à ceux du reinitSmartElement).

# Arguments

parameters (Object) : Paramètres de la transition. L’objet contient les propriétés suivantes :
- nextState (String) : obligatoire. État cible du Smart Element.
- transition (String) : obligatoire. Identifiant de la transition à effectuer.
- unattended (Boolean, default: false) : Si à true, la fenêtre de transition et les ask ne sont pas affichés. Si jamais des ask sont obligatoires et non valués le changement d’état échoue.
- values (Object) : Ensemble des valeurs du ask.
- reinitOptions (Object) : Paramètres de l’affichage du Smart Element après la transition. L’objet contient les propriétés suivantes :
  - initid (Number, default: current value): Identifiant du smart element à charger. Celui du Smart Element en cours par défaut.
  - revision (Number, default: current value): Numéro de révision. Celui du Smart Element en cours par défaut.
  - viewId (String, default: current value): Indique le rendu demandé. Valeurs par défaut possibles : !defaultConsultation, !defaultEdition et !defaultCreation (uniquement pour les Smart Structures). Identifiant de vue en cours par défaut.
  - customClientData (Object, default: null): Données complémentaires à passer au serveur.
- options (Object): Objet portant des fonctions de succès ou d’échec. Ces fonctions seront appelées en cas de transition réussie ou échouée après la réinitialisation du Smart Element. Les propriétés sont les suivantes :
  - success (function) : fonction qui sera appelée en cas de transition réussie et de réinitialisation du Smart Element.
  - error (function) : fonction qui sera appelée en cas de transition échouée

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec du passage de la transition du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur.

# Exceptions

Une exception est levée dans le cas où :

l’argument n’est pas un objet
nextState ou transition ne sont pas spécifiés.

# Exemple

Demande de changement d’état simple (avec fenêtre de ask)

localController.changeStateSmartElement({
  nextState: "zoo_transmited",
  transition: "zoo_Ttransmited"
});

Demande de changement d’état sans ask

localController.changeStateSmartElement({
  nextState: "zoo_transmited",
  transition: "zoo_Ttransmited",
  unattended: true
});

Demande de changement d’état sans ask et en passant en mode édition

localController.changeStateSmartElement(
  {
    nextState: "zoo_transmited",
    transition: "zoo_Ttransmited",
    unattended: true
  },
  {
    viewId: "!defaultEdition"
  }
);

# `cleanSmartFieldErrorMessage`

Cette méthode permet de supprimer tous les messages d’erreur affichés sur un Smart Field.

# Arguments

smartFieldId (string) : identifiant du Smart Field
index (int) : numéro de ligne si le Smart Field est dans un array.

# Retour

Pas de retour.

# Exception

Si le nom du Smart Field n’existe pas.

# Exemple

Supprime tous les messages d’erreur sur le Smart Field ba_title.

localController.cleanSmartFieldErrorMessage("ba_title");

# `deleteSmartElement`

Cette méthode permet de supprimer le Smart Element. Cette suppression est une suppression logique, le Smart Element est marqué comme étant supprimé.

WARNING

Aucun message de demande de confirmation n’est présenté à l’utilisateur.

# Arguments

options (Object) : Objet contenant les options de suppression. Les propriétés sont les suivantes :
- customClientData (any) : Données complémentaires à transmettre au serveur.
- success (function) : Fonction qui sera appelée après le succès de la suppression.
- error (function) : Fonction qui sera appelée après l’échec de la suppression.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec de la suppression du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element supprimé.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : null (pas de next Smart Element)
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur.

# Exceptions

Aucune exception.

# Exemple

controller
  .deleteSmartElement()
  .then(() => {
    alert("La suppression est un succès.");
  })
  .catch(() => {
    alert("La suppression a échouée");
  });

# `drawTab`

Cette méthode permet de forcer la génération du contenu d’un onglet. Par défaut seul un des onglets est produit et affiché. Les autres onglets sont générés que lorsqu'ils sont sélectionnés.

Note : l’événement smartFieldReady est déclenché à la fin de la génération.

Si l’onglet est déjà généré ou en cours de génération, rien ne se passe.

# Arguments

smartFieldId (string) : identifiant du Smart Field (onglet) à générer.

# Retour

L’objet jQuery.

# Exception

Si le nom du Smart Field n’existe pas. Si le Smart Field n’est pas un onglet.

# Exemple

Prépare la génération de tous les onglets.

localController.addEventListener("ready", function(event, smartElement, message) {
  const smartFields = localController.getSmartFields();

  smartFields.forEach(function(field) {
    if (field.getProperties().type === "tab") {
      localController.drawTab(field.id);
    }
  });
});

# `fetchSmartElement`

Permet de charger un Smart Element, en édition ou en consultation.

Si des modifications sont non enregistrées, un message est présenté à l’utilisateur pour lui demander s’il valide le rechargement de la page et la perte de ses données.

# Arguments

value (Object): obligatoire. Un objet spécifiant les données à récupérer. Il contient les propriétés suivantes :
- initid (Number): obligatoire. Identifiant du smart element à charger.
- revision (Number, default: -1): optionnel. Numéro de révision, -1 par défaut.
- viewId (String, default: "!defaultConsultation"): optionnel. Indique le rendu demandé. Valeurs par défaut possibles : !defaultConsultation, !defaultEdition et !defaultCreation (uniquement pour les Smart Structures)
- customClientData (Object, default: null): optionnel. Données complémentaires à passer au serveur.
options (Object): optionnel. Objet spécifiant des options supplémentaires. Il contient les propriétés suivantes :
- force (Boolean, default: false): optionnel. Si l’option est à true, aucune confirmation n’est demandée à l’utilisateur dans le cas où le Smart Element à remplacer est modifié et non enregistré. Par défaut, la valeur est false.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec de la récupération des données et de l’affichage du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur. Si l’utilisateur a choisi de rester sur le formulaire dans le cas d’un Smart Element non enregistré, le code erreur sera USERCANCEL.

# Exceptions

Si l’argument value n’est pas un objet ou si l’initid n’est pas renseigné.

# Exemple

localController.addEventListener("ready", function(event) {
  localController.fetchSmartElement(
    {
      initid: 12345,
      viewId: "!defaultEdition"
    },
    {
      force: true
    }
  );
});

# `getCustomServerData`

Cette méthode permet de récupérer les données complémentaires venant du serveur.

# Arguments

Aucun argument.

# Retour

Retourne la donnée complémentaire, null s’il n’y en a pas.

# Exceptions

Aucune exception.

# Exemple

console.log(localController.getCustomServerData());

# `getProperties`

Cette méthode retourne les propriétés du Smart Element.

# Arguments

Aucun argument.

# Retour

Un objet contenant les propriétés du Smart Element.

# Exceptions

Aucune exception.

# Exemple

const properties = localController.getProperties();
console.log("Les propriétés du Smart Element sont :", properties);

Voici un exemple de retour en format JSON :

{
  "initid": 12345,
  "renderMode": "view",
  "viewId": "!defaultConsultation",
  "id": 12345,
  "title": "Bill 0002 ANDRE Donna",
  "family": {
    "title": "Bill",
    "name": "DEVBILL",
    "id": 97507,
    "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png"
  },
  "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
  "revision": 0,
  "security": {
    "lock": { "id": 0 },
    "readOnly": false,
    "fixed": false,
    "profil": { "id": 0, "title": "" },
    "confidentiality": "public"
  },
  "status": "alive",
  "type": "document",
  "hasUploadingFiles": false,
  "isModified": false,
  "url": "/api/v2/smart-elements/12345/revisions/0/views/!defaultConsultation.html"
}

# `getProperty`

Cette méthode retourne une propriété du Smart Element.

# Arguments

property (String) : Le nom de la propriété à récupérer.

# Retour

La valeur de la propriété. undefined si elle n’existe pas.

# Exceptions

Aucune exception.

# Exemple

const renderMode = localController.getProperty("renderMode");
console.log("Le mode de rendu du Smart Element est :", renderMode);

Voici ce que renvoie la console :

"view"

# `getSmartFields`

Cette méthode retourne la liste des Smart Fields du Smart Element.

# Arguments

Aucun argument.

# Retour

Un tableau de Smart Fields

# Exceptions

Aucune exception.

# Exemple

const fields = localController.getSmartFields();
console.log("Les Smart Fields du Smart Element sont : ", fields);

# `getSmartField`

Cette méthode retourne un Smart Field du Smart Element.

# Arguments

smartFieldId (String) : Le nom de l’attribut du Smart Field à récupérer.

# Retour

L’objet Smart Field demandé, ou null s’il n’existe pas dans le Smart Element.

# Exceptions

Aucune exception.

# Exemple

const title = localController.getSmartField("bill_title");
console.log("Le titre du Smart Element est : ", title);

# `getValues`

Cette méthode retourne les valeurs des Smart Fields du Smart Element.

# Arguments

Aucun argument.

# Retour

Un objet indexé par les noms des Smart Fields, et pour chaque Smart Field les clés suivantes :

value : la valeur brute du Smart Field
displayValue : la valeur affichée du Smart Field

# Exceptions

Aucune exception.

# Exemple

const values = localController.getValues();
console.log("Les valeurs des Smart Fields du Smart Element est : ", values);

# `getValue`

Cette méthode retourne la valeur d’un Smart Field du Smart Element.

# Arguments

smartFieldId (String) : Le nom du Smart Field dont on veut récupérer la valeur.

# Retour À partir de la version 2021.01

Suivant le type du Smart Field et sa multiplicité, le retour est différent.

Le Smart Field est un type simple:
- Un objet avec les clés suivantes :
  - value : la valeur brute du Smart Field
  - displayValue : la valeur affichée du Smart Field
Le Smart Field est un type multiple:
- Un tableau d’objets, chaque objet ayant le format suivant:
  - value : la valeur brute du Smart Field
  - displayValue : la valeur affichée du Smart Field
Le Smart Field est un type tableau (array):
- Un tableau d’objets, chaque objet représente une ligne du tableau et suit le format suivant:
  - <id_de_la_colonne> : objet représentant la valeur simple ou multiple(voir ci-dessus) de la cellule du tableau
Si le Smart Field n’existe pas, le retour sera null.

# Exceptions

Aucune exception.

# Exemple

Smart Field de type simple:

Soit le Smart Field bill_title :

  <smart:field-text name="bill_title" is-title="true" access="ReadWrite" label="Title"/>

Retour de localController.getValue("bill_title"):

{
  "value": "Un titre",
  "displayValue": "Un titre"
}

Smart Field de type multiple:

Soit le Smart Field bill_clients :

  <smart:field-docid name="bill_clients" relation="DEVCLIENT" access="ReadWrite" multiple="true" label="Clients"/>

Retour de localController.getValue("bill_clients"):

[
  {
    "familyRelation": "DEVCLIENT",
    "url": "/api/v2/smart-elements/1272.html",
    "icon": "/api/v2/images/assets/sizes/14x14c/devclient.png",
    "revision": -1,
    "initid": 1272,
    "fromid": 1064,
    "value": "1272",
    "displayValue": "AURADOU Frank ITM ALIMENTAIRE SUD EST",
    "renderUrl": "/api/v2/smart-elements/1272.html",
    "renderTitle": "",
    "index": 0
  },
  {
    "familyRelation": "DEVCLIENT",
    "url": "/api/v2/smart-elements/1317.html",
    "icon": "/api/v2/images/assets/sizes/14x14c/devclient.png",
    "revision": -1,
    "initid": 1317,
    "fromid": 1064,
    "value": "1317",
    "displayValue": "BRETELER Louis ITM ALIMENTAIRE EST",
    "renderUrl": "/api/v2/smart-elements/1317.html",
    "renderTitle": "",
    "index": 1
  },
  {
    "familyRelation": "DEVCLIENT",
    "url": "/api/v2/smart-elements/1364.html",
    "icon": "/api/v2/images/assets/sizes/14x14c/devclient.png",
    "revision": -1,
    "initid": 1364,
    "fromid": 1064,
    "value": "1364",
    "displayValue": "MARTINET Andréa JAGUAR LAND ROVER FRANCE",
    "renderUrl": "/api/v2/smart-elements/1364.html",
    "renderTitle": "",
    "index": 2
  }
]

Smart Field de type tableau (array):

Soit le Smart Field bill_otherclients :

<smart:field-set name="bill_otherclients" type="array" access="ReadWrite" label="Other clients">
  <smart:field-text name="bill_clientname" access="ReadWrite" label="Client name" needed="true"/>
  <smart:field-text name="bill_society" access="ReadWrite" label="Enterprise"/>
</smart:field-set>

Retour de localController.getValue("bill_otherclients"):

[
  {
    "bill_clientname": {
      "value": "Client 1",
      "displayValue": "Client 1"
    },
    "bill_society": {
      "value": "Société 1",
      "displayValue": "Société 1"
    }
  },
  {
    "bill_clientname": {
      "value": "Client 2",
      "displayValue": "Client 2"
    },
    "bill_society": {
      "value": "Société 2",
      "displayValue": "Société 2"
    }
  }
]

# `getMenus`

Cette méthode retourne la liste des menus du Smart Element

# Arguments

Aucun argument.

# Retour

Renvoie un tableau d’objets Menu

# Exceptions

Une exception est levée dans le cas où le modèle du Smart Element n’est pas encore initialisé.

# Exemple

localController.getMenus().forEach(menu => {
  console.log(`Le menu ${menu.id} est dans le Smart Element`);
});

# `getMenu`

Cette méthode retourne un menu du Smart Element à partir de son identifiant.

# Arguments

id (String) : l’identifiant du menu.

# Retour

Renvoie l’objet Menu correspondant. Si l’identifiant n’existe pas, renvoie null.

# Exceptions

Une exception est levée dans le cas où le modèle du Smart Element n’est pas encore initialisé.

# Exemple

const systemMenu = localController.getMenu("system");
console.log("Le menu system du Smart Element est : ", systemMenu);

# `getCustomClientData`

Cette méthode permet de récupérer les données complémentaires précédemment enregistrées par la méthode addCustomClientData.

# Arguments

Aucun argument.

# Retour

L’objet de données complémentaires enregistrées.

# Exceptions

Aucune exception.

# Exemple

localController.addCustomClientData({
  hello: "World"
});

console.log(localController.getCustomClientData()); //Retourne { hello: "world" }

# `hasSmartField`

Cette méthode retourne true si le Smart Field est présent dans le Smart Element.

# Arguments

smartFieldId (String) : le nom du Smart Field.

# Retour

true si le Smart Field existe dans le Smart Element, false sinon.

# Exceptions

Aucune exception.

# Exemple

<ank-smart-element ref="smartElement"></ank-smart-element>

if (localController.hasSmartField("bill_title")) {
  console.log("Le titre du Smart Element est : ", localController.getSmartField("bill_title"));
}

# `hideSmartField`

Cette méthode cache un Smart Field visible du Smart Element.

# Arguments

smartFieldId (String) : le nom du Smart Field à cacher.
index : dans le cas d’un tableau, l’index de la cellule du Smart Field à cacher.

# Retour

Aucun retour.

# Exceptions

Une exception est levée si :

Le Smart Element n’est pas encore initialisé
Le Smart Field n’existe pas.

# Exemple

localController.hideSmartField("bill_title", 1);

# `hasMenu`

Cette méthode retourne true si le menu spécifié est présent dans le Smart Element

# Arguments

menuId (String) : identifiant du menu.

# Retour

Renvoie true si le menu est présent, false sinon.

# Exceptions

Une exception est levée dans le cas où le modèle du Smart Element n’est pas encore initialisé.

# Exemple

function hasMenu(menuId) {
  const hasMenu = localController.hasMenu(menuId);
  console.log("le menu ", menuId, "est-il présent ? ", hasMenu);
}

# `isLoaded`

Permet de savoir si le composant est chargé et prêt à être utilisé.

# Arguments

Pas d’argument.

# Retour

Renvoie true si le Smart Element est prêt à être utilisé, false dans le cas contraire.

# Exceptions

Pas d’exception.

# Exemple

if (localController.isLoaded()) {
  alert("Smart element component is loaded.");
}

# `isModified`

Permet de savoir si les valeurs du Smart Element ont été modifiées.

# Arguments

Aucun.

# Retour

Renvoie true si le Smart Element a été modifié, false dans le cas contraire.

# Exceptions

Pas d’exception.

# Exemple

if (localController.isModified()) {
  alert("Smart element component has been modified.");
}

# `injectJS`

Cette méthode permet d’injecter des scripts Javascript dans la page courante.

# Arguments

jsToInject (String | Array<String>) : Le chemin ou un tableau de chemin vers les scripts à injecter.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite du chargement des scripts.

# Exceptions

Un exception est levée dans le cas où :

Le paramètre jsToInject n’est pas du type String ou Array<String>

# Exemple

controller
  .injectJS("./myScript.js")
  .then(() => {
    alert("My script has been loaded");
  })
  .catch(() => {
    alert("The script injection has failed.");
  });

# `injectCSS`

Cette méthode permet d’injecter de la CSS dans la page courante.

# Arguments

cssToInject (String | Array<String>) : Le chemin ou un tableau de chemin vers les fichiers CSS à injecter.

# Retour

Aucun retour.

# Exceptions

Un exception est levée dans le cas où :

Le paramètre cssToInject n’est pas du type String ou Array<String>

# Exemple

localController.injectCSS("./myStyle.css");

# `insertBeforeArrayRow`

Cette méthode permet d’ajouter une ligne au début d’un Smart Field de type tableau.

# Arguments

smartFieldId (String) : l’identifiant du Smart Field de type tableau
values (Object) : un objet ayant pour clef la valeur d’un des Smart Fields du tableau et pour contenu de chaque clef un objet avec les propriétés :
- value (String) Obligatoire : valeur brute du Smart Field
- displayValue (String, default: value) : valeur du Smart Field présenté aux utilisateurs. Égal à value par défaut.
index (int, default: 0) : Position à laquelle sera insérée la ligne. Au début du tableau par défaut.

# Retour

Aucun retour.

# Exceptions

Une exception est levée dans le cas où :

Le Smart Field n’existe pas
Le Smart Field n’est pas un tableau
Sa valeur n’est pas un objet
L’index ne fait pas partie du tableau.

# Exemple

localController.insertBeforeArrayRow("my_array_field", {
  newRow: { value: "newRow", displayValue: "This is a new row" }
});

# `listConstraints`

Cette méthode permet de lister les contraintes en cours sur le Smart Element. L’objet retourné contient toutes les contraintes actives ou non sur le Smart Element.

# Arguments

Aucun argument.

# Retour

Retourne un objet dont chaque clé est le nom de la contrainte, et dont la valeur est l’objet Contrainte associé.

# Exceptions

Aucune exception.

# Exemple

const constraints = localController.listConstraints();
console.log("L’ensemble des contraintes du Smart Element sont : ", constraints);

# `listEventListeners`

Cette méthode permet de lister les écouteurs attachés au widget. La liste retournée ne préjuge pas de si les événements sont actifs ou pas sur le Smart Element en cours.

# Arguments

Aucun argument.

# Retour

La méthode retourne un tableau contenant les écouteurs.

# Exceptions

Aucune exception.

# Exemple

console.log(JSON.stringify(localController.listEventListeners()));

Retour en console :

[
  { "eventType": "beforeRender", "name": "event_beforeRender7", "once": false, "persistent": false },
  { "eventType": "ready", "name": "event_ready8", "once": false, "persistent": false },
  { "eventType": "smartFieldChange", "name": "event_smartFieldChange9", "once": false, "persistent": false },
  "..."
]

# `maskSmartElement`

Cette méthode affiche une barre de chargement sur le Smart Element

# Arguments

message (String) : Message à afficher sur la barre de chargement.
px (int) : le pourcentage de chargement de la barre.

# Retour

Aucun retour.

# Exceptions

Aucune exception.

# Exemple

localController.maskSmartElement("Loading, please wait...", 60);

# `removeEventListeners`

Cette méthode permet de supprimer un écouteur ou un ensemble d’écouteurs sur le widget en cours.

# Arguments

name (String) : Nom de l’écouteur ou namespace à supprimer.
allKind (Boolean, default: false) : Si à true, supprime également les écouteurs internes.

# Retour

La méthode retourne les écouteurs supprimés.

# Exceptions

Aucune exception.

# Exemple

localController.removeEventListener("myListener");

# `removeCustomClientData`

Permet de supprimer une donnée complémentaire à partir de sa clé.

# Arguments

key (String) : la clé de la donnée complémentaire à supprimer.

# Retour

Retourne le Smart Element Controller.

# Exceptions

Aucune exception.

# Exemple

localController.addCustomClientData({
  hello: "World"
});

localController.removeCustomClientData("hello");

# `removeArrayRow`

Cette méthode permet de supprimer une ligne d’un tableau.

# Arguments

smartFieldId (String) : l’identifiant du Smart Field de type tableau
index (int) : Index de la ligne à supprimer

# Retour

Aucun retour.

# Exceptions

Une exception est levée dans le cas où :

Le Smart Field n’existe pas
Le Smart Field n’est pas un tableau
L’index ne fait pas partie du tableau.

# Exemple

Ici nous supprimons la première ligne du tableau

localController.removeArrayRow("my_array_field", 0);

# `restoreSmartElement`

Cette méthode permet de restaurer un Smart Element supprimé.

# Arguments

options (Object) : Objet contenant les options de suppression. Les propriétés sont les suivantes :
- customClientData (any) : Données complémentaires à transmettre au serveur.
- success (function) : Fonction qui sera appelée après le succès de la suppression.
- error (function) : Fonction qui sera appelée après l’échec de la suppression.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec de la restauration du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element restauré.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : null (pas de next Smart Element)
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur.

# Exceptions

Aucune exception.

# Exemple

controller
  .restoreSmartElement()
  .then(() => {
    alert("La restauration est un succès.");
  })
  .catch(() => {
    alert("La restauration a échouée");
  });

# `removeConstraint`

Cette méthode permet de supprimer une contrainte ou un ensemble de contraintes sur le Smart Element.

# Arguments

constraintName (String) : le nom de la contrainte ou namespace des contraintes à supprimer.
allKind (boolean, default: false) : si égal à true, les contraintes externes seront également supprimées.

# Retour

Retourne un tableau des contraintes supprimées.

# Exceptions

Aucune exception.

# Exemple

Suppression des contraintes du namespace bill

const removedConstraints = localController.removeConstraint(".bill");
console.log("Les contraintes enlevées sont : ", removedConstraints);

# `reinitSmartElement`

Cette méthode permet de recharger le Smart Element.

Le comportement est identique à la méthode fetchSmartElement. La seule différence est que l’argument initid n’est pas obligatoire. Les arguments initid , revision, viewId, s’ils n’ont pas été définis, reprennent les valeurs du Smart Element courant.

# Arguments

value (Object): Un objet spécifiant les données à récupérer. Il contient les propriétés suivantes :
- initid (Number): Identifiant du smart element à charger.
- revision (Number, default: -1): Numéro de révision, -1 par défaut.
- viewId (String, default: "!defaultConsultation"): Indique le rendu demandé. Valeurs par défaut possibles : !defaultConsultation, !defaultEdition et !defaultCreation (uniquement pour les Smart Structures)
- customClientData (Object, default: null): Données complémentaires à passer au serveur.
options (Object): optionnel. Objet spécifiant des options supplémentaires. Il contient les propriétés suivantes :
- force (Boolean, default: false): _Si l’option est à true, aucune confirmation n’est demandée à l’utilisateur dans le cas où le Smart Element à remplacer est modifié et non enregistré. Par défaut, la valeur est false.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec de la récupération des données et de l’affichage du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur. Si l’utilisateur a choisi de rester sur le formulaire dans le cas d’un Smart Element non enregistré, le code erreur sera USERCANCEL.

# Exceptions

Aucune exception.

# Exemple

localController
  .reinitSmartElement({
    viewId: "!defaultEdition"
  })
  .then(function() {
    alert("Le smart élément a été rechargé avec succès");
  })
  .catch(function() {
    alert("Il y a eu un problème dans le chargement du Smart Element");
  });

# `saveSmartElement`

Cette méthode permet d’enregistrer le Smart Element en cours. La bannière de chargement est affichée et le Smart Element est ensuite représenté en mode formulaire avec ses nouvelles valeurs. Les contraintes (cliente et serveur) sont vérifiées. La sauvegarde est équivalente au clic sur le menu Enregistrer. La requête d’enregistrement du Smart Element ne débute que lorsque l’ensemble des téléversements en cours de fichiers ont abouti. La propriété du Smart Element hasUploadingFiles indique s’il y a des téléversement en cours.

Transmission des données d’enregistrement

Par défaut, le formulaire ne transmet au serveur que les valeurs modifiées sauf dans le cas de la création où il transmet toutes les valeurs.

Droit d’accès

L’affichage et la sauvegarde des valeurs sont contraintes par les droits sur les champs.

# Arguments

options (Object) : optionnel. Objet spécifiant des options supplémentaires. Il contient les propriétés suivantes :
- customClientData (Object, default: null): optionnel. Données complémentaires à passer au serveur.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l’échec de la sauvegarde du SmartElement.

En cas de réussite, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.

En cas d’échec, la structure de l’objet de retour est :

element : Élément DOM (jquery) du composant Smart Element
nextDocument : un objet Smart Element décrivant le Smart Element suivant.
previousDocument : un objet Smart Element décrivant le Smart Element précédent.
errorMessage : un objet d’erreur contenant deux propriétés :
- code: Le code d’erreur
- contentText: Le message d’erreur.

WARNING

Si la sauvegarde est annulée par lors de l’événement beforeSave alors la promesse passe en échec.

# Exceptions

Aucune exception.

# Exemple

localController
  .saveSmartElement()
  .then(() => {
    alert("Sauvegarde réussie");
  })
  .catch(() => {
    alert("Sauvegarde échouée");
  });

# `setValue`

Cette méthode met à jour la valeur d’un Smart Field.

# Arguments

smartFieldId (String) : Le nom du Smart Field dont on veut modifier la valeur.
smartFieldValue (Object|Array) : la nouvelle valeur du Smart Field.
options (Object) : Objet d’options facultatives.

Important

La signature de la méthode setValue dépend du type et de la multiplicité du Smart Field indiqué par l’argument smartFieldId.

# Smart Field simple

smartFieldId (String) : Le nom du Smart Field simple dont on veut modifier la valeur.
smartFieldValue (Object) : Un objet avec comme valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : facultatif la valeur qui sera affichée dans le cas des Smart Fields de type docid, account et enum.

WARNING

displayValue n’est pas pris en compte pour les Smart Fields de type text, longtext, int, double, time, date, timestamp, color et htmltext

Par exemple :

Pour un Smart Field simple :

localController.setValue("field_text", { value: "Texte simple" });

Pour un Smart Field simple de type docid, account ou enum :

localController.setValue("field_docid", { value: 2001, displayValue: "document 2" });

# Smart Field multiple

Rappel

Seuls les Smart Field de type docid, account et enum ont la possibilité d’être multiples.

La signature est alors :

smartFieldId (String) : Le nom du Smart Field multiple dont on veut modifier la valeur.
smartFieldValue (Array) : Un tableau d’objets avec comme valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : la valeur qui sera affichée

Par exemple :

localController.setValue("field_docid_multiple", [
  { value: 2000, displayValue: "document 1" },
  { value: 2001, displayValue: "document 2" }
]);

# Smart Field simple dans un tableau (Smart field colonne simple)

Pour les Smart Field colonne, il est possible de modifier toutes les valeurs ou la valeur à un index particulier.

# Modification de toutes les valeurs

La signature est alors :

smartFieldId (String) : Le nom du Smart Field colonne simple dont on veut modifier la valeur.
smartFieldValue (Array) : Un tableau d’objets avec comme valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : facultatif la valeur qui sera affichée dans le cas des Smart Fields de type docid, account et enum.

WARNING

displayValue n’est pas pris en compte pour les Smart Fields de type text, longtext, int, double, time, date, timestamp, color et htmltext

Par exemple :

localController.setValue("field_simple_column", [{ value: "Ligne 1" }, { value: "Ligne 2" }, { value: "Ligne 3" }]);

Pour un Smart Field de type docid:

localController.setValue("field_docid_column", [
  { value: 2000, displayValue: "Document 1" },
  { value: 2001, displayValue: "Document 2" }
]);

# Modification des valeurs à un index donné

smartFieldId (String) : Le nom du Smart Field multiple dont on veut modifier la valeur.
smartFieldValue (Object) : Un objet contenant les valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : facultatif la valeur qui sera affichée dans le cas des Smart Fields de type docid, account et enum.
options (Object): un objet contenant les valeurs :
- index (integer): la position de la valeur dans la colonne. L’index doit être supérieur ou égal à zéro.

Par exemple :

localController.setValue("field_simple_column", { value: "Ligne 2" }, { index: 1 });

Pour un Smart Field de type docid:

localController.setValue("field_docid_column", { value: 2001, displayValue: "Document 2" }, { index: 1 });

# Smart Field multiple dans un tableau (Smart field colonne multiple)

Rappel

Seuls les Smart Field de type docid, account et enum ont la possibilité d’être multiples.

Pour les Smart Fields colonne, il est possible de modifier toutes les valeurs ou la valeur à un index particulier.

# Modification de toutes les valeurs

smartFieldId (String) : Le nom du Smart Field colonne multiple dont on veut modifier la valeur.
smartFieldValue (Array<Array>) : Un tableau contenant des tableaux d’objets avec comme valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : la valeur qui sera affichée dans la colonne.

Par exemple :

localController.setValue("field_docid_multiple_column", [
  [
    { value: 2000, displayValue: "Document 1" },
    { value: 2001, displayValue: "Document 2" }
  ],
  [{ value: 2002, displayValue: "Document 3" }]
]);

# Modification des valeurs à un index donné

smartFieldId (String) : Le nom du Smart Field multiple dont on veut modifier la valeur.
smartFieldValue (Array<Object>) : Un tableau d’objets contenant les valeurs :
- value (String | Integer) : la nouvelle valeur
- displayValue (string) : la valeur qui sera affichée dans la colonne.
options (Object): un objet contenant les valeurs :
- index (integer): la position de la valeur dans la colonne. L’index doit être supérieur ou égal à zéro.

Par exemple :

localController.setValue(
  "field_docid_multiple_column",
  [
    { value: 2001, displayValue: "Document 2" },
    { value: 2002, displayValue: "Document 3" }
  ],
  { index: 2 }
);

# Smart field de type `array`

Il est également possible de modifier les valeurs d’un tableau entier. Dans ce cas, la signature est :

smartFieldId (String) : Le nom du Smart Field tableau dont on veut modifier la valeur.
smartFieldValue (Array<Object>) : Un tableau d’objets représentant chaque ligne du tableau. Chaque objet a comme clé :
- <id_de_la_colonne> : objet représentant la valeur simple ou multiple(voir ci-dessus) de la cellule du tableau
  - avec comme valeurs :
    - Pour les colonnes simples un objet avec la structure :
      - value (String | Integer) : la nouvelle valeur du champ
      - displayValue (string) : facultatif Le libellé qui sera affichée dans la colonne.
    - Pour les colonnes multiples :
      - Un tableau d’objets avec la structure :
        value (String | Integer) : la valeur du champ
        
        displayValue (string) : facultatif Le libellé qui correspondra à cette valeur.

WARNING

Si un champ du tableau n’est pas renseigné alors la valeur du champ sera supprimée. Cela revient à la même chose que de mettre la valeur à null.

Par exemple :

localController.setValue("field_array", [
  {
    field_simple_column: { value: "Ligne 1" },
    field_docid_column: { value: 2001, displayValue: "Document 2" },
    field_docid_multiple_column: [
      { value: 2000, displayValue: "Document 1" },
      { value: 2001, displayValue: "Document 2" }
    ]
  },
  {
    field_simple_column: { value: "Ligne 2" }
  }
]);

// équivaut à
localController.setValue("field_array", [
  {
    field_simple_column: { value: "Ligne 1" },
    field_docid_column: { value: 2001, displayValue: "Document 2" },
    field_docid_multiple_column: [
      { value: 2000, displayValue: "Document 1" },
      { value: 2001, displayValue: "Document 2" }
    ]
  },
  {
    field_simple_column: { value: "Ligne 2" },
    field_docid_column: { value: null },
    field_docid_multiple_column: []
  }
]);

# Retour

Aucun retour.

# Exceptions

Une exception est levée dans le cas où :

Le Smart Field n’existe pas
La propriété value est incorrecte
L’index est inférieur à zéro

# `setSmartFieldErrorMessage`

Cette méthode permet d’afficher un message d’erreur à l’utilisateur sous la même forme qu’une contrainte (c’est à dire faisant référence à un Smart Field).

# Arguments

smartFieldId (string) : identifiant du Smart Field
message (string) (plein texte) : contenu du message
index (int) : numéro de ligne si le Smart Field est dans un array.

# Retour

Pas de retour

# Exception

Si le nom du Smart Field n’existe pas

# Exemple

localController.setSmartFieldErrorMessage("ba_title", "Le titre est obligatoire");

# `selectTab`

Cette méthode permet de sélectionner un onglet du Smart Element.

Note : les événements smartFieldBeforeTabSelect et smartFieldAfterTabSelect sont déclenchés à la fin de la génération.

# Arguments

smartFieldId (string) : identifiant du Smart Field (onglet) à sélectionner.

# Retour

L’objet jQuery.

# Exception

Si le nom du Smart Field n’existe pas. Si le Smart Field n’est pas un onglet.

# Exemple

Affiche l’onglet my_tab.

localController.selectTab("my_tab");

# `showMessage`

Cette méthode permet d’afficher un message à l’utilisateur. Il se présente dans une notification en haut à droite de l’écran.

# Arguments

message (String | Object) : chaîne de caractères ou objet à afficher. Dans le cas d’un objet, il doit contenir les propriétés suivantes :
- type (String, default: "info") : Type du message parmi info (par défaut), error, warning, success et notice.
- message (String) : contenu du message à afficher
- htmlMessage (String) : contenu du message html à afficher (affiché dessous le message brute)

# Retour

Aucun retour.

# Exceptions

Aucune exception.

# Exemple

localController.showMessage({
  type: "warning",
  message: "The user is not logged in."
});

showMessage

# `showSmartField`

Cette méthode affiche un Smart Field caché du Smart Element.

# Arguments

smartFieldId (String) : le nom du Smart Field à afficher.
index : dans le cas d’un tableau, l’index de la cellule du Smart Field à afficher.

# Retour

Aucun retour.

# Exceptions

Une exception est levée si :

Le Smart Element n’est pas encore initialisé
Le Smart Field n’existe pas.

# Exemple

localController.showSmartField("bill_title", 1);

# `triggerEvent`

Cette méthode permet de déclencher un événement sur le widget en cours.

WARNING

Le fait de déclencher un événement ne lance pas l’action associée. Par exemple, le fait de déclencher un beforeSave ne lance pas la sauvegarde du Smart Element.

# Arguments

name (String) : Nom de l’événement à déclencher. Il est possible d’émettre des événements du Smart Element. D’autres événements peuvent être déclenchés à condition que leur nom soit préfixé par custom:.
parameters (Object | Array) : Ensemble d’arguments qui seront transmis aux écouteurs de cet événement.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler l’annulation de l’événement par un preventDefault()

# Exceptions

Aucune exception.

# Exemple

controller
  .triggerEvent("ready")
  .then(() => {
    console.log("L’événement ready a été accepté");
  })
  .catch(() => {
    console.log("L’événement ready a été annulé");
  });

# `tryToDestroy`

Cette méthode essaie de détruire le widget.

Deux cas sont possibles :

le widget est en édition et l’utilisateur a modifié au moins une valeur, il est alors demandé à l’utilisateur s’il souhaite fermer la fenêtre, si oui le widget est détruit, sinon l’action est annulée
le widget n’est pas en édition ou n’a pas été modifié, il est alors détruit

# Arguments

testDirty (booléen) : valeur par défaut true active le test de modification avant la destruction. Si le Smart-element est modifié alors un message est de validation est affiché à l’utilisateur.

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou de la destruction du SmartElement.

En cas de réussite, la structure de l’objet de retour est undefined;

En cas d’échec, la structure de l’objet de retour est une chaîne de caractère "Unable to destroy because user refused it".

# Exceptions

Aucune exception.

# Exemple

controller
  .tryToDestroy()
  .then(() => {
    console.log("Le Smart Element a été détruit avec succès");
  })
  .catch(() => {
    console.log("Le Smart Element n’a pas pu être détruit");
  });

# `unmaskSmartElement`

Cette méthode cache la barre de chargement du Smart Element.

# Arguments

force (Boolean, default: false) : Si à true, force l’effacement de la barre de chargement.

# Retour

Aucun retour.

# Exceptions

Aucune exception.

# Exemple

localController.unmaskSmartElement(true);

# Liste des événements déclenchés sur le Smart Element Ui

Les événements déclenchés sur le Smart Element peuvent être écoutés au moyen de la méthode addEventListener.

Il est possible de ne déclencher le traitement que lorsque le Smart Element satisfait certaines conditions au moyen de la fonction définie dans l'option check du listener.

# `actionClick`

# Déclenchement

Un lien interne de type événement est sélectionné. Ces liens sont de 2 formes :

un élément de type <a> ou <button> qui possède un attribut data-action

Dans ce cas, l'action est la valeur de l'attribut data-action, et doit être de la forme <type_event>:<option1>:<option2>:...
un élément de type <a> dont l'attribut href commence par #action/

Dans ce cas, l'action est la valeur de l'attribut href, et doit être de la forme #action/<type_event>:<option1>:<option2>:...

Note

Il est possible d'ajouter des customClientData en option de l'action.
Ces customClientData doivent être inscrit dans une chaîne de caractères au format JSON et placées en dernière position.

Exemple: #action/<type_event>:<option1>:<option2>:...:<optionN>:{ "key": "value1", "key2": { "key3": "value3"}}.
Note : Voir le tableau des évènements standards pour la compatibilité de cette option

Ces éléments peuvent être présents partout dans la page (menu, template, Smart Field, lien sur un Smart Field, etc.)

WARNING

Lorsqu'un élément de type <a> contient à la fois un attribut data-action=<type_event>... et un attribut href=#action/<type_event>..., alors c'est le type d'événement et les options contenus dans l'attribut data-action qui sont pris en compte.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
options : objet décrivant l'action. Il contient les propriétés suivantes :
- target : élément jquery DOM ayant déclenché l'événement,
- eventId : identifiant du type d'événément (soit le <type_event> du lien présenté ci-dessus),
- options : array d'options de cet événément

# Annulable

Oui. Dans ce cas l'événement associé n'est pas déclenché.

# Liste des événements standards

Les actions prédéfinies sur le widget Smart Element sont :

Identifiant	options	Description	Exemple
`document.close`	`[viewId]`	Demande d'affichage en mode consultation du Smart Element courant en utilisant la vue `viewId` (si `viewId` n'est pas renseigné, la vue `!defaultConsultation` est utilisée)	`#action/document.close`
`document.create`	`[customClientData]`	Demande de sauvegarde du Smart Element courant et de retour en mode modification	`#action/document.create`
`document.createAndClose`	`[viewId[:customClientData]`	Demande de sauvegarde du Smart Element courant et de retour en mode consultation en utilisant la vue `viewId` (si `viewId` n'est pas renseigné, la vue `!defaultConsultation` est utilisée)	`#action/document.createAndClose`
`document.delete`	`[customClientData]`	Demande de suppression du Smart Element courant	`#action/document.delete`
`document.edit`	`[customClientData]`	Demande d'affichage en mode modification du Smart Element courant	`#action/document.edit`
`document.help`	`helpId[:rubriqueId]`	Demande d'affichage de l'aide `helpId` avec un focus sur l'entrée `rubriqueId` (si `rubriqueId` n'est pas renseigné, le focus est en haut de l'aide	`#action/document.helpid:MY_FAMILY:my_attribute`
`document.history`	`[initid]`	Demande d'affichage de l'historique du Smart Element ayant la référence `initid` (si `initid` n'est pas renseigné, c'est l'historique de Smart Element courant qui est affiché)	`#action/document.history`
`document.load`	`initid[:viewId[:revision[:customClientData]]]`	Demande d'affichage du Smart Element ayant la référence `initid` à la place du Smart Element courant	`#action/document.load:1234:!defaultConsultation:0`
`document.lock`		Demande de verrouillage du Smart Element courant	`#action/document.lock`
`document.properties`	`[initid]`	Demande d'affichage des propriétés du Smart Element ayant la référence `initid` (si `initid` n'est pas renseigné, ce sont les propriétés du Smart Element courant qui sont affichées)	`#action/document.properties`
`document.restore`		Demande de restauration du Smart Element courant	`#action/document.restore`
`document.save`		Demande de sauvegarde du Smart Element courant	`#action/document.save`
`document.saveAndClose`	`[viewId]`	Demande de sauvegarde du Smart Element courant et de retour en mode consultation en utilisant la vue `viewId` (si `viewId` n'est pas renseigné, la vue `!defaultConsultation` est utilisée)	`#action/document.saveAndClose`
`document.transition`	`transitionId:nextStateId`	Demande de passage de la transition `transitionId` pour arriver à l'état `nextStateId`	`#action/document.transition:my_transition:my_nextstate`
`document.transitionGraph`		Demande d'affichage du graphe de transitions	`#action/document.transitionGraph`
`document.unlock`		Demande de déverrouillage du Smart Element courant	`#action/document.unlock`

# Exemple

Cet exemple affiche un confirm demandant de valider pour sauvegarder.

controller.addEventListener(
  "actionClick",
  {
    name: "saveDoubleCheck"
  },
  function changeDisplayError(event, smartElement, options) {
    //identify the good click
    if (options.eventId === "document.save") {
      if (!confirm("Voulez vous sauver ?")) {
        event.preventDefault();
      }
    }
  }
);

# `afterDelete`

# Déclenchement

Le Smart Element a été supprimé.

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event],
currentSmart ElementObject : un objet Smart Element décrivant le Smart Element courant.
previousSmart ElementObject : un objet Smart Element décrivant le Smart Element précédent.

# Annulable

Non

# Exemple

Cet exemple affiche le Smart Element 42 en consultation après la suppression.

controller.addEventListener(
  "afterDelete",
  {
    name: "display42"
  },
  function open42(event, smartElement) {
    controller.fetchSmartElement({
      initid: 42,
      viewId: "!defaultConsultation"
    });
  }
);

# `afterSave`

# Déclenchement

Le Smart Element a été sauvegardé.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
previousSmartElement : un objet Smart Element décrivant le Smart Element avant sauvegarde.

# Annulable

Non

# Exemple

Cet exemple passe directement le Smart Element en consultation après sa sauvegarde.

controller.addEventListener(
  "afterSave",
  {
    name: "passToView"
  },
  function reloadInConsultation(event, currentSmartElement) {
    controller.fetchSmartElement({
      viewId: "!defaultConsultation"
    });
  }
);

# `afterRestore`

# Déclenchement

Le Smart Element a été restauré.

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event],

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
previousSmartElement : un objet Smart Element décrivant le Smart Element avant sa restauration.

# Annulable

Non

# Exemple

Cet exemple

ajoute au ready du Smart Element (fonction addAnimalEvents) un écouteur sur l'événement beforeRestore
l'écouteur (fonction confirmRestoreAnimal) affiche un message de confirmation après la restauration.

controller.addEventListener(
  "ready",
  {
    name: "addAnimalEvent",
    check: function(smartElement) {
      return smartElement.family.name === "ANIMAL";
    }
  },
  function addAnimalEvents() {
    controller.addEventListener(
      "afterRestore",
      {
        name: "confirmRestore.animal",
        check: function(smartElement) {
          return smartElement.family.name === "ANIMAL";
        }
      },
      function confirmRestoreAnimal(event, currentSmartElement) {
        controller.showMessage({
          type: "info",
          message: "Le Smart Element a été restauré avec succès"
        });
      }
    );
  }
);

# `beforeClose`

# Déclenchement

Lorsque le Smart Element va être remplacé par un autre Smart Element. Soit pour un changement de rendu (passage de édition à consultation) ou un changement de Smart Element (mais pas lors de la sauvegarde ni de la suppression).

WARNING

L'événement n'est pas déclenchée si l'url de la page est changée ("unload" de la page).

L'événement est déclenché par l'historique du navigateur si des changements de Smart Element ont été réalisés.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
nextSmartElement : un objet Smart Element décrivant le Smart Element suivant.
customData : l'objet customClientData, cet objet peut-être modifié si besoin.

# Annulable

Oui. Dans ce cas, le Smart Element courant reste affiché et le Smart Element suivant n'est pas affiché.

# Exemple

Cet exemple

ajoute à l'événement ready du Smart Element (fonction addAnimalEvents) un écouteur sur l'événement beforeClose
l'écouteur (fonction preventCloseAnimal) empêche la fermeture du Smart Element si
- l'attribut zoo_title est différent de fermer
- le Smart Element est en mode edition.
Dans ce cas, il affiche un message pour avertir l'utilisateur qu'il doit changer la valeur.

controller.addEventListener(
  "ready",
  {
    name: "addAnimalEvent",
    check: function(smartElement) {
      return smartElement.family.name === "ANIMAL";
    }
  },
  function addAnimalEvents() {
    controller.addEventListener(
      "beforeClose",
      {
        name: "preventClose.animal",
        check: function(smartElement) {
          return smartElement.family.name === "ANIMAL";
        }
      },
      function preventCloseAnimal(event, currentSmartElement) {
        if (currentSmartElement.renderMode === "edit" && controller.getValue("zoo_title").value !== "fermer") {
          event.preventDefault();
          controller.showMessage({
            type: "error",
            message: "If you want close the Smart Element, change the title to fermer"
          });
        }
      }
    );
  }
);

# `beforeDelete`

# Déclenchement

Le Smart Element va être supprimé.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
nextSmartElement : un objet Smart Element décrivant le Smart Element suivant.
customData : l'objet customClientData, cet objet peut-être modifié si besoin.

# Annulable

Oui. Dans ce cas, la suppression est annulée et rien n'est fait.

# Exemple

Cet exemple :

ajoute au ready du Smart Element (fonction addAnimalEvents) un écouteur sur l'événement beforeSave,
l'écouteur (fonction preventSaveAnimal) empêche la suppression du Smart Element si l'attribut zoo_title est différent de fermer.

Dans ce cas, il affiche un message pour avertir l'utilisateur qu'il doit changer la valeur.

controller.addEventListener("ready", function addAnimalEvents() {
  controller.addEventListener("beforeDelete", function preventDeleteAnimal(event, smartElement) {
    if (controller.getValue("zoo_title").value !== "fermer") {
      event.preventDefault();
      controller.showMessage({
        type: "error",
        message: "If you want to delete the Smart Element, change the title to fermer"
      });
    }
  });
});

# `beforeRender`

# Déclenchement

La procédure d'affichage du Smart Element commence.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.

# Annulable

Oui. Dans ce cas, l'affichage est annulé.

# Exemple

Cet exemple :

Enregistrement d'un écouteur sur une vue de consultation. Si le champ "note_title" est vide alors la représentation passe en mode formulaire.

window.ank.smartElement.globalController.registerFunction("myCustomHooks", scopedController => {
  scopedController.addEventListener("beforeRender", {}, function testTitle(event, smartElement) {
    let title = scopedController.getValue("note_title");
    if (!title || !title.value) {
      event.preventDefault();
      scopedController.fetchSmartElement({ initid: smartElement.initid, viewId: "!defaultEdition", revision: -1 });
    }
  });
});

# `beforeRestore`

# Déclenchement

Le Smart Element va être restauré.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.

# Annulable

Oui. Dans ce cas, la restauration est annulée et rien n'est fait.

# Exemple

Dans cet exemple, l'écouteur (fonction preventRestoreAnimal) demande une confirmation avant la restauration du Smart Element.

controller.addEventListener("beforeRestore", function preventRestoreAnimal(event, smartElement) {
  if (!confirm("Voulez-vous restaurer ce Smart Element ?")) {
    event.preventDefault();
    controller.showMessage({
      type: "info",
      message: "la restauration a été annulée"
    });
  }
});

# `beforeSave`

# Déclenchement

Le Smart Element va être sauvegardé. Cet événement est déclenché après la phase de [validation][ddui-ref:validateevent] et avant l'envoie de la requête de sauvegarde au serveur.

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
requestOptions : Cette option contient 2 fonctions getRequestData et setRequestData
customData : L'objet customData contient l'objet [customClientData](TODO REF), cet objet peut-être modifié si besoin. La fonction addCustomClientData n'est pas prise en compte durant cet événement. La modification n'est pas prise en compte si la fonction setRequestData est appelée.

La fonction getRequestData retourne un objet json. Cet objet est la donnée envoyée au serveur lors de la sauvegarde.

L'objet requestData a trois principales données :

document.properties
document.attributes
customClientData

Seules les données document.attributes et customClientData peuvent être modifiée. La modification de document.properties n'a aucun effet.

Extrait de données requestData (partielles):

{
  "document": {
    "properties": {
      "initid": 1256,
      "title": "My Awesome Document"
    },
    "attributes": {
      "my_title": {
        "value": "Hello world",
        "displayValue": "Hello world"
      },
      "my_level": {
        "value": 12,
        "displayValue": "12"
      }
    }
  },
  "customClientData": {
    "myKey": "Special Data"
  }
}

La fonction setRequestData prend en entrée, un objet JSON de la forme indiqué ci-dessus.

# Annulable

Oui. Dans ce cas, la sauvegarde est annulée et rien n'est fait.

# Exemple

# Interrompre la sauvegarde

ajoute au ready du Smart Element (fonction addAnimalEvents) un écouteur sur l'événement beforeSave,
l'écouteur (fonction preventSaveAnimal) empêche la sauvegarde du Smart Element si le Smart Field zoo_title est différent de fermer.

Dans ce cas, il affiche un message pour avertir l'utilisateur qu'il doit changer la valeur.

controller.addEventListener("ready", function addAnimalEvents() {
  controller.addEventListener("beforeSave", function preventSaveAnimal(event, smartElement) {
    if (controller.getValue("zoo_title").value !== "fermer") {
      event.preventDefault();
      controller.showMessage({
        type: "error",
        message: "If you want to save the Smart Element, change the title to fermer"
      });
    }
  });
});

# Enregistrer toutes les données À partir de la version 2021.01

Cet exemple montre comment utiliser les fonctions getRequestData et setRequestData pour enregistrer toutes les données du smart element, en plus de celles modifiées.

TIP

Les champs de type tab, frame et array n'étant pas pris en compte dans la sauvegarde, il est inutile de les ajouter dans les données de la requête de sauvegarde.

controller.addEventListener(
  "beforeSave",
  {
    name: "SaveAllFields.test"
  },
  function saveAllFields(event, smartElement, requestOptions, customData) {
    const systemData = requestOptions.getRequestData();

    controller.getSmartFields().forEach(attr => {
      if (!["tab", "frame", "array"].includes(attr.getProperties().type)) {
        // filter set fields
        systemData.document.attributes[attr.id] = attr.getValue("current");
      }
    });
    requestOptions.setRequestData(systemData);
  }
);

# `beforeValidate`

# Déclenchement

Le Smart Element va être sauvegardé. Cet événement est déclenché avant la phase de [validation][ddui-ref:validateevent].

# Éléments passés au callback

event : objet événement standard de jQuery,
currentSmartElement : un objet Smart Element décrivant le Smart Element courant.
requestOptions : Cette option contient 2 fonctions getRequestData et setRequestData
customData : L'objet customData contient l'objet [customClientData](TODO REF), cet objet peut-être modifié si besoin. La fonction addCustomClientData n'est pas prise en compte durant cet événement. La modification n'est pas prise en compte si la fonction setRequestData est appelée.

La fonction getRequestData retourne un objet json. Cet objet est la donnée envoyée au serveur lors de la sauvegarde.

L'objet requestData a trois principales données :

document.properties
document.attributes
customClientData

Seules les données document.attributes et customClientData peuvent être modifiée. La modification de document.properties n'a aucun effet.

Extrait de données requestData (partielles):

{
  "document": {
    "properties": {
      "initid": 1256,
      "title": "My Awesome Document"
    },
    "attributes": {
      "my_title": {
        "value": "Hello world",
        "displayValue": "Hello world"
      },
      "my_level": {
        "value": 12,
        "displayValue": "12"
      }
    }
  },
  "customClientData": {
    "myKey": "Special Data"
  }
}

La fonction setRequestData prend en entrée, un objet JSON de la forme indiqué ci-dessus.

# Annulable

Oui. Dans ce cas, la sauvegarde est annulée et rien n'est fait.

# Exemple

# Interrompre la sauvegarde

ajoute au ready du Smart Element (fonction addAnimalEvents) un écouteur sur l'événement beforeValidate,
l'écouteur (fonction preventSaveAnimal) empêche la sauvegarde du Smart Element si le Smart Field zoo_title est différent de fermer.

Dans ce cas, il affiche un message pour avertir l'utilisateur qu'il doit changer la valeur.

controller.addEventListener("ready", function addAnimalEvents() {
  controller.addEventListener("beforeValidate", function preventSaveAnimal(event, smartElement) {
    if (controller.getValue("zoo_title").value !== "fermer") {
      event.preventDefault();
      controller.showMessage({
        type: "error",
        message: "If you want to save the Smart Element, change the title to fermer"
      });
    }
  });
});

# `close`

# Déclenchement

Le Smart Element a été fermé (quelle que soit la cause : suppression, sauvegarde, changement de rendu, etc.).

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event]
currentSmart ElementObject : un objet Smart Element décrivant le Smart Element courant.
previousSmart ElementObject : un objet Smart Element décrivant le Smart Element précédent.

# Annulable

Non

# Exemple

Cet exemple supprime tous les événements de type animal. Il doit être utilisé conjointement à l'événement ready pour gérer l'enregistrement des événements.

controller.addEventListener("close", function(event, smartElement) {
  controller.removeEventListener(".animal");
});

# `displayError`

# Déclenchement

Un message d'erreur est présenté à l'utilisateur. Ce message peut avoir différentes causes (plus de réseau, contrainte non respectée, etc.)

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event]
smartElement : un objet Smart Element décrivant le Smart Element courant.
message : objet décrivant le message. L'objet contient les propriétés suivantes :
- title : titre du message,
- errorCode : code d'erreur du message.
- message : contenu textuel du message.
- htmlMessage (optionnel) : contenu html du message.

L'élément message peut-être modifié dans le callback de l'événement.

# Annulable

Oui. Dans ce cas le message n'est pas affiché.

# Exemple

Cet exemple modifie le message avant son affichage.

controller.addEventListener("displayError", function changeErrorMessage(event, smartElement, message) {
  if (message.errorCode === "offline") {
    message.message = "Pas de serveur";
  }
});

Cet exemple annule le message d'erreur et le remplace par une alert.

controller.addEventListener("displayError", function changeDisplayError(event, smartElement, message) {
  event.preventDefault();
  alert(message.message);
});

# `displayMessage`

# Déclenchement

Un message d'information est présenté à l'utilisateur.

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event]
smartElement : un objet Smart Element décrivant le Smart Element courant.
message : objet décrivant le message. L'objet contient les propriétés suivantes :
- title : titre du message,
- errorCode : code d'erreur du message.
- message : contenu textuel du message.
- htmlMessage (optionnel) : contenu html du message.

L'élément message peut-être modifié dans le callback de l'événement.

# Annulable

Oui. Dans ce cas le message n'est pas affiché.

# Exemple

Cet exemple annule le message et le remplace par une alert.

controller.addEventListener("displayMessage", function changeDisplayError(event, smartElement, message) {
  event.preventDefault();
  alert(message.message);
});

# `ready`

# Déclenchement

Le Smart Element est chargé, l'interface calculée et présentée à l'utilisateur.

Lorsqu'un écouteur pour cet événement est ajouté alors que le Smart Element est déjà chargé, cet écouteur est déclenché immédiatement.

Note : Lorsqu'un Smart Element a des onglets, cet événement est propagé avant l'affichage du premier onglet. En effet, l'affichage du contenu des onglets est réalisé lors de la sélection de ce dernier. Lorsque l'événement ready est capturé les widgets de Smart Fields présents dans les onglets ne sont pas encore affichés que ce soit sur le premier onglet ou les suivants. L'événement smartFieldReady d'un Smart Field onglet est propagé lorsque son contenu est affiché. Les événements smartFieldReady des onglets sont donc propagés après l'événement ready du Smart Element.

# Éléments passés au callback

event : [objet événement standard de jQuery][jquery.com:event]
smartElement : un objet Smart Element décrivant le Smart Element courant.

# Annulable

Non

# Exemple

Ajouter un message à chaque chargement de Smart Element.

controller.addEventListener("ready", function(event, smartElement, message) {
  controller.showMessage("I'm ready");
});

# Liste des événements déclenchés sur les Smart Fields

Les événements ci-dessous concernent un Smart Field spécifique du Smart Element.

TIP

Bien que concernant un Smart Field précis, les écouteurs de ces événements sont ajoutés au Smart Element au moyen de la méthode addEventListener.

Il est possible de ne déclencher le traitement que lorsque le Smart Element satisfait certaines conditions au moyen de la fonction définie dans l'option check du listener.

Il est possible de ne déclencher le traitement que lorsque le Smart Field satisfait certaines conditions au moyen de la fonction définie dans l'option smartFieldCheck du listener.

# `smartFieldAnchorClick`

# Déclenchement

L'utilisateur a cliqué sur une balise <a> dans un Smart Field de type htmltext.

WARNING

Si le lien est un lien interne de type événement, alors l'événement smartFieldAnchorClick n'est pas déclenché.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.
options : Un objet contenant les caractéristiques du lien : anchor : L'element <a>, anchorsConfig : la configuration définie par setAnchorsOptions pour le Smart Field en cours, composée de :
- target : la target dans laquelle ouvrir ce lien,
- modal : dans le cas ou target vaut _dialog, indique si la fenêtre doit êre modale,
- windowWidth : dans le cas ou target vaut _dialog, indique la largeur de la fenêtre à ouvrir,
- windowHeight : dans le cas ou target vaut _dialog, indique la hauteur de la fenêtre à ouvrir.

Il est possible de modifier directement la configuration dans anchorsConfig pour obtenir un comportement différent (dans ce cas, il ne faut pas annuler l'événement).

# Annulable

Oui. dans ce cas, le lien n'est pas ouvert.

# Exemple

Cet exemple ouvre les fenêtres Wikipedia dans une nouvelle fenêtre, et les autres dans des dialogues :

controller.addEventListener(
  "smartFieldAnchorClick",
  {
    name: "smartFieldAnchorClick",
    smartFieldCheck: function(smartField, smartElement) {
      return smartField.id === "es_decription";
    }
  },
  function smartFieldAnchorClick(event, smartElement, smartField, $el, options, index) {
    if (/wikipedia\./.test(options.anchor.hostname)) {
      options.anchorsConfig.target = "_blank";
    } else {
      options.anchorsConfig.target = "_dialog";
    }
  }
);

Cet exemple empêche l'ouverture des liens qui ne sont pas en https :

controller.addEventListener(
  "smartFieldAnchorClick",
  {
    name: "smartFieldAnchorClick",
    smartFieldCheck: function(smartField, samrtElement) {
      return smartField.id === "es_decription";
    }
  },
  function smartFieldAnchorClick(event, smartElement, smartField, $el, options, index) {
    if (options.anchor.scheme !== "https:") {
      event.preventDefault();
      alert("seuls les liens https peuvent être ouverts !");
    }
  }
);

# `smartFieldArrayChange`

# Déclenchement

Le Smart Field de type array a été modifié (ajout, suppression, drag & drop de lignes).

Cet événement ne concerne que les Smart Fields de type tableau (array).

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
type (string) : type de modification, parmi
- addLine : ajout d'une ligne
- moveLine : déplacement d'une ligne
- removeLine : suppression d'une ligne
options (int|objet) : entier indiquant le numéro de la ligne impacté dans le cas d'un ajout ou d'une suppression. Objet indiquant les index des deux lignes (fromLine, toLine) en cas de déplacement.

# Annulable

Non

# Exemple

Cet exemple affiche un message à l'utilisateur à chaque fois qu'un array est modifié.

controller.addEventListener(
  "smartFieldArrayChange",
  {
    name: "displayArrayModified"
  },
  function displayArrayModified(event, smartElement, smartField) {
    controller.showMessage("Array " + smartField.id + " has changed");
  }
);

# `smartFieldBeforeRender`

# Déclenchement

Le Smart Field va être rendu.

WARNING

Cet événement est déclenché uniquement au rendu des Smart Fields. Si ceux-ci sont déjà rendu lorsque l'écouteur est ajouté, l'événement n'est pas déclenché à nouveau.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.
options : (Object indexé) La clef "customTemplate" indique si c'est le ready est réalisé à l'issue d'un template personnalisé ou non.

Template personnalisé

Si la clef {{{attribute.htmlDefaultContent}}} est utilisée dans le template, le beforeRender du smart field sera déclenché deux fois, une avec l'option {customTemplate: true} pour le beforeRender du champ personalisé et un autre avec l'option {customTemplate: false} pour le beforeRender du champ original.

# Annulable

Oui. dans ce cas, le Smart Field n'est pas rendu.

# Exemple

Cet exemple annule le rendu d'un Smart Field précis : my_title.

controller.addEventListener(
  "smartFieldBeforeRender",
  {
    name: "myPreventTitle",
    smartFieldCheck: function isTitle(smartField, smartElement) {
      return smartField.id === "my_title";
    }
  },
  function smartFieldBeforeRender(event, smartElement, smartField, $el) {
    event.preventDefault();
  }
);

# `smartFieldDownloadFile`

# Déclenchement

Un téléchargement de fichier a été demandé (soit en cliquant sur le lien (hyperlien) en consultation ou sur le bouton de téléchargement en édition).

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.

# Annulable

Oui. Dans ce cas, le fichier n'est pas proposé à l'utilisateur.

# Exemple

Cet exemple n'autorise le téléchargement des fichiers que s'ils sont de type "image".

controller.addEventListener(
  "smartFieldDownloadFile",
  {
    name: "passToView"
  },
  function controlDownload(event, smartElement, smartField, options) {
    const index = options.index;
    let value = smartField.getValue();
    if (_.isArray(value)) {
      value = value[index];
    }

    if (value.mime.indexOf("image") === -1) {
      event.preventDefault();
    }
  }
);

# `smartFieldHelperResponse`

# Déclenchement

L'aide à la saisie associée au Smart Field a été déclenchée et le résultat de cette aide à la saisie est arrivée sur le client.

Cet événement est déclenché après la récupération de la liste des valeurs sur le serveur et permet de personnaliser la liste.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) : Un objet contenant les propriétés suivantes :
- data (array) : liste des valeurs à présenter à l'utilisateur. Le tableau a la forme suivante:
  pour chaque ligne un objet avec les propriétés suivantes :
  - title : élément affiché dans la liste déroulante
  - error: message d'erreur (optionnel)
  - values : objet contenant les valeurs à attribuer au Smart Element en cas de sélection de cette ligne. La clef représente l'identifiant logique du Smart Field auquel la valeur sera affectée, et le contenu est similaire à unsetValue, soit un objet avec les propriétés :
    - value : valeur à stocker
    - displayValue : valeur à présenter à l'utilisateur.

# Annulable

Oui. Dans ce cas l'aide à la saisie est annulée.

# Exemple

Cet exemple inverse l'ordre de retour de toutes les aides à la saisie.

controller.addEventListener(
  "smartFieldHelperResponse",
  {
    name: "invertResult"
  },
  function displayArrayModified(event, smartElement, smartField, options) {
    options.data.reverse();
  }
);

# `smartFieldHelperSearch`

# Déclenchement

L'aide à la saisie associée au Smart field a été déclenchée. Cet événement est déclenché avant la récupération de la liste des valeurs sur le serveur et permet de retourner une liste personnalisée.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) : Un objet contenant les propriétés suivantes :
- data : Object contenant les propriétés suivantes :
  - attributes : valeur des Smart Fields en cours, Objet indiquant pour chaque Smart Field sa valeur (value, displayValue). Les identifiants des Smart Fields sont les clefs de l'objet
  - filter : filtre en cours
- setResult (function) : Pour ne pas utiliser les valeurs fournies par le serveur, mais une liste personnalisée, il faut appeler cette méthode avec un tableau de résultats en paramètres. Le tableau doit être de la forme suivante : Pour chaque ligne un objet avec les propriétés suivantes :
  - title : élément affiché dans la liste déroulante
  - message : message (optionnel)
    - contentText : texte brut à afficher
    - contentHtml : texte formaté à afficher.
    - type : type de message : message (par défaut), warning, error.
  - values : objet contenant les valeurs à attribuer au Smart Element en cas de sélection de cette ligne.
    La clef représente l'identifiant logique du Smart Field auquel al valeur sera affectée, et le contenu doit être similaire à un setValue, soit un objet avec les propriétés :
    - value : valeur à stocker
    - displayValue : valeur à présenter à l'utilisateur

# Annulable

Oui. Dans ce cas la recherche des valeurs n'est pas effectuée sur le serveur et est à la charge du callback, qui doit alors appeler setResult.

# Exemple

Cet exemple intercepte l'aide à la saisie du Smart Field "de_proprietaire". Aucun appel au serveur n'est effectué. Un message est affiché avec un choix unique.

controller.addEventListener(
  "smartFieldHelperSearch",
  {
    name: "displayErrorMessage",
    smartFieldCheck: function(smartField, smartElement) {
      return smartField.id === "de_proprietaire";
    }
  },
  function displayArrayModified(event, smartElement, smartField, options) {
    event.preventDefault();
    options.setResult([
      {
        title: "",
        message: {
          contentText: "Hello from my autocomplete"
        }
      },
      {
        title: "Pas le choix : c'est le propriétaire",
        values: {
          de_proprietaire: {
            value: 1124,
            displayValue: "Le propriétaire"
          }
        }
      }
    ]);
  }
);

# `smartFieldHelperSelect`

# Déclenchement

L'aide à la saisie associée au Smart Field a été déclenchée, le résultat de cette aide à la saisie est arrivé sur le client et l'utilisateur a cliqué sur un résultat. Cet événement permet de personnaliser le comportement de la sélection d'une valeur de l'aide à la saisie.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) Un objet contenant la ligne sélectionnée. Un objet contenant les propriétés suivantes :
- title : élément affiché dans la liste déroulante
- error: message d'erreur (optionnel)
- values : objet contenant les valeurs à attribuer au Smart Element en cas de sélection de cette ligne. La clef représente l'identifiant logique du Smart Field auquel la valeur sera affectée, et le contenu est similaire à unsetValue, soit un objet avec les propriétés :
  - value : valeur à stocker
  - displayValue : valeur à présenter à l'utilisateur.

L'élément options peut-être modifié.

# Annulable

Oui. Dans ce cas l'aide à la saisie est annulée.

# Exemple

Cet exemple annule la sélection de toutes les aides à la saisie.

controller.addEventListener(
  "smartFieldHelperSelect",
  {
    name: "preventHelperSelect"
  },
  function preventHelperSelect(event, smartElement, smartField, options) {
    event.preventDefault();
  }
);

# `smartFieldEnumResponse` À partir de la version 2021.01

# Déclenchement

Cet évènement est déclenché seulement si c'est un smart field Enum de type serveur.

Cet événement est déclenché :

Après la récupération de la liste des valeurs sur le serveur
Après le changement du filtre du smart field Enum

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) : Un objet contenant les propriétés suivantes :
- data : Tableau d'énuméré : Pour chaque ligne un objet avec les propriétés suivantes :
  - key : élément affiché dans la liste déroulante
  - label : message (optionnel)
  - originalLabel: Libellé par défaut (optionnel)
  - parentKey: clé de l'énuméré parent (optionnel)
  - path: chemin vers l'énuméré (optionnel) (regarder comment est le format de la variable (si possible mettre un tableau de KEY))

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l'échec du changement de la liste d'énumérée.

# Annulable

Oui. Dans ce cas la recherche des valeurs n'est pas effectuée sur le serveur et est à la charge du callback, qui doit alors appeler setEnumList.

# Exemple

Cet exemple inverse l'ordre de la liste d'énuméré récupérer sur le serveur.

controller.addEventListener(
  "smartFieldEnumResponse",
  {
    name: "invertResult"
  },
  function reverseArrayList(event, smartElement, smartField, options) {
    options.data.reverse();
  }
);

Cet exemple vérifie si un élément de la liste retournée par le serveur est égal à "Paris" alors la liste est remplacé par une autre liste.

controller.addEventListener(
  "smartFieldEnumResponse",
  {
    name: "invertResult"
  },
  function reverseArrayList(event, smartElement, smartField, options) {
    options.data.forEach(function(element) {
      if (element.key === "Paris") {
        smartField.setEnumList([
          {
            key: "LOUVRE",
            label: "Musée du louvre"
          },
          {
            key: "MODERNE",
            label: "Musée d'Art Moderne"
          },
          {
            key: "POMPIDOU",
            label: "Le centre Pompidou"
          },
          {
            key: "BOURDELLE",
            label: "Musée Bourdelle"
          },
          {
            key: "ORSAY",
            label: "Musée d'Orsay"
          }
        ]);
      }
    });
  }
);

# `smartFieldEnumSearch` À partir de la version 2021.01

# Déclenchement

Cet événement est déclenché :

Avant la récupération de la liste des valeurs sur le serveur
Avant l'affichage du Smart Field Enum sur l'écran de l'utilisateur

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) : Un objet contenant les propriétés suivantes :
- data : Object contenant les propriétés suivantes :
  - request : Object contenant la requête au serveur :
    - type: type de requête,
    - url: url de la requête,
    - dataType: type de data,
    - data: données d'entrée

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l'échec du changement de la liste d'énumérée.

# Annulable

Oui. Dans ce cas la recherche des valeurs n'est pas effectuée sur le serveur et est à la charge du callback, qui doit alors appeler setEnumList.

# Exemple

Cet exemple montre le changement de la liste d'énuméré de la Smart Field Enum "country". Aucun appel au serveur n'est effectué.

controller.addEventListener(
  "smartFieldEnumSearch",
  {
    name: "changeEnumList",
    smartFieldCheck: function(smartField, smartElement) {
      return smartField.id === "country";
    }
  },
  function changeArrayList(event, smartElement, smartField, options) {
    event.preventDefault();
    smartField.setEnumList([
      {
        key: "FR",
        label: "France"
      },
      {
        key: "GB",
        label: "Royaume-uni"
      },
      {
        key: "RU",
        label: "Russie"
      }
    ]);
  }
);

# `smartFieldEnumSelect` À partir de la version 2021.01

# Déclenchement

Cet événement est déclenché :

Après la sélection d'un élément dans la liste d'énuméré

Cet événement permet de personnaliser le comportement de la sélection d'une valeur du filtre.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
options (objet) Un objet contenant la ligne sélectionnée. Un objet contenant les propriétés suivantes :
- data : Object de data sur l'énuméré selection :
  - key : élément affiché dans la liste déroulante
  - label : message (optionnel)
  - originalLabel: Libellé par défaut (optionnel)
  - longLabel: Nom du label avec le nom des label parents (optionnel)
  - parentKey: clé de l'énuméré parent (optionnel)
  - path: chemin vers l'énuméré (optionnel) (regarder comment est le format de la variable (si possible mettre un tableau de KEY))
  - disabled: (Permette de disable chaque élément)

# Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l'échec du changement de la liste d'énumérée.

# Annulable

Oui. Dans ce cas l'ancienne valeur avant la sélection est restaurée.

# Exemple

Cet exemple annule la sélection de toutes les aides à la saisie.

controller.addEventListener(
  "smartFieldEnumSelect",
  {
    name: "preventEnumSelect"
  },
  function preventEnumSelect(event, smartElement, smartField, options) {
    event.preventDefault();
  }
);

# `smartFieldReady`

# Déclenchement

Le Smart Field vient d'être rendu et est disponible pour les utilisateurs.

Lorsqu'un écouteur est ajouté pour cet événement alors que le Smart Field est déjà rendu, l'écouteur est déclenché immédiatement.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.
options : (Object indexé) La clef "customTemplate" indique si c'est le ready est réalisé à l'issue d'un template personnalisé ou non.

Template personnalisé

Si la clef {{{attribute.htmlDefaultContent}}} est utilisée dans le template, le ready du smart field sera déclenché deux fois, une avec l'option {customTemplate: true} pour le ready du champ personalisé et un autre avec l'option {customTemplate: false} pour le ready du champ original.

# Annulable

Non

# Exemple

Cet exemple passe en rouge le background du Smart Field zoo_title.

controller.addEventListener(
  "smartFieldReady",
  {
    name: "doubleCheck",
    smartFieldCheck: function isTitle(smartField, smartElement) {
      return smartField.id === "zoo_title";
    }
  },
  function changeDisplayError(event, smartElement, smartField, $el) {
    $el.css("background-color", "red");
  }
);

Cet exemple ajoute un tooltip qui affiche au survol le nom logique du SMart Field sur tous les Smart Fields.

controller.addEventListener(
  "smartFieldReady",
  {
    name: "displayId"
  },
  function changeDisplayError(event, smartElement, smartField, $el) {
    $el.tooltip({
      placement: "top",
      title: function vDocumentTooltipTitle() {
        return smartField.id;
      }
    });
  }
);

# `smartFieldChange`

# Déclenchement

Le Smart Field a été modifié (soit via l'interface, soit via du code).

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
values : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- current : valeur après la modification
- previous : valeur avant la modification
- initial : valeur initiale (telle que récupérée au chargement du Smart Element).
index : Contient le numéro de la rangée de la valeur modifiée dans le cas des tableaux. (La première rangée a l'index 0). Égale à -1 si la valeur n'est pas dans un tableau ou si plusieurs valeurs ont été modifiées.

# Annulable

Non

# Exemple

Cet exemple affiche un message à l'utilisateur à chaque fois qu'un Smart Field est modifié.

controller.addEventListener(
  "smartFieldChange",
  {
    name: "displayChange"
  },
  function displayChange(event, smartElement, smartField, values) {
    controller.showMessage("Smart Field " + smartField.id + " has changed");
  }
);

# `smartFieldUploadFile`

# Déclenchement

Un téléversement de fichier a été demandé en cliquant sur un Smart Field de type file ou image en édition.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.
options : un objet contenant les propriétés suivantes :
- file : l'objet file qui sera téléversé.
- hasUploadingFiles : (bool) indique s'il y a des téléversements en cours. Le téléversement du fichier courant n'est pas encore en cours. Il vaut true si un autre fichier est en cours de téléversement.

# Annulable

Oui. Dans ce cas, le fichier n'est pas téléversé, le Smart Field n'est pas modifié.

# Exemple

Cet exemple n'autorise que le téléversement des fichiers de type image.

controller.addEventListener("smartFieldUploadFile", function controlUpload(
  event,
  smartElement,
  smartField,
  $el,
  index,
  options
) {
  if (options.file.type.substr(0, 5) !== "image") {
    event.preventDefault();
    alert("seules les images sont autorisées !");
  }
});

# `smartFieldUploadFileDone`

# Déclenchement

Un téléversement qui a été demandé vient d'aboutir.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
index : Le numéro de ligne si le Smart Field est dans un tableau, -1 sinon.

options : un objet contenant les propriétés suivantes :

file : la valeur du Smart Field fichier. Par exemple :

{
  creationDate: "2017-07-04 16:37:23",
  displayValue: "NfGTsK4.jpg",
  fileName: "NfGTsK4.jpg",
  icon: "api/v2/images/assets/sizes/20/mime-image.png",
  size: "50187",
  thumbnail: "api/v2/images/recorded/sizes/48/2673880702159532007.png",
  url: "api/v2/files/recorded/temporary/2673880702159532007.jpg",
  value: "image/jpeg|2673880702159532007|NfGTsK4.jpg"
}

hasUploadingFiles : (bool) indique s'il y a des téléversements en cours. Le téléversement du fichier courant est fini. Il vaut true si un autre fichier est en cours de téléversement.

# Annulable

Non.

# Exemple

Cet exemple affiche un message lorsqu'il n'y a plus de téléversement en cours.

controller.addEventListener(
  "smartFieldUploadFileDone",
  {
    name: "my.uploaddone"
  },
  function(event, smartElement, smartField) {
    if (!smartElement.hasUploadingFiles)
      controller.showMessage({
        message: "All uploads are done",
        type: "success"
      });
  }
);

# `smartFieldBeforeTabSelect`

# Déclenchement

L'affichage d'un onglet est demandé.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field (onglet sélectionné) courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.

# Annulable

Oui. Dans ce cas, l'onglet n'est pas sélectionné. Son contenu n'est pas généré si c'est la première fois qu'il est sélectionné. Son contenu n'est pas affiché.

# Exemple

Cet exemple empêche la sélection de l'onglet my_t_tab_date.

controller.addEventListener(
  "smartFieldBeforeTabSelect",
  {
    name: "NoSelectTabDate",
    smartFieldCheck: function(smartField) {
      return smartField.id === "my_t_tab_date";
    }
  },
  function selectIfNotDate(event, smartElement, smartField, $el) {
    // Onglet affiché en rouge
    $el.css("background-color", "red");

    // Message d'information
    controller.showMessage({
      type: "warning",
      htmlMessage: "Tab <b>" + smartField.getLabel() + "</b> cannot be selected"
    });

    // Ordre d'annulation de la sélection
    event.preventDefault();
  }
);

# `smartFieldAfterTabSelect`

# Déclenchement

L'affichage d'un onglet a été effectué. Lorsque le contenu de l'onglet est affiché.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field (onglet sélectionné) courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.

# Annulable

Non

# Exemple

Cet exemple affiche en jaune les onglets déjà sélectionnés.

controller.addEventListener("smartFieldAfterTabSelect", function selectIfNotData(event, smartElement, smartField, $el) {
  // Onglet affiché en jaune
  $el.css("background-color", "yellow");

  // Message d'information
  controller.showMessage({
    type: "info",
    htmlMessage: "Tab <b>" + smartField.getLabel() + "</b> is now selected"
  });
});

# `smartFieldTabChange`

# Déclenchement

Lorsqu'une erreur sur un Smart Field contenu dans l'onglet a été déclenchée. Lorsque le libellé du label a été modifié.

Cet événement peut être déclenché plusieurs fois si plusieurs Smart Fields contenus dans cet onglet sont en erreur.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
$el : objet jQuery contenant le noeud DOM sur lequel le Smart Field est rendu.
info: Donnée supplémentaire. Contient un champ error si une contrainte a été déclenchée sur un des ses Smart Fields.

# Annulable

Non

# Exemple

Cet exemple affiche une notification en cas d'erreur se rapportant à un onglet.

controller.addEventListener(
  "smartFieldTabChange",
  {
    name: "ChangeTab.test"
  },
  function showTabError(event, smartElement, smartField, $el, info) {
    if (info.error) {
      controller.showMessage({
        type: "error",
        htmlMessage: "Tab <b>" + smartField.getLabel() + "</b> has an error",
        message: info.error
      });
    }
  }
);

# `smartFieldConstraintCheck`

# Déclenchement

Les contraintes du Smart Field sont évaluées.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
smartField : un objet Smart Field décrivant le Smart Field courant.
values : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- current : valeur après la modification
- previous : valeur avant la modification
- initial : valeur initiale (telle que récupérée au chargement du Smart Element).

# Annulable

Non

# Exemple

Cet exemple affiche un message à l'utilisateur à chaque fois qu'une contrainte sur un Smart Field est évaluée.

controller.addEventListener(
  "smartFieldConstraintCheck",
  {
    name: "displayConstraint"
  },
  function displayConstraint(event, smartElement, smartField, values) {
    controller.showMessage("Smart Field constraint for " + smartField.id + " is evaluated");
  }
);

L'option addCreateDocumentButton pour les Smart Fields de type docid déclenche les événements suivants.

smartFieldCreateDialogSmartElementReady : lorsque le formulaire est affiché
smartFieldCreateDialogSmartElementBeforeSetFormValues : avant l'affectation des valeurs dans le formulaire
smartFieldCreateDialogSmartElementBeforeSetTargetValue : avant l'affectation de l'attribut dans le Smart Element principal
smartFieldCreateDialogSmartElementBeforeClose : avant la fermeture de la fenêtre de dialogue
smartFieldCreateDialogSmartElementBeforeDestroy : avant la destruction de la fenêtre de dialogue

# smartFieldCreateDialogSmartElementReady

# Déclenchement

Déclenché lorsque le formulaire est prêt pour être affiché. Il est déclenché sur le "ready" du formulaire.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element principal.
smartField : un objet Smart Field décrivant le Smart Field courant.
options : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- index : Index de la relation en cas de Smart Field multiple. Est égale à "-1" si cela ne concerne pas un Smart Field multiple
- dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow)
- dialogDocument : Widget du Smart Element contenu dans la fenêtre de dialogue

# Annulable

Oui. L'annulation annule la modification des menus ainsi que le déclenchement des affectations de valeur dans le formulaire. L'événement smartFieldCreateDialogSmartElementBeforeSetFormValues ne sera pas déclenché.

# Exemple

# smartFieldCreateDialogSmartElementBeforeSetFormValues

# Déclenchement

Déclenché lorsque le formulaire de création est prêt à recevoir les données à modifier. Il n'est pas déclenché pour le formulaire de modification.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element principal.
smartField : un objet Smart Field décrivant le Smart Field courant.
options : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- getFormValues() : fonction qui retourne l'objet
- setFormvalues(formValues) : enregistre les valeurs dans le formulaire
- index : Index de la relation en cas de Smart Field multiple. Est égale à "-1" si cela ne concerne pas un Smart Field multiple
- dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow)
- dialogDocument : Widget du Smart Element contenu dans la fenêtre de dialogue

# Annulable

Oui. L'annulation indique que les valeurs définies dans l'option formValue ne seront pas prises en compte. Le formulaire est affiché sans ces valeurs spécifiques.

# Exemple

Ajout de 2 nouvelle valeurs dans le formulaire de création :

controller.addEventListener(
  "smartFieldCreateDialogSmartElementBeforeSetFormValues",
  {
    name: "createChild.animal"
  },
  function(event, smartElement, smartField, options) {
    const formValues = options.getFormValues();
    formValues.an_tatouage = { value: "007" };
    formValues.an_sexe = { value: "F" };
    options.setFormValues(formValues);

    // Affichage d'un message dans le formulaire de création
    controller.showMessage("Création d'un nouvel animal");
  }
);

# smartFieldCreateDialogSmartElementBeforeSetTargetValue

# Déclenchement

Déclenché lorsque la valeur du Smart Field a été affectée en cliquant sur le bouton d'enregistrement du Smart Element de la fenêtre de dialogue.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element principal.
smartField : un objet Smart Field décrivant le Smart Field courant.
options : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- index : Index de la relation en cas de Smart Field multiple. Est égale à "-1" si cela ne concerne pas un Smart Field multiple
- dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow)
- dialogDocument : Widget du Smart Element contenu dans la fenêtre de dialogue
- attributeValue : Valeur de la relation à insérer dans le Smart Field. Cette valeur est un objet contenant les champs suivants :
  - displayValue : Titre du Smart Element
  - familyRelation : Nom logique de la Smart Structure
  - icon : Url de l'icône du Smart Element
  - value : Identifiant numérique du Smart Element

# Annulable

Oui. Le formulaire est enregistré, mais la mise à jour du Smart Field n'est pas effectuée. La fenêtre de dialogue n'est pas fermée.

# Exemple

Afficher un message indiquant la sauvegarde.

controller.addEventListener(
  "smartFieldCreateDialogSmartElementBeforeSetTargetValue",
  {
    name: "setChild.animal"
  },
  function(event, smartElement, smartField, options) {
    controller.showMessage("Valeur [" + options.attributeValue.displayValue + "] en cours d'affectation");
  }
);

# smartFieldCreateDialogSmartElementBeforeClose

# Déclenchement

Déclenché avant la fermeture de la fenêtre. Soit lorsque l'utilisateur a demandé la mise à jour, soit lorsque l'utilisateur a demandé la fermeture sans enregistrer.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element principal.
smartField : un objet Smart Field décrivant le Smart Field courant.
options : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- index : Index de la relation en cas de Smart Field multiple. Est égale à "-1" si cela ne concerne pas un Smart Field multiple
- dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow)
- dialogDocument : Widget du Smart Element contenu dans la fenêtre de dialogue
- attributeValue : Valeur de la relation à insérer dans le Smart Field. Cette valeur est un objet contenant les champs suivants :
  - displayValue : Titre du Smart Element
  - familyRelation : Nom logique de la Smart Structure
  - icon : Url de l'icône du Smart Element
  - value : Identifiant numérique du Smart Element

# Annulable

Oui. L'annulation annule la fermeture de la fenêtre de dialogue. Cela annule aussi la demande de confirmation de fermeture lorsque le Smart Element n'a pas été enregistré.

# Exemple

Bloquer la fermeture automatique de la fenêtre après l'enregistrement.

controller.addEventListener("smartFieldCreateDialogSmartElementBeforeClose", function(
  event,
  smartElement,
  smartField,
  options
) {
  if (options.attributeValue) {
    // En cas d'enregistrement
    event.preventDefault();
    controller.showMessage("Valeur enregistrée");
  }
});

# smartFieldCreateDialogSmartElementBeforeDestroy

# Déclenchement

Déclenché lorsque la fenêtre de dialogue est détruite (après la fermeture).

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element principal.
smartField : un objet Smart Field décrivant le Smart Field courant.
options : Un objet contenant les valeurs du Smart Field en cours. Il contient les propriétés suivantes :
- getFormValues() : fonction qui retourne l'objet
- setFormvalues(formValues) : enregistre les valeurs dans le formulaire
- index : Index de la relation en cas de Smart Field multiple. Est égale à "-1" si cela ne concerne pas un Smart Field multiple
- dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow)
- dialogDocument : Widget du Smart Element contenu dans la fenêtre de dialogue

# Annulable

Oui. Cela empêche la destruction de la fenêtre et du formulaire.

# Exemple

Affichage d'un message après la fermeture de la fenêtre de dialogue.

controller.addEventListener("smartFieldCreateDialogSmartElementBeforeDestroy", function displayArrayModified(
  event,
  smartElement,
  smartField,
  options
) {
  controller.showMessage("Fenêtre [" + controller.getProperty("title") + "] a été fermée");
});

Les événements ci-dessous concernent le changement d'état du Smart Element. Ils permettent de piloter la fenêtre de changement d'état.

La fenêtre de changement d'état est représentée dans les événements par l'objet interne correspondant.

WARNING

Les écouteurs de ces événements doivent être ajoutés au widget Smart Element.

# `beforeDisplayTransition`

# Déclenchement

Cet événement est déclenché avant l'affichage de la fenêtre de changement d'état.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.

# Annulable

Oui. Dans ce cas, la demande de transition est annulée.

# Exemple

Cet exemple interdit les changement d'état administrateur (sans transition).

controller.addEventListener("beforeDisplayTransition", function preventTransition(
  event,
  smartElement,
  transitionObject
) {
  if (!transitionObject.transition) {
    event.preventDefault();
    controller.showMessage({
      type: "error",
      message: "You cannot do change state without transition"
    });
  }
});

# `afterDisplayTransition`

# Déclenchement

Cet événement est déclenché après l'affichage de la fenêtre.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.

# Annulable

Non.

# Exemple

Cet exemple affiche un message de confirmation au clic sur le bouton de validation et empêche l'action associée au bouton ok de se lancer si l'utilisateur ne confirme pas.

controller.addEventListener(
  "afterDisplayTransition",
  {
    name: "afterDisplayTransition.changeState"
  },
  function afterDisplayTransition(event, smartElement, transitionObject) {
    transitionObject.$el.find(".dcpTransition-button-ok").on("click", function displayConfirm(event) {
      if (!confirm("Are you sure ?")) {
        transitionObject.close();
        event.preventDefault();
        return false;
      }
    });
  }
);

# `beforeTransitionClose`

# Déclenchement

Cet événement est déclenché avant la fermeture de la fenêtre lorsque l'utilisateur a cliqué sur "fermer" ou s'il a confirmé la transition.

Dans le cas d'une transition confirmé, la requête a déjà été exécutée.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.

# Annulable

Oui. La fenêtre reste ouverte.

# Exemple

Cet exemple affiche un message de confirmation au clic sur le bouton d'annulation et annule la fermeture si ce n'est pas confirmé.

controller.addEventListener(
  "beforeTransitionClose",
  {
    name: "beforeTransitionClose.changeState"
  },
  function beforeTransitionClose(event, smartElement, transitionObject) {
    if (!confirm("Are you sure ?")) {
      event.preventDefault();
    }
  }
);

# `beforeTransition`

# Déclenchement

Cet événement est déclenché avant l'envoi de l'ordre de changement d'étape.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.

# Annulable

Oui. La fenêtre reste ouverte mais la requête n'est pas envoyée.

# Exemple

Cet exemple affiche un message de confirmation au clic sur le bouton de confirmation et laisse la fenêtre ouverte si ce n'est pas confirmé.

controller.addEventListener(
  "beforeTransition",
  {
    name: "beforeTransition.changeState"
  },
  function beforeTransition(event, smartElement, transition) {
    if (!confirm("Are you sure ?")) {
      event.preventDefault();
    }
  }
);

# `failTransition`

# Déclenchement

Cet événement est déclenché après le retour de la demande de changement d'état si celle-ci échoue.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.
message : objet décrivant le message d'errer. L'objet contient les propriétés suivantes :
- title : titre du message
- errorCode : code d'erreur du message.
- message : contenu textuel du message
- htmlMessage (optionnel) : contenu html du message.

# Annulable

Non.

# Exemple

Cet exemple ferme la fenêtre de changement d'état et ouvre le Smart Element en édition en affichant l'erreur à l'utilisateur si le changement d'état échoue (uniquement dans le cas d'une erreur autre que réseau).

controller.addEventListener(
  "failTransition",
  {
    name: "failTransition"
  },
  function failTransition(event, smartElement, transitionObject, message) {
    if (message.errorCode !== "offline") {
      transitionObject.close();
      controller.showMessage({
        type: "error",
        title: message.title || "erreur",
        message: message.htmlMessage || message.message
      });
      controller.fetchDocument({
        initid: smartElement.initid,
        viewId: "!defaultEdition"
      });
    }
  }
);

# `successTransition`

# Déclenchement

Cet événement est déclenché après le retour de la demande de changement d'état si celle-ci a réussi.

# Éléments passés au callback

event : objet événement standard de jQuery,
smartElement : un objet Smart Element décrivant le Smart Element courant.
transitionObject : objet transition décrivant la fenêtre de transition.

# Annulable

Non.

# Exemple

Cet exemple affiche un message à l'utilisateur en cas de transition effectuée avec succès.

controller.addEventListener(
  "successTransition",
  {
    name: "successTransition"
  },
  function successTransition(event, smartElement, transitionObject) {
    controller.showMessage({
      type: "info",
      message: "Well done !"
    });
  }
);

← Contrôleur global Rendu de transition →

# Contrôleur restreint

# Objets internes du contrôleur

# Smart Element

# Smart Field

# Propriétés

# Méthodes

# Types de Smart Field

# Énuméré

# Fenêtre de transition

# Propriétés

# Méthodes

# Menu

# Propriétés

# Méthodes

# getProperties

# Arguments

# Retour

# Exception

# disable

# Arguments

# Retour

# Exception

# enable

# Arguments

# Retour

# Exception

# hide

# Arguments

# Retour

# Exception

# setLabel

# Arguments

# Retour

# Exception

# setHtmlLabel

# Arguments

# Retour

# Exception

# setUrl

# Arguments

# Retour

# Exception

# setCssClass

# Arguments

# Retour

# Exception

# Exemple

# setIconUrl

# Arguments

# Retour

# Exception

# redraw

# Arguments

# Retour

# Exception

# Carte des événements du contrôleur restreint

# Ordonnancement des événements

# Clic sur un élément du Smart Element (docid, élément de menu)

# Modification

# Cas du Smart Field de type docid avec option de création

# Sauvegarde

# Suppression

# Restauration

# Passage de transition

# Autres

# Affichage de message

# Changement du label d'un onglet ou contenu d'un onglet en erreur

# Méthodes du contrôleur restreint de Smart Element

# addEventListener

# Arguments

# Retour

# Exceptions

# Exemple

# addConstraint

# Arguments

# Retour

# Exceptions

# Exemple

# addCustomClientData

# Arguments

# `getProperties`

# `disable`

# `enable`

# `hide`

# `setLabel`

# `setHtmlLabel`

# `setUrl`

# `setCssClass`

# `setIconUrl`

# `redraw`

# Clic sur un élément du Smart Element (`docid`, élément de menu)

# Cas du Smart Field de type `docid` avec option de création

# `addEventListener`

# `addConstraint`

# `addCustomClientData`

# `addCustomClientData(value: Object)`

# `addCustomClientData(check: function, value: Object)`

# `addCustomClientData(check: Object, value: Object)`

# `appendArrayRow`

# `changeStateSmartElement`

# `cleanSmartFieldErrorMessage`

# `deleteSmartElement`

# `drawTab`

# `fetchSmartElement`

# `getCustomServerData`

# `getProperties`

# `getProperty`

# `getSmartFields`

# `getSmartField`

# `getValues`

# `getValue`