6.6 Vue OpenDocument Text

Une vue openDocument text permet de générer une représentation bureautique du document. Cette représentation est au format odt, et peut être convertie en pdf, ou autre format bureautique, au moyen du moteur de transformation.

Étant donné que cette représentation est binaire, il y a de nombreuses différences entre les vues openDocument text et les représentations html.

Il est à noter que les vues openDocument text ne sont utilisables que pour la consultation.

Une vue openDocument text est composée de :

  • un fichier de template (au format odt), définissant la structure,
  • une méthode (appelée contrôleur de vue) du document à représenter, définissant les valeurs.
    Cette méthode peut également être omise. Dans ce cas, dynacase fera appel au contrôleur de vue par défaut.

La syntaxe de la zone documentaire d'une vue openDocument text doit obligatoirement comporter l'option binaire (option B).

Exemple :

MY_APP:my_Document.odt:B

Dans cet exemple le fichier MY_APP/Layout/my_Document.odt sera utilisé comme template.

6.6.1 Référence d'un template à partir d'un paramètre de famille

Si la famille possède un paramètre de type file. Celui-ci peut être utilisé comme template. Dans ce cas, la syntaxe de la zone est de la forme :

THIS:MY_ARGFILE:B

Dans cet exemple MY_ARGFILE peut être soit un paramètre de la famille, soit un attribut du document.

Si le paramètre ou l'attribut est un attribut fichier inclus dans un tableau, il est nécessaire d'ajouter l'index pour préciser le template :

THIS:MY_ARGFILES[2]:B

Dans cet exemple, le template est la troisième valeur de l'attribut multiple MY_ARGFILES.

6.6.2 Le contrôleur de vue

Pour qu'une méthode du document soit utilisable en tant que contrôleur d'une vue, il est nécessaire de lui ajouter la phpDoc @templateController afin de se prémunir d'une éventuelle exécution arbitraire de code.

Les paramètres reçus par la méthode sont au nombre de 3 :

  • $target (string) : toujours "ooo" (ne sert que pour les vues non odt),
  • $ulink (booléen) : toujours false (ne sert que pour les vues non odt),
  • $abstract (booléen) : indique s'il faut générer uniquement les attributs de la fiche résumé (false par défaut).

Par convention :

  • le fichier de template porte l'extension odt,
  • son nom (en minuscule) détermine le nom de la vue,
  • la méthode associée doit porter le même nom (la casse du nom de la méthode n'est pas prise en compte).
    L'objet OooLayout est accessible au moyen de la propriété lay de l'objet courant ($this->lay).

6.6.2.1 Contrôleur par défaut

En l'absence de méthode correspondant à la vue, le contrôleur par défaut est appelé. Ce contrôleur est Doc::viewDefaultCard.

6.6.2.2 Utilisation des valeurs du document en consultation

Le contrôleur par défaut fait automatiquement appel aux méthodes Doc::viewAttr et Doc::viewProp. Elles initialisent les clés suivantes :

  • viewAttr va créer :
    • L_ATTRID pour chaque attribut : le libellé (traduit) de l'attribut,
    • V_ATTRID pour chaque attribut : la valeur (au format html) de l'attribut,
    • S_ATTRID pour chaque attribut : true si l'attribut est vide, false sinon
  • viewProp va créer :
    • ATTRID pour chaque attribut : la valeur brute de l'attribut,
    • PROPID pour chaque propriété : la valeur brute de la propriété,
    • V_TITLE une ancre vers le document lui-même avec son titre.

Note : Toutes ces clefs sont en majuscules.

Lors de l'utilisation d'un contrôleur personnalisé, il est possible d'appeler ces méthodes afin de générer les clés correspondantes. Il est également possible de définir d'autres clés en utilisant les différentes méthodes de la classe OooLayout.

Attention : Toutes ces clés respectent les visibilités : si la visibilité d'un attribut est H pour un utilisateur, les clés L_ATTRID et V_ATTRID sont des chaînes vides. S_ATTRID, pour sa part, n'est pas affecté par les visibilités.

6.6.3 Spécificités du système de template pour les vues openDocument text

Bien que la syntaxe soit très proche de celle des vues textuelles, il y a quelques différences à prendre en compte.

Ces différences sont liées à la structuration des documents odt, qui sont en fait des documents xml, et dont la structure doit rester valide.

Parmi ces différences, il y a notamment :

  • les balises ZONE ne sont pas prises en compte,

  • les balises BLOCK et ENDBLOCK ne sont pas prises en compte et la gestion des éléments répétables se fait de manière spécifique

    En effet, la notion de répétable existe au sein des documents odt sous la forme des

    • listes à puce,
    • tableaux.
  • La gestion des images se fait de manière spécifique.

6.6.3.1 Placer une clé dans le template odt

Les clés utilisent la même notation que dans les templates non odt : [KEY].

Bien que cela ne soit pas obligatoire, il est recommandé d'utiliser des champs utilisateur dont :

  • le nom est libre et n'est pas utilisé par le système de templates,
  • la valeur est la clé souhaitée,
  • le format est text (vous pouvez utilisez d'autres formats, mais dans ce cas, à vous de savoir comment sera rendue la valeur générée).

L'utilisation de champs plutôt que du texte libre présente plusieurs avantages :

  • cela simplifie la modification ultérieure par des utilisateurs,
  • cela permet de recenser l'ensemble des attributs, y compris ceux qui ne sont pas utilisés,
  • le remplacement étant fait au niveau du xml sous-jacent, si l'on n'utilise pas les champs, il est possible que des balises viennent couper la clé. Par exemple, [MA_KEY] peut en fait avoir été stocké sous la forme [<span>MA</span>_KEY] qui n'est alors pas reconnue par le moteur de template.
champ utilisateur

Figure 66. champ utilisateur

6.6.3.2 Placer une clé dans les propriétés du template odt

Il est également possible d'utiliser les clés dans les propriétés du fichier, où elles sont aussi remplacées.

6.6.3.3 Images

Pour incorporer des images issues d'un attribut de type image, il faut insérer dans le template une image quelconque qui sert de placeholder et qui est ensuite remplacée par l'image issue de l'attribut du document lors de la composition du template.

Pour cela, il faut :

  1. Insérer une image quelconque dans le fichier, au moyen du menu Insertion Image À partir d'un fichier,

  2. Cliquer sur le menu contextuel de l'image et choisir image,

  3. Renseigner les clés (qui référencent la valeur et le label de l'attribut de type image) dans l'onglet [Options], champ nom.

    nom de l'image

    Figure 67. nom de l'image

En ce qui concerne la taille de l'image, la largeur est conservée. La hauteur est calculée en fonction du ratio de l'image.

Attention : chaque image « placeholder » doit être insérée de cette façon, et il ne faut surtout pas faire de copier-coller d'une image. En effet, en cas de copier-coller, les 2 images font référence en interne à la même image, même en définissant des noms différents.

6.6.3.4 Répétables

La gestion des éléments multiples est intrinsèque à la structure d'un fichier odt : les listes et tableaux sont multiples par nature. Aussi, utiliser la clé d'un attribut multiple dans une liste ou un tableau va automatiquement insérer le nombre d'éléments nécessaires.

6.6.3.4.1 Déclarer des éléments répétables dans des listes

Le template :

template

Figure 68. template

peut donner le fichier :

résultat

Figure 69. résultat

6.6.3.4.2 Déclarer des éléments répétables dans des tableaux

Le template :

template

Figure 70. template

peut donner le fichier :

résultat

Figure 71. résultat

6.6.3.5 Conditions

Les conditions ([IF] / [ENDIF]) sont utilisables, à condition de respecter la structure du document (Un fichier ODT étant, en interne, un XML, ce fichier doit conserver son intégrité).

Aussi, les balises ouvrante et fermante doivent être au même niveau. Par exemple, on ne peut pas mettre un IF au milieu d'un tableau et le ENDIF à l'extérieur du tableau : le IF et le ENDIF doivent être dans la même cellule du tableau. Il est possible de les utiliser dans le même paragraphe ou entre plusieurs paragraphes de même niveau.

En cas d'erreur de structure, un message d'erreur apparaît lors de la consultation du document généré :

Erreur de structure

Figure 72. Erreur de structure

6.6.3.6 attributs htmltext

Le type htmltext implique des restrictions d'usage : La valeur de l'attribut est filtrée lors de l'incorporation dans un fichier openDocument. Seules certaines balises HTML sont supportées. Les balises non supportées sont ignorées et leur contenu n'est pas affiché.

Une clef correspondant à un attribut htmltext doit être placée seule dans le paragraphe, et ne doit pas contenir de texte autour.

6.6.3.7 Limitations

6.6.3.7.1 Limitation pour les attributs de type Htmltext

  • Les couleurs, police, taille de police ne sont pas prises en compte,
  • pour la mise en forme, seuls les mises en gras, souligné et en italique sont supportées,
  • seuls les titres de niveau 1 à 4 sont pris en compte,
  • lors de l'utilisation dans une liste, les tableaux ne sont pas interprétés et sont traités comme du texte brut,
  • un attribut htmltext ne peut pas être utilisé dans les entêtes et pied de pages,
  • un attribut htmltext ne peut pas être utilisé dans les propriétés du document,
  • les styles (css) ne sont pas pris en compte,

  • les imbrications de paragraphes, exemple :

    <div>Texte ext 1<div>Texte int</div>texte ext 2</div>

    ne sont pas supportées. L'exemple précédent provoquera une erreur d'affichage de fichier openDocument.

6.6.3.7.2 Limitations pour les répétables

  • les répétables ne sont pas gérés dans les entêtes et pied de pages,
  • les répétables ne sont pas gérés dans les propriétés du document,
  • les mots-clefs BLOCK/ENDBLOCK ne sont pas gérés,
  • les listes ne peuvent pas avoir plusieurs niveaux d'imbrication.

6.6.3.7.3 Limitations pour les relations

  • Les relations de document sont partiellement gérées : seul le titre du document est affiché (sans lien).

6.6.3.7.4 Autres limitations

  • les zones (ZONE) ne sont pas gérés,
  • les attributs de type fichier, couleur ne sont pas gérés.

6.6.4 Utilisation avancée

L'utilisation d'un contrôleur spécifique ainsi que les manipulations avancées sont détaillées dans la partie avancée sur les vues OpenDocument Text.

Source : representations/ooo_layout.md Dynacase Platform 3.2 | Core Manuel de référence, version 3.2 édition 13, © Anakeen Labs <labs@anakeen.com>
×
Publié sous licence CC (http://creativecommons.org/licenses/by-nc-sa/2.0/fr/) par Anakeen [www.anakeen.com]
Attribution Vous devez créditer l'Oeuvre, intégrer un lien vers la licence et indiquer si des modifications ont été effectuées à l'Oeuvre. Vous devez indiquer ces informations par tous les moyens possibles mais vous ne pouvez pas suggérer que l'Offrant vous soutient ou soutient la façon dont vous avez utilisé son Oeuvre.
Pas d’Utilisation Commerciale Vous n'êtes pas autoriser à faire un usage commercial de cette Oeuvre, tout ou partie du matériel la composant.
Partage dans les Mêmes Conditions Dans le cas où vous effectuez un remix, que vous transformez, ou créez à partir du matériel composant l'Oeuvre originale, vous devez diffuser l'Oeuvre modifiée dans les même conditions, c'est à dire avec la même licence avec laquelle l'Oeuvre originale a été diffusée.