3.2 Widget de document

Un widget est mis à disposition pour pouvoir créer directement des objets documents dans une page web.

3.2.1 Introduction

Ce widget crée automatiquement une iframe, dans laquelle il charge le document demandé. De plus, ce widget permet de piloter le document depuis la page courante, sans se préoccuper de l'iframe.

Lors de l'initialisation d'un document dans une iframe l'historique du navigateur n'est pas impacté par la navigation au sein du document (changement d'état, de documents, etc.).

3.2.2 Préparation de la page

Le widget nécessite les assets suivants dans la page :

  • jquery : lib/jquery/ddui/jquery.min.js,
  • underscore : lib/underscore/underscore-min.js,
  • le pattern de widget : DOCUMENT/IHM/widgets/widget.js,
  • le widget de document : DOCUMENT/IHM/document.js

3.2.3 Initialisation du widget

Le widget peut être initialisé avec le code suivant :

$(document).ready(function() {
    //initialise le widget de document
    //dans l'élément avec l'id myDocument
    //et avec le document ayant l'initid 1432
    $("#myDocument").document({
        "initid": 1432
    });
});

Une fois les dépendances mises en place, le code exécute le callback et initialise le widget sur la div #myDocument.

Attention : le widget peut aussi être initialisé vide (sans initid), pour charger en asynchrone les dépendances par exemple. Dans ce cas il faut attendre l'évènement documentloaded ensuite effectuer un fetchDocument.

//Chargement du widget et de ses dépendances
$(document).ready(function() {
    //initialisation du widget de document "vide"
    $("#myDocument").document()
        //ajout d'un listener qui se déclenche au documentloaded
        .on("documentloaded", function() {
            //fetch du document ayant l'initid 1432
            $("#myDocument").document("fetchDocument", {
                "initid": 1432
            });
        });
});

3.2.4 Arguments d'initialisation

  • initid : identifiant du document à charger, soit sous la forme d'un entier, soit sous la forme d'un nom logique,
  • viewId : rendu du document. Par défaut plusieurs rendu sont à disposition :
    • !defaultConsultation : rendu de consultation par défaut de l'utilisateur en cours (c'est la valeur utilisée lorsque viewId n'est pas précisé,
    • !defaultEdition : rendu d'édition par défaut de l'utilisateur en cours,
    • !coreCreation : rendu de création (dans ce cas l'initid doit être un identifiant de famille).
  • revision : révision du document (défaut : -1, soit la dernière révision applicable),
  • customClientData : customClientData données additionnelles à envoyer au serveur,
  • noRouter: booléen, désactive l'historique de navigation dans l'iframe (default: true),
  • withoutResize : désactive le calcul automatique de la taille du widget (défault : false),
  • resizeMarginHeight : applique une marge au calcul automatique de la hauteur (défaut : 3),
  • resizeMarginWidth : applique une marge au calcul automatique de la largeur (défaut : 0),
  • resizeDebounceTime: applique un debounce sur le calcul automatique de la taille en millisecondes (défaut : 50).

3.2.5 Méthodes

Ces méthodes sont appelées méthodes du contrôleur externe par opposition au contrôleur interne qui agit depuis l'intérieur du widget. L'ensemble des méthodes décrites dans le chapitre contrôleur interne sont accessibles.

3.2.5.1 Exemples

Passage du document en édition :

 
$("#myDocument").document("fetchDocument" , {
    "initid": 42,
    "viewId": "!defaultEdition"
});

Récupération des propriétés du document.

 
var properties = $("#myDocument").document("getProperties");

Attention : Les méthodes ne peuvent être utilisées que lorsque le widget est loaded, c'est à dire qu'il représente un document et que celui-ci est chargé, excepté pour les méthodes suivantes :

3.2.5.2 isLoaded

Cette méthode permet de savoir si le widget est chargé et associé à une représentant un document.

3.2.5.2.1 Arguments

Pas d'argument

3.2.5.2.2 Retour

Booléen : true si le widget est prêt, false sinon.

3.2.5.2.3 Exception

Pas d'exception

3.2.5.2.4 Exemple

if ($("#myDocument").document("isLoaded")) {
    alert("document is loaded");
}

3.2.5.3 fetchDocument

Voir la méthode fetchDocument du contrôleur interne.

3.2.5.3.1 Exemple

Affichage d'un document affichage d'un avertissement en cas d'échec et d'un message en cas de succès.

$(".myDocumentDiv").document("fetchDocument", 
    { initid: 1234 }, 
    { force: false  }
 ).then(function (data) {
            data.element.documentController("showMessage", {
                type: "info",
                message: "Document "+ data.nextDocument.title+ " has been loaded"
            });
 }).catch(function (data) {
            data.element.documentController("showMessage", {
                type: "warning",
                message: data.errorMessage.contentText
        });
});

3.2.5.4 saveDocument

Voir la méthode saveDocument du contrôleur interne.

3.2.5.4.1 Exemple

Sauvegarde déclenchée sur le bouton ".saveNow". Affichage de l'erreur en cas d'échec et d'un message indiquant la réussite de la sauvegarde en cas de succès.

$("button.saveNow").on("click", function ()
    {
        $(".myDocumentDiv").document("saveDocument").then(function (data)
        {
            data.element.documentController("showMessage", {
                type: "success",
                message: "Document " + data.nextDocument.title + " has been saved"
            });
        }).catch(function (data)
        {
            data.element.documentController("showMessage", {
                type: "error",
                message: data.errorMessage.contentText
            });
        });
    });

3.2.5.5 addEventListener

Voir la méthode addEventListener du contrôleur interne.

Les événements enregistrés dans le widget de document sont automatiquement ré-associés au widget interne chaque fois que celui-ci est chargé ou rechargé.

3.2.5.6 listEventListeners

Voir la méthode listEvents du contrôleur interne.

3.2.5.7 removeEventListener

Voir la méthode removeEventListener du contrôleur interne.

Les événements enregistrés dans le widget de document sont automatiquement ré-associés au widget interne chaque fois que celui-ci est chargé ou rechargé.

3.2.5.8 addConstraint

Voir la méthode addConstraint du contrôleur interne.

Les contraintes enregistrées dans le widget de document sont automatiquement ré-associées au widget interne chaque fois que celui-ci est chargé ou rechargé.

3.2.5.9 listConstraints

Voir la méthode listConstraints du contrôleur interne.

3.2.5.10 removeConstraint

Voir la méthode removeConstraint du contrôleur interne.

Les contraintes enregistrées dans le widget de document sont automatiquement réassociées au widget interne chaque fois que celui-ci est chargé ou rechargé.

3.2.5.11 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

3.2.5.11.1 Arguments

Pas d'argument

3.2.5.11.2 Retour

Une promise.

En cas de réussite, l'argument de la fonction est undefined.

En cas d'échec, la structure de l'argument de la fonction d'échec est une chaine de caractère "Unable to destroy because user refuses it".

3.2.5.11.3 Exception

Pas d'exception

3.2.5.11.4 Exemple

if ($("#myDocument").document("tryToDestroy"))then(
    function onSuccess() { console.log("OK", arguments);}, 
    function onError() { console.log("KO", arguments);}
);

3.2.6 Événements

Les événements suivants sont mis à disposition par le widget.

les événements sont des événements DOM, déclenchés sur l'élément DOM sur lequel a été instancié le widget. De plus, les noms des événements sont tous en minuscules.

3.2.6.1 documentloaded

Cet événement est déclenché dès que le widget de document est associé à un document et que les méthodes internes peuvent être utilisées.

$("#myDocument").on("documentloaded", function(event) {
    console.log("Ready to be used");
});

3.2.6.2 documentunloaded

Cet événement est déclenché dès que le widget de document n'est plus associé à un document :

  • chargement d'une page ne contenant pas un document
  • rechargement de la page contenant le document (dans ce cas, un documentunloaded est déclenché, suivi d'un documentloaded)
  • etc.
$("#myDocument").on("documentunloaded", function(event) {
    console.log("Document disabled");
});

3.2.6.3 documentautoresize

Cet événement est déclenché dès que le widget de document recalcule sa taille.

Par défaut, le widget prend la taille de l'élément le contenant. Il est toutefois possible d'intercepter le resize du widget et de modifier la méthode de calcul.

$("#myDocument").on("documentautoresize", function myResize(event) {
    //récupération de l'iframe contenant le document
    var $iframe = this.find("iframe");
 
    //arrête le calcul automatique
    event.preventDefault();
 
    //redimensionne l'iframe
    $iframe.height(100).width(100);
});

L'exemple ci-dessus force la taille du widget à une carré de 100px de côté.

Source : access/controller.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.