Packaging & Intégration

Un plugin est un ensemble de modules qui s'exécutent dans un processus hôte. Il est entièrement décrit par un fichier manifest qui est chargé par l'environnement Rio au démarrage de l'hôte.

Ce manifest permet de configurer de manière détaillée votre plugin en ciblant un hôte particulier, la version du runtime dans lequel il doit s’exécuter ainsi que les modules auxquels le runtime Rio doit apporter une attention particulière lors du démarrage de votre plugin comme l’enregistrement de vos macros, l’intégration au ruban etc.

L'exemple suivant décrit un plugin pour l'hôte Word. Il s’exécutera avec le CLR .NET* compatible avec la version 4.0. Le plugin cible les versions 11 à 14 de Word et deux modules seront analysés au démarrage du plugin.

<?xml version="1.0" encoding="utf-8" ?>

<manifest xmlns="urn:schemas-rio-platform-com:manifest.v1">

  <host id="${WORD}" version="11.0-14.0">

    <requiredRuntime type="CLR" version="v4.0" />

    <bootstrapper module="Rio.Office, Version=4.0.0.0, Culture=neutral, PublicKeyToken=18c98b08879cb5a4" 

                  class="Rio.Office.DomainManager"/>

  </host>

  <domain name="WordPlugin">

    <setup applicationBase="${PRODSRV}/Plugins/WordPlugin/"

           cachePath="${CACHE}"

           shadowCopyFiles="true">

    </setup>

    <modules>

      <module name="WordPlugin.GUI, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

      <module name="WordPlugin.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />      

    </modules>

  </domain >  

</manifest>

*Chaque plugin s’exécutant dans le CLR .NET est isolé dans un domaine d’application qui lui est propre.

De manière générale il est utile lorsque l’on réalise un plugin d’être notifié lorsque l’hôte est en train de le charger. Ceci permet au développeur d’effectuer les initialisations nécessaires au bon usage du plugin. De même il peut être utile d’être averti lorsque votre plugin est en cours de déchargement.

Le Framework Rio permet de capter les évènements de chargement et déchargement grâce à deux attributs OnStartup et OnShutdown.

L'attribut OnStartup permet de déclarer une méthode ou un constructeur comme un point de démarrage. Ces méthodes peuvent avoir plusieurs prototypes mais de manière générale elles prennent un objet de type Context. Cet objet permet notamment de récupérer l'hôte en cours, d'enregistrer un ruban, de créer un volet office etc. Plusieurs points d'entrée ou point de démarrage peuvent être créés n'importe où dans vos modules.

De même l'attribut OnShutdown disposé sur une méthode d’un de vos types permet d'être notifié lors du déchargement du plugin.

L'exemple suivant montre une classe EntryPoint définissant deux méthodes permettant de capter les évènements de chargement et déchargement. La méthode Start montre de plus comment récupérer l'instance de l'hôte en cours via l’objet de type Context.

using MsWord = Microsoft.Office.Interop.Word;

namespace WordPlugin
{
    public class EntryPoint
    {
        [OnStartup]
        public void Start(Context context)
        {
            MsWord.Application theApp = context.GetHost<MsWord.Application>();
            // ...
        }

        [OnShutdown]
        public static void Close(Context context)
        {
            // Plugin shutdown.
        }
    }
}

Une macro est une fonction qui permet, de modifier l'apparence de l'application hôte, de réagir à un clic de bouton, de modifier le document en cours, d'interagir avec l'utilisateur.

Le Framework Rio permet de créer très facilement des macros grâce à l'attribut MacroFunction. Ce dernier disposé devant une méthode permet de la déclarer automatiquement comme étant une macro comme le montre l'exemple suivant.

        [MacroFunction("SetRandomVector")]
        public void Macro1(Range selection)
        {
            Random rnd = new Random((int)DateTime.Now.Ticks);
            selection.Value = new double[] { rnd.NextDouble(), rnd.NextDouble(), rnd.NextDouble() };
        }

        [MacroFunction]
        public void ShowMessageBox()
        {
            MessageBox.Show("Hello from Macro");
        }

Apparu avec la version 2007 de la suite Office, le ruban apporte une expérience nouvelle aux utilisateurs. Celle-ci est d’autant plus intéressante lorsque l’on réalise des plugins car cette disposition permet à vos utilisateurs d’avoir une vision globale de l’ensemble des fonctionnalités offertes. Le ruban est entièrement configurable à partir d’un fichier XML. Ce fichier décrit les différentes parties de l’interface et les macros associées aux différents évènements (callbacks) déclenchés par les contrôles. A l'heure actuelle le Framework Rio supporte les versions 2007 et 2010 d'Office pour la configuration du ruban.

Le volet office disponible lui aussi à partir de la version 2007 permet d’insérer des formulaires ou d’intégrer des interfaces à base de formulaires et de contrôles au sein des applications de la suite Office. Le Framework Rio via le service IOfficeUI (voir exemple ci-dessous) fournit une manière simple et rapide de customiser ces différentes interfaces. L'enregistrement des rubans et volets Office se fait via l'intermédiaire d'un point d'entrée.

L'exemple suivant montre comment ajouter de nouveau contrôle au ruban à partir d'un fichier Xml, créer un volet Office à partir d'un UserControl (CustomPanel dans l’exemple) que vous avez à fournir et la classe C# chargée de gérer l'enregistrement et les évènements associés.

<?xml version="1.0" encoding="utf-8" ?>

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnRibbonLoad" loadImage="LoadImage">

  <ribbon>

    <tabs>

      <tab id="MyTabId" label="My Tab"  insertAfterMso="TabHome">

        <group id="cg1" label="Sample">

          <button id="button1" label="Click Me" size="large" onAction="OnClick" image="clickImage" />          

        </group>

      </tab>

    </tabs>

  </ribbon>

</customUI>

    // Defines class as a singleton.
    [OfficeClass(Singleton = true)] 
    public class CustomUI
    {
        IRibbonUI ribbonUI = null;
        CustomTaskPane taskPanel = null;

        [OnStartup]
        public CustomUI(Context context)
        {
            // Get officeUI from Context.
            IOfficeUI officeUI = context.GetService<IOfficeUI>();
            // Add Xml Ribbon stream.
            officeUI.CustomUI.Add(Assembly.GetExecutingAssembly().GetManifestResourceStream("WordPlugin.RibbonUI.xml"));
            // Register our CustomPanel.
            taskPanel = officeUI.CustomTaskPanes.Add(new CustomPanel(), "My Custom Panel");
        }

        [MacroFunction("OnRibbonLoad")]
        public void Macro1(IRibbonUI ribbonUI)
        {
            this.ribbonUI = ribbonUI;
        }

        [MacroFunction]
        public Picture LoadImage(string imageId)
        {
            return (imageId == "clickImage") ? Picture.Create(Resource.icon1) : null;
        }

        [MacroFunction("OnClick")]
        public void Macro2(IRibbonControl control)
        {
            taskPanel.Visible = !taskPanel.Visible;
        }
    }