Introduction

La bibliothèque de fonctions de la DLL DocxToolBx permet la manipulation de documents Word au format Office 2007 et versions supérieures (OpenXML WordprocessingML).

Elle permet de construire intégralement un document basique, de gérer des publipostages en renseignant automatiquement les valeurs des champs de fusion, de générer des rapports, etc.

Cette bibliothèque est disponible pour Visual Adélia, Adélia Web et Adélia Cloud.

Limitations

La DocxToolBx peut manipuler statiquement un document, mais n'est pas capable d'effectuer du rendu ou du code script.

Par exemple, il n'est pas possible d'évaluer le résultat d'un appel de fonction dans un tableau, ou de connaître le numéro de la page courante pour une position donnée dans le document. Pour cela, vous devez explicitement ouvrir le document dans Word et sélectionner l'option "Mettre à jour les champs".

Cela signifie en autres que si vous exportez un document au format PDF, il est possible que les champs dynamiques ne soient pas à jour.

Configuration

La DocxToolBx est disponible pour Visual Adélia, Adélia Web et Adélia Cloud. Elle est basée sur une librairie Java de manipulation des documents OpenXML DOCX4J (http://www.docx4java.org/trac/docx4j).

La version Windows de la librairie est en fait implémentée sous la forme d'un proxy utilisant le client/serveur Adélia pour appeler directement la version Java via des services Middleware.

Attention, si vous créez un document vide sans spécifier de modèle, la toolbox essaie de localiser le fichier modèle "Normal.dotm" dans le CLASSPATH de l'application, et à défaut dans l'installation de l'utilisateur si l'application s'exécute sous Windows et qu'Office est installé. Si ce fichier n'est pas trouvé, un document vide est créé avec un paramétrage minimaliste et des styles en anglais.

Vous pouvez contourner ce problème en déployant votre version du fichier "Normal.dotm" dans le CLASSPATH de votre application (soit dans le répertoire JAVARUN du serveur de documentation, soit dans le répertoire WEB-INF\lib d'une application Web).

Configuration pour la version Java

Concerne les programmes Adélia Web, Adélia Cloud et Visual Adélia générés en Java. La DocxToolBx est nativement supportée dans cette configuration, aucune action n'est nécessaire pour la mettre en place.

Néanmoins, la librairie utilisée est relativement gourmande en mémoire, et pour manipuler de gros documents il est préférable d'augmenter l'espace mémoire disponible (paramètres -Xms et -Xmx, valeurs recommandées -Xms256m -Xmx1024m pour une JVM 32bits).

Configuration pour la version Windows

Concerne les programmes Visual Adélia générés en C. Dans cette configuration, le programme fait appel à un service Middleware utilisant le serveur logique *DOC_SERVER.

Vous devez configurer ce serveur logique dans votre configuration client. Le serveur physique doit pointer sur un démon Java.

Attention, si le traitement est déporté, les noms de fichier (fonctions d'ouverture et de sauvegarde) seront relatifs au serveur.

Utilisation

Cette section présente les principes de fonctionnement de la bibliothèque DocxToolBx, et les notions de handles (références d'objets) et de parties de document (DocumentPart).

Handle d'objet

Un "handle" est une référence à un objet manipulable par la toolbox. Il est représenté dans un programme Adélia par une valeur numérique de type NUM_BIN_4.

Un handle peut représenter le document lui-même, une partie de document, un paragraphe, etc.

Toutes les fonctions de manipulations de DocxToolBx prennent en paramètre le handle de l'objet auquel elles s'appliquent.

Une fois que l'on a fini de manipuler un objet, il est nécessaire de fermer explicitement le handle associé pour libérer les ressources via la fonction "UtiCloseHandle" (ou "DocClose" pour un handle de document).

Particularité : lorsque l'on ferme le handle d'un objet, les éventuels handles correspondant à des objets fils de celui-ci sont fermés automatiquement. Si je dispose d'un handle sur une table, ainsi que de handles sur les cellules de celle-ci, les handles de cellule seront implicitement libérés si je libère le handle de la table.

Ainsi, le fait de fermer un document libère l'ensemble des ressources associées.

Attention, la valeur numérique d'un handle est susceptible d'être réutilisée après la fermeture de celui-ci.

Par exemple, ouverture et fermeture d'un document :

APPELER_DLL 'DocxToolBx' 'DocOpen' nomFichier handleDocument rc

APPELER_DLL 'DocxToolBx' 'DocClose' handleDocument rc

Partie de document

Un document OpenXML est en fait constitué d'une arborescence de répertoires contenant des fichiers, notamment des fichiers XML décrivant les différents composants du document Word (texte du document, définition des styles, paramètres, etc.). Une partie de document est un fichier faisant partie de cette arborescence.

DocToolBx ne permet de manipuler directement que des parties de document pouvant contenir du texte (paragraphes, tables), telles que la partie principale du document et les sous-parties accessibles depuis celles-ci (en-têtes et pieds de pages, etc.). D'autres peuvent être manipulées de façon indirecte (styles, paramètres, ...).

De façon abusive, DocxToolBx référence comme "partie de document" tout conteneur pouvant contenir des paragraphes de texte. Par exemple, même si dans la terminologie une cellule de tableau n'est pas réellement une "partie de document", elle peut contenir des paragraphes et donc être analysée par des fonctions de gestion telles que "PartCountParagraphs".

La première opération d'un programme est de récupérer le handle de la partie principale du document, à partir de laquelle on pourra commencer à manipuler le document.

APPELER_DLL 'DocxToolBx' 'DocGetMainDocumentPart' handleDocument handleMainPart rc

…

Manipulation d'un document

Une fois que l'on dispose du handle de la partie principale du document, il est possible de manipuler celui-ci.

Le code suivant insère deux paragraphes en tête d'un document vierge. Le premier est créé en tête de la partie principale du document, le second après le premier :

APPELER_DLL 'DocxToolBx' 'DocCreate' *BLANK handleDocument rc

APPELER_DLL 'DocxToolBx' 'DocGetMainDocumentPart' handleDocument handleMainPart rc

APPELER_DLL 'DocxToolBx' 'ParagraphInsert' handleMainPart _DOCX_POS_FIRST 0 'Normal' 'Bonjour le monde' handlePara1 rc

APPELER_DLL 'DocxToolBx' 'ParagraphInsert' handleMainPart _DOCX_POS_AFTER handlePara1 'Normal' 'Au revoir' handlePara2 rc

APPELER_DLL 'DocxToolBx' 'UtiCloseHandle' handlePara2 rc

APPELER_DLL 'DocxToolBx' 'UtiCloseHandle' handlePara1 rc

APPELER_DLL 'DocxToolBx' 'UtiCloseHandle' handleMainPart rc

APPELER_DLL 'DocxToolBx' 'DocClose' handleDocument rc

Classes

Les fonctions de la DocxToolBx sont regroupées en classes définies par le périmètre d'application de la fonction.

Les différentes classes sont répertoriées dans le tableau ci-dessous :

Classe	Description
Doc	Cette classe fournit des fonctions de gestion d'un document.
Part	Cette classe fournit des fonctions de gestion des parties de document.
Paragraph	Cette classe fournit des fonctions de gestion des paragraphes de texte et des sous-éléments texte des dits paragraphes.
Table	Cette classe fournit des fonctions de gestion des tableaux.
Row	Cette classe fournit des fonctions de gestion des lignes de tableaux.
Cell	Cette classe fournit des fonctions de gestion des cellules de tableaux.
Bookmark	Cette classe fournit des fonctions de gestion des signets.
Field	Cette classe fournit des fonctions utilitaires de gestion des champs de fusion.
Image	Cette classe fournit des fonctions de gestion des images.
Section	Cette classe fournit des fonctions de gestion des sections de document.
Style	Cette classe fournit des fonctions de gestion des styles et des propriétés de texte.
Break	Cette classe fournit des fonctions de gestion des sauts de page et de section.
Uti	Cette classe fournit des fonctions utilitaires générales et des outils de débogage.