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) : toujoursfalse
(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'objetOooLayout
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
etENDBLOCK
ne sont pas prises en compte et la gestion des éléments répétables se fait de manière spécifiqueEn 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.
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 :
Insérer une image quelconque dans le fichier, au moyen du menu
,Cliquer sur le menu contextuel de l'image et choisir
,-
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.
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 :
peut donner le fichier :
6.6.3.4.2 Déclarer des éléments répétables dans des tableaux
Le template :
peut donner le fichier :
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é :
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.