PDF Generator

Un article de Typo3 CMS / Documentation Typo3 / Support Typo3.

EXT : PDF Generator

Clé d'extension : pdf_generator Copyright 2000-2002, je@hades.org, <je@hades.org>

Ce document est publié sous licence Open Content disponible sur http://www.opencontent.org/opl.shtml

Le contenu de ce document est relatif à TYPO3 -Gnu/GPL CMS/Framework disponible sur www.typo3.com

[modifier] Introduction

[modifier] A quoi ça sert ?

Si l'utilisateur désire imprimer un document servi par Typo3, on lui propose habituellement une page HTML contenant uniquement le contenu approprié de la page tandis que les images sont sur un fichier séparé. Cela fonctionne bien pour l'impression, mais si l'utilisateur veut sauvegarder la page pour l'archiver ou pour faire une impression hors ligne, il serait bien d'inclure les images dans un document unique. Le PDF d'adobe Acrobat offre un format approprié de fichier dans ce but qui est largement supporté et indépendant de l'os.

[modifier] Comment ça marche ?

L'extension génère une page HTML 'compatible-imprimante'. Cette page passe au travers de HTMLDOC pour générer un fichier PDF. Le fichier PDF est alors offert à l'utilisateur tout en étant mise en cache par le méchanisme de mise en cache habituel de typo3. La page PDF peux faire office de lien à partir du Template Typoscript utilisant le paramètre stdWrap.postUserFunc. Soit les nom de fichiers dynamiques (c.a.d Index.php?id=12&type=123) soit les noms de fichiers statiques (<alias>.PDF of 12.pdf) sont supportés.

[modifier] Qu'est-ce que HTMLDOC ?

HTMLDOC est un logiciel open-source de Easy Software Products. Entre autres, il a la capacité de modeler les pages HTML en tant que fichiers PDF. HTMLDOC supporte l'HTML standard bien que le css ne soit, pour le moment, pas supporté. HTMLDOC est disponible pour les systèmes compatibles Windows et Linux/Unix.

[modifier] Contenu supporté

Théoriquement l'extension PDF_generator supporte tout les contenus pouvant être modelés en HTML (c.a.d All.). Malgrès cela, comme la conversion d'HTML en PDF est effectué en utilisant HTMLDOC, tout ne sera pas automatiquement bien rendu en PDF.

[modifier] Niveau HTML supporté

HTMLDOC supporte actuellement la plupart des éléments HTML 3.2 et quelques éléments HTML 4.0. HTMLDOC ne supporte pas les tables, les attributs, les feuilles de style ou le scripting HTML 4.0. Les fonctionnalitées HTML 4.0 seront fournies en HTMLDOC 1.9, ce qui est prévu pour plus tard, cette année 2003. Notez, s'il vous plait, qu'il n'y a pas d'estimation de temps pour la sortie.

[modifier] Polices supportées

HTMLDOC est capable de générer les types 1 de polices suivantes dans les fichiers PDF générés. HTMLDOC ne permet pas, pour le moment, l'encastrement de polices arbitraires spécifiées par l'élément de POLICE HTML.

• Courier
• Helvetica
• Symbol
• Times

Chaque police encastrée ajoute environ 43k de données aux fichiers PDF. Le set complet de polices de type 1 ajoutent 555k aux fichiers PDF.

[modifier] Liens vers des pages web et adresses e-mail.

Les liens vers d'autres pages et adresses e-mail dans les fichiers HTML seront aussi gardées dans les fichiers HTML.

[modifier] Pré-requis

Cette extension appelle un autre programme via popen() ou exec() (configurable). Cela ne fonctionnera pas si votre serveur fonctionne en mode sûr (safe).

[modifier] Demo

Une démo fonctionnel peux être trouvée ici : http://test.drachenorden.de.

[modifier] Manuel de l'utilisateur

L'utilisateur peut inclure un lien vers http://www.adobe.com/products/acrobat/readstep.html quelque part sur la page pour permettre aux utilisateurs de télécharger free acrobat reader s'ils ne l'ont pas déjà. Du point de vue utilisateur, pas grand chose de plus n'est à faire. Simplement cliquer sur le lien vers le fichier PDF. Le setup déterminera que soit le fichier sera ouvert dans une fenêtre du navigateur (en ligne) ou dans une fenêtre externe d'adobe acrobat (marche sur l'explorateur internet, pas sur Netscape. Netscape ouvrira toujours le PDF en ligne).

[modifier] Administration

[modifier] Installation de HTMLDOC

[modifier] Installation de HTMLDOC avec un paquet préconfiguré pour Linux

Si votre serveur fonctionne sous Linux, vous devriez être capable d'utiliser mon paquet préconfiguré. Téléchargez le simplement ici http://www.jens-ellerbrock.de/T3X_htmldoc_linux-0_0_0-z.t3x et installez le grâce au manager d'Extension. Laissez le paramétre htmldoc_path vide si vous l'utilisez. Ce paquet est en version 1.8.24 et n'est offert que par courtoisie, ne m'en voulez pas s'il ne marche pas sur votre serveur.

[modifier] Monter HTMLDOC à partir de la source

Premièrement vous devez installer HTMLDOC sur votre serveur. Allez sur http://www.htmldoc.org et téléchargez la source HTMLDOC. Vous pouvez aussi utiliser CVS pour obtenir la dernière version (recommandé). Si vous récuperez la 1.8.23 vous devriez changer ALIGN_TOP en ALIGN_BOTTOM à la ligne 868 de htmldoc/htmllib.cxx. Voyez 'Problèmes connus' pour les détails. (cette phrase est probablement obsolète vu que la version 1.8.24 est sortie). Maintenant compillez et installez.

[modifier] Installation de HTMLDOC sur un serveur sur lequel vous avez un accès telnet/ssh.

Référez vous, s'il vous plait, aux instructions de compilation et installation fournis avec HTMLDOC (./configure; make; make install pour Linux/posix ou simplement compiler avec Visual Studio sur Windows).

[modifier] Installation de HTMLDOC sur un serveur sur lequel vous n'avez qu'un accès ftp.

Vous n'avez pas de chance , à moins d'avoir accès à une machine similaire. Voici ce que j'ai fait pour que cela marche pour mon fournisseur utilisant Linux :
1.Trouvez le chemin absolu du web root (voir phpinfo () par exemple. Dans mon cas /www/htdocs/something)
2.Configurez en utilisant ce chemin apposé avec 'htmldoc' (configure --prefix=<web root>/htmldoc)
3.Compilez (make; make install)
4.Maintenant téléchargez le directory <web root>/htmldoc vers votre serveur de façon a ce qu'il soit écrit dans le même directory absolu d'où il vient. (Vous pouvez effacer en premier les pages de documentation et d'homme)
5.N'oubliez pas de chmod le binaire htmldoc (qui se trouvera dans <web root>/htmldoc/bin/htmldoc) en executable.

[modifier] Verifier que HTMDOC marche bien

1.Générez un fichier dummy.html :

 <html>
 <head>
 <title>Test Title</title>
 <body>Test Body</body>
 </html>

2.Appelez HTMLDOC: <path>/htmldoc --webpage -f dummy.pdf dummy.html Si vous n'avez qu'un accès ftp, utilisez le fichier dummy.php suivant. Vérifiez que le webserver_user dispose d'un accès en écriture au fichier dans lequel vous l'essayez. (/typo3temp devrait faire l'affaire)

<?php
 system('<path>/htmldoc --webpage -f dummy.pdf dummy.html');
?>

3.Verifiez que vous avez créés un fichier dummy.pdf
4.N'oubliez pas d'effacer vos fichiers.

[modifier] Mise à jour .htaccess

Vous devrez mettre à jour votre .htaccess si vous voulez que vos liens pour vos PDF soient statiques (c.a.d <alias.pdf>). Ce changement est necessaire pour faire suivre toutes les requêtes aux fichiers /<...>.PDF à l'index.php de typo3.

ErrorDocument 404 /error.html 
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule   ^typo3$  /typo3/index_re.php
RewriteRule   ^[^/]*\.html$  index.php
RewriteRule   ^[^/]*\.pdf$  index.php

[modifier] Installation de l'extension

1.Téléchargez la nouvelle extension en utilisant le manager d'extension/repository
2.Mettez à jour votre .htaccess si vous voulez utiliser des noms de fichiers PDF statiques.
3.Installez l'extension en utilisant le manager d'extension
4.Configurez l'extension

[modifier] Options disponibles

[modifier] Chemin htmldoc

Vous devriez pouvoir indiquer ici le chemin absolu (ou relatif au root typo3) de HTMLDOC (incluant le binaire). Des paramètres additionnels aux commandes htmldoc peuvent être ajoutées via les paramètres globaux ou sur une base par-template via le Constant Editor.

Note : Vous pouvez changer ce paramètre en 'export LC_TIME=”<your locale>”; <path to htmldoc>' si vous voulez placer un local spécifique pour les commandes HTMLDOC. Cela peux être souhaitable si vous voulez mettre le format de $DATE string dans des titres de bas de page ou des en-têtes HTMLDOC.

[modifier] Paramètres globaux htmldoc

Ici vous pouvez configurer les paramètres qui seront apposés à la commande htmldoc. Par défaut “--t pdf12” qui demandera à htmldoc de générer un fichier PDF Adobe ver 1.2. Le paramètre “--webpage” necessaire est ajouté en interne.

[modifier] Paramètres apposés htmldoc

Ici vous pouvez configurer les paramètres qui s'apposeront à la fin de la ligne de commande htmldoc. Par défaut il s'agit de “2> typo3temp/htmldoc.log” qui notera le résultat de la commande htmldoc dans typo3temp/htmldoc.log. Vous pourriez vouloir le changer en “2> /dev/null” sur Linux/Unix.

[modifier] SimulateStaticPdf

Ce paramètre définira que le lien au fichier PDF sera soit statique (c.a.d. <alias>.pdf) ou dynamique (index.php?id=12&type=123). Si vous permettez ceci vous devrez mettre à jour votre .htaccess.

[modifier] Neutraliser la compression gzip

Si ce paramètre est réglé et que vous avez la compression gzip actif pour Frontend ( [FE][compressionLevel] dans l'outil d'installation) le PDF généré ne sera pas pris en main par la compression gzip. Il est hautement recommandé de laisser ce paramètre par défaut (en marche) étant donné que les fichiers PDF inclus leur propre compression et vous ne gagneriez qu'un gain additionnel de compression minime. De plus vous pourriez avoir des problèmes avec les explorateurs passant le flux à Acrobat sans le décompresser (p.e.. Netscape 4.08).

[modifier] TypeID

Ce paramètre définie le TypeID utilisé pour l'extension. Normalement vous ne devriez pas avoir besoin de le changer.

[modifier] Ajouter un lien dans votre Template Typoscript en utilisant MakePdfLink.

Pour ajouter un lien dans une page PDF vous pouvez envelopper tout élément contenu dans un lien utilisant stdwrap.postUserFunc. Le code suivant donne quelques exemple :

[...]
100 = IMAGE
100.file = fileadmin/pdf_link.gif
100.stdWrap.postUserFunc = tx_pdfgenerator->makePdfLink
[...]

[...]
110 = TEXT
110.value = printable version
110.postUserFunc = tx_pdfgenerator->makePdfLink
100.postUserFunc.target = _blank
[...]

[modifier] Ajouter un lien dans votre Template Typoscript en utilisant openPdfLink.

Alternativement vous pouvez aussi utiliser la fonction tx_pdfgenerator->openPdfLink qui générera le tag d'ouverture du lien. Vous devrez générer le tag de fermeture </a> vous même. Exemple :

page.36= USER_INT
page.36.userFunc = tx_pdfgenerator->openPdfLink

page.37=TEXT
page.37.value = Link to PDF

page.38=HTML
page.38.value = </a>

Pour plus d'exemple voir la documentation pour l'extension make_printlink.

[modifier] Customizer la page PDF via le Constant Editor

Vous pouvez configurer plusieurs options sur une base de pre-template avec le Constant Editor. Ces options résulteront soit en des paramètres spéciaux apposées à la commande htmldoc ou en commentaires html spéciaux contrôlant aussi le comportement de htmldoc. Voir la documentation de htmldoc (http://www.easysw.com/htmldoc/htmldoc.html#CMDREF) pour les détails. Les paramètres suivant peuvent être configurés :

[modifier] Customization de page PDF via Typoscript

Le rendu du PDF est basé sur un Template très simple :

pdf_generator = PAGE
pdf_generator {
 typeNum = {$extension.pdf_generator.typeNum}
 config.pageGenScript = EXT:pdf_generator/gen_pdf.php
 config.admPanel = 0

 50 = CONTENT
 50 < styles.content.get
}

Vous pouvez aisément mettre à jour l'objet du pdf_generator pour contenir des informations additionnelles ou des éléments de contenu sur chaque page PDF. Une utilisation particulièrement intéressante est d'ajouter des commentaires spéciaux HTML pour contrôler le comportement de HTMLDOC. Voir la documentation htmldoc (sur http://www.easysw.com/htmldoc/htmldoc.html#HTMLREF) pour les détails. Quelques uns de ces paramètres (les commentaires de l'en-tête et de bas de page) seront générés automatiquement avec les paramètres configurés via le Constant Editor (voir le chapitre précédent).

Référence pour tx_pdfgenerator->makePdfLink and tx_pdfgenerator->openPdfLink

Content-Type: application/pdf
Content-Disposition: inline

Content-Type: application/pdf
Content-Disposition: attachment

Content-Type: application/octet-stream
Content-Disposition: attachment

[modifier] Configuration

L'extension consiste en deux classes php et un script php.

[modifier] Gen_pdf.pdh

Ceci est le script principal qui génére le fichier PDF. Cela est fait en appelant le script pagegen originel et en convertissant ensuite l'HTML en PDF en utilisant le programme HTMLDOC. Le PDF généré est alors retourné à typo3 pour être mis en cache pour des requêtes ultérieur. Ce script 'fixe' aussi les soucis suivant avec l'HTML généré : 1.Parfois le RTE génére des tags < P > à l'interieur des tags < pre >. Il sont retirés.
2.Lors de l'utilisation de listes buletted la sortie est théoriquement correct mais sont d'apparences plutôt laid (les points sont un peu au dessus de la ligne du texte). En changeant l'alignement des images vers la gauche elles sont visuellement bien mieux.

class.tx_pdfgenerator.php
Cette classe contiens la fonction makePdfLink utilisée pour générer le lien vers le fichier PDF. Il prend l'id de page actuelle et tout les paramètres GET attachés et créé un nouveau lien utilisant ces variables. Si l'option simulateStaticPdf est configuré ce lien sera nomé <alias>.pdf?<paramètres additionnels>. SI non, ils seront appelés index.php?id=<id>&type=<pdf_type>&<additional parameters>.

class.ux_tslib_fe.php
Cette classe surpasse la classe du noyau tslib_fe. Deux fonctions sont surpassées :

checkAlternativeldMethods
Ce changement vérifiera la fin d'un fichier '.pdf' et générera automatiquement la page Type pour la page PDF (defaut:123)

processOutput
Ce changement vérifiera si un fichier PDF est actuellement généré et ajoutera alors les en-tête supplémentaire nécessaires. Ceci inclus
- Content-Type et Content-Disposition voir la référence pour postUserFunc = tx_pdfgenerator->makePdfLink
- Cache-control : privé, connexion : Keep-Alive Ceci est necessaire pour Internet Explorer pour permettre de télécharger le fichier et éviter qu'IE fasse la requête deux fois.
- Content-Lenght: <calculated lenght> Ceci est aussi nécessaire pour éviter la nécessité d'avoir à faire un rafraichissement sur IE lorsque l'on travail sur de petits fichiers PDF. En supplément la compression gzip est éteinte ici en configurant le ['FE']['compressionlevel'] en .

[modifier] Problèmes connus

HTMLDOC 1.8.23 à un bug qui aligne les images en haut au lien d'en bas par défaut. Cela fait mal apparaître certaines choses. Pour réparer ceci, soit récuperer la version actuelle via cvs ou changer ALIGN_TOP en ALIGN_BOTTOM à la ligne 868 de htmldoc/htmllib.cxx. HTMLDOC ne supporte pas le css pour le moment.

[modifier] FAQ

Q : Je vois des erreurs commencant avec :

ySQL server has gone away
Warning: Cannot add header information - headers already sent by (output started at /local/typo3/httpd/htdocs/tslib/class.tslib_fe.php:1312)

A : Ceci peux arriver quand de grands fichiers pdf sont générés. Le document MySql recommande de configurer la valeur max_allowed_packet=# en valeur plus grande. Q : Le PDF généré ne contient pas umlauts et les caractères spéciaux.
A : Ce problème arrive si HTMLDOC ne peux pas trouver ses fichiers de police. Soyez sur d'avoir installé htmldoc correctement. Vous pouvez avoir besoin de configurer l'option HTMLDOC - -datadir.

[modifier] Choses à faire

Ajouter un layer transformant (une partie du) le css en HTML 'regulier'. Cela ferait enfin apparaître le document résultant de façon plus joli.

[modifier] Liste des Modifications

Version Initiale
- 0.1.0 : petits changements, 'correction' pour les listes bulleted
- 1.0.0 : Petites corrections, corrections de la documentation
- 1.1.0 : meilleur support des liens
- 1.2.0 : Support pour la transmission des paramètres POST en tant que paramètres GET. Ceci est utile si vous désirez générer des contenus de page, pour les recherches de résultat par exemple.
- 1.3.0 : Correction d'un bug lorsque le sumulateStaticPdf était configuré et aucun alias n'était défini pour la page.
- 1.4.0 : Correction de la prise en main des paramètres de zone. Necessaire pour beaucoup d'extension frontend.
- 2.0.0 : Capacité de controler beaucoup de fonctionnalitée htmldocs comme les en-tête de page, bas de page etc. sur une base de template via le Constant Editor. Maintenant vous pouvez aussi retirer du contenu spécifique de fichier html à condition qu'il soit passé en htmldoc. Les pages contenant un commentaire d'utilisateur FE ne sera pas mis en cache, que le nom d'utilisateur FE puisse être mis à jour dans le pdf.
- 2.1.0 : Nouveaux paramètres makePdfLink. Bien meilleur prise en main des erreurs.
- 2.2.0 : Ajout de prise en main d'objets USER_INT. Plusieurs petites corrections de bug. Supporte pleinement typo3 3.6.x, ajout du paramètre no_blur.
- 2.3.0 : Le lien vers le PDF est maintenant généré en tant qu'objet non mis en cache USER_INT par défaut, correction pour les paramètres multidimensionnels.
- 2.4.0 : Possibilité d'éteindre la compression additionnelle gzip pour le PDF généré.
- 2.5.0 : Correction de l'option no_link
- 2.5.1 : Ajout du paramètre no_popen.
- 3.0.0 : Utilise maintenant des hameçons de rappel au lieu de classe supérieur lorsque utilisé avec typo3 3.7 et au dessus – S'il vous plait, e-mailez moi si vous rencontrez quelque problème que ce soit.
- 3.0.2 : Echange & avec & dans le lien généré pour complaisance xhtml.