Le module Dynacase API fournit les classes javascript nécessaires pour interagir avec le serveur Dynacase depuis un navigateur web. Il est basé sur un ensemble de classes reprenant les éléments constituant Dynacase tels que le document, la famille, la collection ou le contexte.
Toutes les classes du module appartiennent à la variable globale Fdl (Dynacase Library) et suivent donc la syntaxe : Fdl.<nom de la classe>.
Le module est parfaitement autonome et peut être utilisé conjointement avec d'autres bibliothèques javascript telles que Ext JS ou jQuery.
La documentation de référence contient la description des objets de l'api ainsi que leurs attributs et méthodes. Il s'agit d'une interface identique à la documentation des classes Ext JS. Les classes relatives à Dynacase API se trouvent dans le dossier Fdl.
Les exemples pour ce module se trouvent, en partant d'une installation du module freedom-apisamples, dans le répertoire : <url-freedom>/lib/data-examples/ .
Fdl.Context est la classe de base dans l'utilisation du module Dynacase API. Elle contient les méthodes fondamentales pour effectuer des requêtes sur le serveur Dynacase. Toutes les classes d'objet capables d'interaction avec le serveur Dynacase sont équipées d'un objet Fdl.Context.
Normalement, l'objet Fdl.Context est instancié avec l'url du serveur Dynacase qu'il doit interroger par la suite. Cela effectué, l'instance de Fdl.Context propose un grand nombre de méthodes permettant d'obtenir des informations du serveur. En particulier, elle est capable de servir d'usine (au sens design pattern factory) à un certain nombre d'objet du module. C'est à dire qu'elle donne un certain nombre de méthodes dont l'utilité est de retourner une instance d'objet correctement paramétrée pour être utilisée. En particulier, Fdl.Context sert à récupérer des instances d'objet Fdl.Document et ses héritiers (Fdl.Family, Fdl.Workflow, …).
Fdl.Context contient les méthodes capables de renseigner sur les erreurs rencontrées lors des appels sur le serveur. Lorsqu'une méthode d'un objet du module n'a pas un retour valide (tel que défini dans la spécification de chaque méthode, voir la référence), l'appel de getLastErrorMessage() permet de récupérer le dernier message d'erreur du serveur.
Fdl.Context contient les méthodes qui permettent de gérer l'authentification d'un utilisateur.
Exemple : instanciation d'un contexte et authentification
var context = new Fdl.Context({ url:'http://freedom/' }); if (! context.isConnected()) { alert('Connection Error : ' + context.getLastErrorMessage()); return; } if (! context.isAuthenticated()) { var user = context.setAuthentification({ login:'admin', password:'anakeen' }); } if (! user) { alert('Authentification Error : ' + context.getLastErrorMessage()); return; }
Fdl.Context permet de gérer la traduction des interfaces en utilisant un dictionnaire de langue pour les applications. La méthode _() permet d'appeler le texte localisé selon le profil de l'utilisateur. La génération du fichier correspondant repose sur l'utilisation de l'outil de gestion de langue po. [A compléter]
Fdl.Context permet d'envoyer une requête au serveur Dynacase en utilisant la méthode retrieveData(). Les objets du module reposent sur cette méthode pour charger ou envoyer les données serveur. Elle peut être utilisée pour exécuter une action d'application.
Fdl.Document est la classe représentant un document Dynacase. Il est récupéré depuis un Fdl.Context par la méthode getDocument(). Il faut se souvenir que dans un système Dynacase, tout est document. Fdl.Document possède donc des classes héritées plus spécifiques pour gérer les comportements étendus disponibles dans certaines familles natives de document, en particulier :
La méthode getDocument() retourne un objet qui est une instance correcte parmi Fdl.Document et ses familles héritées. On trouve ici l'intérêt d'avoir un Fdl.Context qui suive le modèle de conception Usine, puisque le développeur n'a pas à déterminer quelle classe instancier. Il peut bien sûr ensuite tester l'appartenance de l'objet qu'il a obtenu à l'une de ces classes pour déterminer des comportements particuliers.
Fdl.Collection est la classe représentant un document Dynacase de type collection, qui peut être soit un dossier, soit une recherche. Ces documents collection contiennent d'autres documents, défini de façon statiques dans le cas des dossiers, par des critères de recherche dans le cas des recherches (ou dossiers intelligents). Dans le cas d'une recherche, la classe filtre est utilisée pour délimiter le périmètre de recherche (voir Fdl.DocumentFilter).
Fdl.SearchDocument est une classe permettant d'effectuer des recherches de documents sur le serveur Dynacase de façon volatile (aucun document permanent n'est créé sur le serveur suite à une recherche effectuée ainsi), afin de récupérer un contenu restreint par un filtre, sans passer par la création d'un document recherche. Sur des interfaces applicatives, elle peut être utilisée par exemple pour assurer le fonctionnement de champs de recherche texte (voir Fdl.DocumentFilter).
Référence Fdl.DocumentSelection
Fdl.DocumentSelection est une classe permettant d'exprimer une sélection de documents. Il est ainsi possible d'utiliser certaines méthodes sur une sélection de documents plutôt que d'effectuer une itération document par document (par exemple, déplacer une sélection de document d'un dossier dans un autre). La structure de base d'un Fdl.DocumentSelection définit : - le mode de sélection ('rien sauf' ou 'tout sauf') - la collection sur laquelle porte la sélection (obligatoire dans le mode 'tout sauf') - une liste de documents ajoutée ou retranchée (selon le mode de sélection, peut être vide) - un filtre Fdl.DocumentFilter (non obligatoire) Les sélections de documents peuvent servir à définir les sélections multiples effectuées et manipulées par les utilisateurs sur des interfaces graphiques.
var selection = new Fdl.DocumentSelection( { mainSelector: 'all', // Select all documents ... collectionId : 2000, // ... from collection 2000 ... selectionItems: [1050,1100,1150] // ... except documents 1050, 1100, and 1150 }); // Add a Fdl.DocumentFilter to the Fdl.DocumentSelection selection.filter = new Fdl.DocumentFilter({ family:'DIR' }); // Insert a document to selectionItems selection.insertToList({id:1200});
Fdl.DocumentFilter est une classe représentant la notion de filtre de documents. Elle permet de caractériser un sous ensemble de documents en exprimant des conditions sur les familles et les valeurs à satisfaire. La classe Fdl.DocumentFilter est à utiliser dans les classes suivantes : Fdl.SearchDocument. Le contenu d'une document de recherche est défini par le filtre qui sert à le construire. Fdl.Collection. Le contenu d'une collection de type recherche est défini par un ensemble de filtre qui peuvent être ajoutés à la recherche. Il est possible de définir de cette façon des recherches multifamille. La récupération du contenu d'une recherche peut également être soumise à un filtre volatile. Fdl.DocumentSelection. Une sélection de documents peut utiliser un filtre pour restreindre à un sous ensemble des documents exprimés par la sélection. La structure de base d'un Fdl.DocumentFilter définit : - une famille sur laquelle porte la contrainte (non obligatoire) - une expression logique comportant des blocs constitués d'un opérateur et d'opérande(s)
Les opérandes peuvent être exprimés sous la forme d'appel à des méthodes définies côté serveur du document Dynacase, comme montré dans l'exemple suivant avec '::getSystemUserId()'.
Exemple : ce filtre permet de sélectionner les documents de la famille Dossier qui ne sont pas verrouillés ou qui sont verrouillés par l'utilisateur courant.
var filter = new Fdl.DocumentFilter( { family : 'DIR', criteria : [ { or : [ { operator : '=', left : 'locked', right : 0 }, { operator : '=', left : 'locked', right : '::getSystemUserId()' } ] }, ] });
Fdl.GroupRequest est une classe permettant d'enchaîner plusieurs opérations sur le serveur Dynacase en un seul appel. Son objectif est de rassembler plusieurs appels serveur en un seul afin de gagner en performance. De façon générale, exécuter un seul appel comportant plusieurs méthodes est plus avantageux en durée qu'exécuter plusieurs petits appels.
Exemple : cette requête groupée permet d'accéder à un document dossier, de le verrouiller, d'accéder à son contenu, et de verrouiller son contenu.
var groupRequest = context.createGroupRequest(); groupRequest.addRequest({d:g.getDocument({id:1000}); groupRequest.addRequest({l:g.get('d').callMethod('lock')}); groupRequest.addRequest({c:g.get('d').callMethod('getContent')}); groupRequest.addRequest({z:g.foreach('c').callMethod('lock')}); var result = groupRequest.submit(); var document = groupRequest.get('d'); var content = groupRequest.get('c');
Fdl.Notifier est une classe permettant de mettre en oeuvre une récupération périodique d'informations sur le serveur Dynacase.
var document = context.getDocument({ id:1000 }); document.fireEvent = function (code,args) { // Process event here } var notifier = context.getNotifier(); notifier.subscribe(document); // or alternatively notifier.subscribe({object:document,callback:'fireEvent'}); notifier.loop();