Développement d'une Document-centric App pour Office 2013

Publié dans: 

Les document-centric Apps sont des applications pour office destinées aux documents, c’est-à-dire les applications de type Task Pane App et Content App.

On introduira dans cet article l'API destinée au développement de ce type d'application, on verra comment interagir avec le contenu d'un document et on citera quelques recommandations à respecter pour ces types d'application pour Office 2013.

API

Office 2013 fournit une API JavaScript pour le développement des applications destinées aux documents. Cette API expose un ensemble d’objets utilisé pour lire/écrire le contenu d’un document.

Cette API sert aussi à créer des Events Handler et des Bindings qu'on détaillera plus tard dans cet article. 

 

L’Office JavaScript Object Model fournis un objet nommé Office avec une propriété Context qui fournit des points d’entrée vers les API. On y trouve trois propriétés :

  • Office.context.document : Accès au document courant. Par exemple le document Excel ou Word dans lequel l'application s'exécute.

  • Office.context.settings : Accès au custom property bag qui permet aux développeurs de sauvegarder et récupérer des propriétés 

  • Office.context.mailbox : Accès à Outlook

Interaction avec le document :

Pour lire et écrire du contenu dans le document, vous pouvez utiliser les méthodes de l’objet Office.context.document getSelectedDataAsync et setSelectedDataAsync. 

Pour écrire du contenu dans le document il faut utiliser la méthode setSelectedDataAsync. Cette méthode reçoit en paramètre la contenu à écrire et une fonction callback pour vérifier le succès de l’opération.

Voici comment passer les valeurs des paramètres de la méthode setSelectedDataAsync suivant le type du contenu :

  • Text : il suffit de passer une chaine de caractère

  • Matrix : un tableau JavaScript à deux dimensions

  • Table : Vous devez utiliser un type TableData fourni dans l’Office JavaScript API.

Type de donnée :

Il y’a trois type de données supportés lors de lecture et écriture d’un document :

  • Text : texte simple

  • Matrix : tableau statique à deux dimensions

  • Table : Tableau dynamique à deux dimensions avec des colonnes nommées et un ensemble de ligne où l’on peut ajouter ou supprimer des éléments.

Event Handler :

Pour la gestion des évènements, vous pouvez par exemple associer un Handler à un événement en appelant la méthode addHandlerAsync avec comme paramètre le callBack de déclenchement de l’événement choisiVous pouvez aussi la désassocier en invoquant la méthode removeHandlerAsync.

Exemple :

Cet exemple explique comment récupérer un texte sélectionné et associer un handler à l'évènement documentSelectionChanged.

Voici la portion de code de notre exemple :

(function () {
    "use strict";

    // La fonction d'initialisation doit être exécutée chaque fois qu'une nouvelle page est chargée
    Office.initialize = function (reason) {
        $(document).ready(function () {
            app.initialize();
            Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, getDataFromSelection);
        });
    };
 


    // Lit les données de la sélection actuelle du document et affiche une notification
    function getDataFromSelection() {
        Office.context.document.getSelectedDataAsync(Office.CoercionType.Text,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Succeeded) {
                    app.showNotification('Le texte sélectionné est :', '"' + result.value + '"');
                } else {
                    app.showNotification('Erreur :', result.error.message);
                }
            }
        );
    }
})();

Lors du démarrage de l'application, on va ajouter un Handler pour l'évènement documentSelectionChanged. Le Handler récupèrera le texte sélectionné et l'affichera dans la zone inférieure de l'application.
Ainsi le texte sélectionné par l'utilisateur sera affiché dans l'application.

Scénario :

  1. Ecrivez du texte dans le document.

  2. Sélectionnez le texte 

  3. Le texte sélectionné s'affichera dans la zone grise en bas de l'application

Le binding :

Le binding est une liaison de l’application à une section du document. Il peut être créé en se basant sur la sélection courante. Il peut être aussi défini sur un rang dans une feuille Excel ou un signet dans un document Word. La gestion des événements est aussi supportée dans les binding, vous pouvez par exemple détecter les changements effectués par un utilisateur dans le contenu de la zone affectée au binding.

Le binding supporte trois types de données :

  • Text Binding : Pour une cellule dans Excel ou du texte dans Word

  • Matrix binding : Pour un tableau à deux dimensions représentant des lignes et des colonnes

  • Table binding : C’est comme la matrix binding supportant un entête.

Pour pouvoir ajouter le binding vous devez utiliser l’une des méthodes suivantes :

  • Bindings.addFromPromptAsync

  • Bindings.addFromSelectionAsync

  • Bindings.addFromNamedItem

Pour récupérer les bindings, vous pouvez utiliser l’une de ces méthodes :

  • Bindings.getAllAsync

  • Bindings.getByIdAsync

  • Office.Select

Pour retirer un binding utilisez la méthode Bindings.releaseByIdAsync

Pour associer un événement à un binding, utilisez la méthode Binding.addHandlerAsync(“type”, Handler);

 

Exemple : 

Dans cet exemple, nous allons voir comment ajouter un binding à une cellule et ensuite récupérer son contenu. 

HTML :

On a ajouté un bouton avec l'action addBindingFromSelection et un input pour afficher le texte de la cellule.

<body>
    <button onclick="addBindingFromSelection()">Bind to cell</button>
    <input id="output" />
</body>

JavaScript :

Dans la méthode addBindingFromSelection nous avons ajouté un binding de type texte pour la cellule sélectionnée, avec un Id et un CallBack. Le CallBack associera un Handler à un évènement pour le binding ajouté.
Le Handler de l’évènement récupèrera la valeur de la cellule et l’affichera dans un input.
Notez qu’on a récupérer le binding  de deux façons différentes pour voir les deux alternatives (Office.context.document.bindings.getByIdAsync() et Office.select("bindings#MyBinding").getDataAsync()).
 

    // Fonction d'initialisation commune (à appeler depuis chaque page)
    Office.initialize = function () {
        $(document).ready(function () {

        });
    };

    function addBindingFromSelection() {

        Office.context.document.bindings.
              addFromSelectionAsync(Office.BindingType.Text,
              { id: 'MyBinding' },
              function (asyncResult) {
                  Office.context.document.bindings.getByIdAsync(asyncResult.value.id,
                    function (result) {
                        if (result.status === Office.AsyncResultStatus.Succeeded) {
                            var binding = result.value;
                            // Et lie un gestionnaire d\'événements de modification à la liaison :
                            binding.addHandlerAsync(
                                Office.EventType.BindingDataChanged,
                                onBindingSelectionChanged
                            );
                        } 
                    });
              }
        );
    }

    function onBindingSelectionChanged(eventArgs) {

        Office.select("bindings#MyBinding").getDataAsync(
              function (asyncResult) {

                  if (asyncResult.value != "") {
                      var dataValue = asyncResult.value;
                      var e = document.getElementById
                             ("output");
                      e.value = dataValue;
                  }
              }
        );
    }

Scénario :

  1. Sélectionnez une cellule et cliquez sur le bouton Bind to cell

  2. Ecrivez du texte dans cette cellule

  3. Sélectionnez une autre cellule

  4. Le texte s’affichera à gauche du bouton.

Recommandation pour le design

Il y’a des recommandations à suivre pour l’implémentation et la conception d’une application pour office destinée pour document.

Expérience utilisateur:

Ces recommandations incluent l’utilisation de Styles Office et une expérience utilisateur standard. Quand vous créez votre application pour office, gardez en tête qu’elle doit garantir que tous les scénarios respectent les recommandations pour l’expérience utilisateur sur navigateur, tablettes et appareils mobiles.

Rappelez-vous que vous pouvez utiliser d’autres technologies à part le HTML5. Flash et Silverlight peuvent fournir des fonctionnalités difficilement réalisables sur HTML 5. Donc choisissez la bonne technologie avant de commencer le développement en tenant en compte l’expérience utilisateur à satisfaire et les limites de ses technologies.

Task Pane App :

Voici les recommandations pour une application de type Task Pane

  • La largeur par défaut de l’application de type Task Pane App est de 270 pixels. Le développeur ne pourra pas changer cette valeur.

  • D’autre part, l’utilisateur peut modifier la largeur, donc vous devez prendre en considération cela dans vos développements pour garantir la même expérience utilisateur pour tous les scénarios.

  • Pour les barres de défilement, vous devez éviter de créer un en Horizontale. Les barres verticales sont permises si nécessaire.

  • Les développeurs peuvent créer des menus contextuels personnalisés au menu contextuel situé en haut à droite. Cependant, vous n’avez pas accès aux autres menus d’Office UI ou au menu contextuel du l’application.

Content App :

Il y’a des recommandations spécifique au Content App.

  • La largeur maximale de l’application est de 2560 pixels et la hauteur est de 2048 pixels.

  • Toutes les barres de défilement doivent être évitées.  

  • En cas où vous jugez qu’il vous faut plus d’espace, changez la largeur et la hauteur de l’application dans le fichier manifest.

  • Comme les Task Pane App, vous n’aurez accès à la modification qu’au menu contextuel situé en haut à droite de l’application.

Permissions demandées :

Pour bien remplir ces fonctions, une application pour office doit avoir des permissions pour interagir avec le document. Ci-dessous la liste des niveaux de permission disponibles :

  • Default (restricted) : permet de lire et écrire dans les paramètres du document mais ne fournit pas l’accès au contenu du document.

  • Read Document : permet de lire le contenu du document ainsi que l’accès en lecture/écriture de ses paramètres. Elle permet aussi l’association des événements et la création de bindings.

  • Write Document : contient le droit en écriture dans le contenu du document, l’accès en  lecture/écriture de ses paramètres. Ce niveau ne permet pas la lecture du contenu du document.

  • Read/Write Document : ce niveau combine les deux niveaux de permissions Read Document et Write Document.

Ces paramètres sont modifiables dans le fichier Manifest de l'application.

 

Liens Utiles

Ci-dessous d'autre articles liés :
Introduction des applications pour Office 2013
Développement d'une Mailbox-centric App pour Office