5.3.2 Méthodes de manipulation réseau

5.3.2.1 saveDocument

Cette méthode permet de sauver le document en cours. La bannière de chargement est affichée et le document est ensuite re-présenté en édition 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 document ne débute que lorsque l'ensemble des téléversements en cours de fichiers ont abouti. La propriété du document hasUploadingFiles indique s'il y a des téléversement en cours.

5.3.2.1.1 Arguments

options
Un objet contenant les propriétés suivantes : success: déprécié : fonction : cette fonction est appelée après une sauvegarde réussie, error : déprécié : fonction : cette fonction est appelée après une sauvegarde échouée, customClientData (valeur par défaut ``) : objet : cette objet de configuration est transféré au serveur à la place des données par défaut (voir customClientData).

5.3.2.1.2 Retour

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

En cas de réussite la structure de l'argument de la fonction de réussite est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document précédent la sauvegarde.
  • nextDocument: un objet document décrivant le document sauvegardé.

En cas d'échec, la structure de l'argument de la fonction d'échec est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: null (pas de document sauvegardé).
  • errorMessage : Message d'erreur composé de 2 parties :
    • code : code erreur
    • contentText : message d'erreur

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

5.3.2.1.3 Exception

Pas d'exception

5.3.2.1.4 Exemple

window.dcp.document.documentController("saveDocument");

5.3.2.2 deleteDocument

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

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

5.3.2.2.1 Arguments

options
Un objet contenant les propriétés suivantes : success déprécié : fonction : cette fonction est appelée après une suppression réussie, error déprécié : fonction : cette fonction est appelée après une suppression échouée, customClientData (valeur par défaut ``) : objet : cette objet de configuration est transféré au serveur à la place des données par défaut (voir customClientData).

5.3.2.2.2 Retour

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

En cas de réussite la structure de l'argument de la fonction de réussite est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document précédent.
  • nextDocument: un objet document décrivant le document supprimé.

En cas d'échec, la structure de l'argument de la fonction d'échec est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: null (pas de document suivant).
  • errorMessage : Message d'erreur composé de 2 parties :
    • code : code erreur
    • contentText : message d'erreur

Si la sauvegarde est annulée par lors de l'événement beforeDelete alors la promise passe en échec.

5.3.2.2.3 Exception

Pas d'exception

5.3.2.2.4 Exemple

window.dcp.document.documentController("deleteDocument");

5.3.2.3 restoreDocument

Cette méthode permet de restaurer un document supprimé.

5.3.2.3.1 Arguments

options
Un objet contenant les propriétés suivantes : success déprécié : fonction : cette fonction est appelée après une suppression réussie, error déprécié : fonction : cette fonction est appelée après une suppression échouée, customClientData (valeur par défaut) : objet : cette objet de configuration est transféré au serveur à la place des données par défaut (voir customClientData).

5.3.2.3.2 Retour

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

En cas de réussite la structure de l'argument de la fonction de réussite est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document précédent.
  • nextDocument: un objet document décrivant le document restauré.

En cas d'échec, la structure de l'argument de la fonction d'échec est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: null (pas de document suivant).
  • errorMessage : Message d'erreur composé de 2 parties :
    • code : code erreur
    • contentText : message d'erreur

5.3.2.3.3 Exception

Pas d'exception

5.3.2.3.4 Exemple

window.dcp.document.documentController("restoreDocument");

5.3.2.4 fetchDocument

Cette méthode permet de charger un autre document, 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.

5.3.2.4.1 Arguments

documentOptions
Un objet contenant les propriétés suivantes : initid obligatoire : identifiant du document à charger revision (optionnel) : numéro de révision (-1 par défaut pour indiquer la dernière révision applicable), viewId (optionnel) : indique le rendu demandé. Les rendus par défaut sont disponibles par les mots-clés suivants : !defaultConsultation (par défaut) : indique le rendu par défaut de consultation, !defaultEdition : indique le rendu par défaut de modification. customClientData (valeur par défaut ``) : objet : cet objet de configuration est transféré au serveur à la place des customClientData
(voir customClientData).
fetchOptions
Options supplémentaires : force : : booléen : Si l'option est à true, aucune confirmation n'est demandée à l'utilisateur dans le cas où le document à remplacer est modifié et non enregistré. Par défaut, la valeur est false. success Deprecié : fonction : cette fonction est appelée après une sauvegarde réussie, error Deprecié : fonction : cette fonction est appelée après une sauvegarde échouée,

5.3.2.4.2 Retour

Retourne un objet Promise. Cet objet permet de contrôler la réussite ou l'échec de l'affichage du document.

En cas de réussite la structure de l'argument de la fonction de réussite est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: un objet document décrivant le document suivant.

En cas d'échec, la structure de l'argument de la fonction d'échec est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: null (pas de document suivant).
  • errorMessage : Message d'erreur composé de 2 parties :
    • code : code erreur
    • contentText : message d'erreur

Si l'utilisateur à choisi de rester sur le formulaire dans le cas d'un document non enregistré, le code erreur sera : USERCANCEL.

Si la sauvegarde est annulée par lors de l'événement beforeClose alors la promise passe en échec.

5.3.2.4.3 Exception

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

5.3.2.4.4 Exemple

Affichage d'un document depuis le contrôleur interne du document :

window.dcp.document.documentController("fetchDocument", {"initid" : 1232});

Log du chargement du document sur la console du navigateur

window.dcp.document.documentController("fetchDocument",
    { initid: 1234 },
    { force: false  }
 ).then(function (data) {
    console.log("Document "+ data.nextDocument.title+ " has been loaded");
 }).catch(function (data) {
    console.warn(data.errorMessage.contentText);
 });

5.3.2.5 reinitDocument

Cette méthode permet de recharger le document.

Le comportement est identique à la méthode fetchDocument.

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 document courant.

5.3.2.5.1 Arguments

  • documentOptions : Un objet contenant les propriétés suivantes :

    • initid : (facultatif) identifiant du document à charger
    • revision : (optionnel) numéro de révision (-1 par défaut pour indiquer la dernière révision applicable)
    • viewId : (optionnel) indique le rendu demandé.

  • Les rendus par défaut sont disponibles par les mots-clés suivants :

  • !defaultConsultation : (par défaut) indique le rendu par défaut de consultation

  • !defaultEdition : indique le rendu par défaut de modification.

5.3.2.5.2 Retour

Retourne la donnée , null si pas de donnée.

5.3.2.5.3 Exception

Aucune.

5.3.2.5.4 Exemple

window.dcp.document.documentController("reinitDocument")
.then(function (data) {
  data.element.documentController("showMessage", {
      type: "success",
      message: "Document " + data.nextDocument.title + " has been reinisialized"
  });
}).catch(function (data) {
    data.element.documentController("showMessage", {
        type: "error",
        message: data.errorMessage.contentText
    });
});

5.3.2.6 changeStateDocument

Cette méthode permet de demander le passage d'une transition pour effectuer un changement d'état pour le document 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 si il n'y a ni ask, ni commentaire demande, 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 document est rechargé (les deuxième et troisième paramètres sont donc similaires à ceux du reinitDocument).

5.3.2.6.1 Arguments

parameters : Paramètres de la transition
Un objet contenant les propriétés suivantes : nextState obligatoire : nouvel état du document transition obligatoire : identifiant de la transition à effectuer unattended booléen : la fenêtre de changement d'état n'est pas affichée et les ask ne sont pas affichés, si jamais des ask sont obligatoires et non valués le changement d'état échoue values (objet) : ensemble des valeurs du ask
documentOptions : Paramétrage de l'affichage du widget document après la transition,
Un objet contenant les propriétés suivantes : initid (par défaut : initid en cours) : identifiant du document revision (par défaut : révision en cours) : numéro de révision (-1 pour indiquer la dernière révision applicable) viewId (par défaut : vue en cours) : indique le rendu demandé. Les rendus par défaut sont disponibles par les mots-clés suivants : !defaultConsultation : indique le rendu par défaut de consultation, !defaultEdition : indique le rendu par défaut de modification. customClientData (valeur par défaut ``) : objet : cet objet de configuration est transféré au serveur à la place des customClientData (voir customClientData).
transitionOption : fonction appelée en cas de transition réussie après la réinitialisation du document
objet : success déprécié : fonction : cette fonction est appelée après une transaction réussie, error déprécié : fonction : cette fonction est appelée après une transaction échouée

5.3.2.6.2 Retour

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

En cas de réussite la structure de l'argument de la fonction de réussite est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: un objet document décrivant le document suivant.

En cas d'échec, la structure de l'argument de la fonction d'échec est :

  • element : Élément DOM (jquery) du widget de document
  • currentDocument: un objet document décrivant le document courant.
  • nextDocument: null (pas de document suivant).
  • errorMessage : Message d'erreur composé de 2 parties :
    • code : code erreur
    • contentText : message d'erreur

5.3.2.6.3 Exception

Si l'argument n'est pas un objet ou si le nextState et la transition ne sont pas valués.

5.3.2.6.4 Exemple

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

window.dcp.document.documentController("changeStateDocument",
  {
    "nextState": "zoo_transmited",
    "transition" : "zoo_Ttransmited"}
);

Demande de changement d'état sans ask

window.dcp.document.documentController("changeStateDocument",
{
    "nextState": "zoo_transmited",
    "transition" : "zoo_Ttransmited",
    "unattended" : true});

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

window.dcp.document.documentController("changeStateDocument",
   {
    "nextState": "zoo_transmited",
    "transition" : "zoo_Ttransmited",
    "unattended" : true
   },
   {
    "viewId" : "!defaultEdition"
   });

5.3.2.7 getCustomServerData

Cette méthode permet de récupérer les données complémentaires émises par la vue.

5.3.2.7.1 Arguments

Aucun.

5.3.2.7.2 Retour

Retourne la donnée ; null si pas de donnée.

5.3.2.7.3 Exception

Aucune.

5.3.2.7.4 Exemple

Récupération de la donnée complémentaire

window.dcp.document.documentController("getServerCustomData");

5.3.2.8 addCustomClientData

Cette méthode permet d'enregistrer des données complémentaires transmises lors de la sauvegarde, suppression, rechargement du document.

La donnée complémentaire est effacée lorsque la commande réussit (avant que les callback soit appelés).

Ces données sont transmises au rendu de document via la méthode setCustomClientData.

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".

5.3.2.8.1 Arguments

Trois types de passage d'arguments sont possibles :

5.3.2.8.1.1 addCustomClientData(data)

data (objet)
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.

5.3.2.8.1.2 addCustomClientData(contrainte, data)

contrainte (fonction)
les données ne sont envoyées que si cette function retourne true lors du prochain échange réseau. Cette contrainte reçoit en entrée les mêmes paramètres que les documentCheck.
data (objet)
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.

5.3.2.8.1.3 addCustomClientData(object, data)

object (objet)
documentCheck : (optionnel) fonction : les données ne sont envoyées que si cette function retourne true lors du prochain échange réseau. Cette contrainte reçoit en entrée les mêmes paramètres que les documentCheck. once (booléen) true par défaut :
s'il est à 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.
data (objet)
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.

5.3.2.8.2 Retour

Aucun.

5.3.2.8.3 Exception

Aucune.

5.3.2.8.4 Exemple

Enregistrement de la donnée complémentaire sur le "ready" du document.

window.dcp.document.documentController(
    "addEventListener",
    "ready",
    {
        "name": "my.clientCustom",
        "documentCheck": function (ddui) {
            return ddui.family.name === "MY_FAMILY"
        }
    },
    function (event, ddui, data) {
        $(this).documentController("addCustomClientData", {"hello":"world"});
    }
);

Enregistrement d'une fonction persistante uniquement pour les documents de type MY_FAMILY

window.dcp.document.documentController("addEventListener", "ready",
    {
        "name": "my.clientCustom",
        "documentCheck": function (ddui) {
            return ddui.family.name === "MY_FAMILY";
        }
    },
    function (event, ddui, data) {
        $(this).documentController("addCustomClientData",
        {"once" : false, "documentCheck" :  function (ddui) {
           return ddui.family.name === "MY_FAMILY";
       },
       {"hello":"world"});
    }
);

Dans cet exemple, les données complémentaires sont envoyées pour la requête suivante et non la requête courante.

5.3.2.9 setCustomClientData

Cette méthode est dépréciée au profit de addCustomClientData

5.3.2.10 getCustomClientData

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

5.3.2.10.1 Arguments

Aucun.

5.3.2.10.2 Retour

Les valeurs enregistrées. null si pas de valeur.

5.3.2.10.3 Exception

Aucune.

5.3.2.10.4 Exemple

Récupération de la donnée complémentaire :

window.dcp.document.documentController("addCustomClientData", {"hello":"world"});
 
var myData=window.dcp.document.documentController("getCustomClientData");
console.log(myData.hello); // => see "world"

5.3.2.11 removeCustomClientData

Cette méthode permet de supprimer des données précédemment enregistrées par la méthode addCustomClientData.

5.3.2.11.1 Arguments

  • key : clef à supprimer

5.3.2.11.2 Retour

Aucune.

5.3.2.11.3 Exception

Aucune.

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