Manuel de référence

Document User Interface 1.0

Labs <labs@anakeen.com>

Table des matières

Chapitre 1 Présentation du module Document UI

Le module Document UI se substitue aux interfaces Document de Dynacase, qui étaient des pages HTML entièrement générées côté serveur.

Il propose une interface graphique en HTML5 compatible avec les navigateurs modernes permettant une conception réactive (s'ajustant aux tailles des écrans), adaptée aux supports tactiles (tablettes) et facilement modifiable.

1.1 Concepts de développement

Les concepts mis en œuvre sont :

1.2 Éléments inclus

Le module inclut toutes les interfaces constituant le document, ce qui comprend :

Chacun des éléments d'interface est disponible sous la forme d'un widget autonome qui peut être utilisé pour concevoir une interface globale uniforme.

De plus, un widget de contrôleur est mis à disposition pour mettre en place un document et interagir facilement avec lui.

1.3 Support navigateur

Les navigateurs compatibles sont :

1.4 Illustrations

1.4.1 Design responsive

Document : largeur d'écran élevée

Figure 1. Document : largeur d'écran élevée

Document : largeur d'écran faible

Figure 2. Document : largeur d'écran faible

Chapitre 2 Conception technique

Ce chapitre évoque les différents choix de conception et l'organisation de la stack technique

2.1 Schéma

Schéma de principe

Figure 3. Schéma de principe

Le schéma ci-dessus présente l'architecture de Document UI.

2.2 Côté serveur

Le serveur s'appuie sur Dynacase Platform et notamment les mécanismes suivants :

La couche REST inclut un ensemble de mécanismes permettant de modifier les informations transmises au moteur de rendu client.

Lors de l'initialisation d'une nouvelle page contenant un document, le serveur fournit une trame minimaliste (liste des assets JS, CSS) et le code de démarrage JS. C'est ensuite le JavaScript qui se charge de faire la requête auprès du REST pour obtenir :

2.3 Côté client

Le client est composé des éléments suivants :

Ces éléments sont organisés en widgets qui sont mis en place par Bacbkone.js. Lors de l'initialisation d'une page, les éléments suivants sont mis en place :

Une fois l'ensemble initialisé, au cours de la vie du document, les widgets communiquent à la vue les modifications effectuées par l'utilisateur. La vue communique ces modifications au modèle. Le pattern inverse est appliqué lorsque le modèle est modifié : le modèle transmet à la vue la modification, et la vue l'applique au travers du widget sur la représentation visible pour l'utilisateur.

Il est à noter que lorsqu'un utilisateur change de document la page entière n'est pas rechargée. Dans ce cas, seul le modèle est mis à jour avec les données du nouveau document, ce qui permet un chargement rapide.

Chapitre 3 Moyen d'accès

Ce chapitre détaille les différents moyens permettant d'accéder au document.

3.1 URL d'accès

3.1.1 Accès au rendu par défaut de consultation d'un document

L'url d'accès à une représentation HTML d'un document est la suivante :

api/v1/documents/<identifiant du document>.html

Cette url permet de voir un document en consultation.

Le paramètre identifiant du document contient soit l'identifiant numérique du document, soit son nom logique.

Note : C'est la dernière révision du document qui est présentée.

3.1.2 Accès au rendu par défaut de modification d'un document

L'url d'accès au formulaire du document est la suivante :

api/v1/documents/<identifiant du document>/views/!defaultEdition.html

Cette url permet de voir le formulaire de modification du document.

Le paramètre identifiant du document contient soit l'identifiant numérique du document, soit son nom logique.

3.1.3 Accès à un rendu défini dans le contrôle de vue d'un document

Si le document à un contrôle de vue qui lui est associé, la vue souhaitée peut être indiquée dans l'url de rendu.

api/v1/documents/<identifiant du document>/views/<identifiant de la vue>.html

3.1.4 Accès au rendu par défaut de création d'un document

L'url d'affichage du formulaire de création est :

api/v1/documents/<identifiant de la famille>/views/!defaultCreation.html

Le paramètre identifiant de la famille contient l'identifiant de la famille du document à créer.

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 :

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

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 :

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 :

$("#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é.

Chapitre 4 Intervenir sur le serveur

4.1 Concepts mis en œuvre sur le serveur

Le code serveur de DDUI manipule plusieurs classes php afin de gérer la représentation et le comportement des documents.

4.1.1 Configuration de rendu de document

La configuration de rendu de document permet de gérer la représentation du document et de ses attributs.

Il est en particulier possible

Les méthodes de la classe de configuration de rendu de document sont documentées dans le chapitre correspondant.

4.1.2 Configuration du menu

Les menus sont manipulables au travers de classes et méthodes dédiées.

Il est notamment possible

4.1.3 Contrôle de vue

Le contrôle de vue ui dispose d'un élément supplémentaire par rapport au contrôle de vue d'origine : la configuration de rendu.

Cet élément est associé à une vue et est identifié par le nom de sa classe.

Si un contrôle de vue est associé au document, sa configuration de rendu est issue de la vue utilisée. Le masque est au préalable affecté avant de demander la configuration de rendu.

Si la vue n'a pas de configuration de rendu c'est la configuration de rendu par défaut qui sera utilisée.

4.1.4 Configuration de rendu de transition

La configuration de rendu de transition permet de gérer la représentation d'une demande de transition.

Lorsqu'un cycle de vie est attaché à un document, le passage de certaines transitions nécessite des paramètres. Le passage de ces transitions affiche un formulaire permettant de saisir les paramètres. L'affichage de ce formulaire est configurable avec un rendu de transition.

Les méthodes de la classe de configuration de rendu de transition sont documentées dans le chapitre correspondant.

4.1.5 Moteur de templates

Le moteur de templates utilisé est mustache, avec les implémentations suivantes :

4.1.6 Pré-parseur CSS

Les CSS peuvent être parsées au moyen de Less.

4.2 Associer une configuration de rendu de document à un document

La configuration de rendu de document peut être associée à un document de trois façons différentes :

  1. Par les fichiers de surcharge des éléments de rendu
  2. Dans le contrôle de vue associé
  3. Dans la définition de la classe de la famille

L'interface de rendu va rechercher la configuration dans l'ordre suivant (l apremière vue trouvée sera applicable) :

  1. Recherche de la vue dans les [fichiers de surcharge des éléments de rendu][ddui-ref:override]
  2. Recherche de la vue par défaut issue du contrôle de vue
    1. Recherche avec la classe d'accès au rendu si elle est définie
    2. Recherche avec les priorités des vues définies dans le contrôle de vue
  3. Recherche de la vue de la famille
  4. Utilisation de la vue système

4.2.1 Classe d'accès à un rendu de document

L'interface PHP Dcp\Ui\IRenderConfigAccess permet de choisir un rendu en fonction du document et du mode.

La seule méthode à implémenter est la méthode getRenderConfig

Dcp\Ui\IRenderConfig getRenderConfig(string $mode,
                                       \Doc $document)

Les paramètres sont :

mode

Le mode de rendu, parmi

  • Dcp\Ui\RenderConfigManager::EditMode (édition),
  • Dcp\Ui\RenderConfigManager::CreateMode (création)
  • Dcp\Ui\RenderConfigManager::ViewMode (consultation)
document
L'objet \Doc en cours.

Cette méthode doit retourner une instance d'une classe implémentant l'interface Dcp\Ui\IRenderConfig compatible avec le mode demandé.

L'objet de configuration retourné peut être fonction des données du document ou en fonction de l'utilisateur. Cela donne toute liberté quant-au choix de la configuration.

Si la méthode retourne null, c'est le rendu par défaut qui sera appliqué.

Exemple :

namespace My;
class MyAccess implements \Dcp\Ui\IRenderConfigAccess
{
    /**
     * @param string $mode
     * @return \Dcp\Ui\IRenderConfig
     */
    public function getRenderConfig($mode, \Doc $document)
    {
        switch ($mode) {
            case \Dcp\Ui\RenderConfigManager::CreateMode:
            case \Dcp\Ui\RenderConfigManager::EditMode:
                return new MyRenderConfigEdit($this);
            case \Dcp\Ui\RenderConfigManager::ViewMode:
                return new MyRenderConfigView($this);
        }
 
        return null;
    }
}

4.2.2 Définir un rendu par défaut pour une famille

La définition du rendu par défaut se fait en implémentant l'interface Dcp\Ui\IRenderConfigAccess sur la classe de la famille. Cette interface demande une seule méthode :

\Dcp\Ui\IRenderConfig getRenderConfig(string $mode,
                                        \Doc $document)

Voir la définition de la classe d'accès à un rendu de document.

Dans ce cas, l'objet $document reçu par la méthode est l'objet lui-même (this).

Exemple :

namespace My;
class MyFamily extends \Dcp\Family\Document implements \Dcp\Ui\IRenderConfigAccess
{
    /**
     * @param string $mode
     * @return \Dcp\Ui\IRenderConfig
     */
    public function getRenderConfig($mode, \Doc $document)
    {
        switch ($mode) {
            case \Dcp\Ui\RenderConfigManager::CreateMode:
            case \Dcp\Ui\RenderConfigManager::EditMode:
                return new MyRenderConfigEdit($this);
            case \Dcp\Ui\RenderConfigManager::ViewMode:
                return new MyRenderConfigView($this);
        }
 
        return null;
    }
}

4.2.3 Définir les rendus dans un contrôle de vue

L'installation du module Dynacase Document Ui, a pour effet de surcharger le contrôle de vue d'origine.

Deux attributs pour la configuration du contrôle de vue sont ajoutés :

cv_renderclass

classe de configuration de rendu de document

Multiple, défini pour chaque vue.

cv_renderaccessclass
classe d'accès à un rendu

L'attribut cv_renderclass indique la classe de rendu à utiliser pour la vue donnée.

L'action de rendu n'utilise pas la zone du contrôle de vue (attribut cv_zview). Par contre, le masque s'il est indiqué est appliqué. Le document fourni en argument aux différentes méthodes de la configuration de rendu, et en particulier lors de l'attribution des visibilités a déjà le masque du contrôle de vue appliqué.

Si une vue indique une zone non standard (différent de FDL:VIEWBODYCARD et FDL:EDITBODYCARD) et n'indique pas de classe de rendu alors la vue ne sera pas applicable pour l'affichage du document avec les interfaces HTML5 fournies par ce module.

Si une vue indique une classe de rendu non standard (différent de Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit) et n'indique pas de zone, alors cette vue sera ignorée par les interfaces traditionnelles fournies par la module Dynacase Core.

Zone Configuration de rendu HTML classique HTML 5
<vide> <vide> OK OK
FDL:VIEWBODYCARD <vide> OK OK
FDL:EDITBODYCARD <vide> OK OK
<vide> Dcp\Ui\DefaultView OK OK
<vide> Dcp\Ui\DefaultEdit OK OK
FDL:VIEWBODYCARD Dcp\Ui\DefaultView OK OK
FDL:EDITBODYCARD Dcp\Ui\DefaultEdit OK OK
<custom> <vide> OK KO
<custom> Dcp\Ui\DefaultView OK OK
<custom> Dcp\Ui\DefaultEdit OK OK
<custom> <custom> OK OK
<vide> <custom> KO OK

Le contrôle de vue peut aussi indiquer une classe d'accès à un rendu dans l'attribut Classe d'accès au rendu (cv_renderaccessclass). Cette classe est utilisée lorsqu'aucune vue spécifique n'est demandée explicitement. Elle permet de choisir un rendu en fonction du mode et du document.

Si la méthode ::getRenderConfig() de cette classe retourne null, alors le choix du rendu est celui désigné par le contrôle de vue en fonction du mode, des droits et des priorité de chacune des vues.

4.3 Associer une configuration de rendu de transition à un cycle de vie

La configuration de rendu de document peut être associée à un document de deux façons différentes :

  1. Par les fichiers de surcharge des éléments de rendu
  2. Dans la définition de la classe du cycle de vie

4.3.1 Classe d'accès à un rendu de transition

L'interface PHP Dcp\Ui\IrenderTransitionAccess permet de choisir un rendu en fonction du workflow et de la transition.

La seule méthode à implémenter est la méthode getTransitionRender

\Dcp\Ui\TransitionRender getTransitionRender(
               string $transitionId, 
                \WDoc $workflow)

Les paramètres sont :

transitionId

l'id de la transition demandée

Il peut être vide dans le cas où l'utilisateur "admin" demande le passage d'une transition invalide (seul cet utilisateur a le privilège pour ce type de transition).

workflow
l'objet \WDoc en cours.

Cette méthode doit retourner une instance d'une classe implémentant l'interface Dcp\Ui\IRenderTransition.

Si la méthode retourne null, c'est le rendu par défaut qui est appliqué.

Cette méthode est appelée par l'api lors de la demande des caractéristiques d'affichage de la transition.

Exemple :

namespace My;
 
class MyTransitionRenderConfig extends \Dcp\Ui\TransitionRender
{
    /**
     * @param string $transitionId
     *
     * @return \Dcp\Ui\RenderOptions
     * @throws \Dcp\Ui\Exception
     */
    public function getRenderOptions($transitionId)
    {
        $options = parent::getRenderOptions($transitionId);
        // Change label of parameter frame
        $options->frame(self::parameterFrameAttribute)->setAttributeLabel("My parameters");
        return $options;
    }
}
 
class MyAccess implements \Dcp\Ui\IRenderTransitionAccess
{
    /**
     * @param string $transitionId
     * @return \Dcp\Ui\IRenderTransition
     */
    public function getTransitionRender($transitionId, \WDoc $workflow)
    {
        if($transitionId)
        {
            return new MyTransitionRenderConfig();
        }
        return null;
    }
}

4.3.2 Définir un rendu par défaut pour un cycle de vie

La définition du rendu par défaut se fait en implémentant l'interface Dcp\Ui\IrenderTransitionAccess sur la classe du workflow. Cette interface demande une seule méthode :

Dcp\Ui\TransitionRender getTransitionRender(string $transitionId,
                                             \WDoc $workflow)

Voir la définition de la classe d'accès à un rendu de transition.

Dans ce cas, l'objet $workflow reçu par la méthode est l'objet lui-même (this).

Exemple :

namespace My;
class My_wfl extends \Dcp\Family\WDoc implements \Dcp\Ui\IrenderTransitionAccess
    const myFirstTransition="my_trans_one";
    const mySecondTransition="my_trans_two";
    public $transitions = array(...);
    public $cycle = array(...);
    /**
     * Get Transition Render object to configure transition render
     * @param string $transitionId transition identifier
     * @param \WDoc $workflow workflow document
     * @return \Dcp\Ui\TransitionRender
     */
    public function getTransitionRender($transitionId, \WDoc $workflow)
    {
        return new CustomRender();
    }
}

4.4 Fichiers de surcharge des éléments de rendu

Il est possible de paramétrer le rendu sans modifier le code existant.

4.4.1 Format

Les fichiers de configurationau sont au format format JSON, et doivent être placés dans le répertoire DOCUMENT/customRender.d du serveur.

Seuls les fichiers dont l'extension est .json sont pris en compte.

Chaque surcharge s'applique explicitement à une famille désignée, et n'est pas propagée à ses sous-familles.

le fichiers est la représentation json d'un tableau à 3 dimensions :

  1. la première dimension est obligatoirement "families"
  2. la deuxième dimension référence une famille par son nom logique
  3. la troisième dimensionindique le nom d'un paramètre.

Exemple :

{
  "families": {
    "MY_FAMILY": {
        "renderAccessClass": "My\\MyRenderAccess",
        "disableTag" : true
        },
    "MY_WORKFLOWFAMILY": {
        "renderAccessTransition": "My\\MyTransitionAccess"
    }
  }
}

4.4.2 Prise en compte des surcharges

Pour que les fichiers soient pris en compte, il est nécessaire de lancer la commande suivante après leur déploiement :

./wsh.php --app=DOCUMENT --action=LOAD_RENDERPARAMETERS

Cette commande peut aussi être lancée depuis le navigateur en tant qu'administrateur.

http://<yourDomain>/?app=DOCUMENT&action=LOAD_RENDERPARAMETERS

Cette commande applique les différents fichiers de configuration. Les paramètres sont fusionnés dans l'ordre croissant des noms de fichiers. Il est d'usage de préfixer le nom du fichier par 2 chiffres afin de rendre l'ordre plus explicite.

Pour une même famille, les différents paramètres sont cumulés.

Exemple :

DOCUMENT/customRender.d/10_myRender.json
{
  "families": {
    "YOUR_FIRSTFAMILY": {
        "renderAccessClass": "My\\MySecondRenderAccess",
        "disableTag" : true
        },
    "MY_FIRSTFAMILY": {
        "renderAccessClass": "My\\MyFirstRenderAccess"
    }
  }
}
DOCUMENT/customRender.d/20_myRender.json
{
  "families": {
    "YOUR_FIRSTFAMILY": {
        "renderAccessClass": "My\\MyOtherRenderAccess",
            "applyRefresh" : true
        },
    "MY_SECONDFAMILY": {
        "renderAccessClass": "My\\MySecondRenderAccess"
    }
  }
}

Les fichiers sont pris dans l'ordre alphabétique, soit :

  1. 10_myRender.json
  2. 20_myRender.json

Le paramétrage résultant est le suivant :

{
    "families": {
        "YOUR_FIRSTFAMILY": {
            "renderAccessClass": "My\\MyOtherRenderAccess",
            "disableTag": true,
            "applyRefresh": true
        },
        "MY_FIRSTFAMILY": {
            "renderAccessClass": "My\\MyFirstRenderAccess"
        },
        "MY_SECONDFAMILY": {
            "renderAccessClass": "My\\MySecondRenderAccess"
        }
    }
}

4.4.3 Réactiver la méthode Doc::refresh()

Par défaut l'appel à la méthode Doc::refresh() n'est pas effectué lors de la récupération d'un rendu. cela est nécessaire pour s'assurer que 2 Get successifs au même doucment retournet la même réponse (aspect REST de l'API).

Par contre, elle est effectuée lors de l'enregistrement (POST, PUT) via la méthode Doc::store().

Si l'option applyRefresh vaut true, alors la méthode Doc::refresh() est appelée à chaque récupération (GET) de rendu.

Dans ce cas, l'etag est calculé après l'appel à la méthode Doc::refresh(). Si le document n'a pas été modifié et si cette méthode ne modifie pas non plus le document, l'etag n'est pas modifié.

Exemple :

{
    "families": {
        "MY_FAMILY": {
            "applyRefresh": true
        }
    }
}

4.4.4 Désactiver le calcul des etag

Par défaut, l'api HTTP calcule des etag.

Lorsque ce n'est pas nécessaire, ou que ce calcul ets trop couteux, il est posible de désactiver ce calcul au moyen du paramètre disableETag.

lorsque disableETag vaut true, l'etag n'est ni calculé, ni transmis ni vérifié.

Exemple :

{
  "families": {
    "MY_FAMILY": {
        "disableEtag": true
    }
  }
}

4.4.5 Définir l'accès à un rendu de document

Le paramètre renderAccessClass indique la classe d'accès à un rendu de document.

Exemple :

{
  "families": {
    "MY_FAMILY": {
        "renderAccessClass": "My\\MyRenderAccess"
    }
  }
}

4.4.6 Définir l'accès à un rendu de transition

Le paramètre renderTransitionClass indique la classe d'accès à un rendu de transition.

Exemple :

{
  "families": {
    "MY_WORKFLOWFAMILY": {
        "renderTransitionClass": "My\\MyTransitionAccess"
    }
  }
}

4.5 Méthodes de la classe de configuration de rendu de document

Une configuration de rendu de document est définie par une classe PHP qui doit implémenter l'interface Dcp\Ui\IRenderConfig.

Dynacase fournit des classes de rendu de document par défaut, qui implémentent cette interface.

Dans les méthodes d'une configuration de rendu de transition, les utilisations de get et de set peuvent sembler inversées. Ce n'est pas le cas : ces méthodes sont utilisées par la plateforme pour générer le rendu.
Par exemple, la méthode getVisibilities est appelée par Dynacase pour obtenir les visibilités à utiliser lors du rendu du document La méthode implémentée ne positionne (set) pas ces visibilités, mais les retourne (get).

4.5.1 Classes de configuration de rendu par défaut

Deux classes de configuration sont fournies par le système :

  1. La classe Dcp\Ui\DefaultView pour la consultation.
  2. La classe Dcp\Ui\DefaultEdit pour l'édition

Ces classes fournissent les différentes options par défaut pour représenter le document. Elles fournissent notamment la définition des menus, les visibilités, les templates et les options de rendu d'attribut données par défaut.

Pour créer sa propre classe de rendu, il est recommandé d'hériter de l'une de ces classes afin d'éviter de coder l'ensemble des méthodes de l'interface Dcp\Ui\IRenderConfig.

Pour des besoins plus spécifiques, il est possible de ne pas hériter de ces classes et d'implémenter directement l'interface. Il est alors nécessaire d'implémenter toutes les méthodes à coder.

4.5.2 getCssReferences

La méthode getCssReferences() permet d'injecter des feuilles de style personnalisées dans le widget de document.

Elle doit retourner un tableau qui contient le chemin des fichiers css à insérer dans la page HTML. Ces chemins sont relatifs au répertoire d'installation.

Par défaut, les classes Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit retournent les css suivantes :

[
    "bootstrap" => "css/dcp/document/bootstrap.css",
    "kendo"     => "css/dcp/document/kendo.css",
    "document"  => "css/dcp/document/document.css",
    "datatable" => "lib/jquery-dataTables/1.10/bootstrap/3/dataTables.bootstrap.css"
]

Pour ajouter une feuille de style, il faut reprendre le tableau de la classe parente puis ajouter le chemin vers le nouveau fichier css.

Ce chemin doit être relatif par rapport au répertoire d'installation de Dynacase.

namespace My;
class MyRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getCssReferences(\Doc $document=null)
    {
        $css = parent::getCssReferences($document);
        $css["myCustom"] = "MY/Layout/custom.css";
        return $css;
    }
}

L'index dans la table permet d'identifier un fichier dans la perspective de le remplacer.

Cet index doit être unique sur l'ensemble des css des rendus.

Note : Dans un soucis de performance, lorsqu'un rendu de document est modifié sur le navigateur, les css déjà enregistrées avec le même identifiant ne sont pas rechargées. Lors du rendu d'un document, les css spécifiques sont supprimées si elles ne sont plus demandées par le nouveau rendu.

Afin de cibler des parties spécifiques du document ou des attributs, la DOM des éléments générs par Dynacase Document UIS est normalisée.

4.5.3 getJsreferences

La méthode getCssReferences() permet d'injecter des fichiers JS personnalisés dans le widget de document.

Elle doit retourner un tableau qui contient le chemin des fichiers js à insérer dans la page HTML. Ces chemins sont relatifs au répertoire d'installation.

Par défaut, les classes Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit ne retournent aucun fichier js spécifique :

[]

Pour ajouter un fichier javascript, il faut reprendre le tableau de la classe parente puis ajouter un nouveau chemin vers le fichier js.

Ce chemin doit être relatif par rapport au répertoire d'installation de Dynacase.

namespace My;
class MyRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getJsReferences(\Doc $document=null) {
        $js=parent::getJsReferences($document);
        $js["myContact"]="MY/Layout/customContact.js";
 
        return $js;
    }
}

L'index dans la table permet d'identifier un fichier dans la perspective de le remplacer.

4.5.4 getTemplates

La méthode getTemplates permet de modifier les templates utilisés lors de la génération du document et des attributs.

Cette méthode retourne un tableau de templates mustache.

4.5.4.1 gérer les modèles

La méthode getTemplates retourne un array à plusieurs niveaux. Le premier niveau est

body

pour définir le template du corps du document.

Le template est alors défini par une des clés suivantes :

file

Le template utilisé est identifié par un fichier le contenant.

Le chemin de ce fichier est relatif au répertoire d'installation de Dynacase.

content
Le template utilisé est directement indiqué sous la forme d'une chaîne de caractères.

Lorsque les clés file et content sont toutes deux non vides, la clé content ets utilisée et la clé file est ignorée.

sections

pour définir le template d'une section du document.

Dans ce cas, sections est un tableau à 2 niveaux.

  1. Le premier niveau est le nom de la section

  2. Le second niveau est une des clés suivantes :

    file

    Le template utilisé est identifié par un fichier le contenant.

    Le chemin de ce fichier est relatif au répertoire d'installation de Dynacase.

    content
    Le template utilisé est directement indiqué sous la forme d'une chaîne de caractères.

    Lorsque les clés file et content sont toutes deux non vides, la clé content ets utilisée et la clé file est ignorée.

Les modèles sont parsés côté client et côté serveur, et plusieurs clés sont utilisables.

4.5.4.2 Corps du document : body

Le corps du document est constitué de 4 sections :

  1. L'entête
  2. Le menu
  3. Le contenu
  4. Le pied

Son template par défaut est le suivant :

{{> header}}
 
{{> menu}}
 
{{> content}}
 
{{> footer}}

Cette définition peut être modifiée au moyen de la clé body du tableau de templates pour ajouter des éléments HTML entre les sections ou tout simplement pour supprimer une ou plusieurs sections.

Exemple : Insérer un titre entre chaque section.

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["body"]["file"]="MY/customDocument.mustache";
        return $templates;
    }
}

Fichier MY/customDocument.mustache :

<h1>Pre Header</h1>
{{> header}}
<h1>Post Header</h1>
 
{{> menu}}
<h1>Post Menu</h1>
 
{{> content}}
<h1>Post Content</h1>
 
{{> footer}}
<h1>Post Footer</h1>

Le pied de page, de par sa css, est toujours affiché en bas du document. Pour afficher des éléments plus bas que le pied de page, il faut modifier la css (classe dcpDocument__footer).

Chacune des sections peut être personnalisée au moyen d'un modèle de section.

4.5.4.3 Sections

Les sections peuvent être modifiées au moyen de la clé sections du tableau de templates.

4.5.4.3.1 Entête du document : header

L'entête du document est la section header de la catégorie sections.

Le template par défaut de la section header est le suivant (version simplifiée) :

<header class="dcpDocument__header">
    <img class="dcpDocument__header__icon" src="{{document.properties.icon}}" alt="Document icon"/>
    <a class="dcpDocument__header__title" href="api/v1/documents/{{document.properties.id}}.html">{{document.properties.title}}</a>
    <div class="dcpDocument__header__family">{{document.properties.family.title}}</div>
</header>

Le template complet comporte des éléments plus spécifiques qui sont fonction du mode de rendu et aussi du fait d'afficher une révision passée ou non. Dans tous les cas, les trois éléments indiqués sont présent.

Exemple : Afficher uniquement le titre.

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["sections"]["header"]["file"]="MY/customHead.mustache";
        return $templates;
    }
}

Fichier MY/customHead.mustache :

<h1>{{document.properties.title}}</h1>

Cela donnera la structure suivante :

<html>
    <head>...</head>
    <body>
        <div class="document">
            <div class="dcpDocument">
                <h1>Mon document</h1>
                <nav class="dcpDocument__menu">...</nav>
                <section class="dcpDocument__body">...</section>
                <footer class="dcpDocument__footer"/>
            </div>
        </div>
    </body>
</html>

4.5.4.3.2 Menu du document : menu

La barre de menu du document est la section menu de la catégorie sections.

Par défaut :

<nav class="dcpDocument__menu"></nav>

Le menu, défini par ::getMenu(), est construit dans l'objet de la classe css dcpDocument__menu.

La barre de menu peut être déplacée dans n'importe quelle autre section.

Exemple : mettre le menu dans le footer du document

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
     public function getTemplates(\Doc $document = null) {
            $templates=parent::getTemplates($document);
            $templates["sections"]["footer"]["content"]=
                '<footer class="dcpDocument__footer"><div class="dcpDocument__menu"/></footer>';
            $templates["sections"]["menu"]["content"]='';
            return $templates;
        }
}

Cela donnera la structure suivante :

<html>
    <head>...</head>
    <body>
        <div class="document">
            <div class="dcpDocument">
                <header class="dcpDocument__header">...</header>
                <!-- plus de menu ici -->
                <section class="dcpDocument__body">...</section>
                <footer class="dcpDocument__footer"><div class="dcpDocument__menu">...</div></footer>
            </div>
        </div>
    </body>
</html>

La barre de menu a un comportement spécifique lorsqu'elle est contenue dans un élément de type nav. Ce comportement implique que le menu passe en position fixed en haut du document lorsque le header n'est plus visible.

4.5.4.3.3 Contenu du document : content

Le contenu du document est la section content de la catégorie sections.

Par défaut :

<section class="dcpDocument__body"/>

Le contenu par défaut du document est construit par le widget dans la section identifiée par la classe css dcpDocument__body. Si celle-ci n'est pas présente, il est nécessaire alors d'indiquer les attributs à afficher explicitement en utilisant les variables mustache.

Exemple : Affichage uniquement du contenu de l'onglet my_tabinformation.

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["sections"]["content"]["file"]="MY/customContent.mustache";
        return $templates;
    }
}

Fichier "MY/customContent.mustache"

<div class="container-fluid">
<h1>Voici :  {{document.properties.title}}</h1>
{{{document.attributes.my_tabinformation.htmlContent}}}
</div>

Cela donnera la structure suivante :

<html>
    <head>...</head>
    <body>
        <div class="document">
            <div class="dcpDocument">
                <header class="dcpDocument__header">...</header>
                <nav class="dcpDocument__menu">...</nav>
                <div class="container-fluid">
                    <h1>Voici :  Mon document</h1>
                    <div class="dcpCustomTemplate--content" data-attrid="my_tabinformation">
                        <div class="dcpTab__content" data-attrid="my_tabinformation" ">
                            ...
                        </div>
                     </div> 
                 </div>
                <footer class="dcpDocument__footer"/>
            </div>
        </div>
    </body>
</html>

4.5.4.3.4 Pied du document : footer

Le bas du document est la section footer de la catégorie sections.

Par défaut :

<footer class="dcpDocument__footer"/>

La classe dcpDocument__footer fixe le pied de document en bas de la page pour être toujours visible.

Les règles pour le footer par défaut sont :

.dcpDocument__footer {
    background-color: #f2f2f2;
    text-align: center;
    position: fixed;
    bottom: 0;
    width: 100%;
    z-index: 2;
}

Exemple : Afficher un copyright.

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["sections"]["footer"]["content"]='
            <footer class="dcpDocument__footer">
                 <strong>All right reserved &copy;</strong>
            </footer>
        ';
        return $templates;
    }
}

Cela donnera la structure suivante :

<html>
    <head>...</head>
    <body>
        <div class="document">
            <div class="dcpDocument">
                <header class="dcpDocument__header">...</header>
                <nav class="dcpDocument__menu">...</nav>
                <section class="dcpDocument__body">...</section>
                <footer class="dcpDocument__footer">
                     <strong>All right reserved &copy;</strong>
                </footer>
            </div>
        </div>
    </body>
</html>

4.5.4.4 Variables des templates

Il est possible d'utiliser des variables liées au document dans les templates.

4.5.4.4.1 Variables client

Les variables sur les propriétés et les attributs du document sont utilisables dans les templates :

4.5.4.4.1.1 Propriétés

Clef Définition
{{document.properties.id}} Identifiant du document
{{document.properties.name}} Nom logique du document
{{document.properties.initid}} Identifiant de la lignée du document
{{document.properties.icon}} Url de l'icône du document
{{document.properties.title}} Titre du document
{{document.properties.family.title}} Titre de la famille du document
{{document.properties.family.id}} Identifiant de la famille du document
{{document.properties.family.icon}} Icône de la famille du document
{{document.properties.isReadMode}} (booléen) Indique si le rendu de document est en mode consultation
{{document.properties.isWriteMode}} (booléen) Indique si le rendu de document est en mode modification

4.5.4.4.1.2 Attributs

Clef Définition
{{document.attributes.attrid.label}} Libellé de l'attribut "attrid"
{{document.attributes.attrid.attributeValue.value}} Valeur brute
{{document.attributes.attrid.attributeValue.displayValue}} valeur affichable
{{document.attributes.attrid.attributeValue.specialProperty}} Autres propriétés (Voir formatCollection)
{{{document.attributes.attrid.htmlContent}}} Contenu (HTML) formaté de la valeur (Attention aux triple accolades : {{{…}}})
{{{document.attributes.attrid.htmlView}}} Contenu (HTML) formaté de la valeur avec le libellé (non applicable au type tab ni aux attributs contenu dans un tableau) (Attention aux triple accolades : {{{…}}})

Exemple : Remplacement de l'entête

<h1>Voici le document : "{{document.properties.title}}"</h1>
{{> menu}}
{{> content}}
{{> footer}}

Exemple : Affichage du cadre my_firstframe

{{>header}}
{{> menu}}
<h1>Voici un cadre</h1>
{{{document.attributes.my_firstframe.htmlView}}}
 
{{> footer}}

Ces variables sont remplacées sur le client lors du rendu du document.

4.5.4.4.2 Variables serveur

Le template est aussi analysé par le serveur. Les variables notées entre double crochets sont des variables qui sont remplacées par le contrôleur avant d'être envoyé sur le client.

Les clefs disponibles côté serveur sont celles gérées par le contrôleur.

L'ensemble des clefs ne sont pas les mêmes que celle côté client. En particulier, les clefs de rendu HTML (htmlContent, htmlView) ne sont pas disponibles.

Exemple : Remplacement de l'entête côté serveur

<h1>[[#i18n]]my::This my document[[/i18n]] : "[[document.properties.title]]"</h1>
{{> menu}}
{{> content}}
{{> footer}}

4.5.5 getContextController

La méthode getContextController permet d'ajouter des variables personnalisées au contrôleur de modèles. Le contrôleur de modèles parse les templates côté serveur avant de les envoyer au client.

Elle doit retourner une classe Dcp\Ui\DocumentTemplateContext qui implémente ArrayAccess. L'ajout de nouvelles variables se fait donc en précisant la clef comme index du tableau :

$templateContext[$key] = $value

La valeur peut revêtir trois formes :

  1. Une valeur scalaire pour renseigner une clef simple
  2. Un tableau pour renseigner une liste de clef (répétable)

  3. Une fonction qui retourne soit une valeur scalaire soit un tableau de valeur

    Cette fonction n'est exécutée que si la clé correspondante est présente dans le modèle, au moment du remplacement.

Les variables définies sont disponibles pour tous les modèles du document.

Exemple :

class RenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getContextController(\Doc $document)
    {
        $controller = parent::getContextController($document);
        $controller["myController"] = $document->getFamilyParameterValue("myController");
        $controller["myValues"] = [
            ["myList"=>"Un"],
            ["myList"=>"Deux"]
        ];
        $controller["myDefinition"] = function () use ($document) {
            return $document->getMyComplexDefinition();
        };
        return $controller;
     }
 
     public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["sections"]["footer"]["file"]="MY/customFoot.mustache";
        return $templates;
     }
}

Fichier : MY/customFoot.mustache :

<footer class="dcpDocument__footer">
    <strong>[[myController]]</strong>
 
    <ol>
        [[#myValues]]
            <li>[[myList]]</li>
        [[/myValues]]
    </ol>
    <p>[[myDefinition]]</p>
</footer>

4.5.5.1 Controleur par défaut par défaut

les classes de configuration de rendu par défaut utilisent le contrôleur Dcp\Ui\DocumentTemplateContext.

Ce contrôleur donne accès aux variables suivantes :

4.5.5.1.1 Propriétés

Clef Définition
[[document.properties.id]] Identifiant du document
[[document.properties.initid]] Identifiant de la lignée documentaire
[[document.properties.title]] Titre du document
[[document.properties.icon]] Url de l'icône du document
[[document.properties.revision]] Numéro de révision
[[document.properties.revdate]] Date de révision (YYYY-MM-DD HH:MM)
[[document.properties.status]] Status du document : alive, deleted, fixed
[[document.properties.family.id]] Identifiant de la famille
[[document.properties.family.title]] Titre de la famille
[[document.properties.family.name]] Nom logique de la famille
[[document.properties.family.icon]] Url de l'icône de la famille

4.5.5.1.2 Attributs

Clef Définition
[[document.attribute.<attrid>.label]] Libellé de l'attribut
[[document.attribute.<attrid>.attributeValue.value]] Valeur brute
[[document.attribute.<attrid>.attributeValue.displayValue]] valeur affichable
[[document.attribute.<attrid>.attributeValue.<specialProperty>]] Autres propriétés (Voir formatCollection)

4.5.5.1.3 Fonctions

Clef Définition
[[i18n]] Fonction de traduction

4.5.5.1.3.1 Traduction

Le contrôleur traduit les textes indiqués entre les balises i18n. Le texte traduit doit être fourni par le catalogue de langue du module.

Exemple :

<h1>[[#i18n]]my::Hello world[[/i18n]]</h1>

La clef my::Hello world doit être une entrée traduite du catalogue.

Il est recommandé d'utiliser un préfixe pour chaque traduction afin de ne pas être en conflit avec d'autres traductions.

L'extraction des clefs de traduction peut être réalisée avec le programme xgettextMustache disponible dans les outils de build.

4.5.5.1.4 Exemples

Modification du pied de page pour afficher une valeur.

class MyRenderConfigCustom extends \Dcp\Ui\DefaultView
{
    public function getTemplates(\Doc $document = null) {
        $templates=parent::getTemplates($document);
        $templates["sections"]["footer"]["file"]="MY/customFoot.mustache";
        return $templates;
    }
}

Fichier MY/customFoot.mustache :

<footer class="dcpDocument__footer">
     <strong>[[document.attributes.my_information.attributeValue.displayValue]]</strong>
</footer>

4.5.6 getVisibilities

La méthode getVisibilities permet de redéfinir la visibilité des attributs.

/**
 * @param \Doc $document
 * @return RenderAttributeVisibilities new attribute visibilities
 */
public function getVisibilities(\Doc $document);

Les classes Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit retournent les visibilités par défaut, en fonction du contrôle de vue.

Cette méthode doit retourner un objet de la classe Dcp\Ui\RenderAttributeVisibilities qui contient les visibilités à appliquer pour chacun des attributs.

La classe RenderAttributeVisibilities expose la méthode setVisibility qui permet de modifier la visibilité d'un attribut en particulier. Cette visibilité outrepasse la visibilité par défaut et la visibilité indiquée par un masque provenant du contrôle de vue.

/**
 * Affect new visibility to an attribute
 * This visibility is more prioritary than mask
 * @param string $attributeId attribute identifier
 * @param string $visibility one of I,H,O,R,W,S
 * @return $this
 * @throws Exception
 */
public function setVisibility($attributeId, $visibility);

Les visibilités utilisables sont définies comme constantes de la classe \Dcp\Ui\RenderAttributeVisibilities.

Si une visibilité est appliquée à un attribut structurant, une propagation de cette visibilité sera effectuée.

4.5.6.1 Exemple

Modification des visibilités de 2 attributs en surchargeant la classe de vue par défaut.

use Dcp\Ui\RenderAttributeVisibilities;
use Dcp\AttributeIdentifiers\My_family;
 
class RenderConfigCustom extends \Dcp\Ui\DefaultView
{
    /**
     * @param \Doc $document
     * @return \Dcp\Ui\RenderAttributeVisibilities new attribute visibilities
     */
    public function getVisibilities(\Doc $document)
    {
        $visibilities = parent::getVisibilities($document);
 
        $visibilities->setVisibility(
            My_family::my_tab_info, 
            \Dcp\Ui\RenderAttributeVisibilities::ReadOnlyVisibility
        );
 
        $visibilities->setVisibility(
            My_family::my_tab_annexe,
            \Dcp\Ui\RenderAttributeVisibilities::WriteOnlyVisibility
        );
 
        return $visibilities;
    }
}

4.5.7 getNeeded

La méthode getNeeded permet de redéfinir le caractère obligatoire des attributs.

/**
 * @param \Doc $document
 * @return RenderAttributeNeeded needed attribute list property
 */
public function getNeeded(\Doc $document);

Les classes Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit retournent les obligations par défaut, en fonction du contrôle de vue.

Cette méthode doit retourner un objet de la classe Dcp\Ui\RenderAttributeNeeded qui contient les obligations à appliquer pour chacun des attributs.

La classe RenderAttributeNeeded expose la méthode setNeeded qui permet de modifier l'obligation d'un attribut en particulier. Cette obligation outrepasse l'obligation par défaut ainsi que l'obligation indiquée par un masque issu du contrôle de vue.

/**
 * Affect new needed property to an attribute
 * This property is more prioritary than mask
 * @param string $attributeId attribute identifier
 * @param bool $isNeeded attribut is needed or not
 * @return $this
 * @throws Exception
 */
public function setNeeded($attributeId, $isNeeded);

Cette obligation ne peut pas être appliquée à un attribut structurant, ni à un attribut contenu dans un tableau.

4.5.7.1 Exemple

Modification de l'obligation de 2 attributs en surchargeant la classe de vue par défaut.

use Dcp\Ui\RenderAttributeNeeded;
use Dcp\AttributeIdentifiers\My_family;
 
class RenderConfigCustom extends \Dcp\Ui\DefaultView
{
    /**
     * @param \Doc $document
     * @return \Dcp\Ui\RenderAttributeNeeded new mandatory attribute 
     */
    public function getNeeded(\Doc $document)
    {
        $needed = parent::getNeeded($document);
 
        $needed->setNeeded(My_family::my_phone, true);
        $needed->setNeeded(My_family::my_level, false);
 
        return $needed;
    }
}

4.5.8 getCustomServerData

La méthode getCustomServerData définit des données supplémentaires transmises au client web.

Ces données peuvent ensuite être utilisées sans contrainte par le client au moyen de la méthode getServerCustomData du widget javascript.

 
/**
 * Defined some data to be used by client
 * @param \Doc $document current document to render
 * @return mixed
 */
public function getCustomServerData(\Doc $document);

Les données retournées sont converties en json lors de l'envoi.

Si la donnée est un objet PHP, il est préférable d'implémenter l'interface JsonSerializable pour maîtriser son encodage.

4.5.8.1 Exemple

Le document a un paramètre de type color. Le rendu utilise la valeur pour changer le fond de la de la page.

La classe de rendu, définit les données à envoyer et le traitement javascript à utiliser pour traiter ces données complémentaires.

class RepaintRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getCustomServerData(\Doc $document) {
        return array(
            "repaintColor", $document->getFamilyParameterValue("my_color"),
            "textColor" => $document->getFamilyParameterValue("my_textColor")
        );
    }
 
    public function getJsReferences(\Doc $document=null) {
        $js=parent::getJsReferences($document);
 
        $js["customRepaint"]="MY/Layout/customRepaint.js";
 
        return $js;
    }
}

Sur le client, les données sont récupérées sur le "ready".

MY/Layout/customRepaint.js
window.dcp.document.documentController(
    "addEventListener",
    "ready",
    {
        "name": "my.custom",
        "documentCheck": function (documentObject) {
            return documentObject.family.name === "MY_FAMILY"
        }
    },
    function (event, documentObject, data) {
        var myData=this.documentController("getCustomServerData");
 
        if (myData && myData.repaintColor) {
            $("body").css("background-color", myData.repaintColor);
        }
    }
);

4.5.9 setCustomClientdata

Lors de la demande du rendu, des données complémentaires peuvent être fournies par le client au moyen de la méthode addCustomClientData.

Ces données sont récupérables via la méthode `setCustomClientData.

/**
 * Retrieve some custom data
 *
 * @param mixed $data data provided by client
 *
 * @return mixed
 */
public function setCustomClientData(\Doc $document, $data)

Dans les rendus par défaut (Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit), ces données sont stockées et accessibles dans la variable protégée customClientData.

Le programme de rendu de rendu appelle cette méthode après la construction de l'objet. Ces variables sont alors accessibles pour les autres méthodes.

Cette méthode est appelée après l'enregistrement du document lorsqu'il s'agit d'une demande de création (POST) , de mise à jour (PUT) ou de suppression (DELETE).

Une méthode statique est disponible pour récupérer les données complémentaires depuis d'autres méthodes comme par exemple depuis le hook preStore de l'objet document.

\Dcp\Ui\Utils::getCustomClientData()

Cette méthode retourne la donnée complémentaire décodée qui est fournie dans la requête courante.

4.5.9.1 Exemple

Ajouter un message dans l'historique lors de la sauvegarde.

Sur le client, le code suivant est exécuté :

window.dcp.document.documentController("addEventListener", "beforeSave",
    {
        "name": "my.custom",
        "documentCheck": function (document) {
            return document.family.name === "MY_FAMILY"
        }
    },
    function (event, document, data) {
        this.documentController("setCustomClientData", {"History": "Hello World!"});
    }
);

Le serveur récupère la donnée History pour l'enregistrer dans l'historique lors de la demande de sauvegarde.

class MyConfig extends \Dcp\Ui\DefaultEdit
{
    public function setCustomClientData(\Doc $document, $data)
    {
        if (! empty($data["History"])) {
            $document->addHistoryEntry($data["History"]);
        }
    }
}

4.5.10 getLabel

La méthode getLabel permet de définir le libellé de la vue.

Ce libellé est accessible dans la structure retournée par l'api REST de récupération du rendu au moyen de la clé data.view.renderLabel.

/**
 * Get the label of this view
 * @return string the text label
 */
public function getLabel(\Doc $document=null);

4.5.10.1 Exemple

class ExampleRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getLabel(\Doc $document) {
        return "Example view";
    }
}

Retour du rendu suite à la requête de demande du rendu  

http://www.example.net/api/v1/documents/1211/views/!defaultConsultation
data: {
    uri: "http://localhost/tmp32/api/v1/documents/1211/views/!defaultConsultation",
    properties: {
        requestIdentifier: "!defaultConsultation",
        identifier: "!coreConsultation",
        label: "Core View Consultation",
        uri: "http://localhost/tmp32/api/v1/documents/1211/views/!coreConsultation",
        ...
    },
    uri: "http://localhost/tmp32/api/v1/documents/1211/views/!defaultConsultation",
    view: {
        renderLabel: "Example view",
        documentData: {...}
        locale: {...}
        menu: [...]
        ...
    }
    ...
}

La variable data.properties.label contient le label système du rendu. Ce label est celui du contrôle de vue s'il est utilisé.

4.5.11 getOptions

La méthode getOptions permet de spécifier des options de représentations

/**
 * @param \Doc $document current document to render
 * @return RenderOptions default render configuration options
 */
public function getOptions(\Doc $document);

Les options d'attributs sont différentes en fonction du type de l'attribut. certaines options sont communes à tous les types d'attributs, alors que les autes dépendent du type d'attribut.

Les classes Dcp\Ui\DefaultView et Dcp\Ui\DefaultEdit retournent les options par défaut des attributs.

Cette méthode doit retourner un objet de la classe Dcp\Ui\RenderOptions qui contient les options choisies pour les attributs du document à visualiser.

Les options sont des objets héritant de la classe \Dcp\Ui\BaseRenderOptions. Cette classe permet d'associer chaque option à un ou plusieurs attributs au moyen de la méthode setScope.

En particulier, il existe

Exemple :

$options=new Dcp\Ui\RenderOptions();
$enumOption = new Dcp\Ui\EnumRenderOptions();
$enumOption->setScope(\Dcp\AttributeIdentifiers\My_family::my_continent);
$enumOption->useFirstChoice(false);
$options->setOption($enumOption);

Afin de simplifier la définition des options, des alias sont définis sur la classe Dcp\Ui\RenderOptions :

Type Méthode Classe associée
document document() Dcp\Ui\DocumentRenderOptions
commune common() Dcp\Ui\CommonRenderOptions
account account() Dcp\Ui\AccountRenderOptions
array arrayAttribute() Dcp\Ui\ArrayRenderOptions
color color() Dcp\Ui\ColorRenderOptions
date date() Dcp\Ui\DateRenderOptions
docid docid() Dcp\Ui\DocidRenderOptions
double double() Dcp\Ui\DoubleRenderOptions
enum enum() Dcp\Ui\EnumRenderOptions
file file() Dcp\Ui\FileRenderOptions
frame frame() Dcp\Ui\FrameRenderOptions
htmltext htmltext() Dcp\Ui\HtmltextRenderOptions
int int() Dcp\Ui\IntRenderOptions
image color() Dcp\Ui\ImageRenderOptions
longtext longtext() Dcp\Ui\LongtextRenderOptions
password password() Dcp\Ui\PasswordRenderOptions
money money() Dcp\Ui\MoneyRenderOptions
tab tab() Dcp\Ui\TabRenderOptions
text text() Dcp\Ui\TextRenderOptions
time time() Dcp\Ui\TimeRenderOptions
timestamp timestamp() Dcp\Ui\TimestampRenderOptions

Exemple :

use Dcp\Ui\RenderAttributeNeeded;
use Dcp\AttributeIdentifiers\My_family;
 
class RenderConfigCustom extends \Dcp\Ui\DefaultView
{
    /**
     - @param \Doc $document current document to render
     - @return RenderOptions default render configuration options
     */
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
 
        $options->enum(My_family::my_continent)->display(\Dcp\Ui\EnumRenderOptions::horizontalDisplay);
        $options->money()->setCurrency('EUR');
 
        return $options;
    }
}

4.5.11.1 Remarques

Une option posée pour un attribut identifié est prioritaire sur l'option posée pour un type.

Une option posée pour un type est prioritaire à une option commune posée pour tous les attributs.

Exemple :

use Dcp\Ui\RenderAttributeNeeded;
use Dcp\AttributeIdentifiers\My_family;
 
class RenderConfigCustom extends \Dcp\Ui\DefaultView
{
    /**
     - @param \Doc $document current document to render
     - @return RenderOptions default render configuration options
     */
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
 
        $options->commonOption()->showEmptyContent("Non communiqué");
        $options->commonOption("my_phone")->showEmptyContent("Pas de téléphone");
 
        return $options;
    }
}

4.5.11.2 Options personnalisées

Des options personnalisées peuvent aussi être propagée à la vue du client. Ces options non utilisées sur le rendu standard peuvent être exploitées par un code javascript spécifique.

La méthode setOption permet d'ajouter des options supplémentaires.

Les identifiants de ces options ne doivent pas être en conflit avec les noms des options existantes. Si l'identifiant est un identifiant déjà reconnu, cela revient à modifier ce paramètre de représentation

Les valeurs de l'option peuvent être des nombres, des chaînes de caractères, des tableaux ou tout autre type qui peut être converti en JSON. C'est la donnée convertie en JSON qui sera exploitée.

$options=new Dcp\Ui\RenderOptions();
$options->commonOptions(My_contact::zct_photo)
    ->setOption("MyFirstCustomOption", "MyOptionValue");
    ->setOption("MySecondCustomOption", [
        "One"=>"MyFirstValue",
        "Two"=>"MySecondValue"
    ]);

Exemple récupération en JS :

$.ready(function() {
    //Ajouter un event au ready
    window.dcp.document.documentController(
        "addEventListener",
        "change",
        "my_attr"
        {
            "documentCheck" : function(document) { return document.family.name === "MY_FAMILY"},
            "name": "myEvent.myFamily"
        }, 
        function(document, attribute) {
            // Si l'attribut my_attr égal "GO" alors les attributs ayant l'option MyFirstCustomOption sont cachés
            if (attribute.attributeValue.value === "GO") {
                var attributes = this.documentController("getAttributes");
 
                _.each(attributes, function (attr) {
                    if (attr.getOption("MyFirstCustomOption") === "MyOptionValue") {
                        this.documentController("hideAttribute", attr.id);
                    }
                })
            }
          }
      );
});

4.6 Méthodes de la classe de configuration de rendu de transition

Une configuration de rendu de transition est définie par une classe PHP qui doit implémenter l'interface Dcp\Ui\IRendertransition.

Dans les méthodes d'une configuration de rendu de transition, les utilisations de get et de set peuvent sembler inversées. Ce n'est pas le cas : ces méthodes sont utilisées par la plateforme pour générer le rendu.
Par exemple, la méthode getTransitionParameters est appelée par Dynacase pour obtenir les paramètres à utiliser lors du rendu du document La méthode implémentée ne positionne (set) pas ces visibilités, mais les retourne (get).

4.6.1 getCssReferences

La méthode getCssReferences() retourne une liste de fichiers css à inclure.

string[] getCssReferences(string $transitionId)

Le tableau retourné doit être indexé. L'index identifie le fichier. Le fichier css est ajouté lors de l'affichage de la transition. Il est supprimé lorsque le formulaire est effacé.

L'élément DOM de plus haut niveau est de la classe dcpTransition. Chaque section a sa propre classe comme indiqué dans la méthode \Dcp\Ui\TransitionRender::getTemplates.

De plus, l'élément de haut niveau possède les attributs data-transition et data-state qui contiennent respectivement l'identifiant de la transition et l'identifiant de l'étape suivante. Ces éléments permettent de cibler précisément la transition voulue avec une feuille de style générale.

Le fichier css inséré étant applicable sur l'ensemble du document, il est recommandé de cibler les éléments fils de la classe dcpTransition.

4.6.1.0.1 Exemples

Les fichier css ajoutés ne sont pas enlevés lorsque la fenêtre de transition se ferme. Il sont par contre enlevés lorsqu'on charge un autre document ou un autre rendu.

4.6.2 getJsReferences

La méthode getJsReferences() retourne une liste de fichiers javascript à inclure.

string[] getJsReferences(string $transitionId)

Le tableau retourné doit être indexé. L'index identifie le fichier. Le fichier js est inséré lors de l'affichage de la transition.

Une fois injecté dans la page, le fichier js est ensuite conservé même après la fermeture de la transition.

4.6.3 getRenderOptions

La méthode getRenderOptions() permet de modifier les options de rendu des paramètres de transition.

Dcp\Ui\RenderOptions getRenderOptions(string $transitionId)

Les options de rendu des paramètres de transition se gèrent comme des options de rendu d'attribut.

4.6.3.1 Exemples

4.6.4 getTransitionParameters

La méthode getTransitionParameters() permet de modifier les caractéristiques des paramètres de transitions.

Dcp\Ui\AttributeInfo[] getTransitionParameters(string $transitionId)

Elle doit retourner un array d'objets de la classe \Dcp\Ui\AttributeInfo.

L'attribut cadre dans lequel les attributs sont insérés est identifié par la constante TransitionRender::parameterFrameAttribute;

Si la caractéristique nr de la transition n'est pas true, un attribut TransitionRender::commentAttribute est ajouté à la liste des paramètres. Il inséré dans un cadre propre : TransitionRender::commentFrameAttribute.

Les attributs de types tab ou frame ne peuvent pas être utilisés dans la déclaration des paramètres de la transition.

4.6.4.1 Exemples

4.6.5 getTemplates

La méthode getTemplates permet de modifier les templates utilisés pour générer le formulaire de demande de transition.

String[] getTemplates(string $transitionId)

Le formulaire de demande de transitions est composé d'un corps, lui même calculé à partir des 4 sections suivantes :

  1. transitionHeader : contient le graphe indiquant l'étape de départ et d'arrivée
  2. transitionAsk : contient les champs des paramètres
  3. transitionMessages : contient les messages suite à la demande de transition
  4. transitionButtons : contient les boutons de confirmation et d'annulation

Les modèles par défaut de ces sections sont les suivants :

"sections" => array(
    "transitionHeader" => '<div class="dcpTransition--header"/>',
    "transitionAsk" => '<section class="dcpTransition--ask dcpDocument__body"/>',
    "transitionMessages" => '<div class="dcpTransition--messages"/>',
    "transitionButtons" => '<div class="dcpTransition--buttons"/>'
)

Le corps est une concaténation des 4 sections décrites ci-dessus.

"body" => "{{>transitionHeader}}{{>transitionAsk}}{{>transitionMessages}}{{>transitionButtons}}",

Il est possible d'ajouter des fragments HTML avant ou après chaque sections

4.6.5.0.1 Exemples

4.7 Manipulation des menus

4.7.1 Déclaration

Le définition du menu du document est indiqué dans la classe de configuration de rendu.

Elle est fournie par la méthode IRenderConfig::getMenu().

/**
 * @param \Doc $document Document object instance
 * @return BarMenu Menu configuration
 */
public function getMenu(\Doc $document);

Cette méthode retourne un objet Dcp\Ui\Barmenu qui contient la définition de chacun des éléments constituant le menu.

4.7.2 Éléments de menu

4.7.2.1 Élément de menu simple

Un élément de menu est défini par un objet de la classe Dcp\Ui\ItemMenu.

4.7.2.1.1 Construction

Dcp\Ui\ItemMenu __construct(string $identifier, 
                            string $label = '', 
                            string $url = '')

Arguments :

id
Identifiant du menu : Il doit être unique dans la barre de menu.
label (optionnel)
Texte brut affiché sur le menu
url (optionnel)
Url cible du menu

Exemple :

public function getMenu(\Doc $document) {
    $myMenu = new \Dcp\ui\BarMenu();
 
    $myItem = new \Dcp\Ui\ItemMenu(
        "myTest5",
        ___("My label", "my")
    );
 
    $myItem->setUrl("http://www.example.net");
 
    $myMenu->appendElement($myItem);
 
    return $myMenu;
}

4.7.2.1.2 Définition de l'url

4.7.2.1.2.1 Indiquer une Url statique

L'url est indiquée sur le constructeur ou par la méthode setUrl().

Dcp\Ui\ItemMenu setUrl(string $url)

Cette url peut être relative ou absolue.

L'url est un template Mustache, et accepte les variables suivantes :

Variable Description
document.properties.id Identifiant du document
document.properties.initid Identifiant de la lignée documentaire
document.properties.icon Url de l'icône du document
document.properties.revision Numéro de révision
document.properties.status Statut du document : alive, deleted, fixed
document.properties.title Titre du document
document.properties.renderMode Mode de rendu : view, edit
document.properties.viewId Identifiant de lu rendu
document.properties.family.id Identifiant de la famille
document.properties.family.title Titre de la famille
document.properties.family.name Nom logique de la famille
document.properties.family.icon Url de l'icône de la famille

Exemple :

$myItem->setUrl("http://www.example.net/?id={{document.properties.id}}");
4.7.2.1.2.2 Indiquer la cible du menu

Par défaut, la cible du menu est _self. Elle peut être modifiée par la méthode setTarget().

Dcp\Ui\ItemMenu setTarget(string $target, 
        Dcp\Ui\MenuTargetOptions $dialogOptions=null)

Arguments :

$target

la cible du menu

Si $target vaut _dialog, le résultat de la requête sera affiché dans une fenêtre de dialogue interne.

$dialogOptions

Lorsque la cible est _dialog, la fenêtre de dialogue peut être paramétrée au moyen d'un objet \Dcp\Ui\MenuTargetOptions.

Cet objet a les propriétés suivantes :

title
Titre de la fenêtre de dialogue
windowHeight
Hauteur de la fenêtre de dialogue. Les unités doivent être absolue ("px", "em")
windowWidth
Largeur de la fenêtre de dialogue. Les unités doivent être absolue ("px", "em")

Cette option n'est pas applicable si l'url est celle d'un événement.

Si la cible est _self, les options windowHeight et windowWidth peuvent être utilisée. Par contre l'unité doit obligatoirement être un nombre (exprimé en "px"). Dans ce cas, la fenêtre ouverte ne possède ni menus ni barre d'adresse.

Exemple :

$item = new \Dcp\Ui\ItemMenu(
    "myMessage",
    ___("My message", "My")
);
 
$targetOption = new \Dcp\Ui\MenuTargetOptions();
$targetOption->title = ___("This is my message", "My");
$targetOption->windowHeight = "300px";
$targetOption->windowWidth = "400px";
 
$item->setTarget("_dialog", $targetOption);
4.7.2.1.2.3 Émettre un événement

L'url peut aussi être définie pour être capturée par le client avec du code javascript.

Si l'url est de la forme #action/<eventType>:<option1>:<option2>:..., l'événement peut être capturé par l'écoute de actionClick.

Exemple :

class MyRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getJsReferences() {
        $js=parent::getJsReferences();
        $js["myContact"]="MY/Layout/myCustom.js";
        return $js;
    }
 
    public function getMenu(\Doc $document) {
        $menu = parent::getMenu($document);
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myAlert",
            ___("My alert", "my")
        );
 
        $myItem->setUrl("#action/my:myOptions");
 
        $menu->appendElement($myItem);
 
        return $menu;
    }
}

Fichier MY/Layout/myCustom.js :

window.dcp.document.documentController(
    "addEventListener",
    "actionClick",
    {
        "name": "my.alert",
        "documentCheck": function (documentObject) {
            return (documentObject.family.name === "MY_FAMILY");
        }
    },
    function(event, documentObject, data) {
        if (data.eventId === "my") {
            if (data.options.length > 0 && data.options[0] === "myOptions" ) {
                alert("I catched my event");
            }
        }
    }
);

4.7.2.1.3 Contenu du menu

Le contenu du menu est la partie affichée.

4.7.2.1.3.1 Libellé du menu

Le libellé du menu est indiqué sur le constructeur ou par l'une des méthodes suivantes :

setTextLabel()

La méthode setTextLabel() indique un libellé texte brut. Les caractères spéciaux seront échappées en entités HTML.

Dcp\Ui\ItemMenu setTextLabel(string $label)
setHtmlLabel()

La méthode setHtmlLabel() indique un fragment html qui sera affiché.

Dcp\Ui\ItemMenu setHtmlLabel(string $label)

Dans le cas où les 2 méthodes sont utilisées, le label brut est précédé du label HTML.

4.7.2.1.3.2 Préfixe de menu

Il est possible d'ajouter un préfixe de menu (ce préfixe sera aligné verticalement sur le menu) au moyen des méthodes suivantes :

setBeforeContent

La méthode setBeforeContent() permet d'ajout un fragment HTML avant le texte (par exemple, un caractère font-awesome).

Dcp\Ui\ItemMenu setBeforeContent(string $htmtText)
setIcon

La méthode setIcon() permet d'ajouter une icône avant le texte.

Dcp\Ui\ItemMenu setIcon(string $imagePath, int $imageWidth = 12)

4.7.2.1.4 Tooltip de menu

Dcp\Ui\ItemMenu setTooltipLabel(string $tooltipLabel, bool $html=true)

La méthode setTooltipLabel() permet d'ajouter un texte (brut ou html) comme tooltip qui sera affiché au survol de l'élément.

4.7.2.1.5 Attributs personnalisés sur le menu

Dcp\Ui\ItemMenu setHtmlAttribute(string $attrid, string $value)

La méthode setHtmlAttribute() permet d'ajouter des attributs html quelconque comme par exemple une classe ou des données spécifiques.

Exemple :

public function getMenu_(\Doc $document) {
        $myMenu=new \Dcp\ui\BarMenu();
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myFirstMenu",
            ___("My label", "my")
        );
        $myItem->setUrl("http://www.example.net/?a={{document.properties.id}}");
 
        // Utilisation de caractère fontawesome
        $myItem->setBeforeContent('<div class="fa fa-cog" />');
 
        $myMenu->appendElement($myItem);
 
        $myItem = new \Dcp\Ui\ItemMenu(
            "myHelpMenu"
        );
        $myItem->setUrl("?app=MY&action=HELP");
 
        // Utilisation d'un label gras et rouge
        $myItem->setHtmlLabel('<strong style="color:red">HELP</strong> : ');
 
        // Utilisation d'une icône
        $myItem->setIcon("MY/Images/myHelp.png");
 
        // ajout d'une classe personnalisée
        $myItem->setHtmlAttribute("class","my--menu-help");
 
        $myMenu->appendElement($myItem);
 
        return $myMenu;
    }

4.7.2.1.6 Confirmation d'un menu

Un élément de menu peut demander une confirmation avant d'être envoyé. La confirmation est indiquée par la méthode useConfirm().

Dcp\Ui\ItemMenu useConfirm(string $question,
        Dcp\Ui\MenuConfirmOptions $dialogOptions=null)

Une fenêtre de dialogue modale est affichée avec la question et deux boutons : un bouton de confirmation et un bouton d'annulation.

Arguments :

$question
Un fragment HTML qui contient la question de confirmation.
$dialogOptions

un objet Dcp\Ui\MenuConfirmOptions.

Cet objet a les propriétés de configuration suivantes :

title
Fragment HTML pour le titre de la fenêtre de dialogue (texte variable) Les variables utilisables sont les propriétés du document.
windowWidth
Largeur de la fenêtre (il est nécessaire d'indiquer l'unité)
windowHeight
Hauteur de la fenêtre (il est nécessaire d'indiquer l'unité)
confirmButton
Texte brut du bouton de confirmation ("Confirmer" par défaut) (texte variable) Les variables utilisables sont les propriétés du document.
cancelButton
Texte brut du bouton d'annulation ("Annuler" par défaut) (texte variable) Les variables utilisables sont les propriétés du document.

Exemple extrait de menu de suppression de document :

$item = new ItemMenu("delete", ___("Delete", "UiMenu") , "#action/document:delete");
$item->setTooltipLabel(___("Put document to the trash", "UiMenu"));
 
$confirmOption = new MenuConfirmOptions();
$confirmOption->title = ___("Confirm deletion of {{{document.properties.title}}}");
$confirmOption->confirmButton = ___("Confirm deletion", "UiMenu");
$confirmOption->windowWidth = "350px";
$confirmOption->windowHeight = "150px";
 
$item->useConfirm(sprintf(___("Sure delete %s ?", "UiMenu") , $document->getHtmlTitle()) , $confirmOption);
$item->setBeforeContent('<div class="fa fa-trash-o" />');
$menu->appendElement($item);

4.7.2.2 Liste d'éléments de menu

Un menu peut contenir des éléments simples ou des listes d'éléments (sous-menus).

Une liste d'éléments de menu est définie par un objet de la classe Dcp\Ui\ListMenu.

4.7.2.2.1 Construction

Dcp\Ui\ListMenu __construct(string $identifier,
                            string $label = '')

Arguments :

identifier
Identifiant du menu : Il doit être unique dans la barre de menu.
label
(optionnel): Texte brut affiché sur la liste de menu

4.7.2.3 Liste dynamique d'éléments de menu

La liste dynamique est une liste d'éléments qui est constituée sur le serveur à chaque ouverture de la liste.

Une liste dynamique d'éléments de menu est définie par un objet de la classe Dcp\Ui\DynamicMenu.

4.7.2.3.1 Construction

Dcp\Ui\DynamicMenu __construct(string $identifier,
                               string $label = '')

Arguments :

identifier
Identifiant du menu : Il doit être unique dans la barre de menu.
label
(optionnel): Texte brut affiché sur la liste de menu.

4.7.2.3.2 Génération de la liste

La méthode setContent() permet d'indiquer la méthode qui sera appelée à chaque ouverture de la liste.

Dcp\Ui\DynamicMenu setContent(\Closure $definition)

L'argument $definition est une méthode qui a comme argument l'objet Dcp\Ui\ListMenu en cours. Les éléments de la liste dynamique doivent être ajoutés dans cette liste.

Exemple : Affichage des 10 dernières notes modifiées.

class AllRenderConfigView extends \Dcp\Ui\DefaultView
{
    public function getMenu(\Doc $document) {
        $menu = parent::getMenu($document);
        $lastNoteList = new \Dcp\Ui\DynamicMenu("lastNotes", "Dernières notes");
        $lastNoteList->setContent(function (\Dcp\Ui\ListMenu & $menu) use ($document)
        {
            $s=new \SearchDoc("", "MY_NOTES");
            $s->setSlice(10);
            $s->setOrder("revdate desc");
            $s->setObjectReturn(true);
            $dl=$s->search()->getDocumentList();
            foreach ($dl as $doc) {
                $myNote = new \Dcp\Ui\ItemMenu("doc".$doc->id, $doc->getHtmlTitle());
                $myNote->setUrl(sprintf("#action/document:load:%d",$doc->initid));
                $myNote->setIcon($doc->getIcon());
                $menu->appendElement($myNote);
            }
        });
        $menu->appendElement($lastNoteList);
        return $menu;
    }
}

4.7.2.4 Séparateur

Un élément texte peut être ajouté pour séparer les autres éléments d'une liste ou de la barre de menu.

Un séparateur est défini par un objet de la classe Dcp\Ui\SeparatorMenu.

4.7.2.4.1 Construction

Dcp\Ui\SeparatorMenu __construct(string $identifier, 
                                 string $label = '')

Arguments :

identifier
Identifiant du menu : Il doit être unique dans la barre de menu.
label
(optionnel): Texte brut affiché sur le séparateur.

Les méthodes applicables sont les mêmes que celle du formatage d'un élément simple.

Exemple :

$myItem = new \Dcp\Ui\SeparatorMenu(
    "mySeparator",
    ___("Séparateur", "my")
);
$myItem->setBeforeContent('<div class="fa fa-cog" />');
$menu->appendElement($myItem);

4.7.3 Intégration d'éléments dans un menu

Les classes Dcp\Ui\Barmenu et Dcp\Ui\ListMenu sont des listes d'éléments. À ce titre, elles permettent de gérer les éléments les composant.

4.7.3.1 Ajout d'un élément en fin de liste

L'ajout d'un élément en fin de liste est réalisé par la méthode appendElement().

Dcp\Ui\Barmenu|ListMenu|DynamicMenu appendElement(Dcp\Ui\ElementMenu $elMenu)

Cette méthode ajoute un élément simple ou une autre liste afin de créer des sous-listes.

4.7.3.2 Ajout d'un élément à une position donnée

La méthode insertBefore() insère le nouvel élément avant l'élément indiqué.

Dcp\Ui\Barmenu|ListMenu|DynamicMenu insertBefore(string $menuId, Dcp\Ui\ElementMenu $elMenu)

L'argument $menuId est l'identifiant de l'élément avant lequel le nouvel élément sera est inséré.

La méthode insertAfter() insère le nouvel élément après l'élément indiqué.

Dcp\Ui\Barmenu|ListMenu|DynamicMenu insertAfter(string $menuId, Dcp\Ui\ElementMenu $elMenu)

L'argument $menuId est l'identifiant de l'élément après lequel le nouvel élément sera est inséré.

Exemple :

Trois menus affichés dans une liste affichée en dernier dans la barre de menu.

public function getMenu(\Doc $document) {
    $menu = parent::getMenu($document);
 
    $myList = new \Dcp\Ui\ListMenu("myCustomList", ___("Custom Menu", "my"));
    $myList->setIcon("Images/app_switcher.png");
 
    $myItem = new \Dcp\Ui\ItemMenu("myTest", ___("My label", "my"));
    $myItem->setUrl("?app=TEST&ction=X&id={{document.properties.id}}");
    $myList->appendElement($myItem);
 
    $myItem = new \Dcp\Ui\ItemMenu("myAlert", ___("My alert", "my"));
    $myItem->setUrl("#action/my:myOptions");
    $myList->appendElement($myItem);
 
    $myItem = new \Dcp\Ui\ItemMenu("myHelp", ___("My help", "my"));
    $myItem->setUrl("#action/my:myHelp");
    $myList->insertBefore("myAlert", $myItem);
 
    $menu->appendElement($myList);
    return $menu;
}

4.7.3.3 Suppression d'un élément

La méthode removeElement()` retire un élément de la liste.

Dcp\Ui\BarMenu|ListMenu removeElement(string $menuId)

L'argument $menuId est l'identifiant de l'élément à retirer.

4.7.4 Surcharge d'un élément de menu

Les éléments de menu contenus dans un objet Dcp\UiBarMenu ou Dcp\Ui\ListMenu sont accessibles au moyen de la méthode getElements(), qui retourne un tableau d'éléments.

Array getElements()

Pour accéder à un élément de menu par son id, on peut utiliser la méthode getElement(). L'élément est alors recherché récursivement à partir de la liste depuis laquelle la méthode est appelée.

Dcp\Ui\BarMenu|ListMenu getElement(string $menuId)

Exemple :

Modifier le menu standard de consultation :

public function getMenu(\Doc $document) {
    $myMenu=parent::getMenu($document);
 
    $modifyItem=$myMenu->getElement("modify");
    if ($modifyItem) {
        $myMenu->removeElement("modify");
        $modifyItem->setTextLabel("Afficher le formulaire");
        $myMenu->appendElement($modifyItem);
    }
 
    $myMenu->removeElement("historic");
 
    $deleteItem=$myMenu->getElement("delete");
    if ($deletItem) {
        $deleteItem->setHtmlAttribute("style","background-color:red");
    }
 
    return $myMenu;
}

4.7.5 Visibilité des éléments de menu

Les menus déclarés sont affichés et actifs par défaut. Leur visibilités et leur activation peuvent être modifiées.

Ces états de menu peuvent être ensuite manipulés par le client afin d'inhiber ou désinhiber les menus en fonction des actions sur l'interface.

Dcp\Ui\ElementMenu setVisibility(string $visibility)

Les visibilités possibles sont :

La visibilité est applicable aux éléments simples ou aux listes.

Exemple : Inhibition de la liste myCustomList si l'attribut my_level du document vaut 44.

public function getMenu(\Doc $document) {
    $menu = parent::getMenu($document);
 
    $myList = new \Dcp\Ui\ListMenu("myCustomList", ___("Custom Menu", "my"));
    if ($document->getValue("my_level") === "44") {
        $myList->setVisibility(\Dcp\Ui\ListMenu::VisibilityDisabled);
    }
    $menu->appendElement($myList);
    return $menu;
}

4.7.6 Menus prédéfinis

4.7.6.1 Rendu de consultation

La classe Dcp\Ui\DefaultView retourne un menu avec les éléments suivants :

Identifiant menu Description Note
modify Modifier (Affichage du formulaire)
delete Suppression du document
restore Restauration du document
historic Affichage de l'historique
advanced.properties Affichage des propriétés
advanced.security.lock Verrouillage du document pas implémenté
advanced.security.unlock Déverrouillage du document pas implémenté
workflow Liste des transitions possibles

4.7.6.2 Rendu de modification

La classe Dcp\Ui\DefaultEdit retourne un menu avec les éléments suivants :

Identifiant menu Description note
save Enregistrement du document
save! Enregistrement forcé pas implémenté
create Création et enregistrement
create! Création forcée pas implémenté
close Fermeture (Affichage en mode consultation)
workflow Nom de l'activité (pas de boutons)

4.7.6.3 Événements prédéfinis

Les événements suivants sont écoutés par défaut pour les menus 

url Description
#action/document.close:<viewId> Ouverture avec la rendu "viewId" (optionnel : consultation par défaut)
#action/document.create Enregistrement nouveau document
#action/document.delete Suppression du document
#action/document.edit Ouverture en mode modification
#action/document.history Affichage de l'historique
#action/document.load:<documentId>:<viewId> Ouverture d'un autre document "documentId"
#action/document.properties Affichage des propriétés
#action/document.save Enregistrement du document
#action/document.restore Restauration du document
#action/document.selectTab:<tabId> Sélection d'un onglet de document

4.8 Options de rendu du document

Ces options permettent de modifier la façont dont le document est rendu dans son ensemble.

4.8.1 setTabPlacement

Cette option indique le positionnement des onglets.

Dcp\Ui\DocumentRenderOptions setTabPlacement(string $tabPlacement)

Le widget de gestion des onglets est basé sur un widget [Kendo tab Strip][kendotab].

4.8.1.1 Restrictions

Aucune

4.8.1.2 Paramètres

L'argument tabPlacement peut valoir :

Dcp\Ui\DocumentRenderOptions::tabTopFixPlacement

affichage horizontal en haut "taille des onglets fixe" (par défaut)

Si la largeur de l'ensemble des d'onglets dépasse la largeur de la page, le dernier onglet visible devient un sélecteur permettant d'accéder aux onglets suivants qui ne sont pas affichés.

Pour modifier la largeur d'un onglet dans ce mode, la règle css suivante peut être surchargée :

.dcpDocument__tabs--fixed .dcpTab__label {
    width: 10em;
}
Dcp\Ui\DocumentRenderOptions::tabTopProportionalPlacement

affichage horizontal en haut "taille des onglets variable"

Tous les onglets ont la même largeur qui est proportionnelle à la largeur du document. Tous les onglets sont affichés quelque soit la largeur. Si le texte complet n'a pas la place de s'afficher, il est tronqué (ellipsis).

Dcp\Ui\DocumentRenderOptions::tabLeftPlacement

affichage vertical à gauche

Pour modifier la largeur d'un onglet dans ce mode, la règle css suivante peut être surchargée :

.dcpDocument__tabs--left .dcpDocument__tabs__list {
    width: 10em;
}

4.8.1.3 Cas particuliers

Aucun

4.8.1.4 Exemples

Positionnement à gauche :

$options->document()
    ->setTabPlacement(\Dcp\Ui\DocumentRenderOptions::tabLeftPlacement);

4.8.2 setOpenFirstTab

Cette option permet d'indiquer que l'onglet concerné est le premier affiché lors de la consultation du document.

Dcp\Ui\DocumentRenderOptions setOpenFirstTab(string $tabId)

4.8.2.1 Restrictions

Aucune

4.8.2.2 Paramètres

L'argument tabId indique l'identifiant de l'onglet à ouvrir lors de l'affichage du document.

4.8.2.3 Cas particuliers

4.8.2.4 Exemples

Ouverture de l'onglet my_informations.

$options->document()->setOpenFirstTab(My_family::my_informations);

4.8.3 setStickyTabs

Cette option laisse la barre d'onglet visible lors d'un défilement vertical.

Dcp\Ui\DocumentRenderOptions setStickyTabs(string $height)

4.8.3.1 Restrictions

Aucune

4.8.3.2 Paramètres

Ce paramètre doit indiquer une valeur absolue avec son unité : "100px", "10rem" La valeur "auto" peut être utilisé. Dans ce cas, la valeur sera celle de la barre de menu.

4.8.3.3 Cas particuliers

Aucun

4.8.3.4 Exemples

$options->document()->setStickyTabs('100px');

4.9 Options de rendu des attributs

Descriptions des différentes méthodes de configuration de la représentation des attributs.

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Les restrictions indiquées dans les différents sous-chapitres ne sont pas contrôlés par le client. Toute option qui ne respecte pas ces restrictions est ignorée.

Sur tous les arguments de type "texte" (texte brut ou html) des différentes méthodes d'option de rendu, sauf indication contraire, les textes sont des textes bruts qui ne seront pas parsés par l'analyseur "mustache" pour affecter des parties variables.

Les arguments de type fragment HTML, sauf indication contraire, sont des fragments qui sont insérés dans des div et peuvent contenir un contenu de flux.

4.9.1 Options communes de représentation d'attribut

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.1.1 showEmptyContent

Cette option indique le texte à afficher dans le cas où la valeur de l'attribut est vide.

Dcp\Ui\CommonRenderOptions showEmptyContent(string $htmlText)

4.9.1.1.1 Restrictions

4.9.1.1.2 Paramètres

L'argument en entrée est un fragment html affiché à la place de la valeur de l'attribut lorsque sa valeur est vide.

4.9.1.1.3 Cas particuliers

Aucun

4.9.1.1.4 Exemples

use Dcp\AttributeIdentifiers\My_contact;
class MyCustomRender extends \Dcp\Ui\DefaultView
{
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
 
        $options->commonOption()->showEmptyContent("Non communiqué");
        $options->commonOption(My_contact::zct_civility)
            ->showEmptyContent("Non communiquée");
        $options->commonOption(My_contact::zct_phone)
            ->showEmptyContent('<b class="my-nophone">Pas de téléphone</b>');
        $options->image(My_contact::zct_photo)
            ->showEmptyContent('<img src="MY/Images/my_nophoto.png"/>');
 
        return $options;
    }

4.9.1.2 setLink

Cette option ajoute un hyperlien sur la valeur de l'attribut si celui-ci est affiché.

Dcp\Ui\CommonRenderOptions setLink(Dcp\ui\htmlLinkOptions $linkOption)

4.9.1.2.1 Restrictions

4.9.1.2.2 Paramètres

L'argument en entrée est un objet de type Dcp\Ui\htmlLinkOptions qui configure les différents paramètres du lien :

target
Nom de la fenêtre du navigateur vers laquelle le lien sera envoyé. * Si la valeur est _self (valeur par défaut), la fenêtre courante est utilisée. * Si la valeur est _dialog, une fenêtre de dialogue interne sera utilisée.
title
Message du tooltip du lien visible lorsque le pointeur de la souris est sur le lien. Ce titre est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.
Les parties variables du titre ne sont pas actualisées en cas de modification de la valeur.
url
Url d'accès à la page. L'url est composée lors du rendu de l'attribut et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées. Ces valeurs sont encodées (au moyen de la fonction encodeUriComponent).
Les parties variables de l'url ne sont pas actualisées en cas de modification de la valeur.
urls
Tableau d'url d'accès à la page pour les attributs inclus dans un tableau.
Si l'url à l'index (0 étant la première rangée) de la rangée du tableau est présent, la valeur donnée par le tableau "urls" est utilisé à la place de l'url standard.

Si target est différente de _self les options suivantes sont prises en compte :

windowHeight
Hauteur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). Sinon la dimension est un nombre entier exprimé en pixels.
windowWidth
Largeur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). Sinon la dimension est un nombre entier exprimé en pixels.
windowTitle (seulement si target est égal à _dialog)
Titre de la fenêtre de dialogue. Si cet argument est vide, alors le titre de la page ciblée est utilisée si son accès est autorisé (même domaine). Le titre est composé dynamiquement et les variables définissant la valeur de l'attribut peuvent être utilisées ({{value}} et {{displayValue}} pour tous les types d'attribut).

De plus, lorsque windowHeight ou windowWidth est défini et que target est différent de _self et _dialog, la fenêtre ouverte ne possède ni menus ni barre d'adresse.

Dans le rendus de consultation par défaut ( Dcp\Ui\DefaultView), les liens sont affectés en fonction de la colonne link défini dans la définition de l'attribut.

4.9.1.2.3 Cas particuliers

Pour les attributs "multiple" (type docid, account et enum), les variables de valeurs d'attribut sont des tableaux. Ils doivent être adressés en Mustache par des répétables.

Exemple :

`<b>Voici les valeurs : <ul>{{#.}}<li>{{displayValue}}</li>{{/.}}</ul></b>`

Pour les attributs dans les tableaux, les variables {{value}} et {{displayValue}} sont remplacés par la valeur de l'attribut à la rangée (index) donnée.

Il possible d'utiliser des url différentes par index. Dans ce cas, il faut renseigner la variable "urls" afin de donner des urls spécifiques par rangée.

4.9.1.2.4 Exemples

Sur l'attribut "my_text", ajout d'un lien vers "http://www.example.net".

$linkOption = new \Dcp\ui\htmlLinkOptions();
$linkOption->target = "_dialog";
$linkOption->title = "Go to My page";
$linkOption->windowHeight = "300px";
$linkOption->windowWidth = "500px";
$linkOption->windowTitle = "Mon test {{value}} {{displayValue}}";
$linkOption->url = "http://www.example.net";
$options->text("my_text")->setLink($linkOption);

Sur les images affichage d'une plus grande miniature et affichage de l'image en taille "200px" dans une boite de "200px".

$linkOption = new \Dcp\ui\htmlLinkOptions();
$linkOption->target = "_dialog";
$linkOption->title = ' <h3><img src="{{thumbnail}}&size=100"/>{{displayValue}}</h3>';
$linkOption->url = "{{{url}}}&size=200";
$linkOption->windowHeight = "200px";
$linkOption->windowWidth = "200px";
$options->image()->setLink($linkOption);

Modifier le titre (tooltip) du lien de la relation "myRelation" :

/**
 * @var $link \Dcp\Ui\HtmlLinkOptions
 */
$link = $options->docid(myAttributes::myRelation)->getOption(\Dcp\Ui\CommonRenderOptions::htmlLinkOption);
if ($link) {
    $link->title = "Voir le document de <br/><b>\"{{displayValue}}\"<b>";
}

4.9.1.2.5 Css setLink

La couleur du tooltip généré par l'argument title  est surchargeable à l'aide des règles css suivantes :

Exemple : tooltip écrit en noir sur fond vert pour tous les attributs du cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__linkvalue .tooltip-inner {
    background-color:  #f7f942; /* Green */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__linkvalue.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__linkvalue.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

Exemple : tooltip écrit en noir sur fond rose pour l'attribut' "my_mail"

.dcpAttribute[data-attrid=my_mail]  .tooltip.dcpAttribute__linkvalue .tooltip-inner {
    background-color: #f99adf; /* Pink */
    color: #000000;
}
.dcpAttribute[data-attrid=my_mail] .tooltip.dcpAttribute__linkvalue.tooltip.top .tooltip-arrow {
    border-top-color:  #f99adf;
}
.dcpAttribute[data-attrid=my_mail] .tooltip.dcpAttribute__linkvalue.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f99adf;
}

4.9.1.3 setLabelPosition

Cette option indique le placement du label par rapport à la valeur de l'attribut.

Dcp\Ui\CommonRenderOptions setLabelPosition(string $position)

4.9.1.3.1 Restrictions

4.9.1.3.2 Paramètres

L'argument en entrée peut prendre les valeurs suivantes :

Dcp\Ui\CommonRenderOptions::autoPosition (valeur par défaut)
Le libellé est positionné à gauche de la valeur si la limite de largeur de page ("480px") n'est pas atteinte. Si la limite de largeur de page est atteinte le libellé est positionné au dessus de la valeur. La limite peut être modifiée lors de la définition d'un style personnalisé. Cette limite est indiquée dans la variable less (@grid-float-breakpoint)
Dcp\Ui\CommonRenderOptions::leftPosition
Le libellé est positionné systématiquement à gauche de sa valeur quelle que soit la largeur de la fenêtre. La largeur du libellé correspond à 2/12ème de la largeur disponible.
Dcp\Ui\CommonRenderOptions::upPosition
Le libellé est positionné systématiquement au dessus de la valeur. La valeur et le libellé occupent chacun toute la largeur du document.
Dcp\Ui\CommonRenderOptions::nonePosition
Le libellé n'est pas visible. La valeur occupe toute la largeur du document.

Ces différentes positions sont définies comme des constantes de la classe Dcp\Ui\CommonRenderOptions.

4.9.1.3.3 Cas particuliers

Pour les cadres (type frame) :

Pour les tableaux (type array) :

4.9.1.3.4 Exemples

$options->text("my_attribute")->labelPosition(Dcp\Ui\CommonRenderOptions::leftPosition);

4.9.1.4 setAttributeLabel

Cette option permet de modifier le texte d'un libellé d'attribut.

Dcp\Ui\CommonRenderOptions setAttributeLabel(string $label)

4.9.1.4.1 Restrictions

Aucune

4.9.1.4.2 Paramètres

L'argument $label est un texte brut (et non un fragment HTML) qui sera utilisé comme label de l'attribut.

4.9.1.4.3 Cas particuliers

Aucun

4.9.1.4.4 Exemples

$options->text("my_attribute")->setAttributeLabel("Mon nouveau texte");

4.9.1.5 setDescription

Cette option permet d'afficher une description détaillée pour un attribut.

Dcp\Ui\CommonRenderOptions setDescription(
                                        string $htmlTitle,
                                        string $position = Dcp\Ui\CommonRenderOptions::topPosition,
                                        string $htmlContent = "",
                                        bool   $collapsed = false)

4.9.1.5.1 Restrictions

Aucune

4.9.1.5.2 Paramètres

$htmlTitle
Description courte de l'attribut. Ce texte est en HTML, il convient au développeur d'échapper les éventuelles variables.
$position
Position du texte à afficher. La position du texte dépend aussi du type d'attribut. L'ensemble de ces positions ne sont pas reconnues pour tous les types d'attributs.
$htmlContent
Description longue de l'attribut. Ce texte est en HTML, il convient au développeur d'échapper les éventuelles variables. Ce texte est affiché en dessous du texte du titre. Il est escamotable via un bouton. Un ascenseur est affiché si la longueur de ce texte dépasse la limite. Cette limite ("10em" par défaut) est configurable par css.
$collapsed
Présentation de la description longue lors de l'affichage du document. Par défaut, cette description est affichée. Si le paramètre vaut true alors la description est escamotée. L'utilisateur doit alors cliquer sur le bouton présent sur le titre pour l'afficher.

4.9.1.5.3 Position de la description des attribut non structurant (hors tableau)

Attribut contenant une valeur : type "text", "int", "date", etc. Ne concerne pas ces attributs s'ils sont définis dans un tableau.

Placement "click"

Figure 12. Placement "click"

4.9.1.5.4 Cas particuliers

Le positionnement dans les tableaux est propre à ce type. Voir la position dans les tableaux.

Le positionnement dans les cadres est propre à ce type. Voir la position dans les cadres.

Le positionnement dans les onglets est propre à ce type. Voir la position dans les onglets.

4.9.1.5.5 Variables utilisables dans les textes de descriptions.

Les variables suivantes sont utilisables comme variable "Mustache" dans la description courte ou la description longue.

4.9.1.5.6 Règles css applicables aux descriptions

Les descriptions sont identifiables grâce à la classe dcpAttribute__description.

La description d'un attribut donné peut être repéré en indiquant l'attribut HTML data-attrid sur la règle.

.dcpAttribute__description[data-attrid="tst_ban_etablissement"] {
    ...
}

Modifier la couleur de fond pour toutes les descriptions :

.dcpAttribute__description  {
    background-color:#F4FFBA;
}
/* Flèche vers la droite */
.dcpAttribute__description--left::after {
    border-left-color:#F4FFBA;
}
/* Flèche vers la gauche */
.dcpAttribute__description--right::after {
    border-right-color:#F4FFBA;
}
/* Flèche vers le bas */
.dcpAttribute__description--topLabel::after,
.dcpAttribute__description--topValue::after,
.dcpAttribute__description--top::after {
    border-top-color:#F4FFBA;
}
/* Flèche vers le haut */
.dcpAttribute__description--bottomLabel::after,
.dcpAttribute__description--bottomValue::after,
.dcpAttribute__description--bottom::after {
    border-bottom-color:#F4FFBA;
}

Modifier la couleur de la bordure pour toutes les descriptions :

.dcpAttribute__description {
    border-color:#BFAF00;
}
/* Flèche vers la droite */
.dcpAttribute__description--left::before {
    border-left-color:#BFAF00;
}
/* Flèche vers la gauche */
.dcpAttribute__description--right::before {
    border-right-color:#BFAF00;
}
/* Flèche vers le bas */
.dcpAttribute__description--topLabel::before,
.dcpAttribute__description--topValue::before,
.dcpAttribute__description--top::before {
    border-top-color:#BFAF00;
}
/* Flèche vers le haut */
.dcpAttribute__description--bottomLabel::before,
.dcpAttribute__description--bottomValue::before,
.dcpAttribute__description--bottom::before {
    border-bottom-color:#BFAF00;
}

Supprimer la flèche pour la description de l'attribut "tst_ban_etablissement" :

.dcpAttribute__description[data-attrid="tst_ban_etablissement"]::after,
.dcpAttribute__description[data-attrid="tst_ban_etablissement"]::before {
    display:none;
}

Modifier la hauteur maximale de la description longue :

.dcpAttribute__description__content {
    max-height: 10em; /* hauteur maximale à indiquer */
}

4.9.1.5.7 Exemples

Affichage de descriptions dans diverses positions :

$displayPosition='<b style="float:right;color:orange;border:solid 1px orange;margin-left:2px">{{renderOptions.description.position}}</b>';
 
$options->text(myAttribute::tst_ban_agence)->setDescription(
    $displayPosition."<p>Nom et localisation de l'agence bancaire</p>",
    \Dcp\Ui\CommonRenderOptions::leftPosition);
 
$options->text(myAttribute::tst_ban_etablissement)->setDescription(
    $displayPosition."<p>L'identifiant domestique du compte : code banque<p><b> (5 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::topValuePosition);
 
$options->text(myAttribute::tst_ban_guichet)->setDescription(
    $displayPosition."<p>Le code guichet de la banque<p><b> (5 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::topLabelPosition);
 
$options->text(myAttribute::tst_ban_numcompte)->setDescription(
    $displayPosition."<p>Numéro du compte bancaire<p><b> (11 chiffres ou lettres)</b>",
    \Dcp\Ui\CommonRenderOptions::bottomValuePosition);
 
$options->text(myAttribute::tst_ban_clecompte)->setDescription(
    $displayPosition."<p>Clé du relevé d'identité bancaire<p><b> (2 chiffres)</b>",
    \Dcp\Ui\CommonRenderOptions::rightPosition);
 
$options->text(myAttribute::tst_ban_iban)->setDescription(
    $displayPosition."<p>Le code IBAN <i>(International Bank Account Number)</i> représenté par une série de <b>27</b> chiffres et de lettres</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition, "<p>Reprenant notamment (mais regroupés différemment) le code banque, le code guichet et le numéro de compte</p>",
    true);
 
$options->text(myAttribute::tst_ban_bic)->setDescription(
    $displayPosition."<p>Le code BIC <i>(Business Identifier Code)</i> représenté par une série de <b>11 ou 8</b> lettres .</p>",
    \Dcp\Ui\CommonRenderOptions::bottomPosition);
Différentes options de placement de la description

Figure 13. Différentes options de placement de la description

Ajout d'information complémentaire au libellé. Dans cet exemple, le libellé n'est pas affiché (utilisation de setLabelPosition - nonePosition) mais il est utilisé dans la description qui est affiché au dessus de chaque attribut.

$originalLabel='<p><b>{{label}}</b></p>';
 
$options->text(myAttribute::tst_ban_agence)->setDescription(
    $originalLabel."<p>Nom et localisation de l'agence bancaire</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_etablissement)->setDescription(
    $originalLabel."<p>L'identifiant domestique du compte : code banque <b> (5 chiffres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_guichet)->setDescription(
    $originalLabel."<p>Le code guichet de la banque<b> (5 chiffres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_numcompte)->setDescription(
    $originalLabel."<p>Numéro du compte bancaire<b> (11 chiffres ou lettres)</b><p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_clecompte)->setDescription(
    $originalLabel."<p>Clé du relevé d'identité bancaire <b> (2 chiffres)</b></p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_iban)->setDescription(
    $originalLabel."<p>Le code IBAN <i>(International Bank Account Number)</i> représenté par une série de <b>27</b> chiffres et de lettres</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition, "<p>Reprenant notamment (mais regroupés différemment) le code banque, le code guichet et le numéro de compte</p>",
    true)->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
 
$options->text(myAttribute::tst_ban_bic)->setDescription(
    $originalLabel."<p>Le code BIC <i>(Business Identifier Code)</i> représenté par une série de <b>11 ou 8</b> lettres .</p>",
    \Dcp\Ui\CommonRenderOptions::topPosition)
    ->setLabelPosition(\Dcp\Ui\CommonRenderOptions::nonePosition);
Libellé enrichi avec la description

Figure 14. Libellé enrichi avec la description

Le même exemple avec de la css pour personnaliser l'aspect :

/* Positionnement 2 colonnes pour les attributs du cadre tst_f_dombancaire */
.dcpFrame__content[data-attrid="tst_f_dombancaire"] .dcpAttribute {
    float: left;
    display: inline-block;
    min-height: 34px;
    width: calc(50% - 1em);
    margin-left: 0.5em;
    margin-right: 0.5em;
}
 
/* Colorisation des descriptions d'attributs */
.dcpAttribute__description[data-attrid="tst_ban_agence"] {
    background-color: rgba(0, 128, 50, 0.2);
    border-color: #02bf54;
    background: linear-gradient(to right, #c9de96 0%,#8ab66b 44%, #47bc43 100%);
}
 
.dcpAttribute__description[data-attrid="tst_ban_etablissement"],
.dcpAttribute__description[data-attrid="tst_ban_guichet"],
.dcpAttribute__description[data-attrid="tst_ban_numcompte"],
.dcpAttribute__description[data-attrid="tst_ban_clecompte"] {
    background-color: rgba(15, 61, 128, 0.2);
    border-color: #0062bf;
    background: linear-gradient(to right, #e4f5fc 0%,#bfe8f9 34%,#2ab0ed 71%,#9fd8ef 100%);
}
.dcpAttribute__description[data-attrid="tst_ban_iban"],
.dcpAttribute__description[data-attrid="tst_ban_bic"] {
    background-color: rgba(128, 63, 13, 0.2);
    border-color: #bf7410;
    background: linear-gradient(to right, #fceabb 0%,#fccd4d 37%,#f8b500 70%,#fbdf93 100%);
}
 
/* Alignement des descriptions pour le mode 2 colonnes */
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description {
    min-height:6em;
}
/* Suppression de la flêche pour les description du cadre tst_f_dombancaire */
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description::after,
.dcpFrame[data-attrid="tst_f_dombancaire"] .dcpAttribute__description::before  {
    display:none;
}
Libellé enrichi avec css

Figure 15. Libellé enrichi avec css

4.9.1.6 setLinkHelp

Cette option permet d'associer un document d'aide avec un attribut.

Dcp\Ui\CommonRenderOptions setLinkHelp(string|int $documentIdentifier)

Un document d'aide est un document de la famille HELPPAGE. Ce document permet de fournir des descriptions statiques sur les attributs. À la différence de l'option setDescription, cette option va afficher un lien (indiqué par l'icone ) vers un document d'aide complet lié à la famille et non une description contextuelle.

Ce lien va afficher le document d'aide dans une fenêtre de dialogue en pointant vers le paragraphe lié à l'attribut.

Dans le rendu d'édition par défaut (classe Dcp\Ui\DefaultEdit), tous les attributs définis dans le document d'aide associé à la famille ont cette option.

Dans les rendus de consultation (classe Dcp\Ui\DefaultView) et d'édition par défaut un menu " Aide" est ajouté. Ce menu ouvre le document d'aide dans une fenêtre de dialogue.

Dans ces 2 classes de rendu, le document d'aide est fourni par la méthode :

protected function getDefaultHelpPageDocument(\Doc $document)

Cette méthode retourne le document de la famille HELPPAGE qui est associé avec la famille du document. Elle ne recherche pas une aide parmi les familles parentes si le document d'aide liés exactement à la famille n'existe pas. S'il y a plusieurs documents d'aide c'est le premier, ordonné par titre, qui est retourné.

Cette méthode peut être surchargée, dans la classe de rendu, pour utiliser un autre document d'aide ou pour simplement ne pas afficher l'aide par défaut.

4.9.1.6.1 Restrictions

Aucunes.

4.9.1.6.2 Paramètres

L'argument $documentIdentifier indique l'identifiant du document d'aide à ouvrir. Cet identifiant doit indiquer un document de la famille "HELP".

La méthode retourne une exception si l'identifiant ne correspond pas à un document de la famille HELPPAGE.

4.9.1.6.3 Cas particuliers

Aucun

4.9.1.6.4 Exemples

Lier l'attribut "my_attribute" avec le document d'aide qui a le nom logique "MY_SPECIAL_HELP".

$options->text("my_attribute")->setLinkHelp("MY_SPECIAL_HELP");

Utilisation du dernier document d'aide créé.

namespace My;
class MyViewRender extends \Dcp\Ui\DefaultView {
    protected function getDefaultHelpPageDocument(\Doc $document) {
        $s = new \SearchDoc("", "HELPPAGE");
        // Filtre sur les aides liés à la famille du document
        $s->addFilter("help_family='%d'", $document->fromid);
        $s->setOrder("id desc"); // L'id indique l'ordre de création
        $s->setSlice(1);
        $s->setObjectReturn();
        $helps = $s->search();
        if (count($helps) > 0) {
            return $helps->getNextDoc();
        }
        return null;
    }
}

4.9.1.7 displayDeleteButton

Cette option indique si le bouton de suppression doit être affiché ou non.

Dcp\Ui\CommonRenderOptions displayDeleteButton(bool $display)

4.9.1.7.1 Restrictions

4.9.1.7.2 Paramètres

L'argument $display indique si le bouton de suppression doit être affiché. Le bouton de suppression est affiché par défaut.

4.9.1.7.3 Cas particuliers

Aucun

4.9.1.7.4 Exemples

$options->text("my_attribute")->displayDeleteButton(false);

4.9.1.8 setInputTooltip

Cette option indique un texte à afficher lorsque le champ de l'attribut à saisir a le focus. Le tooltip n'est pas affiché au survol (hover), mais lorsque le champ de saisie obtient le focus.

Dcp\Ui\CommonRenderOptions setInputTooltip(string $htmlText)

4.9.1.8.1 Restrictions

4.9.1.8.2 Paramètres

L'argument htmlText est un fragment HTML qui sera utilisé pour le texte du tooltip.

4.9.1.8.3 Cas particuliers

Aucun

4.9.1.8.4 Exemples

4.9.1.8.5 Css setInputTooltip

La couleur de ce tooltip est surchargeable à l'aide des règles css suivantes :

Exemple tooltip écrit en noir sur fond jaune pour le cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__editlabel .tooltip-inner {
    background-color:  #f7f942; /* Yellow */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__editlabel.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__editlabel.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

4.9.1.9 setAutoCompleteHtmlLabel

Cette option permet d'afficher un tooltip lorsque la souris passe au dessus du bouton de déclenchement de l'aide à la saisie. Par défaut aucun tooltip n'est affiché.

Dcp\Ui\CommonRenderOptions setAutoCompleteHtmlLabel(string $htmlText)

4.9.1.9.1 Restrictions

4.9.1.9.2 Paramètres

L'argument htmlText est un fragment HTML qui sera utilisé pour le texte du tooltip.

4.9.1.9.3 Cas particuliers

Aucun

4.9.1.9.4 Exemples

$options->text(My_family::my_workpostalcode)
{{Hello>setAutoCompleteHtmlLabel("Choisissez un code postal du <b>Gers</b>");

4.9.1.9.5 Css setAutoCompleteHtmlLabel

La couleur de ce tooltip est surchargeable à l'aide des règles css suivantes :

Exemple tooltip écrit en noir sur fond jaune pour le cadre "my_frame"

.dcpFrame__content[data-attrid=my_frame]  .tooltip.dcpAttribute__autocomplete .tooltip-inner {
    background-color:  #f7f942; /* Yellow */
    color: #000000;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__autocomplete.tooltip.top .tooltip-arrow {
    border-top-color:  #f7f942;
}
.dcpFrame__content[data-attrid=my_frame] .tooltip.dcpAttribute__autocomplete.tooltip.bottom .tooltip-arrow {
    border-bottom-color:  #f7f942;
}

4.9.1.10 addButton

Cette option ajoute un bouton à droite de la valeur.

En mode édition il est placé à gauche du bouton de suppression.

En mode consultation, il est placé à l'extrémité droite de la valeur.

Dcp\Ui\CommonRenderOptions addButton(Dcp\Ui\ButtonOptions $buttonOptions)

4.9.1.10.1 Restrictions

4.9.1.10.2 Paramètres

L'argument en entrée est un objet de type Dcp\Ui\ButtonOptions qui configure les différents paramètres du bouton.

target
Nom de la fenêtre du navigateur vers laquelle le lien sera envoyé. Si le nom est _dialog , une fenêtre de dialogue interne sera utilisée. Dans ce cas, les options suivantes sont prises en compte : windowHeight : Hauteur de la fenêtre de dialogue La dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). windowWidth : Largeur de la fenêtre de dialogue La dimension doit être une dimension css valable (c'est à dire un nombre suivi immédiatement de son unité). windowTitle : Titre de la fenêtre de dialogue. Si cet argument est vide alors le titre de la page ciblée est utilisé si son accès est autorisé (même domaine). Le titre est composé dynamiquement et les variables {{value}} et {{displayValue}} peuvent être utilisées.
title
Texte HTML du tooltip du bouton visible lorsque le pointeur de la souris est sur le lien. Ce texte est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.
url
Url d'accès à la page. L'url est composée dynamiquement et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées. Ces valeurs sont encodées (au moyen de la fonction encodeUriComponent).
htmlContent
Texte du bouton (fragment HTML de contenu phrasé). Ce texte est un fragment HTML et les variables de valeur d'attribut ({{value}} et {{displayValue}}) peuvent être utilisées.
class
Classe css supplémentaire à mettre sur le bouton afin de personnaliser le bouton par css ou l'identifier par javascript.

4.9.1.10.3 Cas particuliers

Pour les attributs "multiple" (type docid, account et enum), les variables de valeurs d'attribut sont des tableaux. Ils doivent être adressés en Mustache par des répétables.

Exemple :

`<b>Voici les valeurs : <ul>{{#.}}<li>{{displayValue}}</li>{{/.}}</ul></b>`

4.9.1.10.4 Exemples

$buttonConfig = new ButtonOptions();
$buttonConfig->url = "?app=MYAPP&action=MY_SENDRESPONSE&myto={{value}}";
$buttonConfig->title = "Send a mail to response";
$buttonConfig->class = "myClass";
$buttonConfig->target = "_dialog";
$buttonConfig->htmlContent = "<b>Send it</b>";
$options->text("my_mail")->addButton($buttonConfig);

Afficher un bouton sur une relation pour avoir un aperçu du document.

$viewDoc=new \Dcp\Ui\ButtonOptions();
$viewDoc->htmlContent='<i class="fa fa-eye"></i>';
$viewDoc->url=sprintf("api/v1/documents/{{value}}.html" );
$viewDoc->target="_dialog";
$viewDoc->windowWidth="400px";
$options->docid("my_relation")->addButton($viewDoc);

4.9.1.11 setTemplate

Permet de définir le template à utiliser pour afficher la valeur de l'attribut.

Ce template ne s'applique qu'à la valeur et pas au label. Le label peut être effacé si nécessaire avec l'option de rendu setLabelPosition.

Dcp\Ui\CommonRenderOptions setTemplate(string $htmlText
                                        array $extraKeys = array()) )

4.9.1.11.1 Restrictions

En consultation, le template n'est pas appliqué si la valeur est vide. Dans ce cas, c'est l'option showEmptyContent qui est appliquée.

4.9.1.11.2 Exception

Si un des templates ajoutés n'existe pas alors l'exception suivante est déclenchée à l'exécution :

UI0004 = 'Render template file not found : %s'

4.9.1.11.3 Paramètres

L'argument $htmlText est un template Mustache.

L'argument $extraKeys est un tableau de clés additionnelles.

4.9.1.11.4 Déclaration d'un modèle

Exemple :

$options->frame("my_frame")->setTemplate('<div class="my">{{{attributes.my_firstattr.htmlContent}}}</div>');
 
$options->text("my_text")->setLabelPosition("none");
$options->text("my_text")->setTemplate(
    '<div class="my">{{attributes.my_text.label}}/{{attributes.my_text.id}}'.
                   ' {{attributes.my_text.attributeValue.value}}</div>');
 
// récupération du modèle dans un fichier (chemin relatif au répertoire d'installation)
$options->text("my_info")->setTemplate(file_get_contents("MYAPP/Templates/myInfo.mustache"));

Applicable à tous les types, y compris "array", même si ce dernier offre d'autres possibilités dans la déclaration d'un template spécifique comme cela est décrit dans les chapitres suivants.

La visibilité est applicable au contenu donc à l'ensemble du template d'attribut.

4.9.1.11.5 Clefs applicables au template

Le template est un template Mustache.

Clef Signification
{{properties.id}} Identifiant du document
{{properties.name}} Nom logique du document
{{properties.initid}} Identifiant de la lignée du document
{{properties.icon}} Url de l'icône du document
{{properties.title}} Titre du document
{{properties.family.title}} Titre de la famille du document
{{properties.family.id}} Identifiant de la famille du document
{{properties.family.icon}} Icône de la famille du document
{{properties.isReadMode}} (booléen) Indique si le rendu de document est en mode consultation
{{properties.isWriteMode}} (booléen) Indique si le rendu de document est en mode modification
{{attributes.attrid.label}} Libellé de l'attribut attrid
{{attributes.attrid.attributeValue.value}} Valeur brute de l'attribut attrid
{{attributes.attrid.attributeValue.displayValue}} Valeur affichable de l'attribut attrid
{{attributes.attrid.attributeValue.[y]}} Information de content supplémentaire suivant le type d'attribut
{{attributes.attrid.label}} Libellé de l'attribut attrid
{{attributes.attrid.isReadMode}} Valeur booléenne indiquant que le mode d'affichage de l'attribut est la consultation
{{attributes.attrid.isWriteMode}} Valeur booléenne indiquant que le mode d'affichage de l'attribut est la modification
{{attributes.attrid.isEmpty}} Valeur booléenne indiquant que l'attribut a une valeur vide (chaîne vide ou "null", tableau vide pour les multiples). 0 n'est pas considéré comme vide. Pour les structures, isEmpty est vrai si tous ses éléments sont vides aussi.
{{attributes.attrid.renderOptions}} Paramètres de rendu comme par exemple "labelPosition" ou "showEmptyContent"
{{{attributes.attrid.htmlContent}}} Fragment html interne correspondant à l'attribut x (fonction de la visibilité et du mode de rendu)
{{{attributes.attrid.htmlView}}} Fragment html interne correspondant label + content (non applicable au type tab ni aux attributs contenu dans un tableau)
{{{attributes.attrid.htmlDefaultContent}}} Idem htmlContent sauf que dans ce cas, si l'attribut a lui-même un template spécifique alors il ne sera pas pris en compte
{{{attributes.attrid.htmlDefaultView}}} Idem htmlView sauf que dans ce cas, si l'attribut a lui-même un template spécifique alors il ne sera pas pris en compte
{{attribute.label}} Label de l'attribut courant
{{attribute.attributeValue.value}} Valeur brute de l'attribut courant (uniquement pour les attributs non structurant)
{{attribute.attributeValue.displayValue}} Valeur affichable de l'attribut courant
{{attribute.attributeValue.[y]}} Information de content supplémentaire: suivant le type d'attribut
{{attribute.renderOptions}} Paramètres de rendu de l'attribut comme par exemple "labelPosition" ou "showEmptyContent"
{{{attribute.htmlContent}}} Fragment html interne de l'attribut courant (contenu seulement sans le label)
{{{attribute.htmlView}}} Fragment html interne de l'attribut courant (label + content) (non applicable au type tab)
{{{attribute.htmlDefaultContent}}} Idem htmlContent sauf que dans ce cas, si l'attribut a lui-même un template spécifique alors il ne sera pas pris en compte
{{{attribute.htmlDefaultView}}} Idem htmlView sauf que dans ce cas, si l'attribut a lui-même un template spécifique alors il ne sera pas pris en compte
{{attribute.id}} Identifiant de l'attribut courant
{{attribute.isReadMode}} Valeur booléenne indiquant que le mode est la consultation (Utilisable pour avoir un template conditionnel en fonction du mode)
{{attribute.isWriteMode}} Valeur booléenne indiquant que le mode d'affichage de l'attribut est la modification
{{attribute.isEmpty}} Valeur booléenne indiquant que l'attribut a une valeur vide. Ne peux pas être utilisé en consultation car si la valeur est vide, l'attribut n'est pas affiché (Voir showEmptyContent)

Pour les attributs multiples, la valeur de attribute.attributeValue ou attributes.<attrid>.attributeValue est un tableau de valeur.

Exemple pour ajouter une <div> autour d'un attribut :

$options->account(MyFamily::my_text)->setTemplate(
'<div style="outline:solid 1px red;padding:5px;">
        {{{attribute.htmlDefaultView}}}
  </div>');

On notera dans cet exemple, l'utilisation de htmlDefaultView et non htmlView afin d'indiquer explicitement qu'on utilise pas notre propre template personnalisé.

Exemple de modèle pour un attribut de type account multiple

$options->account(MyFamily::my_account_multiple)->setTemplate(
    '<div style="border:solid 1px grey;padding:5px;">
            <ol>
                 {{#attribute.attributeValue}}
                 <li><img src="{{icon}}"> {{displayValue}}</li>
                  {{/attribute.attributeValue}}
            </ol>
      </div>');

Si l'attribut a modifier est dans un tableau alors les clefs en attributes.<attrid>.* sont restreintes au seul attrid de l'attribut courant. Il n'est donc pas possible dans ce cas de représenter un autre attribut que l'attribut courant.

4.9.1.11.6 Modèle de tableau

Les clefs supplémentaires suivantes sont disponibles pour les tableaux.

Clef Signification
{{attributes.<arrayAttrid>.rows}} Liste des lignes de tableaux ("arrayAttrid" est un attribut de type tableau)
{{content.<attrid>.label}} Label de l'attribut "attrid" (élément de rows)
{{{content.<attrid>.htmlContent}}} Fragment html interne de la cellule y (élément de "rows") .
{{content.<attrid>.attributeValue.value}} Valeur brute (élément de "rows")
{{content.<attrid>.attributeValue.displayValue}} Valeur affichable (élément de "rows")
{{content.<attrid>.attributeValue.[z]}} Information de content supplémentaire suivant le type d'attribut (élément de "rows")
...
{{attribute.rows}} Liste des lignes du tableau courant
{{index}} Numéro de la rangée (élément de "rows")

Le template de tableau doit contenir une balise table avec la classe dcpArray__table pour indiquer le container qui sera utilisé pour représenter l'attribut.

Les classes de styles et les attributs nécessaires au fonctionnement du widget de tableau seront ajoutés au modèle pour disposer d'un comportement et d'un aspect similaire au tableau original.

Exemple de modèle de tableau :

<table class="dcpArray__table">
    <thead>
        <tr>
            <th class="special">Identification</th>
            <th>Deuxième et troisième cellules</th>
        </tr>
    </thead>
    <tbody>
    {{#attribute.rows}}
        <tr>
            <td>
                <b>{{content.my_firstcell.label}}</b>
                <br/>
                {{{content.my_firstcell.htmlContent}}}
            </td>
            <td>
                {{{content.my_secondcell.htmlContent}}}
                <br/>
                {{{content.my_thirdcell.htmlContent}}}
            </td>
        </tr>
    {{/attribute.rows}}
    </tbody>
</table>

Si le modèle de tableau n'est pas une balise table, il est nécessaire de préciser la classe dcpArray__content__line dans l'élement qui sera considéré comme la rangée (tr).

Exemple de modèle de tableau contenant un attribut image (my_photo) et un attribut relation (my_species) avec des balises div :

<div class="dcpArray__table">
      {{#attribute.rows}}
       <div class="dcpArray__content__line">
            {{#content.my_photo.attributeValue.value}}
               <img class="my__photo" src="api/v1/documents/{{properties.id}}/images/my_photo/{{index}}/sizes/60x60c.png" />
            {{/content.my_photo.attributeValue.value}}
            {{^content.my_photo.attributeValue.value}}
               <img class="my__nophoto" src="api/v1/images/assets/sizes/60x60c/zoo_nophoto.png" />
            {{/content.my_photo.attributeValue.value}}
            <div>{{{content.my_species.htmlContent}}} </div>
        </div>
    {{/attribute.rows}}
</div>

4.9.1.11.7 Complément pour la modification de tableau

En mode "modification", le modèle général de tableau n'affiche pas les boutons pour supprimer, sélectionner et ajouter des lignes.

Pour placer ces éléments d'interface il faut les insérer explicitement dans le modèle.

<table class="dcpArray__table">
    <thead>
        <tr>
            {{#attribute.toolsEnabled}}<th>Outils</th>{{/attribute.toolsEnabled}}
            <th class="special">
                Identification
            </th>
            <th>
                Deuxième et troisième cellules
            </th>
        </tr>
    </thead>
    <tbody>
    {{#attribute.rows}}
        <tr>
            {{#attribute.toolsEnabled}}<td>{{{rowTools}}}</td>{{/attribute.toolsEnabled}}
            <td>
                <b>{{content.my_firstcell.label}}</b>
                <br/>
                {{content.my_firstcell.htmlContent}}
            </td>
            <td>
                {{content.my_secondcell.htmlContent}}
                <br/>
                {{content.my_thirdcell.htmlContent}}
            </td>
        </tr>
    {{/attribute.rows}}
    </tbody>
</table>
<div>
    {{{attribute.tableTools}}}
</div>
Clef Signification
{{rowTools}} Boutons de gestion de la rangée de tableau (élément de rows)
{{attributes.attrid.tableTools}} Boutons de gestion du tableau attrid (contient le boutons d'ajout et de duplication)
{{attributes.attrid.toolsEnabled}} Booléen indiquant que le tableau peut être modifié (ajout, suppression, déplacement de lignes)

 : Pour avoir un même modèle de tableau en consultation et en modification, il est possible d'afficher les boutons suivant la variable {{attribute.toolsEnabled}}.

Les modèles de tableau pour les formulaires doivent être basés sur des tableaux (balise table) HTML.

4.9.1.11.8 Modèle d'attribut contenu dans un tableau

Les attributs qui sont dans un tableau disposent des mêmes possibilités que les modèles classiques. La différence se situe au niveau de la clef {{attribute.attributeValue}}. Cette clef retourne la valeur de l'attribut en fonction de la rangée du tableau et non un tableau de valeurs.

Note : Pour les attributs "multiple" dans un tableau, la valeur est un tableau qui contient la liste de valeurs de l'attribut pour la rangée.

4.9.1.11.9 Ajouter des clefs de modification

En plus des clefs prédéfinies des clefs supplémentaires peuvent être fournies pour le modèle.

$options->docid(MyFamily::my_relation)->setTemplate(
    "<div style=\"border:inset 3px orange\">{{{Hello}}}<h1>{{attribute.id}}</h1> {{{attribute.htmlContent}}}</div>",
        array("Hello"=>"<h1>World</h1>")
);

Ces clefs sont des variables Mustache, elles peuvent aussi être utilisées dans un itérateur (valeur de type array) ou pour une condition.

$options->docid()->setTemplate("<div>{{{Hello}}}<ol>{{#NumberList}}<li>{{Number}}</li>{{/NumberList}}</ol>
                                    <h1>{{attribute.id}} / {{attribute.label}}</h1>
                                    {{{attribute.htmlContent}}}</div>",
        array("Hello"=>"<h1>World</h1>",
             "NumberList"=>array(array("Number"=>"One"),
                                 array("Number"=>"Two"),
                                 array("Number"=>"Three")))
        );

Pour ajouter des clefs dans les rangées d'un tableau, il faut utiliser "attributes.rows".

Exemple d'utilisation des clefs pour renseigner la composition de la dernière colonne d'un tableau.

$options->arrayAttribute("zoo_array_dates")->setTemplate('
         <table class="dcpArray__table"" rules="all" style="border:solid 3px orange; ">
            <thead>
                <tr>
                    <th class="special dcpArray__head__cell">
                        Identification : {{attributes.zoo_date_array.label}}
                    </th>
                    {{#attribute.isWriteMode}}
                        <th class="dcpArray__head__cell">
                            Tools
                        </th>
                    {{/attribute.isWriteMode}}
                    <th class="dcpArray__head__cell">
                        Deuxième et troisième cellules
                    </th>
                    <th class="dcpArray__head__cell">
                        Extra custom {{customTitle}}
                    </th>
                </tr>
            </thead>
            <tbody>
            {{#attribute.rows}}
                <tr>
                    <td>
                        <b>{{content.zoo_date_array.label}}</b>
                        <br/>
                        {{{content.zoo_date_array.htmlContent}}}
                    </td>
                    {{#attribute.isWriteMode}}
                        <td>
                            {{{rowTools}}}
                            <br/>
                            THE TOOLS IN THE MIDDLE
                        </td>
                    {{/attribute.isWriteMode}}
                    <td>
                        {{{content.zoo_time_array.htmlContent}}}
                        <br/>
                        {{{content.zoo_timestamp_array.htmlContent}}}
                    </td>
                    <td>
                        {{custom.foo}}/{{custom.bar}}/{{customTitle}}
                    </td>
                </tr>
            {{/attribute.rows}}
            </tbody>
        </table>
        <div style="border:solid 2px green; font-size:200%">
            The table tools
            {{#attribute.isWriteMode}}
                {{{attribute.tableTools}}}
            {{/attribute.isWriteMode}}
        </div>
     ', array(
        "customTitle" => "Titre personnalisé",
        "attribute" => array(
            "rows" => array(
                "custom" => array(
                    array(
                        "foo" => "One",
                        "bar" => "Uno"
                    ) ,
                    array(
                        "foo" => "Two",
                        "bar" => "Duo"
                    ) ,
                    array(
                        "foo" => "Three",
                        "bar" => "Trio"
                    ) ,
                )
            )
        )
    ));

4.9.1.12 setTranslations

Configuration des différents textes utilisés dans les interfaces des attributs. Ces textes sont par défaut configurés et sont modifiés suivant la locale de l'utilisateur connecté.

Dcp\Ui\CommonRenderOptions setTranslations(array $labels)

4.9.1.12.1 Restrictions

Les textes à traduire sont fonction des types d'attributs.

Les labels suivants sont communs à tous les types :

Suivant les types d'autres textes peuvent être traduits :

4.9.1.12.2 Paramètres

L'argument $labels est un tableau php contenant chacun des labels défini par sa clé.

4.9.1.12.3 Cas particuliers

4.9.1.12.4 Exemples

$options->commonOption("my_attribute")->setTranslations(
    array(
        "closeErrorMessage"=>___("Close error message","my"),
        "deleteLabel"=>___("Remove attribute value","my")
    )
);

4.9.1.13 setCustomWidgetAttributeFunction

Modification du widget utilisé pour rendre l'attribut

Dcp\Ui\CommonRenderOptions setCustomWidgetAttributeFunction(string $widgetFunctionName)

4.9.1.13.1 Restrictions

Le nom du widget doit être le nom d'un widget héritant de $.dcp.dcpAttribut qui est ajouté dans le contexte d'exécution du document avant le rendu du widget.

4.9.1.13.2 Paramètres

L'argument $widgetFunctionName est un nom de widget jquery ui héritant de $.dcp.dcpAttribut.

4.9.1.13.3 Cas particuliers

Aucun.

4.9.1.13.4 Exemples

Cet exemple associe le widget myCustomAttribute à l'attribut my_attribute.

Déclaration de l'option dans le options de rendu :

/**
 * L'attribut `my_attribute` utilisera le widget `myCustomAttribute`.
 */
public function getOptions(\Doc $document)
{
    $options = parent::getOptions($document);
    $options->text("my_attribute")->setCustomWidgetAttributeFunction("myCustomAttribute");
 
    return $options;
} 
/**
 * Ajout du fichier JS contenant le code du nouveau widget
 */
public function getJsReferences(\Doc $document = null)
{
    $js = parent::getJsReferences();
    $js["myWidget"] = "MY/Layout/myWidget.js";
    return $js;
}

Fichier "myWidget.js" de définition d'un nouveau widget d'attribut.

$.widget("myproject.myCustomAttribute",$.dcp.dcpAttribute, {
 
    /**
     * Init the dom of the attribute
     * @private
     */
    _initDom: function ()
    {
        this._super();
 
        if(this.getMode() === "write"){
            //Add code for write representation of the attribute
        }
        else{
            //Add code for consult representation of the attribute
        }
    },
 
    /**
     * Init the event of the attribute
     * @private
     */
    _initEvent: function () {
        //Add the custom event of the attribute
        this._super();
    },
 
    /**
     * Modify value to widget and send notification to the view
     * @param value
     */
    setValue: function wDcpViewTreeSetValue(objValue) {
        this._super(objValue);
        //Add code for the modification of the value of the attribute
    },
 
    /**
     * Return the value stored in the wiget
     *
     * @returns {*|number|.options.attributeValue}
     */
    getValue: function wDcpViewTreeGetValue() {
        let value = this._super();
        //Add code for the consultation of the value of the attribute
        return value;
    },
 
    getType: function wDcpViewTreegetType() {
        //return the type of the attribute
        return "myAttribute";
    }
});

Autre exemple :

$options->htmltext()->setCustomWidgetAttributeFunction("dcpText");

Dans ce cas, tous les attributs de type htmltext sont rendus comme des attributs de type text. Le résultat est que la valeur brute (texte avec les balises html) apparaitra à la place du texte formaté.

4.9.2 Options de représentation type account

Le type account bénéficie des options de représentation de l'attribut de type docid.

Aucune méthode spécifique n'est disponible pour l'attribut account.

4.9.3 Options de représentation type array

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.3.1 setRowCountThreshold

Cette option indique que le nombre de rangées d'un tableau doit être affiché lorsqu'il est supérieur à un certain seuil.

Par défaut, le nombre de rangée n'est pas affiché.

Dcp\Ui\ArrayRenderOptions setRowCountThreshold(int $number)

4.9.3.1.1 Restrictions

Aucune

4.9.3.1.2 Paramètres

Si L'argument number est :

4.9.3.1.3 Cas particuliers

Aucun

4.9.3.1.4 Exemples

Affichage du nombre à partir de 10 rangées.

$options->arrayAttribute(My_family::my_definition)->setRowCountThreshold(10);

4.9.3.2 disableRowAdd

Cette option permet d'inhiber la possibilité d'ajouter une rangée dans un tableau.

À proprement parler, cette options supprime le bouton d'ajout de ligne, mais n'empêche pas l'ajout de rangées par programmation.

Dcp\Ui\ArrayRenderOptions disableRowAdd(bool $disable)

4.9.3.2.1 Restrictions

4.9.3.2.2 Paramètres

l'argument $disable indique si le bouton d'ajout de ligne doit être masqué.

4.9.3.2.3 Cas particuliers

Aucun

4.9.3.2.4 Exemples

Inhiber l'ajout dans le tableau "my_definition".

$options->arrayAttribute(My_family::my_definition)->disableRowAdd(true);

4.9.3.3 disableRowDel

Cette option permet d'inhiber la possibilité de supprimer une rangée dans un tableau.

À proprement parler, cette options supprime le bouton de suppression de ligne, mais n'empêche pas la suppression de rangées par programmation.

Dcp\Ui\ArrayRenderOptions disableRowDel(bool $disable)

4.9.3.3.1 Restrictions

4.9.3.3.2 Paramètres

l'argument $disable indique si le bouton de suppression de ligne doit être masqué.

4.9.3.3.3 Cas particuliers

Aucun

4.9.3.3.4 Exemples

Inhiber la suppression de rangée dans le tableau "my_definition".

$options->arrayAttribute(My_family::my_definition)->disableRowDel(true);

4.9.3.4 disableRowMove

Cette option permet d'inhiber la possibilité de déplacer une rangée dans un tableau.

À proprement parler, cette options supprime le bouton permettant de déplacer une ligne, mais n'empêche pas le déplacement d'une rangée par programmation. [php] Dcp\Ui\ArrayRenderOptions disableRowMove(bool $disable)

4.9.3.4.1 Restrictions

4.9.3.4.2 Paramètres

l'argument $disable indique si le bouton de déplacement de ligne doit être masqué.

4.9.3.4.3 Cas particuliers

Aucun

4.9.3.4.4 Exemples

Inhiber le déplacement de rangée dans le tableau "my_definition".

$options->arrayAttribute(My_family::my_definition)->disableRowMove(true);

4.9.3.5 setRowMinLimit

Cette option permet d'indiquer le nombre minimum de rangées pour un tableau.

Si le tableau a moins de rangées que le minimum indiqué, des rangées sont ajoutées jusqu'à cette limite lors du rendu du tableau. Les rangées ajoutées contiennent les valeurs par défaut des colonnes du tableau.

Le bouton de suppression de rangée est inhibé si la limite est atteinte.

Dcp\Ui\ArrayRenderOptions setRowMinLimit(int $limit)

4.9.3.5.1 Restrictions

4.9.3.5.2 Paramètres

l'argument $limit indique le nombre en dessous duquel le tableau sera automatiquement complété et le bouton de suppression de ligne désactivé.

Si la limite est négative ou zéro aucune limite n'est définie.

4.9.3.5.3 Cas particuliers

Cette option n'empêche pas supprimer des rangées par programmation. Elle empêche simplement les interactions utilisateur afin de ne pas supprimer des rangées si le seuil est atteint.

4.9.3.5.4 Exemples

Le tableau "my_definition" doit avoir 5 rangées minimum.

$options->arrayAttribute(My_family::my_definition)->setRowMinLimit(5);

4.9.3.6 setRowMaxLimit

Cette option permet d'indiquer le nombre maximum de rangées pour un tableau.

Le bouton d'ajout de rangée est inhibé si la limite est atteinte.

Dcp\Ui\ArrayRenderOptions setRowMaxLimit(int $limit)

4.9.3.6.1 Restrictions

4.9.3.6.2 Paramètres

l'argument $limit indique le nombre au-dessus duquel le bouton d'ajout de rangée sera désactivé.

4.9.3.6.3 Cas particuliers

Cette option n'empêche pas d'ajouter des lignes au dela du seuil par programmation. Elle contrôle juste l'interaction de bouton qui permets d'ajouter les rangées.

Si le tableau initial a plus de rangées que le seuil indiqué, les lignes au delà du seuil ne sont pas supprimées. Le bouton "ajouter" est juste désactivé.

4.9.3.6.4 Exemples

Le tableau peut avoir 10 rangées maximum dans le tableau "my_definition".

$options->arrayAttribute(My_family::my_definition)->setRowMaxLimit(10);

4.9.3.7 setRowMinDefault

Cette option permet d'indiquer le nombre minimum de rangées à afficher lors de l'édition d'un tableau.

Si le tableau a moins de rangées que le minimum indiqué, des rangées sont ajoutées jusqu'à cette limite lors du rendu du tableau. Les rangées ajoutées contiennent les valeurs par défaut des colonnes du tableau.

Dcp\Ui\ArrayRenderOptions setRowMinDefault(int $default)

4.9.3.7.1 Restrictions

4.9.3.7.2 Paramètres

l'argument $default indique le nombre en dessous duquel le tableau sera automatiquement complété.

Si la limite est négative ou zéro aucune limite n'est définie.

4.9.3.7.3 Cas particuliers

Cette option n'empêche pas la suppression des rangées par l'interface.

4.9.3.7.4 Exemples

Le tableau "my_definition" affiche toujours au moins la première rangée.

$options->arrayAttribute(My_family::my_definition)->setRowMinDefault(1);

4.9.3.8 setDescription

Cette option est une option commune qui permet d'afficher une description pour un tableau.

Son usage est le même mais le positionnement de la description est propre au type "tableau".

4.9.3.8.1 Positionnement pour les attributs contenu dans un tableau

4.9.3.8.2 Positionnement de la description d'un tableau

4.9.3.9 setResponsiveBreakpoints

Cette option permet d'indiquer les règles d'affichage des tableaux en fonction de la taille de la fenêtre.

Dcp\Ui\ArrayRenderOptions setResponsiveBreakpoints(
    string $transposition=self::transpositionRule, 
    string $labelUp=self::upRule
);

4.9.3.9.1 Restrictions

4.9.3.9.2 Paramètres

4.9.3.9.3 Cas particuliers

Aucun

4.9.3.9.4 Exemples :

4.9.4 Options de représentation type color

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le widget de sélection de couleur est basé sur un widget Kendo Ui Color Picker.

4.9.4.1 setKendoColorConfiguration

Cette option permet de configurer l'aspect du widget de couleur.

Dcp\Ui\ColorRenderOptions setKendoColorConfiguration(array $config)

4.9.4.1.1 Restrictions

4.9.4.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

Les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.4.1.3 Cas particuliers

Aucun

4.9.4.1.4 Exemples

Choix d'une palette de deux couleurs.

$options->color(myFamily::my_choice)->setKendoColorConfiguration([
    "palette"  => ["#457fe2", "#e50054"],
    "tileSize" => [
        "width"=>100, 
        "height"=>50
    ]
]);

4.9.5 Options de représentation type date

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le widget d'édition des date est basé sur un widget kendo UI Date Picker.

4.9.5.1 setKendoDateConfiguration

4.9.5.1.1 Restrictions

Attention : Les options propres à Kendo ne sont pas maintenues par Anakeen et leur bon fonctionnement n'est pas garanti par Anakeen.

4.9.5.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.5.1.3 Cas particuliers

4.9.5.1.4 Exemples

Affichage de la date avec le jour de la semaine suivant la locale. Imposer une date inférieure à la date du jour

$options->date("MyFamily::my_birthday")->setKendoDateConfiguration(
    array(
        "format"=>"D",
        "footer"=>"La date de naissance"
        "max" => date("Y-m-d")
    )
 );

4.9.5.2 setFormat

Cette option permet de modifier l'aspect de la valeur de l'attribut.

Dcp\Ui\DateRenderOptions setFormat(string $format)

4.9.5.2.1 Restrictions

4.9.5.2.2 Paramètres

L'argument format est un template Mustache. Les variables qu'il peut utiliser sont :

Ce format doit être un fragment HTML valide.

Par défaut, le format est {{displayValue}}.

Ce format est différent de celui indiqué par le widget kendo ui. La valeur de la variable {{displayValue}} contient la valeur formatée par le widget si un format widget est précisé.

4.9.5.2.3 Cas particuliers

Aucun

4.9.5.2.4 Exemples

4.9.5.3 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\DateRenderOptions setPlaceHolder(string $text)

4.9.5.3.1 Restrictions

4.9.5.3.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.5.3.3 Cas particuliers

Aucun

4.9.5.3.4 Exemples

$options->date(My_family::my_date)
    ->setPlaceHolder("Select a future date");

4.9.6 Options de représentation type docid

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

N> Le widget d'édition des relation est basé sur un widget kendo MultiSelect.

4.9.6.1 setKendoMultiSelectConfiguration

Cette option permet de configurer le widget d'édition des relations.

Dcp\Ui\DocidRenderOptions setKendoMultiSelectConfiguration(array $config )

4.9.6.1.1 Restrictions

4.9.6.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.6.1.3 Cas particuliers

Leur éventuelle modification est ignorée par le widget.

4.9.6.1.4 Exemples

Modification des paramètres :

$options->docid()->setKendoMultiSelectConfiguration([
    // Attendre 3 caractères avant de lancer l'aide à la saisie
    "minLength"      => 3,
    // text de substitution lorsque le champ est vide
    "placeholder"    => "Search a document",
    // Entête de la recherche
    "headerTemplate" => '<div><h2>Résultat de la recherche</h2></div>'
]);

4.9.6.2 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\DocidRenderOptions setPlaceHolder(string $text)

4.9.6.2.1 Restrictions

4.9.6.2.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.6.2.3 Cas particuliers

Aucun

4.9.6.2.4 Exemples

$options->docid(My_family::my_document)
    ->setPlaceHolder("Select the good document");

4.9.6.3 setFormat

Cette option permet de modifier l'aspect de la valeur de l'attribut.

Dcp\Ui\TextRenderOptions setFormat(string $format)

4.9.6.3.1 Restrictions

4.9.6.3.2 Paramètres

L'argument format est un format Mustache qui a comme variables les informations sur la valeur de l'attribut.

Ces informations pour le type docid sont :

Ce format doit être un fragment HTML valide.

Par défaut, le format est

<img class="dcpAttribute__value--icon" src="{{icon}}" />
<span class="dcpAttribute__content__value">{{displayValue}}</span>`.

4.9.6.3.3 Cas particuliers

Aucun

4.9.6.3.4 Exemples

Enlever l'icône de la famille pour les relations :

$options->docid(My_family::my_relation)
    ->setFormat('<span class="dcpAttribute__content__value">{{displayValue}}</span>');

4.9.6.4 setDocumentIconSize

Cette option indique la dimension de l'icône de la relation'.

Dcp\Ui\DocidRenderOptions setDocumentIconSize(string $size)

4.9.6.4.1 Restrictions

4.9.6.4.2 Paramètres

L'argument size indique la dimension de l'image à afficher.

Par défaut, la dimension est 14x14c. Cela affiche une icône carrée de 14px.

Le redimensionnement ne peut excéder la taille de l'icône originale.

Cette option ne modifie pas la taille css mais affiche une icône à la dimension désirée. Le poids du fichier icône est proportionnel à la taille demandée.

4.9.6.4.3 Cas particuliers

Pour rétablir la taille par défaut, il faut indiquer null. Une dimension de 0 ou de 0x0, n'affichera pas l'icône.

4.9.6.4.4 Exemples

Dimension de 32x32 rognée.

$options->docid(My_family::my_relation)->setDocumentIconSize("32x32c");

4.9.6.5 addCreateDocumentButton

Cette option permet d'ajouter un bouton permettant de créer un document et de l'insérer dans l'attribut. Si l'attribut a déjà une valeur, le bouton affiche le formulaire de modification du document cible. Si l'attribut n'a pas de valeur, le bouton affiche le formulaire de création.

Dans le cas d'un attribut multiple, le bouton ajouté affiche toujours un formulaire en création afin d'ajouter le nouveau document à la liste.

Dcp\Ui\DocidRenderOptions addCreateDocumentButton(\Dcp\Ui\CreateDocumentOptions $options)

4.9.6.5.1 Restrictions

4.9.6.5.2 Paramètres

L'argument $options permet de configurer le document à insérer. Il reprend les options de addbutton pour configurer la taille de la fenêtre et les caractéristiques du bouton.

Par contre, l'option target ne peux être que _dialog. Le formulaire pour le document à insérer ne s'ouvre que dans une fenêtre de dialogue et ne peut être ouverte dans une autre fenêtre du navigateur.

L'option url n'est pas prise en compte. L'url utilisée pour l'affichage du formulaire est calculée en fonction des paramètres de cette option.

L'option windowTitle est vide par défaut et le titre de la fenêtre de dialogue est calculé. Il reprend les informations d'identification du document (icone et le nom du document). Dans ce cas l'entête du document n'est pas affichée. Si cette option est indiquée, l'entête du document est affiché.

Les autres paramètres sont :

familyName
Le nom logique de la famille utilisé pour la création. S'il n'est pas indiqué, la famille utilisée est celle du format du type de l'attribut. Ce paramètre n'est pas utilisé pour l'affichage du formulaire de modification.
htmlCreateContent
Fragment HTML du bouton pour l'affichage en création. Le texte de l'option htmlContent (vide par défaut) précède ce texte.
Par défaut : <i class="fa fa-plus-circle" />
htmlEditContent
Fragment HTML du bouton pour l'affichage en modification. Le texte de l'option htmlContent (vide par défaut) précède ce texte. Par défaut : <i class="fa fa-plus-pencil" />

createLabel: Fragment HTML du label qui sera affiché sur le bouton du menu du formulaire permettant la sauvegarde et la fermeture de la fenêtre de dialogue.
Par défaut : Create and insert to "{{label}}"

updateLabel: Fragment HTML du label qui sera affiché sur le bouton du menu du formulaire permettant la création, l'insertion de la valeur et la fermeture de la fenêtre de dialogue.
Par défaut : Save and update "{{label}}"

formValues: Tableau indiquant les champs du formulaire qui doivent être modifiés lors de l'affichage du formulaire de création. Ces valeurs ne sont pas utilisées pour le formulaire de modification. Les valeurs par défaut sont déjà prérenseignées dans le formulaire. Les valeurs peuvent avoir 2 formes.
Si c'est une chaîne de caractères, elle sera considérée comme la valeur brute (value) et la valeur affichable (displayValue) de l'attribut. Dans ce cas, la chaîne de caractères peut contenir des parties variables qui permettent d'indiquer des informations du document principal.
Si cette chaîne est un tableau, il sera utilisé comme valeur complète de l'attribut. Dans ce cas, il doit contenir au moins "value" dans ses index. Les valeurs complètes n'ont pas de parties variables.
Exemples :

    ["value" => "application/word|2892|Mon fichier.doc",  
       "displayValue" => "Mon fichier.doc",  
       "size" => 4567`  
       "icon" => "resizeimg.php?img=CORE%2FImages%2Fmime-doc.png&size=14"  
    ]

4.9.6.5.3 Cas particuliers

Aucun

4.9.6.5.4 Exemples

Affichage d'un formulaire d'un document de la famille "espèce" pour être inséré dans l'attribut "an_species" de la famille "animal".

use Dcp\AttributeIdentifiers\Zoo_animal as AnimalAttributes;
use Dcp\AttributeIdentifiers\Zoo_espece as EspeceAttributes;
class AnimalRenderConfigEdit extends \Dcp\Ui\DefaultEdit
{
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
        $viewDoc=new \Dcp\Ui\CreateDocumentOptions();
        $viewDoc->formValues=[
            EspeceAttributes::es_name => "Nouvelle espèce",
            EspeceAttributes::es_description => "Provient de l'animal {{attributes.an_nom.attributeValue.displayValue}}",
            EspeceAttributes::es_classe => sprintf("{{attributes.%s.attributeValue}}", AnimalAttributes::an_classe),
            EspeceAttributes::es_isprotected => ["value" => "1"],
            EspeceAttributes::es_gardian => [
                "value" => getIdFromName("", "ZOO_BIGGARDE"), 
                "displayValue"=>$document->getTitle("ZOO_BIGGARDE")],
            ];
        $options->docid(AnimalAttributes::an_species)->addCreateDocumentButton($viewDoc);
        return $options;
}

4.9.6.5.5 Événements

Cette option déclenche les événements suivants sur la page web. Ils peuvent être interceptés par le contrôleur de document.

  1. attributeCreateDialogDocumentReady : lorsque le formulaire est affiché
  2. attributeCreateDialogDocumentBeforeSetFormValues : avant l'affectation des valeurs dans le formulaire
  3. attributeCreateDialogDocumentBeforeSetTargetValue : avant l'affectation de l'attribut dans le document principal
  4. attributeCreateDialogBeforeClose : avant la fermeture de la fenêtre de dialogue
  5. attributeCreateDialogBeforeDestroy : avant la destruction de la fenêtre de dialogue

4.9.7 Options de représentation type double

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le type double bénéficie des options de représentation des attributs de type int.

Les méthodes suivantes sont spécifiques à l'attribut double.

4.9.7.1 setDecimalPrecision

Cette option indique le nombre de décimales du nombre.

En modification, la valeur est arrondie lors de la perte de focus (limitant ainsi la précision qui sera enregistrée en base).

En consultation, le nombre est affiché avec la précision indiquée. il ets complété par des 0 s'il ne possède pas assez de décimales, et est arrondi si sa précision est supérieure.

Dcp\Ui\DoubleRenderOptions setDecimalPrecision(int $number)

4.9.7.1.1 Restrictions

Aucune

4.9.7.1.2 Paramètres

L'argument number est un nombre positif ou nul. Si ce nombre est égal à 0, aucune limite n'est appliquée.

4.9.7.1.3 Cas particuliers

Attention, lors de l'affichage du formulaire, les valeurs du serveurs sont tronquées si le nombre de décimales est atteint. Par défaut, le nombre maximum de décimales n'est pas fixé. Par contre, la précision de la valeur est contrainte par le type double de javascript.

4.9.7.1.4 Exemples

Affichage de 4 décimales maximum.

$options->double()->setDecimalPrecision(4);

Ne pas montrer les zéros non significatifs avec 10 décimales :

$options->double()
    ->setDecimalPrecision(10)
    ->setKendoNumericConfiguration([
        "spinner" => false, // pas d'incrément prédéfini
        "format" => "#,#.##########" // 10 décimales
    ]);

4.9.8 Options de représentation type enum

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.8.1 setDisplay

Cette option indique l'aspect du widget de choix d'énuméré.

Dcp\Ui\EnumRenderOptions setDisplay(string $display)

4.9.8.1.1 Restrictions

4.9.8.1.2 Paramètres

Les valeurs possible pour l'argument $display sont :

list (valeur par défaut)

L'affichage de la sélection se présente sous forme d'une liste déroulante.

Cette liste n'est pas actualisée dynamiquement.

Si l'énuméré est déclaré multiple (option multiple=yes), cet affichage est similaire à celui de autoCompletion.

Dans ce mode d'affichage, la liste des énumérés est récupérée une seule fois lors de l'initialisation de l'affichage de l'attribute. Le filtre est réalisé sur le client avec les données initiales.

Énuméré simple - mode list

Figure 31. Énuméré simple - mode list

Énuméré multiple - mode list

Figure 32. Énuméré multiple - mode list

autoCompletion

Une liste de suggestions est présentée lorsqu'on saisit des caractères.

Si useSourceUri est true, le serveur est interrogé à chaque caractère tapé pour retourner le résultat filtré. Si les données de l'énuméré sont déjà présentes sur le client, le résultat est filtré par le client sur le titre des libellés. L'opérateur utilisé est "commence par".

Dans ce mode d'affichage, le filtre est réalisé sur le serveur après chaque modification du texte recherché.

Énuméré simple - mode autocomplétion

Figure 33. Énuméré simple - mode autocomplétion

Énuméré multiple - mode autocomplétion

Figure 34. Énuméré multiple - mode autocomplétion

vertical

L'affichage présente des boutons à cocher alignés verticalement, chaque choix s'affichant sur sa propre ligne.

Si l'énuméré est déclaré multiple (option multiple=yes), les boutons seront des checkbox ; dans le cas contraire, ce seront des boutons radio.

Cet affichage ne convient que si le nombre de choix est limité.

Énuméré simple - mode vertical

Figure 35. Énuméré simple - mode vertical

Énuméré multiple - mode vertical

Figure 36. Énuméré multiple - mode vertical

horizontal

L'affichage présente des boutons à cocher alignés horizontalement.

Si l'énuméré est déclaré multiple (option multiple=yes), les boutons seront des checkbox ; dans le cas contraire, ce seront des boutons radio.

Énuméré simple - mode horizontal

Figure 37. Énuméré simple - mode horizontal

Énuméré multiple - mode horizontal

Figure 38. Énuméré multiple - mode horizontal

bool

Cet affichage présente un seul bouton à bascule (coché ou pas coché).

Cet affichage ne fonctionne que si le nombre d'éléments est de deux et seulement si l'énuméré n'est pas déclaré multiple (option multiple=yes).

Lors de l'affichage du formulaire, si la valeur initiale est vide, alors elle est affectée à la première valeur des deux valeurs possibles de l'énuméré.

Énuméré premier choix - mode bool

Figure 39. Énuméré premier choix - mode bool

Énuméré second choix - mode bool

Figure 40. Énuméré second choix - mode bool

4.9.8.1.3 Cas particuliers

Aucun

4.9.8.1.4 Exemples

Affichage vertical :

$options->enum(My_family::my_choice)->setDisplay(\Dcp\Ui\EnumRenderOptions::verticalDisplay);

4.9.8.2 useSourceUri

Cette option indique que le widget interroge le serveur pour avoir les données de l'énumeré.

Il n'utilise pas les données de l'énuméré fournie par l'api REST de la structure de la famille.

Dcp\Ui\EnumRenderOptions useSourceUri(bool $useIt)

Important : Les données de l'énuméré sont fournis par l'api "structure" sauf si l'option eformat=auto est indiqué comme option de l'attribut.

Le widget demande les informations de l'énuméré (via une requête au serveur) si ces données ne sont par fournies par la structure de la famille au moment de l'initialisation du widget même si useSourceUri vaut false.

Par contre, si useSourceUri vaut true, les données sont demandées systématiquement au serveur.

En résumé, la requête serveur est envoyée dans les cas suivants :

Requête serveur useSourceUri=false useSourceUri=true
eformat != auto Non Oui
eformat == auto Oui Oui

Par défaut useSourceUri est égal à false et eformat est égal à list, donc le serveur n'est pas interrogé par défaut pour connaître la liste des élements de l'énuméré.

4.9.8.2.1 Restrictions

4.9.8.2.2 Paramètres

Le paramètre $useIt indique si le serveur doit être interrogé.

4.9.8.2.3 Cas particuliers

4.9.8.2.4 Exemples

4.9.8.3 useFirstChoice

Cette option indique que le premier élément de la liste est sélectionné si la valeur est vide.

Dcp\Ui\EnumRenderOptions useFirstChoice(bool $useFirst)

4.9.8.3.1 Restrictions

4.9.8.3.2 Cas particuliers

Si une valeur par défaut est définie, cette option est sans effet.

4.9.8.3.3 Exemples

4.9.8.4 useOtherChoice

Cette option permet de rajouter un champ "Autre", permettant à l'utilisateur de saisir une valeur différente de celles proposées.

Dcp\Ui\EnumRenderOptions useOtherChoice(bool $useIt)
 

4.9.8.4.1 Restrictions

4.9.8.4.2 Paramètres

Le paramètre $useIt indique si le champ de saisi est visible.

4.9.8.4.3 Cas particuliers

4.9.8.4.4 Exemples

4.9.8.5 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\EnumRenderOptions setPlaceHolder(string $text)

4.9.8.5.1 Restrictions

4.9.8.5.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.8.5.3 Cas particuliers

Aucun

4.9.8.5.4 Exemples

$options->enum(My_family::my_enum)
    ->setPlaceHolder("Select the good one");

4.9.8.6 setTranslations

En plus des labels communs à tous les types d'attributs, les labels sur le widget de choix de fichier peuvent être configurés.

Dcp\Ui\FileRenderOptions setTranslations(array $labels)

4.9.8.6.1 Restrictions

Aucune.

4.9.8.6.2 Paramètres

Les labels suivants sont utilisés en modification :

Le label suivant est utilisé en consultation :

4.9.8.7 setOrderBy

Cette option indique l'ordre de tri des entrées de l'énuméré.

Dcp\Ui\EnumRenderOptions setOrderBy(string $orderBy)

4.9.8.7.1 Restrictions

Lors de la consultation, les éléments des énumérés multiples sont affichés dans l'ordre dans lequel ils ont été sélectionnés.

4.9.8.7.2 Paramètres

Les valeurs possible pour l'argument $orderBy sont :

Dcp\Ui\EnumRenderOptions::orderByOrderOption (default)
trie les énumérés par leur ordre inscrit dans la définition de l'énuméré.
Dcp\Ui\EnumRenderOptions::orderByKeyOption
trie les énumérés par ordre alphabétique de leur clé

ce tri ne tient pas compte de la locale de l'utilisateur. C'est un tri alphabétique non naturel.

Dcp\Ui\EnumRenderOptions::orderByLabelOption
trie les énumérés par ordre alphabétique de leur label.

ce tri tient compte de la locale de l'utilisateur.

4.9.8.7.3 Cas particuliers

Aucun

4.9.8.7.4 Exemples

$options->enum(My_family::my_enum)
    ->setOrderBy(Dcp\Ui\EnumRenderOptions::orderByLabelOption);

4.9.9 Options de représentation type file

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.9.1 setContentDispositionInline

Cette option indique si le fichier à télécharger peut être consulté directement depuis le navigateur.

Dcp\Ui\FileRenderOptions setContentDispositionInline(bool $inline)

4.9.9.1.1 Restrictions

4.9.9.1.2 Paramètres

Si l'argument inline est false(par défaut), le fichier est proposé au téléchargement lorsqu'on clique sur le lien. Si la valeur est true, le fichier sera affiché sur le navigateur si celui-ci prend en compte son format.

Note : Les options de liens sont applicables sur le l'hyperlien généré.

4.9.9.1.3 Cas particuliers

Aucun

4.9.9.1.4 Exemples

Affichage direct sur une page différente

$fileLink=new \Dcp\Ui\HtmlLinkOptions();
$fileLink->target="_blank";
$options->file(My_family::my_abstract)
    ->setLink($fileLink)
    ->setContentDispositionInline(true);

4.9.9.2 setTranslations

En plus des labels communs à tous les types d'attributs, les labels sur le widget de choix de fichier peuvent être configurés.

Dcp\Ui\FileRenderOptions setTranslations(array $labels)

4.9.9.2.1 Restrictions

4.9.9.2.2 Paramètres

Les labels suivants utilisés en modification peuvent être changés :

Les textes de ces labels sont différents pour le type image.

Les labels suivants sont utilisés en consultation pour afficher la taille du fichier dans le tooltip :

4.9.9.2.3 Cas particuliers

4.9.9.2.4 Exemples

Modification des traductions.

$options->file("my_file")
    ->setTranslations([
        "tooltipLabel"=>"Choisissez un plan",
    ]);

4.9.9.3 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\FileRenderOptions setPlaceHolder(string $text)

4.9.9.3.1 Restrictions

4.9.9.3.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ lorsque le champ est vide.

4.9.9.3.3 Cas particuliers

Aucun

4.9.9.3.4 Exemples

$options->file(My_family::my_file)->setPlaceHolder("Select a pdf file, please.");

4.9.9.4 setMimeIconSize

Cette option indique la dimension de l'icône du type mime du fichier.

Dcp\Ui\FileRenderOptions setMimeIconSize(string $size)

4.9.9.4.1 Restrictions

4.9.9.4.2 Paramètres

L'argument size indique la dimension de l'image à afficher.

Par défaut, la dimension est 20x20c. Cela affiche une icône carrée de 20px.

Le redimensionnement ne peut excéder la taille de l'icône originale qui est de 80x80px.

Cette option ne modifie pas la taille css mais affiche une icône à la dimension désirée. Le poids du fichier icône est proportionnel à la taille demandée.

4.9.9.4.3 Cas particuliers

Pour rétablir la taille par défaut, il faut indiquer null. Une dimension de 0 ou de 0x0, n'affiche par l'icône.

Sur le formulaire, l'icône est utilisée en image de fond (background-image) du champ de saisie (input). Elle ne peut dépasser la dimension du champ de saisie.

Les attributs de type "image" n'utilisent pas cette icône dans leur représentation par défaut.

4.9.9.4.4 Exemples

Dimension de 32x32 rognée.

$options->file(My_family::my_file)->setMimeIconSize("32x32c");

4.9.10 Options de représentation type frame

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.10.1 setCollapse

Le contenu d'un cadre est visible par défaut et son contenu peut être replié.

Cette option indique si la cadre peut être plié ou s'il doit être plié ou déplié par défaut.

Dcp\Ui\TabRenderOptions setCollapse(bool|null $collapse)

4.9.10.1.1 Restrictions

Aucune

4.9.10.1.2 Paramètres

L'argument $collapse indique si le contenu du cadre doit être rendu replié.

4.9.10.1.3 Cas particuliers

4.9.10.1.4 Exemples

Ne pas autoriser le repliage des cadres :

class MyNoCollapseRender extends \Dcp\Ui\DefaultView
{
    public function getOptions(\Doc $document)
    {
        $options = parent::getOptions($document);
        $options->frame()->setCollapse(\Dcp\Ui\FrameRenderOptions::collapseNone);
        return $options;
    }
}

4.9.10.2 setDescription

Cette option est une option commune qui permet d'afficher une description pour un tableau.

Son usage est le même mais le positionnement de la description est propre au type "cadre".

4.9.10.2.1 Positionnement de la description d'un cadre

4.9.11 Options de représentation type htmltext

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le widget d'édition des textes formaté est basé sur un widget CKEditor.

4.9.11.1 setHeight

Cette option indique la hauteur de la zone d'écriture du widget d'édition.

Dcp\Ui\HtmltextRenderOptions setHeight(string $heigth)

4.9.11.1.1 Restrictions

4.9.11.1.2 Paramètres

L'argument height est une valeur avec unité (120px par défaut). Les unités possibles sont les unités css. Le pourcentage n'est pas une unité valide pour cette option.

Si l'unité n'est pas précisé, c'est l'unité px qui est utilisée.

4.9.11.1.3 Cas particuliers

Cette option est priroritaire à l'option setCkEditorConfiguration.

4.9.11.1.4 Exemples

Affichage d'une hauteur de 150px (Barre de menu non comprise).

$options->htmltext(My_family::my_article)->setHeight("150px");

4.9.11.2 setToolbarStartupExpanded

Cette option indique si la barre de menu doit être dépliée ou non lors de l'affichage du document.

Dcp\Ui\HtmltextRenderOptions setToolbarStartupExpanded(bool $expanded)

4.9.11.2.1 Restrictions

4.9.11.2.2 Paramètres

Si l'argument expanded est true (valeur par défaut), la barre de menu est visible. Si cette argument est false, la barre de menu est minimisée. Un bouton sur cette barre de menu permet de la déplier ou de la replier.

Cette option correspond à l'option toolbarStartupExpanded de CKEditor.

4.9.11.2.3 Cas particuliers

Cette option est priroritaire à l'option setCkEditorConfiguration.

4.9.11.2.4 Exemples

4.9.11.3 setToolbar

Cette option indique la barre de menu qui doit être disponible sur cet éditeur.

Dcp\Ui\HtmltextRenderOptions setToolbar(string $toolbar)

4.9.11.3.1 Restrictions

4.9.11.3.2 Paramètres

L'argument toolbar indique l'identifiant de la barre de menu à utiliser. La valeur par défaut est Simple.

Les valeurs prédéfinies sont :

Dcp\Ui\HtmltextRenderOptions::basicToolbar
Barre de menu *Basic*

Figure 49. Barre de menu *Basic*

Dcp\Ui\HtmltextRenderOptions::defaultToolbar
Barre de menu *Default*

Figure 50. Barre de menu *Default*

Dcp\Ui\HtmltextRenderOptions::simpleToolbar
Barre de menu *Simple*

Figure 51. Barre de menu *Simple*

Dcp\Ui\HtmltextRenderOptions::fullToolbar
Barre de menu *Full*

Figure 52. Barre de menu *Full*

Cette option correspond à l'option toolbar de CKEditor.

4.9.11.3.3 Cas particuliers

4.9.11.3.4 Exemples

Affichage du menu "Basic".

$options->htmltext(My_family::my_article)->setToolbar(\Dcp\Ui\HtmltextRenderOptions::basicToolbar);

4.9.11.4 setCkEditorConfiguration

Cette option permet de configurer le widget CKeditor.

Dcp\Ui\HtmltextRenderOptions setCkEditorConfiguration(array $config)

4.9.11.4.1 Restrictions

Attention : Les options propres à CKEditor ne sont pas maintenues par Anakeen et leur bon fonctionnement n'est pas garanti par Anakeen.

4.9.11.4.2 Paramètres

L'argument config permet de modifier les valeurs de configuration du widget CKeditor. Les valeurs possibles sont celles du widget CKEditor.

4.9.11.5 Cas particuliers

Aucun

4.9.11.5.1 Exemples

Configurer sa propre barre de menu avec seulement "Gras" et "Italique".

$options->htmltext(My_family::my_article)
    ->setToolbar("mySample")
    ->setCkEditorConfiguration([
        "toolbarCanCollapse" => false,
        "toolbar_mySample" => [
            "name" => "Basics",
            "items" => ["Bold", "Italic"]
        ]
    ]);

4.9.11.6 setCkEditorAllowAllTags

Cette option permet d'autoriser tous les tags HTML dans l'éditeur ckEditor. Par défaut, les tags autorisés sont fonctions de la barre de menu affichée.

Dcp\Ui\HtmltextRenderOptions setCkEditorConfiguration(bool $allow)

4.9.11.6.1 Restrictions

4.9.11.6.2 Paramètres

L'argument allow s'il faut true permet d'autoriser toute balise HTML supportée.

Les attributs de ces balises peuvent aussi être utilisées à l'exception des attributs commençant par on tel que onclick ou onmouseover.

Les balises supportées sont : a, abbr, acronym, address, applet, area, article, aside, audio, b, base, basefont, bdi, bdo, big, blockquote, body, br, button, canvas, caption, center, cite, code, col, colgroup, command, datalist, dd, del, details, dfn, dialog, dir, div, dl, dt, em, embed, fieldset, figcaption, figure, font, footer, form, h1, h2, h3, h4, h5, h6, head, header, hgroup, hr, html, i, iframe, img, input, ins, isindex, kbd, keygen, label, legend, li, link, main, map, mark, menu, meta, meter, nav, noframes, noscript, object, ol, optgroup, option, output, p, param, pre, progress, q, rp, rt, ruby, s, samp, section, select, small, source, span, strike, strong, style, sub, summary, sup, table, tbody, td, textarea, tfoot, th, thead, time, title, tr, track, tt, u, ul, var, video, wbr.

4.9.11.7 Cas particuliers

Aucun

4.9.11.7.1 Exemples

Affichage de la barre de menu complète et autorisation de tous les tags.

$options->htmltext(My_family::my_article)
    ->setToolbar(\Dcp\Ui\HtmltextRenderOptions::fullToolbar)
    ->setCkEditorAllowAllTags(true);

4.9.11.8 setAnchorsOptions

Cette option permet de définir les modalités d'ouverture des liens contenus dans cet attribut.

\Dcp\Ui\HtmltextRenderOptions::setAnchorsOptions(\Dcp\Ui\anchorOptions $anchorOptions)

4.9.11.9 Restrictions

Uniquement pris en compte lorsque l'attribut n'est pas en modification.

4.9.11.9.1 Paramètres

L'argument en entrée est un objet de type Dcp\Ui\anchorOptions qui configure les différents paramètres du lien :

target

Nom de la fenêtre du navigateur vers laquelle le lien sera envoyé.

  • Si la valeur est _blank (valeur par défaut), une nouvelle fenêtre est utilisée.
  • Si la valeur est _self, la fenêtre courante est utilisée.
  • Si la valeur est _dialog, une fenêtre de dialogue interne sera utilisée.

Si target est différente de _self les options suivantes sont prises en compte :

windowHeight

Hauteur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une [dimension css valable][css_dimension] (c'est à dire un nombre suivi immédiatement de son unité).

Sinon la dimension est un nombre entier exprimé en pixels.

La valeur par défaut est 300px.

windowWidth

Largeur de la fenêtre de dialogue. Si target est égal à _dialog, la dimension doit être une [dimension css valable][css_dimension] (c'est à dire un nombre suivi immédiatement de son unité).

Sinon la dimension est un nombre entier exprimé en pixels.

La valeur par défaut est 200px.

Si target est _dialog, les options suivantes sont prises en compte :

modal
indique si la fenêtre de dialogue doit être modale (false par défaut).

4.9.11.10 Cas particuliers

Aucun

4.9.11.10.1 Exemples

Ouverture de tous les liens dans une modale de 400 x 300px.

$options->htmltext(My_family::my_article)
        ->setAnchorOptions(new \Dcp\Ui\anchorOptions('_dialog', '400px', '300px', true))

4.9.12 Options de représentation type image

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le type image bénéficie des options de représentation des attributs de type file.

Les méthodes suivantes sont spécifiques à l'attribut image.

4.9.12.1 setThumbnailSize

Cette option indique la dimension de la miniature affichée.

Dcp\Ui\ImageRenderOptions setThumbnailSize(string $size)

4.9.12.1.1 Restrictions

4.9.12.1.2 Paramètres

L'argument size indique la dimension de l'image à afficher.

Par défaut 48 indique une image de 48px de large.

Le redimensionnement ne peux excéder la taille de l'image originale.

Cette option ne modifie pas la taille css mais affiche une image à la largeur désirée. Le poids du fichier image est proportionnel à la taille demandée.

Par défaut, l'image est un lien qui affiche l'image originale dans une "target" _dialog de dimension 300x400.

4.9.12.1.3 Cas particuliers

Pour afficher l'image dans sa taille originale, il faut indiquer null.

4.9.12.1.4 Exemples

Largeur de 100px.

$options->image(My_family::my_photo)->setThumbnailSize("100");

Hauteur de 100px.

$options->image(My_family::my_photo)->setThumbnailSize("x100");

Largeur et hauteur de 100px rognée.

$options->image(My_family::my_photo)->setThumbnailSize("100x100c");

4.9.12.2 setThumbnailWidth

1.1.0 Utiliser setThumbnailSize.

Cette option indique la largeur de la miniature affichée.

Dcp\Ui\ImageRenderOptions setThumbnailWidth(int $width)

4.9.12.2.1 Restrictions

4.9.12.2.2 Paramètres

L'argument size est un nombre positif qui indique la largeur (en pixels) de l'image affichée (48 par défaut).

Le redimensionnement ne peux excéder la taille de l'image originale.

Pour afficher l'image dans sa taille originale, il faut mettre 0.

Cette option ne modifie pas la taille css mais affiche une image à la largeur désirée. Le poids du fichier image est proportionnel à la taille demandée.

Par défaut, l'image est un lien qui affiche l'image originale dans une "target" _dialog de dimension 300x400.

4.9.12.2.3 Cas particuliers

Aucun

4.9.12.2.4 Exemples

Largeur de 100px.

$options->image(My_family::my_photo)->setThumbnailWidth(100);

4.9.13 Options de représentation type int

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le widget d'édition des entiers est basé sur un widget Kendo Numeric textbox.

4.9.13.1 setKendoNumericConfiguration

Cette option permet de configurer le widget d'édition des nombres entiers.

Dcp\Ui\IntRenderOptions setKendoNumericConfiguration(array $config )

4.9.13.1.1 Restrictions

4.9.13.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui

Pour le mode consultation, seul le format est pris en compte.

4.9.13.1.3 Cas particuliers

4.9.13.1.4 Exemples

Ajouter des limites sur le nombre à saisir.

$options->int(My_family::my_number)
    ->setPlaceHolder("Give a number between 10 and 20")
    ->setKendoNumericConfiguration(
        ["min"=>10,
         "max"=>20]
);

4.9.13.2 setFormat

Cette option permet de modifier l'aspect de la valeur de l'attribut.

Dcp\Ui\IntRenderOptions setFormat(string $format)

4.9.13.2.1 Restrictions

4.9.13.2.2 Paramètres

L'argument format est un format Mustache qui a comme variables les informations sur la valeur de l'attribut.

Ces informations pour le type int sont :

Ce format doit être un fragment HTML valide.

Par défaut, le format est {{displayValue}}.

4.9.13.2.3 Cas particuliers

Note : Ce format est différent de celui indiqué par le widget kendo ui. La valeur de la variable {{displayValue}} contient la valeur formatée par le widget si un format widget est précisé.

4.9.13.2.4 Exemples

4.9.13.3 setTranslations

En plus des labels communs à tous les types d'attributs, les labels sur les flèches d'incrémentation et de décrémentation peuvent être configurés.

Dcp\Ui\CommonRenderOptions setTranslations(array $labels)

4.9.13.3.1 Restrictions

4.9.13.3.2 Paramètres

Les labels decreaseLabel et increaseLabel indiquent les textes surgissant sur les flèches d'incrémentation et de décrémentation.

4.9.13.3.3 Cas particuliers

4.9.13.3.4 Exemples

Incrément de 5 et pose de l'unité "kg". Modification des traductions.

$options->int(My_Family::my_mass)
    ->setKendoNumericConfiguration([
        "step" => 5, 
        "format" => "#,# kg"
    ])
    ->setTranslations([
        "decreaseLabel"=>"5 kilos de moins",
        "increaseLabel"=>"5 kilos de plus"
    ]);

4.9.13.4 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\IntRenderOptions setPlaceHolder(string $text)

4.9.13.4.1 Restrictions

4.9.13.4.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.13.4.3 cas particuliers

4.9.13.4.4 Exemples

$options->int(My_family::my_number)->setPlaceHolder("Number less than 10");

4.9.14 Options de représentation type longtext

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le type longtext bénéficie des options de représentation des attributs de type text.

Les méthodes suivantes sont spécifiques à l'attribut longtext.

4.9.14.1 setMaxDisplayedLineNumber

Cette option permet de limiter le nombre de lignes visibles sur le champs de saisie du texte.

Si le nombre de ligne de la valeur dépasse la limite un ascenseur vertical apparaît.

Dcp\Ui\LongtextRenderOptions setMaxDisplayedLineNumber(int $number)

Par défaut, le champ est agrandi pour voir l'intégralité du texte. À chaque nouvelle ligne saisie la hauteur du champ s'agrandit. Par contre, la hauteur n'est pas diminuée si le nombre de ligne diminue.

Si le nombre est positif, le champ de saisie n'est pas redimensionnable manuellement pour les navigateurs qui le supportent.

4.9.14.1.1 Restrictions

4.9.14.1.2 Paramètres

L'argument number est un nombre positif ou nul. Si ce nombre est égal à 0 aucune limite n'est appliquée et le champ de saisie s'agrandit en fonction du nombre de lignes saisies.

4.9.14.1.3 Cas particuliers

Aucun

4.9.14.1.4 Exemples

Affichage de 10 lignes maximum. Au delà un ascenseur vertical apparaît.

$options->longtext(My_family::my_definition)->setMaxDisplayedLineNumber(10);

4.9.15 Options de représentation type money

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le type money bénéficie des options de représentation de l'attribut de type double.

Les méthodes suivantes sont spécifiques à l'attribut money.

4.9.15.1 setCurrency

Cette option indique la devise de la somme d'argent.

Dcp\Ui\MoneyRenderOptions setCurrency(string $currency)

4.9.15.1.1 Restrictions

Aucune

4.9.15.1.2 Paramètres

L'argument currency est une chaîne de caractère qui représente la devise.

Par défaut, la valeur est €.

4.9.15.1.3 Cas particuliers

4.9.15.1.4 Exemples

Exemple :

Utiliser la livre comme devise.

$options->money(My_family::my_benefit)->setCurrency('£');

4.9.16 Options de représentation type tab

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Les options d'affichage générales des onglets sont fournies par les options de document.

Le widget de gestion des onglets est basé sur un widget Kendo tab Strip.

4.9.16.1 setTooltipLabel

Cette option d'afficher un tooltip au dessus de l'onglet lors du survol.

Si le label est particulièrement long et qu'il ne peut être affiché intégralement dans l'onglet, le tooltip permet de voir le libellé en entier.

Dcp\Ui\TabRenderOptions setTooltipLabel(string $label,
                                          bool $html=false)

4.9.16.1.1 Restrictions

Aucune

4.9.16.1.2 Paramètres

4.9.16.1.3 Cas particuliers

Aucun

4.9.16.1.4 Exemples

$options->tab(My_family::my_informations)
    ->setTooltipLabel('Onglet informatif');

4.9.16.2 setDescription

Cette option est une option commune qui permet d'afficher une description pour un tableau.

Son usage est le même mais le positionnement de la description est propre au type "onglet".

4.9.16.2.1 Positionnement de la description d'un onglet

4.9.17 Options de représentation type text

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

4.9.17.1 setMaxLength

Cette option permet de limiter le nombre de caractères saisis par l'utilisateur. Cela n'est pas une contrainte et le champ saisie peut excéder cette limite par programmation.

Dcp\Ui\TextRenderOptions setMaxLength(int $max)

4.9.17.1.1 Restrictions

4.9.17.1.2 Paramètres

L'argument $max est un nombre positif. Si ce nombre est égal à 0, aucune limite n'est appliquée.

4.9.17.1.3 Cas particuliers

Aucun

4.9.17.1.4 Exemples

Limiter la saisie d'un numéro de téléphone à 10 caractères.

$options->text(My_family::my_phone)->setMaxLength(10);

4.9.17.2 setKendoAutoCompleteConfiguration

Cette option permet de configurer le widget d'édition des relations.

Dcp\Ui\DocidRenderOptions setKendoMultiSelectConfiguration(array $config )

4.9.17.2.1 Restrictions

4.9.17.2.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.17.2.3 Cas particuliers

Leur modification est ignorée par le widget.

4.9.17.2.4 Exemples

Modification des paramètres :

$options->docid()->setKendoAutoCompleteConfiguration([
    // Attendre 3 caractères avant de lancer l'aide à la saisie
    "minLength"      => 3,
    // Entête de la recherche
    "headerTemplate" => '<div><h2>Résultat de la recherche</h2></div>'
]);

4.9.17.3 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\DocidRenderOptions setPlaceHolder(string $text)

4.9.17.3.1 Restrictions

4.9.17.3.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.17.3.3 Cas particuliers

Aucun

4.9.17.3.4 Exemples

$options->text(My_family::my_phone)->setPlaceHolder("Write work phone number");

4.9.17.4 setFormat

Cette option permet de modifier l'aspect de la valeur de l'attribut.

Dcp\Ui\TextRenderOptions setFormat(string $format)

4.9.17.4.1 Restrictions

4.9.17.4.2 Paramètres

L'argument format est un format Mustache qui a comme variables les informations sur la valeur de l'attribut.

Ces informations pour le type text sont :

Ce format doit être un fragment HTML valide.

Par défaut, le format est {{displayValue}}.

4.9.17.4.3 Cas particuliers

Aucun

4.9.17.4.4 Exemples

$options->text(My_family::my_title)
    ->setFormat('<h1 class="my-red">{{displayValue}}</h1>');

4.9.18 Options de représentation type time

Le widget d'édition des temps (heure / minute) est basé sur un widget kendo Time Picker.

4.9.18.1 setKendoTimeConfiguration

Cette option permet de configurer l'aspect du widget de temps.

Dcp\Ui\TimeRenderOptions setKendoTimeConfiguration(array $config)

4.9.18.1.1 Restrictions

Attention : Les options propres à Kendo ne sont pas maintenues par Anakeen et leur bon fonctionnement n'est pas garanti par Anakeen.

4.9.18.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.18.1.3 Cas particuliers

Pour le mode consultation, seul le format est pris en compte.

4.9.18.1.4 Exemples

Intervalle de choix de 5 minutes

$options->time("MyFamily::my_time")
    ->setKendoTimeConfiguration([
        "interval" => 5
    ]);

4.9.18.2 setFormat

Cette option permet de modifier l'aspect de la valeur de l'attribut.

Dcp\Ui\TimeRenderOptions setFormat(string $format)

4.9.18.2.1 Restrictions

4.9.18.2.2 Paramètres

L'argument $format est un format Mustache qui a comme variables les informations sur la valeur de l'attribut.

Ces informations pour le type text sont :

Ce format doit être un fragment HTML valide.

Par défaut, le format est {{displayValue}}.

4.9.18.2.3 Cas particuliers

Ce format est différent de celui indiqué par le widget kendo ui. La valeur de la variable {{displayValue}} contient la valeur formatée par le widget si un format widget est précisé.

4.9.18.2.4 Exemples

4.9.18.3 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\TimeRenderOptions setPlaceHolder(string $text)

4.9.18.3.1 Restrictions

4.9.18.3.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.18.3.3 Cas particuliers

Aucun

4.9.18.3.4 Exemples

$options->enum(My_family::my_time)
    ->setPlaceHolder("Select the hour");

4.9.19 Options de représentation type timestamp

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Le type timestamp bénéficie des options de représentation de l'attribut de type date.

Les méthodes suivantes sont spécifiques à l'attribut timestamp.

Le widget d'édition des date est basé sur un widget kendo Date Time Picker.

4.9.19.1 setKendoDateConfiguration

Cette option permet de configurer l'aspect du widget de date.

Dcp\Ui\DateRenderTimestamp setKendoDateConfiguration(array $config)

4.9.19.1.1 Restrictions

Attention : Les options propres à Kendo ne sont pas maintenues par Anakeen et leur bon fonctionnement n'est pas garanti par Anakeen.

4.9.19.1.2 Paramètres

L'argument config est un tableau de valeurs indexées qui servent à modifier la configuration du widget.

En modification, les valeurs possibles sont les propriétés de configuration du widget kendo ui.

4.9.19.1.3 Cas particuliers

Pour le mode consultation, seul le format est pris en compte.

4.9.19.1.4 Exemples

Affichage de la date avec le jour de la semaine suivant la locale ainsi que des heures, minutes et secondes.

$options->date("MyFamily::my_wakeup")->setKendoDateConfiguration(
    array("format"=>"F")
 ));

4.9.20 Options de représentation type password

Les options de représentation indiquées dans la structure de la famille ne sont pas prises en compte dans les interfaces HTML5.

Les méthodes suivantes sont spécifiques à l'attribut password.

4.9.20.1 hideValue

Cette option indique un texte qui sera utilisé pour l'affichage du mot de passe lorsque celui-ci n'est pas vide.

Dcp\Ui\PasswordRenderOptions hideValue(string $text)

La valeur du mot de passe enregistré dans le document n'est pas crypté. Elle est accessible comme n'importe quelle autre valeur du document. Il est de la responsabilité du développeur de crypter et de protéger cette valeur si nécessaire.

4.9.20.1.1 Restrictions

4.9.20.1.2 Paramètres

L'argument $text est un texte simple (pas de html) pour la valuer d'affichage. Par défaut la valeur est *****.

4.9.20.1.3 Cas particuliers

Aucun

4.9.20.1.4 Exemples

$options->enum(My_family::my_password)
    ->setPlaceHolder("Select a secret password");

4.9.20.2 setPlaceHolder

Cette option indique un texte qui est placé dans le champ de saisie lorsque la valeur est vide pour préciser le rôle de ce champ.

Dcp\Ui\PasswordRenderOptions setPlaceHolder(string $text)

4.9.20.2.1 Restrictions

4.9.20.2.2 Paramètres

L'argument $text est un texte simple (pas de html) qui sera utilisé comme placeholder du champ.

4.9.20.2.3 Cas particuliers

Aucun

4.9.20.2.4 Exemples

$options->enum(My_family::my_password)
    ->setPlaceHolder("Select a secret password");

4.9.21 Correspondances avec les options d'interface de Dynacase Core

La configuration des rendus utilisée par ce module n'est pas applicable aux interfaces "historique" de document de "Dynacase Core" ("FDL_CARD").

Les options d'affichage indiquées dans les attributs des familles (fichiers "csv/ods") ne sont pas prises en compte dans les configurations de rendus. Elles restent valides uniquement avec les interfaces fournies par Dynacase Core.

4.9.21.1 Tableau d'équivalence

Les options d'affichage "Dynacase Core" ont une équivalence qui peut être faite avec les options de rendu de "Dynacase Document UI".

4.9.21.1.1 Options communes à tous les types d'attributs

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
showempty Indique que l'attribut doit être présenté en consultation, même si sa valeur est vide. showempty()
vlabel Indique la position du libellé de l'attribut. setlabelposition()
elabel Texte du tooltip du label de l'attribut pour le document en mode modification. setDescription()
ititle Texte du tooltip du bouton '...' de l'aide à la saisie. setAutoCompleteHtmlLabel()
ltitle Texte affichable en tooltip sur l'hyperlien lorsque la souris passe dessus. setlink()
ltarget Nom de la fenêtre destinataire de l'hyperlien. setlink()
lconfirm Indique si on veut un message de confirmation avant l'activation du lien. useConfirm() pour les menus uniquement
tconfirm Texte de la confirmation. useConfirm() pour les menus uniquement
autosuggest En édition, sur une aide à la saisie, indique que la recherche est lancée à chaque modification du texte saisi. setKendoAutoCompleteConfiguration()
eltitle Options pour pour les extra liens (elink). addButton()
elsymbol Caractère affiché sur le bouton généré par l'extra lien. addButton()
eltarget Nom de la fenêtre destinataire sur le bouton généré par l'extra lien. addButton()
viewtemplate Référence de la vue d'attribut à utiliser lors de la consultation du document. setTemplate()
edittemplate Référence de la vue d'attribut à utiliser lors de la modification du document. setTemplate()

4.9.21.1.2 Options des attributs de type array

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
cellbodystyle Indique le style css appliqué sur les cellules du corps de tableau. Règles css
cellheadstyle Indique le style css appliqué sur les cellules de l'entête de tableau. Règles css
classname Indique une classe css à appliquer aux cellules du corps tableau en consultation. Pas d'équivalence directe - à réaliser sur le ready du tableau ou avec un template
displayrowcount Indique si le nombre de lignes du tableau est affiché dans l'entête de la première colonne. setRowCountThreshold()
empty Indique que le tableau, s'il est vide ne doit pas afficher la première rangée en modification. setRowMinDefault()
height Indique la hauteur du corps du tableau. Règles css
sorttable Indique que le tableau est triable. Pas d'équivalence directe - peut être réalisé sur le ready avec jquery-dataTable
twidth Indique la largeur du tableau. Règles css
userowadd Indique si l'utilisateur est autorisé à ajouter des rangées au tableau. disableRowAdd()
rowviewzone Indique une vue spécifique de tableau pour la consultation. setTemplate()
roweditzone Indique une vue spécifique de tableau pour la modification. setTemplate()
align Indique l'alignement horizontal pour les cellules de la colonne. Règles css
bgcolor Indique la couleur de fond des cellules de la colonne. Règles css
color Indique la couleur du texte pour les cellules de la colonne. Règles css
cwidth Indique la largeur de la colonne. Règles css

4.9.21.1.3 Options des attributs de type docid

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
create Indique qu'un document de la famille cible de la relation pourra être créé depuis le formulaire. addCreateDocumentButton()
docrev Indique quelle est la révision pointée par la relation. Cette option n'est pas une option de rendu mais elle est utilisée pour définir le lien vers le document cible à la révision voulue

4.9.21.1.4 Options des attributs de type enum

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
boolcolor Indique que l'énuméré sera représenté (en consultation) par un carré de couleur. Pas d'équivalence directe. Peut être implémenté par du code spécifique au moyen des événements.
eformat Indique le mode d'affichage de l'énuméré. setDisplay()
esort Indique l'ordre dans lequel les entrées seront listées. Pas d'équivalence
etype Indique si la valeur est restreinte aux valeurs de la liste. Pas d'équivalence
eunset Indiquer que l'énuméré sera vide par défaut. useFirstChoice()
mselectsize Indique le nombre d'items présentés pour les énumérés multiples lorsque l'option eformat est list. Non applicable

4.9.21.1.5 Options des attributs de type file

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
inline Indique si le fichier doit être consulté directement dans le navigateur. setContentDispositionInline()
pdffile Utilisé conjointement avec l'option viewfiletype, indique l'attribut contenant le fichier pdf à afficher. Pas d'équivalence
preventfilechange Ajoute une contrainte pour que le fichier à remplacer provienne de la dernière version du serveur. Pas d'équivalence
viewfileheigth Utilisé conjointement avec l'option viewfiletype, indique la hauteur du rendu affiché sur le navigateur. Pas d'équivalence
viewfiletype Indique qu'une prévisualisation du fichier sera disponible dans le navigateur, ne nécessitant donc pas de logiciel tiers. Pas d'équivalence

4.9.21.1.6 Options des attributs de type frame

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
bgcolor Indique la couleur de fond du cadre. Règle css
viewonfly Indique que le contenu du tab est chargé dynamiquement lorsque l'utilisateur clique sur l'onglet. Non applicable
firstopen Indique que cet onglet doit être sélectionné à l'ouverture du document. setOpenFirstTab()

4.9.21.1.7 Options des attributs de type htmltext

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
doclink Active l'option doclink du HTMLEditor. Pas d'équivalence
editheight Indique la hauteur de la zone d'édition. setHeight()
jsonconf Cette option permet de configurer finement l'éditeur de texte WYSIWYG. setCkEditorConfiguration()
toolbar Indique le template à utiliser pour la barre de menu. setToolbar()
toolbarexpand Indique si la barre de menu doit être dépliée lors de l'affichage de l'éditeur. setToolbarStartupExpanded()
allowedcontent Indique que la liste des balises autorisées n'est pas liée au menu. setCkEditorAllowAllTags()

4.9.21.1.8 Options des attributs de type image

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
iwidth Indique la largeur de l'image dans l'interface web de consultation. setThumbnailWidth()

4.9.21.1.9 Options des attributs de type longtext

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
editheight Indique la hauteur du textarea correspondant. setMaxDisplayedLineNumber()

4.9.21.1.10 Options des attributs de type menu

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
barmenu Indique que la popup doit s'ouvrir avec la barre de menus du navigateur. setTarget()
global Indique que l'action effectuée par le menu n'est pas liée à un document en particulier. Pas d'équivalence
lconfirm Indique qu'une confirmation doit être demandée avant activation du lien. confirmMenu()
lcontrol Indique que le menu est disponible uniquement dans le menu contextuel du document, lorsque la touche control est appuyée. Non applicable
mheight Indique la hauteur de la fenêtre popup. setTarget()
mtarget Indique le name de la fenêtre cible de l'hyperlien. setTarget()
mwidth Indique la largeur de la fenêtre popup. setTarget()
onlyglobal Utilisé conjointement avec l'option global, indique que le menu ne doit pas apparaître sur le document. Non applicable
submenu Indique que le menu doit avoir un menu parent. appendElement()
tconfirm Indique la question apparaissant pour la confirmation (ce doit être une question fermée). confirmMenu()

4.9.21.1.11 Options des attributs de type text

Les options sont définies dans le manuel de référence

Option Description de l'option d'affichage "Dynacase Core" Équivalence "Dynacase Document UI"
esize Valeur de l'attribut @size de l'input correspondant. setMaxLength()

Chapitre 5 Intervenir sur le client

Ce chapitre décrit les différentes méthodes mises à disposition par le contrôleur interne pour manipuler le document.

5.1 Fonctionnement du widget de document

5.1.1 Introduction

Ce chapitre détaille le fonctionnement du widget de document. Il explicite les différents éléments le composant et les relations entre ces éléments.

5.1.2 Architecture

Le client document est composé des éléments suivants :

5.1.3 Cinématique

Ce chapitre présente la cinématique des éléments fondamentaux du widget de document.

La légende des schémas suivants est :

5.1.3.1 Initialisation

Ce schéma montre le comportement du document lors du chargement d'un nouveau widget document.

Initialisation

Figure 56. Initialisation

Le point de départ (Initialisation du widget) est soit déclenché automatiquement (chargement d'une nouvelle page), soit à la demande du widget document.

Le controller se charge d'effectuer toutes les opérations nécessaires au rendu du document (initialisation des objets internes, récupération des données et représentation des données). En cas d'erreur, un message est affiché à l'utilisateur.

Les événements déclenchés sont les suivants :

1 : attributeReady
à chaque attribut rendu un événement est déclenché.
2 : ready (document)
lorsque le document est rendu un événement est déclenché.

5.1.3.2 Sauvegarde du document

Sauvegarde

Figure 57. Sauvegarde

La sauvegarde du document est déclenchée soit via une action utilisateur (clic sur un menu) ou via le controller (dans ce cas le schéma commence à l'émission de l'événement 2).

La sauvegarde serveur peut échouer pour plusieurs raisons :

Les événements déclenchés sont les suivants :

1 : actionClick
cet événement est déclenché au clic sur le menu et peut être annulé. Dans ce cas, la suite de la procédure est annulée sans avertissement à l'utilisateur.
2 : beforeSave
cet événement est déclenché quelle que soit la méthode de sauvegarde demandée et peut être annulé. Dans ce cas, la suite de la procédure est annulée sans avertissement à l'utilisateur.
3 : constraint
cet élément n'est pas un événement en tant que tel (voir chapitre sur les contraintes). Les contraintes sont déclenchées pour chaque attribut du document. En cas d'annulation, le processus de sauvegarde est annulé et un message est affiché à l'utilisateur et sur l'attribut concerné.
4 : validate
cet événement est déclenché une fois les contraintes analysées. En cas d'annulation, la suite de la procédure est annulée sans avertissement à l'utilisateur.
5 : afterSave/close
ces événements sont déclenchés une fois le retour des données du serveur et l'analyse de ces données faite. Cet événement n'est pas annulable.
6 : attributeReady
à chaque attribut rendu cet événement est déclenché.
7 : ready
lorsque le document est rendu cet événement est déclenché.

5.1.3.3 Changement de document

Changement de document

Figure 58. Changement de document

Le changement de document peut-être déclenché soit via le menu, via des liens internes ou via le controller (dans ce cas le schéma commence à l'émission de l'événement 1).

Le changement de document peut échouer pour :

Les événements déclenchés sont les suivants :

1 : beforeClose
cet événement est déclenché (dans le contexte de l'ancien document) avant le changement de document (fetchDocument). En cas d'annulation le processus de changement est annulé sans avertissement à l'utilisateur.
2 : attributeReady
à chaque attribut rendu cet événement est déclenché.
3 : ready (document ready)
lorsque le document est rendu cet événement est déclenché. Attention : dans le cas d'un document avec onglets, cet événement arrive avant que l'onglet par défaut ne soit complètement affiché. Les événements attributeReady des attributs de l'onglet arrivent après le ready du document.

5.1.3.4 Suppression de document

La suppression d'un document est une suppression logique : mise à la corbeille. Un document supprimé reste visible mais n'est plus modifiable.

Suppression de document

Figure 59. Suppression de document

La suppression d'un document peut-être déclenchée soit via le menu soit via le controller (dans ce cas le schéma commence à l'émission de l'événement 2).

Cette opération est la seule conduisant à la suppression de l'objet interne document. Celui-ci est automatiquement réinstancié une fois la suppression terminée et le document supprimé est ensuite affiché.

Les événements déclenchés sont les suivants :

1 : actionClick
cet événement est déclenché au clic sur le menu et peut être annulé. Dans ce cas, la suite de la procédure est annulée sans avertissement à l'utilisateur.
2 : beforeDelete
cet événement est déclenché quelle que soit la méthode de suppression demandée et peut être annulé. Dans ce cas, la suite de la procédure est annulée sans avertissement à l'utilisateur.
3 : afterDelete/close
ces événements sont déclenchés une fois le retour des données du serveur et l'analyse de ces données faite. Cet événement n'est pas annulable.
4 : attributeReady
à chaque attribut rendu cet événement est déclenché.
5 : ready (document)
lorsque le document (supprimé) est rendu cet événement est déclenché.

5.1.3.5 Changement d'une valeur (via l'interface)

Changement d'une valeur via l'interface

Figure 60. Changement d'une valeur via l'interface

l'appel à la contrainte se fait après le changement de la valeur de l'attribut, la contrainte ne permet donc que d'afficher un message (et ne peut en aucun cas empêcher la saisis de la valeur. Néanmoins, l'enregistrement sur le serveur pourra être interdit en cas de contrainte non respectée.

Les événements déclenchés sont les suivants :

1 : change
cet événement est déclenché à chaque fois qu'un attribut est modifié.
2 : constraint
cet élément n'est pas événement en tant que tel, voir chapitre sur les contraintes. En cas d'annulation, un message est affiché sur l'attribut concerné.

5.1.3.6 Changement d'une valeur (controller)

Changement d'une valeur via le controller

Figure 61. Changement d'une valeur via le controller

l'appel à la contrainte se fait après le changement de la valeur de l'attribut, la contrainte ne permet donc que d'afficher un message (et ne peut en aucun cas empêcher la saisis de la valeur. Néanmoins, l'enregistrement sur le serveur pourra être interdit en cas de contrainte non respectée.

Les événements déclenchés sont les suivants :

1 : change
cet événement est déclenché à chaque fois qu'un attribut est modifié.
2 : constraint
cet élément n'est pas événement en tant que tel, voir chapitre sur les contraintes. En cas d'annulation, un message est affiché sur l'attribut concerné.

5.2 Objets de manipulation sur le client

5.2.1 Introduction

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

5.2.2 Document

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

id
identifiant du document,
initid
identifiant de la lignée documentaire,
title
titre du document,
family

objet décrivant la famille en cours, et contenant les propriétés suivantes :

title
titre de la famille,
name
nom logique de la famille,
id
identifiant de la famille,
icon
lien vers l'icone de la famille,
icon
lien vers l'icone du document,
revision
numéro de révision du document,
status
statut du document (actif, supprimé, etc.),
viewId
rendu en cours,
renderMode

mode de rendu en cours, parmi :

edit
édition,
view
consultation,
isModified (booléen)
indique si le document 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 document ne peut être commencée que lorsque l'ensemble des téléversements sont finis.

5.2.3 Attribut

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

5.2.3.1 Propriétés

id
identifiant de l'attribut

5.2.3.2 Méthodes

getProperties() : {}
retourne l'ensemble des propriétés de l'attribut sous la forme d'un objet indexé par les noms des propriétés,
getOptions() : {}
retourne l'ensemble des options de l'attribut 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) de l'attribut en cours. L'option facultative type permet d'avoir les valeurs suivantes :

current
valeur courante de l'attribut (valeur par défaut). La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée,
previous
valeur précédente de l'attribut avant modification. La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée,
initial
valeur initiale de l'attribut. La méthode retourne alors un objet value : valeur brute, displayValue : valeur formatée,
all (valeur par défaut)
retourne toutes les valeurs de l'attribut sous la forme d'un objet indexé par type de valeur.
setValue(newValue): $
permet de modifier la valeur courante de l'attribut. 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 attributs à valeurs multiple, le valeur doit être un tableau de valeur.
getLabel() : text
permet de récupérer le libellé de l'attribut.
setLabel(newLabel) : $
permet de modifier le libellé de l'attribut. L'argument est du texte, le format HTML n'est pas accepté.
isModified() : bool
permet de savoir si la valeur de l'attribut a été modifiée depuis la dernière sauvegarde. Retourne true si la valeur a été modifiée.

5.2.4 Fenêtre de transition

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

5.2.4.1 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).

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

5.2.5 Menu

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

5.2.5.1 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),
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 icone 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'icone 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

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

5.2.5.2 Méthodes

5.2.5.2.1 getProperties

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

5.2.5.2.1.1 Arguments

Pas d'arguments

5.2.5.2.1.2 Retour

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

5.2.5.2.1.3 Exception

Pas d'exception

5.2.5.2.2 disable

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

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

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

5.2.5.2.2.2 Retour

Pas de retour.

5.2.5.2.2.3 Exception

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

5.2.5.2.3 enable

Cette méthode active le menu.

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

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

5.2.5.2.3.2 Retour

Pas de retour.

5.2.5.2.3.3 Exception

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

5.2.5.2.4 hide

Cette méthode cache le menu.

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

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

5.2.5.2.4.2 Retour

Pas de retour.

5.2.5.2.4.3 Exception

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

5.2.5.2.5 setLabel

Cette méthode modifie le label du menu.

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

5.2.5.2.5.2 Retour

Pas de retour.

5.2.5.2.5.3 Exception

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

5.2.5.2.6 setHtmlLabel

Cette méthode modifie le label du menu.

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

5.2.5.2.6.2 Retour

Pas de retour.

5.2.5.2.6.3 Exception

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

5.2.5.2.7 setUrl

Cette méthode modifie l'url menu.

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

5.2.5.2.7.2 Retour

Pas de retour.

5.2.5.2.7.3 Exception

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

5.2.5.2.8 setCssClass

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

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

5.2.5.2.8.1 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`][redraw] permet de rendre le menu ensuite.
    Utile pour faire un unique rendu après plusieurs modifications.
5.2.5.2.8.2 Retour

Pas de retour.

5.2.5.2.8.3 Exception

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

5.2.5.2.8.4 Exemple

Ajout d'une classe à un menu

var menuId = 'mon-menu',
    menu = window.dcp.documentController("getMenu", menuId),
    currentClasses = menu.getProperties().cssClass.split(/\s+/),
    newClass = 'menu-highlight';
if(-1 === currentClasses.indexOf(newClass)) {
    curentClasses.push(newClass);
    menu.setCssClass(currentClasses.join(' '));
}

5.2.5.2.9 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 Dcp\Ui\ItemMenu::setIcon.

Attention, contrairement à Dcp\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).

5.2.5.2.9.1 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`][redraw] permet de rendre le menu ensuite.
    Utile pour faire un unique rendu après plusieurs modifications.
5.2.5.2.9.2 Retour

Pas de retour.

5.2.5.2.9.3 Exception

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

5.2.5.2.10 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 redessiner le menu une unique fois en appliquant tous les changements.

5.2.5.2.10.1 Arguments

Pas d'argument.

5.2.5.2.10.2 Retour

Pas de retour.

5.2.5.2.10.3 Exception

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

5.3 Méthodes de manipulation du document

5.3.1 Introduction

Ces méthodes permettent de manipuler le document en cours d'affichage.

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 :

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

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 :

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

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 :

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

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 :

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

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

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 :

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 :

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

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

5.3.2.11.2 Retour

Aucune.

5.3.2.11.3 Exception

Aucune.

5.3.3 Méthodes de manipulation de l'affichage du document

5.3.3.1 hideAttribute

Cette méthode permet de cacher un attribut affiché.

Les attributs invisibles (en consultation : I, H, et O ; en modification : I, H et R) ne peuvent ni être cachés, ni montrés.

5.3.3.1.1 Arguments

attributeId (string)
nom de l'attribut à cacher

5.3.3.1.2 Retour

Pas de retour

5.3.3.1.3 Exception

Si le nom de l'attribut n'existe pas

5.3.3.1.4 Exemple

window.dcp.document.documentController("hideAttribute", "animal_title");

5.3.3.2 showAttribute

Cette méthode permet de montrer un attribut caché.

Les attributs invisibles (en consultation : I, H, et O ; en modification : I, H et R) ne peuvent ni être cachés, ni montrés.

5.3.3.2.1 Arguments

attributeId (string)
nom de l'attribut à montrer

5.3.3.2.2 Retour

Pas de retour

5.3.3.2.3 Exception

Si le nom de l'attribut n'existe pas

5.3.3.2.4 Exemple

window.dcp.document.documentController("showAttribute", "animal_title");

5.3.3.3 showMessage

Cette méthode permet d'afficher un message à l'utilisateur.

Il se présente dans une notification en haut à droite de l'écran.

5.3.3.3.1 Arguments

message (string|object)
soit une chaine de caractères, soit une structure contenant : type : l'importance du message parmi * info (valeur par défaut), * error, * warning * success * notice message (plein texte) : le contenu du message.

5.3.3.3.2 Retour

Pas de retour

5.3.3.3.3 Exception

Pas d'exception

5.3.3.3.4 Exemple

window.dcp.document.documentController("showMessage", "Bonjour utilisateur");

5.3.3.4 setAttributeErrorMessage

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 attribut).

5.3.3.4.1 Arguments

attributeId (string)
identifiant de l'attribut,
message (string) (plein texte)
contenu du message,
index (int)
numéro de ligne si l'attribut est dans un array.

5.3.3.4.2 Retour

Pas de retour

5.3.3.4.3 Exception

Si le nom de l'attribut n'existe pas

5.3.3.4.4 Exemple

window.dcp.document.documentController("setAttributeErrorMessage", "ba_title", "Le titre est obligatoire");

5.3.3.5 cleanAttributeErrorMessage

Cette méthode permet de supprimer tous les messages d'erreur affichés sur un attribut.

5.3.3.5.1 Arguments

attributeId (string)
identifiant de l'attribut,
index (int)
numéro de ligne si l'attribut est dans un array.

5.3.3.5.2 Retour

Pas de retour.

5.3.3.5.3 Exception

Si le nom de l'attribut n'existe pas.

5.3.3.5.4 Exemple

Supprime tous les messages d'erreur sur l'attribut ba_title.

window.dcp.document.documentController("cleanAttributeErrorMessage", "ba_title");
 

5.3.3.6 selectTab

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

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

5.3.3.6.1 Arguments

attributeId (string)
identifiant de l'attribut (onglet) à sélectionner.

5.3.3.6.2 Retour

L'objet jQuery.

5.3.3.6.3 Exception

Si le nom de l'attribut n'existe pas. Si l'attribut n'est pas un onglet.

5.3.3.6.4 Exemple

Affiche l'onglet my_tab.

window.dcp.document.documentController("selectTag", "my_tab");

5.3.3.7 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 attributeReady 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.

5.3.3.7.1 Arguments

attributeId (string)
identifiant de l'attribut (onglet) à générer.

5.3.3.7.2 Retour

L'objet jQuery.

5.3.3.7.3 Exception

Si le nom de l'attribut n'existe pas. Si l'attribut n'est pas un onglet.

5.3.3.7.4 Exemple

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

window.dcp.document.documentController("addEventListener",
      "ready",
      function (event, documentObject, message) {
          var _this=this;
          var attrs=_this.documentController("getAttributes");
 
          attrs.forEach(function (attr) {
              if (attr.getProperties().type === "tab") {
                  _this.documentController("drawTab", attr.id);
              }
          });
      }
  );

5.3.4 Méthodes d'accès aux valeurs du document

Ces méthodes permettent de récupérer et de modifier les valeurs du document en cours.

5.3.4.1 getProperties

Cette méthode retourne les propriétés du document en cours sous la forme d'un objet.

5.3.4.1.1 Arguments

Pas d'arguments

5.3.4.1.2 Retour

Objet

5.3.4.1.3 Exception

Pas d'exception

5.3.4.1.4 Exemple

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

retourne

{
    "id": 1435,
    "title": "12/05/1985",
    "family": {
        "title": "Test tout type",
        "name": "TST_ALLTYPE",
        "id": 1430,
        "icon": "resizeimg.php?img=Images%2Fdoc.png&size=24"
    },
    "icon": "resizeimg.php?img=Images%2Fdoc.png&size=24",
    "revision": 0,
    "status": "alive",
    "initid": 1435,
    "viewId": "!defaultEdition",
    "renderMode": "edit",
    "isModified": false
}

5.3.4.2 getProperty

Cette méthode retourne une propriété du document en cours.

5.3.4.2.1 Arguments

property (string)
nom de la propriété

5.3.4.2.2 Retour

Suivant la propriété demandée. Si la propriété n'existe pas, le retour est undefined.

5.3.4.2.3 Exception

Pas d'exception

5.3.4.2.4 Exemple

window.dcp.document.documentController("getProperty", "title")

retourne

"COLLET Noah"

5.3.4.3 hasAttribute

Cette méthode retourne true si l'attribut est présent dans le document en cours.

5.3.4.3.1 Arguments

attributeId (string): nom de l'attribut

5.3.4.3.2 Retour

Un Booléen.

5.3.4.3.3 Exception

Pas d'exception

5.3.4.3.4 Exemple

Ajout d'une méthode hasAttribute

function (attributeId) {
        var hasAttribute = window.dcp.document.documentController("hasAttribute",attributeId)
        console.log("l'attribut ", attributeId, "est présent dans le document ?", hasAttribute)
}

5.3.4.4 getAttributes

Cette méthode retourne la liste des attributs du document en cours.

5.3.4.4.1 Arguments

Pas d'arguments

5.3.4.4.2 Retour

Un tableau d'objet attributs.

5.3.4.4.3 Exception

Pas d'exception

5.3.4.4.4 Exemple

Ajout d'une méthode getAttributes

function () {
        var getAttributes = window.dcp.document.documentController("getAttributes")
        console.log("les attribut du document sont :", getAttributes)
}

5.3.4.5 getAttribute

Cette méthode retourne un attribut du document en cours.

5.3.4.5.1 Arguments

attributeId (string)
nom de l'attribut

5.3.4.5.2 Retour

Un objet attribut. Retourne null, si l'attribut n'existe pas.

5.3.4.5.3 Exception

Pas d'exception

5.3.4.5.4 Exemple

Ajout d'une méthode getAttribute

function (attributeId:string) {
        var getAttribute = window.dcp.document.documentController("getAttribute",attributeId)
        console.log("voici l'attribut ", attributeId, " : ", getAttribute)
}

5.3.4.6 getValues

Cette méthode retourne les valeurs des attributs du document en cours.

5.3.4.6.1 Arguments

pas d'argument

5.3.4.6.2 Retour

Un objet indexé par les noms des attributs, et pour chaque attribut les clés suivantes :

value
la valeur brute
displayValue
la valeur telle qu'affichée

5.3.4.6.3 Exception

Pas d'exception

5.3.4.6.4 Exemple

window.dcp.document.documentController("getValues")

retourne

{
    "zct_civility": {
        "value": null,
        "displayValue": null
    },
    "zct_lname": {
        "value": "COLLET",
        "displayValue": "COLLET"
    },
    "zct_fname": {
        "value": "Noah",
        "displayValue": "Noah"
    },
    "zct_mail": {
        "value": "noah142@zoo.net",
        "displayValue": "noah142@zoo.net"
    },
    "zct_photo": {
        "value": null,
        "displayValue": null
    },
    "zct_phone": {
        "value": null,
        "displayValue": null
    },
    "zct_mobile": {
        "value": null,
        "displayValue": null
    },
    "zct_workaddr": {
        "value": null,
        "displayValue": null
    },
    "zct_workpostalcode": {
        "value": null,
        "displayValue": null
    },
    "zct_worktown": {
        "value": "Châteauroux",
        "displayValue": "Châteauroux"
    }
}

5.3.4.7 getValue

Cette méthode retourne la valeur d'un attribut du document en cours.

5.3.4.7.1 Arguments

attributeId (string)
identifiant de l'attribut

5.3.4.7.2 Retour

Un objet

5.3.4.7.3 Exception

Si l'attribut n'existe pas

5.3.4.7.4 Exemple

window.dcp.document.documentController("getValue", "zct_civility")

retourne

{
    "value":null,
    "displayValue":null
}

5.3.4.8 setValue

Cette méthode met à jour la valeur d'un attribut du document en cours.

5.3.4.8.1 Arguments

attributeId (string)
identifiant de l'attribut
value (object)
La valeur sous la forme d'un objet contenant value : valeur brute de l'attribut, (obligatoire) displayValue : valeur de l'attribut présentée aux utilisateurs.

Suivant les types d'attribut, la valeur peut nécessiter d'autres informations. Si displayValue n'est pas renseignée, elle sera affectée à la valeur de value.

Pour les attributs multivalués (attributs dans les tableaux ou avec l'option multiple=yes), la valeur doit renseigner un "index" pour indiqué le rang de l'élément à modifier.

5.3.4.8.2 Retour

Pas de retour

5.3.4.8.3 Exception

Dans le cas d'un multiple, la valeur doit contenir aussi l'index ou être un tableau. Dans le cas de nombres multiple dans un tableau, la propriété display value doit être renseignée (cette valeur ne peut pas utiliser de point comme séparateur de décimal dans un nombre)

5.3.4.8.4 Exemples

Cas d'un attribut texte simple :

window.dcp.document.documentController("setValue", "zct_title", {value: "Bonjour à tous"});

Cas d'un attribut énuméré simple : value est la clef

window.dcp.document.documentController("setValue", "zct_civility",
    {
        value: "M",
        displayValue: "Monsieur"
    }
);

Cas d'une relation (docid) multiple : affectation du troisième élément

window.dcp.document.documentController("setValue", "zct_annexes",
    {
         value : "9876",
         displayValue:"Conjecture de Hodge",
         index: 2
    }
);

Cas d'une date dans un tableau : affectation du premier élément

window.dcp.document.documentController("setValue", "zct_dates",
    {
        value : "1999-12-25",
        index: 0
    }
);

Si l'index est égal au nombre d'élément déjà présent dans le tableau, une rangée est ajoutée avec la nouvelle valeur. Si l'index dépasse le nombre d'élément, des rangées supplémentaires sont ajoutées. Ces rangées supplémentaires contiennent les valeurs par défaut.

Cas d'une relation (docid) multiple : affectation de 3 éléments

window.dcp.document.documentController("setValue","zct_mathematical_problems",
    [
        {value:"1978", displayValue:"Équations de Navier-Stokes"},
        {value:"2032", displayValue:"Conjecture de Poincaré"},
        {value:"2123", displayValue:"Hypothèse de Riemann"}
    ]
);

Cas de nombres dans un tableau : affectation d'une colonne avec 3 éléments. Le résultat produit un tableau avec 3 rangées.

window.dcp.document.documentController("setValue","zct_widths",
    [
        {value: 187.5},
        {value: 209.56},
        {value: -12.5}
    ]
);

Dans ce cas, si le nombre d'éléments est inférieur au nombre de rangées, les rangées supérieures à ce nombre d'éléments sont supprimées. Si le nombre est supérieur aux nombres de rangée, des rangées supplémentaires sont ajoutées. Ces rangées supplémentaires contiennent les valeurs par défaut.

Cas de relation multiple dans un tableau : affectation de 3 liens dans la cellule "zct_annexes" de la rangée n°2. Dans ce cas, la valeur contient un tableau de valeurs. Il n'est pas possible de modifier directement un sous-index particulier des relations multiples dans les tableaux.

window.dcp.document.documentController("setValue","zct_annexes",
    {
        index : 1,
        value: [
            {value:"4948", displayValue:"Conjecture de Birch et Swinnerton-Dyer"},
            {value:"1032", displayValue:"Équations de Yang-Mills"},
            {value:"2123", displayValue:"Hypothèse de Riemann"}
        ]
    }
);

5.3.4.9 appendArrayRow

Cette méthode permet d'ajouter une ligne à la fin d'un attribut de type tableau.

Si une des colonnes du tableau n'est pas renseignée, la valeur par défaut sera utilisée.

5.3.4.9.1 Arguments

attributeId
identifiant de l'attribut
values
un objet ayant pour clef la valeur d'un des attributs du tableau et pour contenu de chaque clef un objet avec les propriétés : value : valeur brute de l'attribut, displayValue : valeur de l'attribut présenté aux utilisateurs.

5.3.4.9.2 Retour

Pas de retour

5.3.4.9.3 Exception

5.3.4.9.4 Exemple

Insérer une ligne à la fin du tableau

window.dcp.document.documentController("appendArrayRow", "zct_array_numbers",
    {
        zct_integers:{value:12},
        zct_doubles:{value:3.1415},
        zct_moneys:{value:12.5}
    }
);

5.3.4.10 insertBeforeArrayRow

Cette méthode permet d'ajouter une ligne avant une ligne d'un attribut de type tableau.

5.3.4.10.1 Arguments

attributeId
identifiant de l'attribut
values
un objet ayant pour clef la valeur d'un des attributs du tableau et pour contenu de chaque clef un objet avec les propriétés : value : valeur brute de l'attribut, displayValue : valeur de l'attribut présenté aux utilisateurs.
index (int)
Position à laquelle sera insérée la ligne (0 étant au début du tableau)

5.3.4.10.2 Retour

Pas de retour

5.3.4.10.3 Exception

5.3.4.10.4 Exemple

Insérer une ligne en première place d'un tableau :

window.dcp.document.documentController(
    "insertBeforeArrayRow",
    "tst_apibase_array",
    {
        "tst_dates" :{
            value : "1985-05-13"
        }
    },
    0
);

5.3.4.11 removeArrayRow

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

5.3.4.11.1 Arguments

attributeId (string)
identifiant de l'attribut
index (int)
index de la ligne avant l'insertion

5.3.4.11.2 Retour

Pas de retour

5.3.4.11.3 Exception

5.3.4.11.4 Exemple

Supprimer la première ligne d'un tableau

window.dcp.document.documentController("removeArrayRow", "tst_apibase_array", 0)

5.4 Manipulation des menus

5.4.1 Introduction

Ces méthodes permettent de manipuler les menus du document.

Les menus dynamiques (dont la valeur provient du serveur) ne sont pas concernés par ces méthodes.

5.4.2 Liste des méthodes

5.4.2.1 hasMenu

Cette méthode retourne truesi le menu est présent dans le document.

5.4.2.1.1 Arguments

id (string): identifiant du menu

5.4.2.1.2 Retour

Booléen.

5.4.2.1.3 Exception

Si jamais le modèle n'est pas déjà initialisé.

5.4.2.1.4 Exemple

function (menuId) {
    var hasMenu = window.dcp.document.documentController("hasMenu",menuId)
    return console.log("le menu ", menuId , "est-il présent ? ", hasMenu)
}

5.4.2.2 getMenus

Cette méthode retourne la liste des menus.

5.4.2.2.1 Arguments

Pas d'arguments

5.4.2.2.2 Retour

Tableau d'objets menu.

5.4.2.2.3 Exception

Si jamais le modèle n'est pas déjà initialisé

5.4.2.2.4 Exemple

function () {
    var getMenus = window.dcp.document.documentController("getMenus")
    return console.log("les menus de mon document sont : ", getMenus)
}

5.4.2.3 getMenu

Cette méthode retourne un objet menu à partir de son identifiant.

5.4.2.3.1 Arguments

id (string): identifiant du menu

5.4.2.3.2 Retour

Objet menu.

5.4.2.3.3 Exception

Si jamais le modèle n'est pas déjà initialisé

5.4.2.3.4 Exemple

function (menuId) {
    var getMenu = window.dcp.document.documentController("getMenu",menuId)
    return console.log("le menu ", menuId , "a pour id ", getMenu.id)
}

5.5 Internationalisation

Il est possible de traduire des chaînes de caractères côté client. Ces traductions se font au moyen d'un translator, qui expose les méthodes _, ___ et getLocale.

5.5.1 Récupération d'un translator

Un translator peut être obtenu au moyen de la fonction window.dcp.getTranslator

5.5.1.1 La fonction getTranslator

5.5.1.1.1 Arguments

catalog
Le nom du catalogue à utiliser pour ce translator. Par défaut, dynacase génère un catalogue par application, appelé du même nom que l'application.
success
Fonction de callback appelée une fois le translator prêt.
Elle reçoit le _translator_ en argument.
error
Fonction de callback appelée en cas d'erreur.
Elle reçoit le message d'erreur en argument.

5.5.1.1.2 Retour

Retourne une promise qui peut être utilisée à la place du callback.

5.5.1.1.3 Exception

Aucune

5.5.2 Utilisation d'un translator

5.5.2.1 La méthode _

Cette méthode retourne la traduction d'un texte.

5.5.2.1.1 Arguments

key
La chaîne à traduire

5.5.2.1.2 Retour

Retourne la chaîne traduite. Lorsque la traduction en figure pas dans le catalogue, la chaîne non traduite est retournée.

5.5.2.1.3 Exceptions

Aucune

5.5.2.2 La méthode ___

Cette méthode retourne la traduction d'un texte dans un contexte donné.

5.5.2.2.1 Arguments

key
La chaîne à traduire
contexte
Le contexte dans lequel chercher la traduction

5.5.2.2.2 Retour

Retourne la chaîne traduite. Lorsque la traduction en figure pas dans le catalogue pour le contexte demandé, la chaîne non traduite est retournée.

5.5.2.2.3 Exceptions

Aucune

5.5.2.3 La méthode getLocale

Cette méthode retourne un objet décrivant la locale de ce catalogue.

5.5.2.3.1 Arguments

aucun

5.5.2.3.2 Retour

Retourne un objet conforme à la description de locale de dynacase

5.5.2.3.3 Exceptions

Aucune

5.5.3 Usage avancé

Il est possible de générer un translator à partir d'un catalogue au moyen de la fonction window.dcp.translatorFactory.

5.5.3.1 La fonction translatorFactory

Retourne un nouvel objet translator à partir du catalogue passé en argument

5.5.3.1.1 Arguments

catalog
le catalogue - au format JSON - sous la forme d'un objet javascript

Le format des ces objets est défini dans le manuel de référence.

5.5.3.1.2 Retour

Un translator, avec les méthodes _, ___ et getLocale.

Si le catalogue n'est pas du JSON valide, le translator retourné ne contient que des traductions vides.

5.5.3.1.3 Exceptions

Aucune

5.5.4 Génération du catalogue

La génération du catalogue est couverte par le chapitre correspondant du manuel de référence

5.5.4.1 Format du catalogue

Le format du catalogue est couvert par le chapitre correspondant du manuel de référence

5.6 Contraintes

5.6.1 Introduction

Ces méthodes permettent de programmer des contraintes clientes. Ces contraintes sont appliquées localement et ne permettent pas une vérification de la cohérence des données sécurisée, elles sont toutefois utiles pour améliorer l'ergonomie du document.

5.6.2 Fonctionnement

Les contraintes sont appliquées sur une instance du widget document. Elles restent donc valables durant toute la vie de cette instance de widget et sont appliquées quelque soit le document représenté par cette instance.

Les contraintes sont appelées à deux moments lors de la vie du document :

Les contraintes enregistrées possèdent toutes un nom logique qui permet de les identifier. Ce nom logique peut être composé avec un namespace, celui-ci est séparé du nom logique par un ..

Ce nom logique est unique : si deux événements sont enregistrés avec le même nom, le plus récent écrase le plus ancien. Toutes les contraintes ayant le même namespace peuvent être désinscrites via un appel à la méthode de désinscription avec le namespace. Soit par exemple, checkAge.animal, checkPoids.animal peuvent être supprimées en appelant removeConstraint avec .animal.

5.6.2.1 Cycle de vie des contraintes

Une contrainte possède deux pré-conditions :

documentCheck
cette pré-condition est exécutée à chaque rechargement du document. Si elle retourne true, la contrainte est exécutée par le document en cours, sinon elle est mise en attente ;
attributeCheck
cette pré-condition est exécutée à chaque modification d'attribut. Si elle retourne true, la contrainte est exécutée sur l'attribut en cours, sinon elle est mise en attente.

Les pré-conditions permettent de n'appliquer les contraintes que dans leur cas d'utilisation et de réduire la charge d'exécution sur le client.

5.6.3 Les méthodes associées

5.6.3.1 addConstraint

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

Une contrainte n'est pas déchargée automatiquement lors du changement d'état du widget document ( changement de document, d'état, etc.).

5.6.3.1.1 Arguments

options (objet)

L'argument décrit la contrainte il contient les champs suivants :

documentCheck (function javascript, facultative)
cette function permet d'indiquer pour quel type de document s'applique la contrainte. Elle doit retourner true pour indiquer que la contrainte est applicable pour ce type de document. Par défaut, la contrainte s'applique pour tous les documents.
attributeCheck(function javascript, facultative)
Cette function permet d'indiquer pour quel attribut s'applique la contrainte. Elle doit retourner true pour indiquer que la contrainte est applicable pour cet attribut. Par défaut, la contrainte s'applique à tous les attributs.
name (string, facultative)
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.
once (booléen, facultatif)
si once est à true, la contrainte n'est appliquée qu'une seule fois et ensuite supprimée,
constraintCheck (function javascript)

cet argument est une fonction qui est appelée lors de la modification d'un attribut du document. Si une chaine 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" Elle reçoit les paramètres suivants :

document
un objet document,
attribute
un objet attribut,
values

objet décrivant la valeur de l'attribut en cours. Il contient trois valeurs :

current
valeur courante de l'attribut,
previous
valeur précédente de l'attribut,
initial
valeur de l'attribut au chargement du document.

5.6.3.1.2 Retour

Le nom de la contrainte est retourné.

5.6.3.1.3 Exception

Pas d'exception

5.6.3.1.4 Exemple

Ajout d'une contrainte s'appliquant uniquement

window.dcp.document.documentController(
    "addConstraint",
    {
        "name": "checkAge.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "animal_date";
        }
    },
    function(documentObject, attribute, value) {
        if (value.current.value < "1885-05-12") {
            return "La date doit être inférieure au 12/05/1885";
        }
    }
);

Cas d'un attribut inclus dans un tableau. Dans ce cas, la contrainte est indiquée pour une rangée particulière. Cet exemple vérifie si une des valeurs est vide ou non.

Si l'index n'est pas indiqué, alors la contrainte sera affichée pour toutes les rangées.

window.dcp.document.documentController(
    "addConstraint",
    {
        "name": "checkEmpty.child",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "my_childs";
        }
    },
    function(documentObject, attribute, value) {
        var currentDocids=value.current;
        // The value is an array for a multiple value
        _.each(currentDocids, function (aDocid, k) {
            if (!aDocid.value) {
                // k is the row number : first row is zero
                return [{
                    message : "Ne doit pas être vide",
                    index:k
                }];
            }
        });
    }
);

5.6.3.2 listConstraints

Cette méthode permet de lister les contraintes en cours sur le widget. La liste retournée affiche toutes les contraintes actives ou pas sur le document en cours.

5.6.3.2.1 Arguments

Pas d'argument

5.6.3.2.2 Retour

Tableau de contraintes

5.6.3.2.3 Exception

Pas d'exception

5.6.3.2.4 Exemple

Liste les contraintes associées au widget.

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

Retourne

[{
    documentCheck: function (documentObject) { return documentObject.family.name === "ANIMAL"},
    attributeCheck: function (attribute, documentObject) { return attribute.id = "animal_date"},
    constraintCheck: function (documentObject, attribute) {…}
}]

5.6.3.3 removeConstraint

Cette méthode permet de supprimer une contrainte ou un ensemble de contraintes sur le widget en cours.

5.6.3.3.1 Arguments

nom (string)
nom de la contrainte ou namespace des contraintes à supprimer.

5.6.3.3.2 Retour

La ou les contraintes supprimées.

5.6.3.3.3 Exception

Pas d'exception.

5.6.3.3.4 Exemple

Suppression de la contrainte nommée animal ou des contraintes ayant le namespace animal.

window.dcp.document.documentController("removeConstraint", ".animal");

Retour :

[{
    documentCheck: function (document) { return document.family.name === "ANIMAL"},
    attributeCheck: function (attribute, documentObject) { return attribute.id = "animal_date"},
    constraintCheck: function (document, attribute) {…}
}]

5.7 Les événements documentaires

Ces méthodes et ces événements permettent de réagir aux modifications et à l'évolution du document.

5.7.1 Fonctionnement des événements

Les écouteurs sont appliqués sur une instance du widget document. Ils restent donc valables durant toute la vie de cette instance de widget et sont déclenchés quel que soit le document représenté par cette instance.

Les écouteurs enregistrés possèdent tous un nom logique qui permet de les identifier.

Ce nom logique est unique. Si deux écouteurs sont enregistrés avec le même nom, le plus récent écrase le plus ancien.

Ce nom logique peut être composé avec un namespace. Celui-ci est séparé du nom logique par un .. Tous les écouteurs ayant le même namespace peuvent être désinscrits via un appel à la méthode de désinscription avec ce namespace. Soit par exemple, validate.animal, change.animal peuvent être supprimés en appelant removeEvent avec .animal.

5.7.1.1 Cycle de vie des événements

Une écouteur possède une pré-condition :

documentCheck
cette pré-condition est exécutée à chaque rechargement du document. Si elle retourne true, l'écouteur est exécuté par le document en cours, sinon il est mis en attente.

Les pré-conditions permettent de n'appliquer les écouteurs que dans leur cas d'utilisation et de réduire la charge d'exécution sur le client.

5.7.2 Les méthodes associées aux événements

5.7.2.1 addEventListener

Cette méthode permet de charger un écouteur dans le widget de document. Une fois l'événement chargé, il est valide durant toute la vie du widget document.

Un évènement n'est pas déchargé automatiquement lors du changement d'état du widget document (changement de document, d'étape, etc.).

5.7.2.1.1 Arguments

type
type de l'événement à suivre. Voir les types d'événements déclenchés par * le document, * les attributs, * les changements d'état, * les événements personnalisés
options (object)

il contient les champs suivants :

documentCheck(function javascript, facultatif)
Cette fonction permet d'indiquer pour quel type de document s'applique l'écouteur. Elle reçoit en entrée un objet document décrivant le document courant. Elle doit retourner true pour indiquer que l'écouteur' est applicable pour ce type de document. Par défaut l'écouteur s'applique pour tous les documents.
name (string, facultative)

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 seron donc plus déclenché.

once (booléen, facultatif)
si once est à true, l'écouteur n'est appliqué qu'une seule fois et ensuite supprimé.
callback (function javascript)

cette fonction est appelée lorsque l'événement type est émis. Elle reçoit les paramètres suivants :

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attribute (uniquement sur les événements concernant les attributs)
un objet attribut.
values (uniquement sur les événement concernant les attributs)

objet décrivant la valeur de l'attribut en cours, il contient trois propriétés :

current
valeur courante de l'attribut,
previous
valeur précédente de l'attribut,
initial
valeur de l'attribut au chargement du document

5.7.2.1.2 Retour

Le nom de l'événement est retourné.

5.7.2.1.3 Exception

Pas d'exception

5.7.2.1.4 Exemples

Ajout d'un écouteur s'appliquant uniquement sur le changement des attributs de la famille ANIMAL.

window.dcp.document.documentController("addEventListener",
    "change",
    {
        "name": "alertChange.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        }
    },
    function(event, documentObject, attribute, value) {
        alert(value.currentValue);
    }
);

Ajout d'un écouteur s'appliquant uniquement sur les messages de la famille ANIMAL et annulant les événements reçus.

window.dcp.document.documentController("addEventListener",
    "displayMessage",
    {
        "name": "preventMessages.animal",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        }
    },
    function(event, documentObject, message) {
        event.preventDefault();
    }
);

5.7.2.2 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 document en cours.

5.7.2.2.1 Arguments

Pas d'argument

5.7.2.2.2 Retour

Tableau d'écouteurs

5.7.2.2.3 Exception

Pas d'exception

5.7.2.2.4 Exemples

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

retourne

[{
    "documentCheck" : function(document) {...},
    "eventCallback": function(event, document, data) {...},
    "eventType" : "change",
    "name" : "alertChange.animal"
},{
    "documentCheck" : function(document) {...},
    "eventCallback": function(event, document, data) {...},
    "eventType" : "displayMessage",
    "name" : "preventMessages.animal"
}]

5.7.2.3 removeEventListener

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

5.7.2.3.1 Arguments

nom (string)
nom de l'événement ou namespace des événements à supprimer.

5.7.2.3.2 Retour

Le ou les écouteur(s) supprimé(s).

5.7.2.3.3 Exception

Pas d'exception.

5.7.2.3.4 Exemple

Suppression des événements ayant le namespace animal.

window.dcp.document.documentController("removeEventListener", ".animal");

Retourne

[{
    documentCheck: function (document) { return document.family.name === "ANIMAL"},
    attributeCheck: function (attribute, documentObject) { return attribute.id = "animal_date"},
    constraintCheck: function (document, attribute, response) {...
}]

5.7.3 Liste des événements déclenchés sur le document

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

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

5.7.3.1 actionClick

5.7.3.1.1 Déclenchement

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

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

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.

5.7.3.1.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document 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

5.7.3.1.3 Annulable

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

5.7.3.1.4 Liste des événements standards

Les actions prédéfinies sur le widget document sont :

Identifiant options Description Exemple
document.close [viewId] Demande d'affichage en mode consultation du document courant en utilisant la vue viewId (si viewId n'est pas renseigné, la vue !defaultConsultation est utilisée) #action/document.close
document.create Demande de sauvegarde du document courant et de retour en mode modification #action/document.create
document.createAndClose [viewId] Demande de sauvegarde du document 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 Demande de suppression du document courant #action/document.delete
document.edit Demande d'affichage en mode modification du document courant #action/document.edit
document.help helpId[:rubriqueId] Demande daffichage 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 document ayant la référence initid (si initid n'est pas renseigné, c'est l'historique de document courant qui est affiché) #action/document.history
document.load initid[:viewId[:revision]] Demande d'affichage du document ayant la référence initid à la place du document courant #action/document.load:1234:!defaultConsultation:0
document.lock Demande de verrouillage du document courant #action/document.lock
document.properties [initid] Demande d'affichage des propriétés du document ayant la référence initid (si initid n'est pas renseigné, ce sont les propriétés du document courant qui sont affichées) #action/document.properties
document.restore Demande de restauration du document courant #action/document.restore
document.save Demande de sauvegarde du document courant #action/document.save
document.saveAndClose [viewId] Demande de sauvegarde du document 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 document courant #action/document.unlock

5.7.3.1.5 Exemple

Cet exemple affiche un confirm demandant de valider pour sauvegarder.

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

5.7.3.2 beforeClose

5.7.3.2.1 Déclenchement

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

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 document ont été réalisés.

5.7.3.2.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
nextDocumentObject
un objet document décrivant le document suivant.
customData
l'objet customClientData, cet objet peut-être modifié si besoin.

5.7.3.2.3 Annulable

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

5.7.3.2.4 Exemple

Cet exemple

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController("addEventListener",
        "beforeClose",
        {
            "name": "preventClose.animal",
            "documentCheck": function(document) {
                return document.family.name === "ANIMAL";
            }
        },
        function preventCloseAnimal(event, currentDocumentObject) {
            if (currentDocumentObject.renderMode === "edit" &&
                this.documentController("getValue", "zoo_title").value !== "fermer") {
                event.preventDefault();
                this.documentController("showMessage", {
                    "type" : "error",
                    "message" : "If you want close the doc, change the title to fermer"
                });
            }
        });
    }
);

5.7.3.3 close

5.7.3.3.1 Déclenchement

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

cet événement est idéal pour supprimer les écouteurs qui ne sont plus nécessaires.

5.7.3.3.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
previousDocumentObject
un objet document décrivant le document précédent.

5.7.3.3.3 Annulable

Non

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

window.dcp.document.documentController("addEventListener",
    "close",
    {
        "name": "removeAnimalsEvent",
        "documentCheck": function(document) {
            return document.family.name === "ANIMAL";
        }
    },
    function(event, document) {
        this.documentController("removeEventListener", ".animal");
    }
);

Exemple complet : ajout d'événements au ready des documents de type ANIMAL et suppression de ceux-ci au close des documents de type ANIMAL.

//Ajout de l'événement au ready
window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(document) {
            return document.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController("addEventListener",
        "beforeClose",
        {
            "name": "preventClose.animal",
            "documentCheck": function(documentObject) {
                return true;
            }
        },
        function preventCloseAnimal(event, documentObject) {
            if (documentObject.renderMode === "edit" &&
                this.documentController("getValue", "zoo_title").value !== "fermer") {
                event.preventDefault();
                this.documentController("showMessage", {
                    "type" : "error",
                    "message" : "If you want close the doc, change the title to fermer"
                });
            }
        });
    }
);
 
//Suppression de l'événement au close
window.dcp.document.documentController("addEventListener",
    "close",
    {
        "name": "removeAnimalsEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    },
    function(event, documentObject) {
        // Désenregistrement de addAnimalEvents
        this.documentController("removeEventListener", ".animal");
    }
);

5.7.3.4 downloadFile

Cet événement est renommé attributeDownloadFile

5.7.3.4.1 Déclenchement

Voir attributeDownloadFile

5.7.3.4.2 Éléments passés au callback

Voir attributeDownloadFile

5.7.3.4.3 Annulable

Voir attributeDownloadFile

5.7.3.4.4 Exemple

Voir attributeDownloadFile

5.7.3.5 beforeDelete

5.7.3.5.1 Déclenchement

Le document va être supprimé.

5.7.3.5.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
nextDocumentObject
un objet document décrivant le document suivant.
customData
l'objet customClientData, cet objet peut-être modifié si besoin.

5.7.3.5.3 Annulable

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

5.7.3.5.4 Exemple

Cet exemple :

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(document) {
            return document.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController("addEventListener",
        "beforeDelete",
        {
            "name": "preventDelete.animal",
            "documentCheck": function(document) {
                return document.family.name === "ANIMAL";
            }
        },
        function preventDeleteAnimal(event, document) {
            if (this.documentController("getValue", "zoo_title").value !== "fermer") {
                event.preventDefault();
                this.documentController("showMessage", {
                    "type" : "error",
                    "message" : "If you want to delete the doc, change the title to fermer"
                });
            }
        });
    }
);

5.7.3.6 afterDelete

5.7.3.6.1 Déclenchement

Le document a été supprimé.

5.7.3.6.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
previousDocumentObject
un objet document décrivant le document précédent.

5.7.3.6.3 Annulable

Non

5.7.3.6.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "afterDelete",
    {
        "name": "display42"
    },
    function open42(event, document) {
        this.documentController("fetchDocument", {
            "initid" : 42,
            "viewId" : "!defaultConsultation"
        });
    }
);

5.7.3.7 displayError

5.7.3.7.1 Déclenchement

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

5.7.3.7.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document 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. Les plus courants sont :

  • offline : requête impossible pour cause de réseau,
  • CRUD0211 : un attribut n'est pas au bon format et n'a pas pu être sauvé,
  • CRUD0212 : une contrainte n'est pas respectée.

Les autres identifiants d'erreurs peuvent être trouvés dans la documentation de l'API HTTP.

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.

5.7.3.7.3 Annulable

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

5.7.3.7.4 Exemple

Cet exemple modifie le message avant son affichage.

window.dcp.document.documentController("addEventListener",
    "displayError",
    {
        "name": "changeErrorMessage"
    },
    function changeErrorMessage(event, documentObject, message) {
        if (message.errorCode === "offline") {
            message.message = "Pas de serveur";
        }
    }
);

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

window.dcp.document.documentController("addEventListener",
    "displayError",
    {
        "name": "changeDisplayError"
    },
    function changeDisplayError(event, documentObject, message) {
        event.preventDefault();
        alert(message.message);
    }
);

5.7.3.8 displayMessage

5.7.3.8.1 Déclenchement

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

5.7.3.8.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document 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. Les plus courants sont :

  • offline : requête impossible pour cause de réseau,
  • CRUD0211 : un attribut n'est pas au bon format et n'a pas pu être sauvé,
  • CRUD0212 : une contrainte n'est pas respectée.

Les autres identifiants d'erreurs peuvent être trouvés dans la documentation de l'API HTTP.

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.

5.7.3.8.3 Annulable

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

5.7.3.8.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "displayMessage",
    {
        "name": "changeDisplayError"
    },
    function changeDisplayError(event, documentObject, message) {
        event.preventDefault();
        alert(message.message);
    }
);

5.7.3.9 ready

5.7.3.9.1 Déclenchement

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

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

Note : Lorsqu'un document 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 d'attributs présents dans les onglets ne sont pas encore affichés que ce soit sur le premier onglet ou les suivants. L'événement attributeReady d'un attribut onglet est propagé lorsque son contenu est affiché. Les événements attributeReady des onglets sont donc propagés après l'événement ready du document.

5.7.3.9.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.

5.7.3.9.3 Annulable

Non

5.7.3.9.4 Exemple

Ajouter un message à chaque chargement de document.

window.dcp.document.documentController("addEventListener",
    "ready",
    function(event, documentObject, message) {
        this.documentController("showMessage", "I'm ready");
    }
);

Enregistrer un suivi de la modification de l'âge pour les documents de type animal.

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    },
    function(event, documentObject) {
        this.documentController("addEventListener",
            "change",
            {
                "name" : "changeAge.animal",
                "documentCheck": function(documentObject) {
                    return documentObject.family.name === "ANIMAL";
                },
                "attributeCheck" : function(attributeObject) {
                    return attributeObject.id === "animal_date"
                }
            },
            function() {
                this.documentController("showMessage", "You have changed the age");
            }
        );
   }
);

Présenté de cette manière, cet événement sera ajouté à chaque chargement du document. Il faudra donc enlever l'événement changeAge.animal à la fermeture du document (voir l'événement close).

5.7.3.10 beforeRestore

5.7.3.10.1 Déclenchement

Le document va être restauré.

5.7.3.10.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.

5.7.3.10.3 Annulable

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

5.7.3.10.4 Exemple

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

window.dcp.document.documentController(
    "addEventListener",
    "beforeRestore",
    {
        "name": "preventRestore.animal",
        "documentCheck": function(document) {
            return document.family.name === "ANIMAL";
        }
    },
    function preventRestoreAnimal(event, currentDocumentObject) {
        if (!confirm("Voulez-vous restaurer ce document ?")) {
            event.preventDefault();
            this.documentController("showMessage", {
                "type" : "info",
                "message" : "la restauration a été annulée"
            });
        }
    }
);

5.7.3.11 afterRestore

5.7.3.11.1 Déclenchement

Le document a été restauré.

5.7.3.11.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
previousDocumentObject
un objet document décrivant le document avant sa restauration.

5.7.3.11.3 Annulable

Non

5.7.3.11.4 Exemple

Cet exemple

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController(
        "addEventListener",
        "afterRestore",
        {
            "name": "confirmRestore.animal",
            "documentCheck": function(document) {
                return document.family.name === "ANIMAL";
            }
        },
        function confirmRestoreAnimal(event, currentDocumentObject) {
            this.documentController("showMessage", {
                "type" : "info",
                "message" : "Le document a été restauré avec succès"
            });
        });
    }
);

5.7.3.12 beforeSave

5.7.3.12.1 Déclenchement

Le document va être sauvegardé. Cet événement est déclenché après la phase de validation.

5.7.3.12.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
requestOptions
Cette option contient 2 fonctions getRequestData et setRequestData
customData
L'objet customData contient l'objet customClientData, 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 :

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.

5.7.3.12.3 Annulable

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

5.7.3.12.4 Exemple

5.7.3.12.4.1 Interrompre la sauvegarde

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController("addEventListener",
        "beforeSave",
        {
            "name": "preventSave.animal",
            "documentCheck": function(document) {
                return document.family.name === "ANIMAL";
            }
        },
        function preventSaveAnimal(event, currentDocumentObject) {
            if (this.documentController("getValue", "zoo_title").value !== "fermer") {
                event.preventDefault();
                this.documentController("showMessage", {
                    "type" : "error",
                    "message" : "If you want to save the doc, change the title to fermer"
                });
            }
        });
    }
);

5.7.3.12.4.2 Enregistrer seulement les données modifiées

Cet exemple montre comment utiliser les fonctions getRequestData et setRequestData pour ne renvoyer que les données modifiées lors de la sauvegarde.

window.dcp.document.documentController("addEventListener", "beforeSave", {
    "name": "SaveOnlyModified.test", 
}, function saveOnlyModified(event, currentDocumentObject, requestOptions, customData)
{
    var systemData= requestOptions.getRequestData();
 
    this.documentController("getAttributes").forEach(function (attr) {
       if (!attr.isModified()) {
           delete systemData.document.attributes[attr.id];
       }
    });
    requestOptions.setRequestData( systemData );
});

5.7.3.13 afterSave

5.7.3.13.1 Déclenchement

Le document a été sauvegardé.

5.7.3.13.2 Éléments passés au callback

event
objet événement standard de jQuery,
currentDocumentObject
un objet document décrivant le document courant.
previousDocumentObject
un objet document décrivant le document précédent.

5.7.3.13.3 Annulable

Non

5.7.3.13.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "afterSave",
    {
        "name": "passToView"
    },
    function reloadInConsultation(event, currentDocumentObject) {
        this.documentController("fetchDocument", {
            "viewId" : "!defaultConsultation"
        });
    }
);

5.7.3.14 validate

5.7.3.14.1 Déclenchement

Le document va être sauvegardé. Cet événement est déclenché avant la sauvegarde.

5.7.3.14.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.

5.7.3.14.3 Annulable

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

5.7.3.14.4 Exemple

Cet exemple

window.dcp.document.documentController("addEventListener",
    "ready",
    {
        "name": "addAnimalEvent",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL";
        }
    }, function addAnimalEvents() {
        this.documentController("addEventListener",
        "validate",
        {
            "name": "preventValidate.animal",
            "documentCheck": function(documentObject) {
                return documentObject.family.name === "ANIMAL";
            }
        },
        function preventValidateAnimal(event, documentObject) {
            if (this.documentController("getValue", "zoo_title").value !== "fermer") {
                event.preventDefault();
                this.documentController("showMessage", {
                    "type" : "error",
                    "message" : "If you want close the doc, change the title to fermer"
                });
            }
        });
    }
);

5.7.4 Liste des événements déclenchés sur les attributs

Les événements ci-dessous concernent un attribut spécifique du document.

Bien que concernant un attribut précis, les écouteurs de ces événements doivent être ajoutés au widget document au moyen de la méthode addEventListener.

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

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

5.7.4.1 attributeAnchorClick

5.7.4.1.1 Déclenchement

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

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

5.7.4.1.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le noeud DOM sur lequel l'attribut est rendu.
index
Le numéro de ligne si l'attribut 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 l'attribut 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).

5.7.4.1.3 Annulable

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

5.7.4.1.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeAnchorClick",
    {
        "name": "attributeAnchorClick",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ZOO_ESPECE";
        },
        "attributeCheck" : function(attribute, documentObject) {
            if (attributeObject.id === "es_decription") {
                return true;
            } else {
                return false;
            }
        }
    },
    function attributeAnchorClick(event, documentObject, attributeObject, $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 :

window.dcp.document.documentController("addEventListener",
    "attributeAnchorClick",
    {
        "name": "attributeAnchorClick",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ZOO_ESPECE";
        },
        "attributeCheck" : function(attribute, documentObject) {
            if (attributeObject.id === "es_decription") {
                return true;
            } else {
                return false;
            }
        }
    },
    function attributeAnchorClick(event, documentObject, attributeObject, $el, options, index) {
        if(options.anchor.scheme !== 'https:') {
            event.preventDefault();
            alert('seuls les liens https peuvent être ouverts !');
        }
    }
);

5.7.4.2 attributeArrayChange

5.7.4.2.1 Déclenchement

L'attribut de type array a été modifié (ajout, suppression, drag & drop de lignes).

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

5.7.4.2.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut 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.

5.7.4.2.3 Annulable

Non

5.7.4.2.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeArrayChange",
    {
        "name": "displayarrayModified"
    },
    function displayArrayModified(event, documentObject, attribut) {
        this.documentController("showMessage", "Array "+attribut.id+" has changed");
    }
);

5.7.4.3 attributeBeforeRender

5.7.4.3.1 Déclenchement

L'attribut va être rendu.

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

5.7.4.3.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le noeud DOM sur lequel l'attribut est rendu,
index
Le numéro de ligne si l'attribut est dans un tableau, -1 sinon.

5.7.4.3.3 Annulable

Oui. dans ce cas, l'attribut n'est pas rendu.

5.7.4.3.4 Exemple

Cet exemple annule le rendu d'un attribut précis.

window.dcp.document.documentController("addEventListener",
    "attributeBeforeRender",
    {
        "name": "attributeBeforeRender",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck" : function isTitle(attribute, documentObject) {
            if (attributeObject.id === "zoo_title") {
                return true;
            }
        }
    },
    function attributeBeforeRender(event, documentObject, attributeObject, $el) {
        event.preventDefault();
    }
);

5.7.4.4 attributeDownloadFile

5.7.4.4.1 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).

5.7.4.4.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le noeud DOM sur lequel l'attribut est rendu.
index
Le numéro de ligne si l'attribut est dans un tableau, -1 sinon.

5.7.4.4.3 Annulable

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

5.7.4.4.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeDownloadFile",
    {
        "name": "passToView"
    },
    function controlDownload(event, documentObject, attributeObject, options) {
            var index = options.index;
            var value = attributeObject.getValue();
            if (_.isArray(value)) {
                value = value[index];
            }
 
            if (value.mime.indexOf("image") === -1) {
                event.preventDefault();
            }
    }
);

5.7.4.5 attributeHelperResponse

5.7.4.5.1 Déclenchement

L'aide à la saisie associée à l'attribut a été déclenchée et le résultat de cette aide à la saisie est arrivé 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.

5.7.4.5.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut 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 document en cas de sélection de cette ligne.

      La clef représente l'identifiant logique de l'attribut auquel al valeur sera affectée, et le contenu est similaire à un setValue, soit un objet avec les propriétés

      • value : valeur à stocker,
      • displayValue : valeur à présenter à l'utilisateur.

5.7.4.5.3 Annulable

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

5.7.4.5.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeHelperResponse",
    {
        "name": "invertResult"
    },
    function displayArrayModified(event, documentObject, attributeObject, options) {
       options.data.reverse();
    }
);

5.7.4.6 attributeHelperSearch

5.7.4.6.1 Déclenchement

L'aide à la saisie associée à l'attribut 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.

5.7.4.6.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
options (objet)

Object contenant les propriétés suivantes :

data

Object contenant les propriétés suivantes :

attributes
valeur des attributs en cours, Objet indiquant pour chaque attribut sa valeur (value, displayValue) Les identifiants des attributs 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 document en cas de sélection de cette ligne.

      La clef représente l'identifiant logique de l'attribut 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.

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

5.7.4.6.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeHelperSearch",
    {
        "name": "displayErrorMessage",
        "documentCheck": function (documentObject)
        {
            return documentObject.family.name === "DEMANDEADOPTION"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "de_proprietaire";
        }
    },
    function displayArrayModified(event, documentObject, attributObject, 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"
                    }
                }
 
            }
            ]
        );
    }
);

5.7.4.7 attributeHelperSelect

5.7.4.7.1 Déclenchement

L'aide à la saisie associée à l'attribut 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.

5.7.4.7.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
options (objet)

Un objet contenant la ligne sélectionnée. Il contient 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 document en cas de sélection de cette ligne.

    La clef représente l'identifiant logique de l'attribut auquel al valeur sera affectée, et le contenu est similaire à un setValue, soit un objet avec les propriétés

    • value : valeur à stocker,
    • displayValue : valeur à présenter à l'utilisateur.

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

5.7.4.7.3 Annulable

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

5.7.4.7.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeHelperSelect",
    {
        "name": "attributeHelperSelect"
    },
    function displayArrayModified(event, documentObject, attributeObject, options) {
       event.preventDefault();
    }
);

5.7.4.8 attributeReady

5.7.4.8.1 Déclenchement

L'attribut vient d'être rendu et est disponible pour les utilisateurs.

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

5.7.4.8.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le noeud DOM sur lequel l'attribut est rendu,
index
Le numéro de ligne si l'attribut est dans un tableau, -1 sinon.

5.7.4.8.3 Annulable

Non

5.7.4.8.4 Exemple

Cet exemple passe en rouge le background d'un attribut précis.

window.dcp.document.documentController("addEventListener",
    "attributeReady",
    {
        "name": "doubleCheck",
        "documentCheck": function(documentObject) {
            return documentObject.family.name === "ANIMAL"
        },
        "attributeCheck" : function isTitle(attribute, documentObject) {
            if (attribute.id === "zoo_title") {
                return true;
            }
        }
    },
    function changeDisplayError(event, documentObject, attributeObject, $el) {
        $el.css("background-color", "red");
    }
);

Cet exemple ajoute un tooltip qui affiche au survol le nom logique de l'attribut sur tous les attributs.

window.dcp.document.documentController("addEventListener",
    "attributeReady",
    {
        "name": "displayId"
    },
    function changeDisplayError(event, documentObject, attributeObjecte, $el) {
        $el.tooltip({
            placement : "top",
            title : function vDocumentTooltipTitle() {
                return attribute.id
            }
        });
    }
);

5.7.4.9 change

5.7.4.9.1 Déclenchement

L'attribut a été modifié (soit via l'interface, soit via du code).

5.7.4.9.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
values

Un objet contenant les valeurs de l'attribut 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 document).
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.

5.7.4.9.3 Annulable

Non

5.7.4.9.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "change",
    {
        "name": "displayChange"
    },
    function displayChange(event, documentObject, attributeObject, values) {
        this.documentController("showMessage", "Attribut "+attributeObject.id+" has changed");
    }
);

La valeur (Structure des valeurs) d'un type fichier contient les propriétés suivantes :

5.7.4.10 attributeUploadFile

5.7.4.10.1 Déclenchement

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

5.7.4.10.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le nœud DOM sur lequel l'attribut est rendu.
index
Le numéro de ligne si l'attribut 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.

5.7.4.10.3 Annulable

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

5.7.4.10.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeUploadFile",
    {
        "name": "restrictToImages"
    },
    function controlUpload(event, documentObject, attributeObject, $el, index, options) {
            if(options.file.type.substr(0, 5) !== 'image') {
                event.preventDefault();
                alert('seules les images sont autorisées !');
            }
    }
);

5.7.4.11 attributeUploadFileDone

5.7.4.11.1 Déclenchement

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

5.7.4.11.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut courant.
$el
objet jQuery contenant le nœud DOM sur lequel l'attribut est rendu.
index
Le numéro de ligne si l'attribut est dans un tableau, -1 sinon.
options

un objet contenant les propriétés suivantes :

file
la valeur de l'attribut fichier.

Exemple :

{
    creationDate:"2017-07-04 16:37:23"
    displayValue:"NfGTsK4.jpg"
    fileName:"NfGTsK4.jpg"
    icon:"api/v1/images/assets/sizes/20/mime-image.png"
    size:"50187"
    thumbnail:"api/v1/images/recorded/sizes/48/2673880702159532007.png"
    url:"api/v1/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.

5.7.4.11.3 Annulable

Non.

5.7.4.11.4 Exemple

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

window.dcp.document.documentController("addEventListener",
  "attributeUploadFileDone",
  {
    "name": "my.uploaddone",
    "documentCheck": function (document) {
      return document.family.name === "MY_FAMILY"
    }
  },
  function (event, document, data) {
    if (!document.hasUploadingFiles)
      $(this).documentController("showMessage", {
        message: "All uploads are done",
        type: "success"
      });
  }
);

5.7.4.12 attributeBeforeTabSelect

5.7.4.12.1 Déclenchement

L'affichage d'un onglet est demandé.

5.7.4.12.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut (onglet en cours de sélection) courant.
$el
objet jQuery contenant le nœud DOM sur lequel le label de l'attribut est rendu.

5.7.4.12.3 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é

5.7.4.12.4 Exemple

Cet exemple n'autorise pas la sélection de l'onglet my_t_tab_date.

window.dcp.document.documentController("addEventListener", 
"attributeBeforeTabSelect", {
     "name": "NoSelectTabDate", 
     "documentCheck": function (document)
     {
         return document.family.name === "MY_FAMILY";
     },
     "attributeCheck": function (attribute)
     {
         return (attribute.id === "my_t_tab_date");
     }
 }, function selectIfNotDate(event, currentDocumentObject, Attribute, $el)
 {
     // Onglet affiché en rouge
     $el.css("background-color", "red");
 
     // Message d'information 
     this.documentController("showMessage", {
         type: "warning",
         htmlMessage: "Tab <b>"+Attribute.getLabel()+ "</b> cannot be selected"
     });
 
     // Ordre d'annulation de la sélection
     event.preventDefault();
 });

5.7.4.13 attributeAfterTabSelect

5.7.4.13.1 Déclenchement

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

5.7.4.13.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut (onglet sélectionné) courant.
$el
objet jQuery contenant le nœud DOM sur lequel le label de l'attribut est rendu.

5.7.4.13.3 Annulable

Non

5.7.4.13.4 Exemple

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

window.dcp.document.documentController("addEventListener", 
"attributeAfterTabSelect", {
     "name": "SelectTabDate", 
     "documentCheck": function (document)
     {
         return document.family.name === "MY_FAMILY";
     },
     "attributeCheck": function (attribute)
     {
         return true;
     }
 }, function selectIfNotData(event, currentDocumentObject, Attribute, $el)
 {
     // Onglet affiché en jaune
     $el.css("background-color", "yellow");
 
     // Message d'information 
     this.documentController("showMessage", {
         type: "info",
         htmlMessage: "Tab <b>"+Attribute.getLabel()+ "</b> is now selected"
     });
 
 });

5.7.4.14 attributeTabChange

5.7.4.14.1 Déclenchement

Lorsqu'une erreur sur un attribut a été déclenchée. Lorsque le libellé du label a été modifié.

Cette événement peut être déclenché plusieurs fois si plusieurs attributs contenu dans cet onglet sont en erreur.

5.7.4.14.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
attributeObject
un objet attribut décrivant l'attribut (onglet sélectionné) courant.
$el
objet jQuery contenant le nœud DOM sur lequel le label de l'attribut est rendu.
info:
Donnée supplémentaire : Contient un champ error si une contrainte a été déclenchée sur un des ses attributs.

5.7.4.14.3 Annulable

Non

5.7.4.14.4 Exemple

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

window.dcp.document.documentController("addEventListener", "attributeTabChange", {
        "name": "ChangeTab.test", "documentCheck": function (document)
        {
            return document.family.name === "MY_FAMILY";
        },
        "attributeCheck": function (attribute)
        {
            return true;
        }
    }, function showTabError(event, currentDocumentObject, Attribute, $el, info)
    {
        if (info.error) {
            this.documentController("showMessage", {
                type: "error",
                htmlMessage: "Tab <b>" + Attribute.getLabel() + "</b> has an error",
                message: info.error
            });
        }
    });

5.7.5 Liste des événements déclenchés par l'option "addCreateDocumentButton"

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

  1. attributeCreateDialogDocumentReady : lorsque le formulaire est affiché
  2. attributeCreateDialogDocumentBeforeSetFormValues : avant l'affectation des valeurs dans le formulaire
  3. attributeCreateDialogDocumentBeforeSetTargetValue : avant l'affectation de l'attribut dans le document principal
  4. attributeCreateDialogBeforeClose : avant la fermeture de la fenêtre de dialogue
  5. attributeCreateDialogBeforeDestroy : avant la destruction de la fenêtre de dialogue

5.7.5.1 attributeCreateDialogDocumentReady

5.7.5.1.1 Déclenchement

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

5.7.5.1.2 Éléments passés au callback

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

5.7.5.1.3 Annulable

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

5.7.5.1.4 Exemple

5.7.5.2 attributeCreateDialogDocumentBeforeSetFormValues

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

5.7.5.2.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document principal.
attributeObject
un objet attribut décrivant l'attribut courant.
options
Un objet contenant les valeurs de l'attribut 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 d'attribut multiple. Est égale à "-1" si Cela ne concerne pas un attribut multiple dialogWindow : Widget de la fenêtre de dialogue (de type dcpWindow) dialogDocument : Widget du document contenu dans la fenêtre de dialogue

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

5.7.5.2.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeCreateDialogDocumentBeforeSetFormValues",
    {
        "name": "createChild.animal",
        "documentCheck": function(document) {
            return document.family.name === "ZOO_ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "an_enfant";
        }
    }, function (event, document, attribut, options) {
        var 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
        options.dialogDocument.documentController("showMessage", "Création d'un nouvel animal");
    }
);

5.7.5.3 attributeCreateDialogDocumentBeforeSetTargetValue

5.7.5.3.1 Déclenchement

Déclenché lorsque la valeur de l'attribut a été affecté en cliquant sur le bouton d'enregistrement du document de la fenêtre de dialogue.

5.7.5.3.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document principal.
attributeObject
un objet attribut décrivant l'attribut courant.
options

Un objet contenant les valeurs de l'attribut en cours. Il contient les propriétés suivantes :

index
Index de la relation en cas d'attribut multiple. Est égale à "-1" si Cela ne concerne pas un attribut multiple
dialogWindow
Widget de la fenêtre de dialogue (de type dcpWindow)
dialogDocument
Widget du document contenu dans la fenêtre de dialogue
attributeValue

Valeur de la relation à insérer dans l'attribut Cette valeur est un objet contenant les champs suivants :

  • displayValue : Titre du document
  • familyRelation : Nom logique de la famille
  • icon : Url de l'icone du document
  • value : Identifiant numérique du document

5.7.5.3.3 Annulable

Oui. Le formulaire est enregistré, mais la mise de l'attribut n'est pas effectuée. La fenêtre de dialogue n'est pas fermée.

5.7.5.3.4 Exemple

Afficher un message indiquant la sauvegarde.

window.dcp.document.documentController("addEventListener",
    "attributeCreateDialogDocumentBeforeSetTargetValue",
    {
        "name": "setChild.animal",
        "documentCheck": function(document) {
            return document.family.name === "ZOO_ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "an_espece";
        }
    }, function (event, document, attribut, options) {
    options.dialogDocument.documentController("showMessage",
        "Valeur [" + options.attributeValue.displayValue+ "] en cours d'affectation");
    }
);

5.7.5.4 attributeCreateDialogBeforeClose

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

5.7.5.4.2 Éléments passés au callback

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

Valeur de la relation à insérer dans l'attribut. Cette valeur est vide (non définie) lorsque l'affectation n'a pas eu lieu. Cette valeur est un objet contenant les champs suivants en cas d'enregistrement :

  • displayValue : Titre du document
  • familyRelation : Nom logique de la famille
  • icon : Url de l'icone du document
  • value : Identifiant numérique du document

5.7.5.4.3 Annulable

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

5.7.5.4.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeCreateDialogDocumentBeforeClose",
    {
        "name": "closeEspece.animal",
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "an_espece";
        }
    }, function (event, document, attribut, options) {
        if (options.attributeValue) { // En cas d'enregistrement
            event.preventDefault();
            options.dialogDocument.documentController("showMessage", "Valeur enregistrée");
        }
    }
);

5.7.5.5 attributeCreateDialogBeforeDestroy

5.7.5.5.1 Déclenchement

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

5.7.5.5.2 Éléments passés au callback

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

5.7.5.5.3 Annulable

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

5.7.5.5.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "attributeCreateDialogDocumentBeforeDestroy",
    {
        "name": "acloseEspece.animal",
        "documentCheck": function(document) {
            return document.family.name === "ZOO_ANIMAL"
        },
        "attributeCheck": function(attribute, documentObject) {
            return attribute.id === "an_espece";
        }
    }, function displayArrayModified(event, document, attribut, options) {
        this.documentController("showMessage",
            "Fenêtre ["+
            options.dialogDocument.documentController("getProperty","title")+
            "] a été fermée");
    }
);

5.7.6 Liste des événements de changement d'état

Les événements ci-dessous concernent le changement d'état du document. 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.

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

5.7.6.1 beforeDisplayTransition

5.7.6.1.1 Déclenchement

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

5.7.6.1.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
objet transition décrivant la fenêtre de transition.

5.7.6.1.3 Annulable

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

5.7.6.1.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "beforeDisplayTransition",
    {
        "name": "preventTransition.changeState"
    },
    function preventTransition(event, documentObject, changeStateObject) {
        if (!changeStateObject.transition) {
            event.preventDefault();
            this.documentController("showMessage", {
                type : "error",
                "message" : "You cannot do change state without transition"
            });
        }
    }
);

5.7.6.2 afterDisplayTransition

5.7.6.2.1 Déclenchement

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

5.7.6.2.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
objet transition décrivant la fenêtre de transition.

5.7.6.2.3 Annulable

Non.

5.7.6.2.4 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 ce lancer si l'utilisateur ne confirme pas.

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

5.7.6.3 beforeTransitionClose

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

5.7.6.3.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
objet transition décrivant la fenêtre de transition.

5.7.6.3.3 Annulable

Oui. La fenêtre reste ouverte.

5.7.6.3.4 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é.

window.dcp.document.documentController("addEventListener",
    "beforeTransitionClose",
    {
        "name": "beforeTransitionClose.changeState"
    },
    function beforeTransitionClose(event, documentObject, changeStateObject) {
        if (!confirm("Are you sure ?")) {
            event.preventDefault();
        }
    }
);

5.7.6.4 beforeTransition

5.7.6.4.1 Déclenchement

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

5.7.6.4.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
objet transition décrivant la fenêtre de transition.

5.7.6.4.3 Annulable

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

5.7.6.4.4 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é.

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

5.7.6.5 failTransition

5.7.6.5.1 Déclenchement

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

5.7.6.5.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
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. Les plus courants sont :

  • offline : requête impossible pour cause de réseau,
  • CRUD0211 : un attribut n'est pas au bon format et n'a pas pu être sauvé,
  • CRUD0212 : une contrainte n'est pas respectée.

Les autres identifiants d'erreurs peuvent être trouvés dans la documentation de l'API HTTP.

message
contenu textuel du message,
htmlMessage (optionnel)
contenu html du message.

5.7.6.5.3 Annulable

Non.

5.7.6.5.4 Exemple

Cet exemple ferme la fenêtre de changement d'état et ouvre le document 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).

window.dcp.document.documentController("addEventListener",
    "failTransition",
    {
        "name": "failTransition"
    },
    function failTransition(event, documentObject, changeStateObject, error) {
       if (error.type !== "offline") {
            changeStateObject.close();
            this.documentController("showMessage", {
                "type" : "error",
                "title" : error.title || "erreur",
                "message" : error.htmlMessage || error.message
            });
            this).documentController("fetchDocument", {
                "initid": documentObject.initid,
                "viewId" : "!defaultEdition"
            });
       }
    }
);

5.7.6.6 successTransition

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

5.7.6.6.2 Éléments passés au callback

event
objet événement standard de jQuery,
documentObject
un objet document décrivant le document courant.
changeStateObject
objet transition décrivant la fenêtre de transition.

5.7.6.6.3 Annulable

Non.

5.7.6.6.4 Exemple

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

window.dcp.document.documentController("addEventListener",
    "successTransition",
    {
        "name": "successTransition"
    },
    function successTransition(event, documentObject, changeStateObject) {
        this.documentController("showMessage", {
            "type" : "info",
            "message" : "Well done !"
        });
    }
);

5.7.7 Déclencher des événements

Il est possible de déclencher manuellement des événements.

5.7.7.1 triggerEvent

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

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 la,nce pas la sauvegarde du document.

5.7.7.1.1 Arguments

nom (string)
nom de l'événement à déclencher.

Il est possible de déclencher les événements standards.
D'autres événements peuvent être déclenchés à condition que leur nom soit préfixé par custom:.

autres arguments (un ensemble d'arguments)
ensemble d'arguments, ces arguments sont transférés aux méthodes écoutant les événements.

5.7.7.1.2 Retour

Booléen :

5.7.7.1.3 Exception

Le nom de l'événement n'est pas valide.

Les noms valides sont tous les noms d'événements standards et les noms préfixés par custom:.

5.7.7.1.4 Exemple

Déclenchement et écoute de l'événement custom:MyEvent.

 
window.dcp.document.documentController("addEventListener",
    "custom:MyEvent",
    function(event, documentProperties, date) {
        console.log("MyEvent", event, documentProperties, date);
    }
);
 
window.dcp.document.documentController( "triggerEvent", 
                                        "custom:MyEvent", 
                                        window.dcp.document.documentController("getProperties"), 
                                        Date());
 

Chapitre 6 Extension de l'api HTTP

Ce module étend l'API HTTP de dynacase avec les routes suivantes :

6.1 Carte de l'api donnée

Type URL Implémenté Signification
GET /api/v1/documents/<docid>/views/ Oui Liste des rendus de documents
PUT /api/v1/documents/<docid>/views/ N/A N/A
POST /api/v1/documents/<docid>/views/ N/A N/A
DELETE /api/v1/documents/<docid>/views/ N/A N/A
GET /api/v1/documents/<docid>/views/<viewId> Oui Récupération du rendu d'un document
PUT /api/v1/documents/<docid>/views/<viewId> Oui Mise à jour d'un document avec le rendu indiqué
POST /api/v1/documents/<docid>/views/<viewId> N/A N/A
DELETE /api/v1/documents/<docid>/views/<viewId> N/A N/A
GET /api/v1/families/<famid>/views/structure Oui Récupération de la structure d'une famlille (caractéristiques des attributs)
PUT /api/v1/families/<famid>/views/structure Non N/A
POST /api/v1/families/<famid>/views/structure N/A N/A
DELETE /api/v1/families/<famid>/views/structure N/A N/A
GET /api/v1/documents/<docid>/revision/<revision>/views/<viewId> Oui Récupération du rendu d'une révision de document
PUT /api/v1/documents/<docid>/revision/<revision>/views/<viewId> N/A N/A
POST /api/v1/documents/<docid>/revision/<revision>/views/<viewId> N/A N/A
DELETE /api/v1/documents/<docid>/revision/<revision>/views/<viewId> N/A N/A
GET /api/v1/families/<famid>/documentsViews/ N/A N/A
PUT /api/v1/families/<famid>/documentsViews/ N/A N/A
POST /api/v1/families/<famid>/documentsViews/ Oui Création d'un document de la famille en utilisant le rendu de création
DELETE /api/v1/families/<famid>/documentsViews/ N/A N/A
GET /api/v1/documents/<docid>/views/states/<states> Oui [Caractéristiques d'affichage de la transition vers l'état "state"]
PUT /api/v1/documents/<docid>/views/states/<states> N/A N/A
POST /api/v1/documents/<docid>/views/states/<states> Oui Passage de la transition vers l'état "state"
DELETE /api/v1/documents/<docid>/views/states/<states> N/A N/A
GET /api/i18n/<catalogName> Oui Récupération du catalogue catalogName
PUT /api/i18n/<catalogName> N/A N/A
POST /api/i18n/<catalogName> N/A N/A
DELETE /api/i18n/<catalogName> N/A N/A

Légende :

6.2 Carte de l'api HTML

Type URL Implémenté Signification
GET /api/v1/documents/<docid>.html Oui Affichage du document n°docid
GET /api/v1/documents/<docid>/revision/<revision>.html Oui Affichage de la révision n°revision du document n°docid
GET /api/v1/documents/<docid>/views/<viewId>.html Oui Affichage de la vue viewId du document n°docid
GET /api/v1/documents/<docid>/views/<viewId>/revision/<revision>.html Oui Affichage de la vue viewId de la révision n°revision du document n°docid

Si les extensions "html" sont remplacés par l'extension "json", l'url reste valide et retourne les données du documents ou de la vue.

Chapitre 7 Techniques avancées avec Dynacase Document UIs

7.1 Structure HTML des éléments de Dynacase Document UIs

La DOM des éléments générs par Dynacase Document UIS est normalisée selon les règles suivantes.

7.1.1 Le document

La page globale d'un document HTML standard contient la structure suivante :

<html>
    <head>...</head>
    <body>
        <div class="document">
            <div class="dcpDocument">
                <header class="dcpDocument__header">L'entête de document</header>
                <nav class="dcpDocument__menu">La barre de menu</nav>
                <section class="dcpDocument__body">Le corps du document</section>
                <footer class="dcpDocument__footer">Le pied de document</footer>
            </div>
        </div>
    </body>
</html>

Exemple : mettre un fond noir sur la page

.dcpDocument {
    background-color: black;
}
.dcpDocument .dcpDocument__header,
.dcpDocument .dcpDocument__menu,
.dcpDocument .dcpDocument__body,
.dcpDocument .dcpDocument__footer
{
    background-color: inherit;
}

En fonction du mode de rendu (consultation, modification, création), une classe de style supplémentaire est ajoutée sur la div <div class="dcpDocument">.

Cette balise contient aussi une classe dcpFamily--[familyName] qui permet de différencier les documents par famille. familyName contient le nom logique de la famille.

Exemple : <div class="dcpDocument dcpDocument--view dcpFamily--MY_FAMILY"></div>

En outre, une classe est ajoutée si le navigateur supporte les événements tactiles :

<div class="dcpDocument dcpTouch">

7.1.2 Le contenu DOM du corps de document

Le contenu de rendu d'un document est inséré dans une section .dcpDocument__body.

L'exemple ci-dessous représente un document ayant la structure suivante :

<section class="dcpDocument__body">
    <div class="dcpDocument__frames">
        <div class="dcpFrame" data-attrid="f1">
            <div class="dcpFrame__label dcpLabel" data-attrid="f1">
                Label du cadre
            </div>
            <div class="dcpFrame__content" data-attrid="f1" >
                <div class="dcpAttribute dcpAttribute--type--text" data-attrid="a2" >
                    <label class="dcpAttribute__label dcpLabel dcpAttribute__label--text " data-attrid="a2">
                        Label de l'attribut
                    </label>
                    <div class="dcpAttribute__content dcpAttribute__content--text" data-attrid="a2">
                        Valeur de l'attribut
                    </div>
                </div>
                <div class="dcpAttribute dcpAttribute--type--int" data-attrid="a3">
                    <label class="dcpAttribute__label dcpLabel dcpAttribute__label--int" data-attrid="a3">
                        Label d'un autre attribut
                    </label>
                    <div class="dcpAttribute__content dcpAttribute__content--int" data-attrid="a3">
                        Valeur d'un autre attribut
                    </div>
                </div>
                <div class="dcpArray" data-attrid="array1">
                    <div class="dcpArray__label dcpLabel" data-attrid="array1">
                        Label du tableau
                    </div>
                    <div class="dcpArray__content" data-attrid="array1">
                        <table>
                            <thead class"dcpArray__head" data-attrid="array1">
                                <tr>
                                    <th class="dcpArray__head__cell dcpLabel dcpAttribute__label--text " data-attrid="a5">
                                        Label d'un attribut
                                    </th>
                                    <th class="dcpArray__head__cell dcpLabel dcpAttribute__label--docid " data-attrid="a6">
                                        Label d'un autre attribut
                                    </th>
                                </tr>
                            </thead>
                            <tbody class="dcpArray__body" data-attrid="array1">
                                <tr class="dcpArray__content__line" data-attrid="array1" data-line="0">
                                    <td class="dcpAttribute__content dcpAttribute__label--text" data-attrid="a5">
                                        Valeur d'un attribut
                                    </td>
                                    <td class="dcpAttribute__content dcpAttribute__label--docid" data-attrid="a6">
                                        Valeur d'un autre attribut
                                    </td>
                                </tr>
                                <tr class="dcpArray__content__line" data-attrid="array1" data-line="1">
                                    <td class="dcpAttribute__content dcpAttribute__label--text" data-attrid="a5">
                                        Valeur d'un attribut
                                    </td>
                                    <td class="dcpAttribute__content dcpAttribute__label--docid" data-attrid="a6">
                                        Valeur d'un autre attribut
                                    </td>
                                </tr>
                            </tbody>
                       </table>
                   </div>
                </div>
            </div>
        </div>
    </div>
    <div class="dcpDocument__tabs">
        <ul class="dcpDocument__tabs__list">
            <li class="dcpTab__label dcpLabel dcpLabel--active" data-attrid="t1">
                Label de l'onglet
            </li>
            <li class="dcpTab__label dcpLabel dcpLabel--default" data-attrid="t2">
                Label de l'onglet
            </li>
        </ul>
        <div class="dcpTab__content" data-attrid="t1">
            <div class="dcpFrame" data-attrid="f2">
                Contenu d'un cadre…
            </div>
            <div class="dcpFrame" data-attrid="f3">
                Contenu d'un autre cadre…
            </div>
        </div>
        <div class="dcpTab__content" data-attrid="t2">
            <div class="dcpFrame" data-attrid="f4">
                Contenu d'un cadre…
            </div>
            <div class="dcpFrame" data-attrid="f5">
                Contenu d'un autre cadre…
            </div>
        </div>
    </div>
</section>

7.1.3 Identifier les attributs dans la css

Les attributs sont au sein de la section .dcpDocument__body, dans une div de la forme
<div class="dcpAttribute dcpAttribute--type--***" data-attrid="***"/>

7.1.3.1 Label des attributs

7.1.3.1.1 Label en général

Tous les labels d'attributs peuvent être adressée avec les mêmes règles :

Règle Définition
.dcpDocument .dcpLabel Tous les labels (hormis les onglets)
.dcpDocument .dcpLabel[data-attrid="attributeId"] Label de l'attribut attributeId

Exemple :

.dcpDocument .dcpLabel {
    color: #ffff00;
    background-color: #262600;
}
.dcpDocument .dcpLabel[data-attrid="my_text"] {
    color:blue;
}
.dcpDocument .dcpLabel[data-attrid="my_number"] {
    color: #ff6d8c;
}

7.1.3.1.2 Label des onglets

Les onglets (attribut de type tab) ont deux états :

De par ces états, des règles plus précises sont nécessaires pour modifier leur apparence :

Règle Définition
.dcpDocument .dcpLabel.dcpLabel--active Label de l'onglet actif
.dcpDocument .dcpLabel.dcpLabel--default Label des onglets inactifs
.dcpDocument .dcpLabel.dcpLabel--active[data-attrid="attributeId"] Label de l'onglet attributeId lorsqu'il est actif
.dcpDocument .dcpLabel.dcpLabel--default[data-attrid="attributeId"] Label de l'onglet attributeId lorsqu'il est inactif

Les onglets ont un élément actif permettant de changer d'onglet. Cet élément est une ancre HTML (a) et sa couleur ne peut être modifiée que par des règles plus précises portant sur l'ancre elle-même :

Règle Définition
.dcpDocument .dcpLabel.dcpLabel--active[data-attrid="attributeId"] a Texte du label de l'onglet attributeId lorsqu'il est actif
.dcpDocument .dcpLabel.dcpLabel--default[data-attrid="attributeId"] a Texte du label de l'onglet attributeId lorsqu'il est inactif

Exemple :

.dcpDocument .dcpLabel--default[data-attrid="tst_myframe"] {
    color:violet;
    background: #fdffbb;
}
.dcpDocument .dcpLabel--active[data-attrid="tst_myframe"] {
    background:violet;
    color: #fdffbb;
}

7.1.3.2 Contenu des attributs

Le contenu des attributs peut être adressé avec les règles suivantes :

Règle Définition
.dcpDocument .dcpAttribute__content Tous les contenus d'attributs (hormis les attributs de structure)
.dcpDocument .dcpArray__content Les contenus des tableaux
.dcpDocument .dcpFrame__content Les contenus des cadres
.dcpDocument .dcpTab__content Le contenu des onglets
.dcpDocument .dcpAttribute__content[data-attrid="attributeId"] Contenu de l'attribut attributeId
.dcpDocument .dcpArray__content[data-attrid="attributeId"] Contenu du tableau attributeId
.dcpDocument .dcpFrame__content[data-attrid="attributeId"] Contenu du cadre attributeId
.dcpDocument .dcpTab__content[data-attrid="attributeId"] Contenu de l'onglet attributeId

Exemple : Afficher les attributs du cadre "my_frame" sur deux colonnes, et changer ses couleurs :

.dcpFrame__content[data-attrid="my_frame"] {
    background: linear-gradient(45deg, rgba(206,219,233,1) 0%,rgba(97,153,199,1) 51%,rgba(65,154,214,1)  84%,rgba(38,85,139,1) 100%);
    color: white;
}
 
.dcpFrame__content[data-attrid="my_frame"] a{
    color: yellow;
}
 
.dcpFrame__content[data-attrid="my_frame"] .dcpAttribute {
    float: left;
    display: inline-block;
    width: 50%;
    height: 3em;
}
Rendu par défaut

Figure 62. Rendu par défaut

Rendu avec css personnalisée

Figure 63. Rendu avec css personnalisée

7.2 La navigation au clavier

Afin de faciliter l'utilisation des formulaires générés au moyen de Dynacase DocumentUIs, seules les zones de saisie de texte sont accessibles au moyen de la touche tabulation (↹).

Ainsi, un utilisateur peut saisir l'ensemble des données d'un formulaire sans quitter le clavier.

Cela veut dire que les boutons qui accompagnent les input ne sont pas accessibles au moyen du clavier. Cela inclut notamment :

Cependant, la plupart des opérations correspondantes sont accessibles via le clavier.

7.2.1 Cas particuliers

7.2.1.1 Attributs de type file ou image

Une fois que l'attribut a obtenu le focus, il faut utiliser la touche enter (⏎) pour que la fenêtre de sélection de fichier s'ouvre.

La navigation dans cette fenêtre dépend ensuite du système d'exploitation de l'utilisateur.

7.2.1.2 Attributs de type docid ou enum

La liste déroulante est accessible au moyen de la touche flèche vers le bas (↓).

Il est ensuite possible de sélectionner un élément au moyen de la touche enter (⏎).

Lorsque l'attribut est multiple, il est possible de se déplacer entre les valeurs au moyen des flèches gauche et droite. Il est ensuite possible de supprimer la valeur à gauche du curseur au moyen de la touche retour (⌫)

7.2.1.3 Attributs de type color

Le colorpicker est accessible au moyen de la touche enter (⏎).

Il est ensuite possible de changer la couleur au moyen des flèches, puis de valider son choix au moyen de la touche enter (⏎).

7.2.2 Limitations

Pour changer d'onglet, il faut se positionner sur la barre des onglets, et utiliser les flèches latérales pour passer d'un onglet à l'autre.

7.2.3 Prendre en compte la navigation au clavier dans les interfaces spécifiques

Lors du développements d'interfaces spécifiques (vues d'attributs notamment), il est important d'exclure certains éléments de la navigation par clavier afin de rester homogène avec l'approche des formulaires générés par Dynacase Document UIs.

Cela se fait au moyen de l'attribut tabindex auquel on donne la valeur -1.

Liste des illustrations

Licence

Ce document est publié sous licence CC http://creativecommons.org/licenses/by-nc-sa/2.0/fr/

Vous êtes libres :

Selon les conditions suivantes :

Édition

Manuel de référence
© Anakeen, Labs <labs@anakeen.com>
Module Document User Interface, version 1.0
Édition 2
Publié le 03/08/2018

Ce livre a été produit avec easybook 4.8, logiciel libre et open source développé par Javier Eguiluz à l'aide de différents composants Symfony.

Anakeen

Créé en 1998, Anakeen est un éditeur expert dans l'amélioration de la gestion des processus et de l'information avec pour objectif principal : valoriser les fonctions support en les libérant des tâches à faible valeur ajoutée. Le résultat opérationnel a toujours été recherché par toutes les entreprises et particulièrement aujourd'hui où le moindre détail peut faire la différence afin d'être ou de rester compétitif sur son marché. Pour chaque fonction support, être en situation de valoriser sa contribution au résultat global de l’entreprise est plus que jamais devenu une nécessité.

Impliqué depuis 1998 dans le logiciel libre, Anakeen est un acteur majeur de la gestion de l'information. Nos contributions pour l'utilisation des standards ouverts, la garantie de l'accès au code source et la grande diversité de nos partenaires vous assure pérennité et réversibilité.

L'ensemble du code PHP de Dynacase Platform est disponible sous licence Open Source, le modèle de données est documenté et public. Mais plus que ça, le code source est commenté dans l'objectif de faciliter sa compréhension pour la réutilisation ou la modification. Aussi toute la documentation concernant le produit est mise en ligne sur www.dynacase.org.

En choisissant un logiciel Open Source, vous faites le choix de la sécurité, car vous avez l'assurance de vérifier le fonctionnement du logiciel et la qualité du code.

Nos offres et services, nous permettent d'assurer le financement du développement produit mais aussi de contribuer chaque jour à l'adoption du business model Open Source.