Avertissement de sécurité
Présentation
Le plugin génère des fichiers PDF à partir d’un squelette écrit au format HTML 4.
Il vous permet donc de créer un PDF réellement sur mesure sans d’autre compétence que de connaître le HTML 4 et CSS.
Que ce soit un squelette pour vos articles, vos rubriques, votre plan de site ou d’autres éléments plus spécifiques, spiPDF génère le contenu en PDF.
Plusieurs librairies, plusieurs possibilités
Le plugin [1] se base - au choix de l’utilisateur - sur plusieurs classes de génération de PDF à partir de HTML :
Par défaut, le plugin utilise mPDF. Vous verrez plus bas dans cet article comment utilisez un autre librairie à la place.
Chacune des classes à ses avantages et ses inconvénients. On notera par exemple que mPDF gére le positionnement flottant (“float”) des éléments ce qui est indéniablement un plus pour de la génération d’article contenant des images.
N’hésitez pas à donner votre avis et vos expériences sur les différentes librairies dans les commentaires de l’article.
Pré-requis
A partir de la version v2.0.2 (compatible SPIP 4)
il est nécessaire d’avoir PHP 8.0 ou plus (pour la compatibilité avec les librairies embarquées)
Pour les versions v1.2.0 et précédentes, le plugin requiert :
- PHP 5
- d’installer manuellement dans le répertoire /lib/ une librairie (voir chapitre précédent)
Téléchargement et installation des librairies requises
A partir de la version v2.0.2 (compatible SPIP 4)
Il n’est plus nécessaire d’intégrer les librairies d’une facon externe, elles sont intégrées dans le répertoire vendor
du plugin
Dans les anciennes versions
Vous devez les télécharger sur leurs sites respectifs et les décompresser dans un répertoire lib/ à la racine de votre site ou dans un répertoire lib/ dans le répertoire du plugin :
Les dossiers doivent se nommer exactement respectivement mpdf, html2pdf ou dompdf (sans majuscules).
Rendu obtenu avec les différentes librairies
Après un test simple de chacune des librairies, voici les résultats que j’ai obtenu :
- mPDF version 6.0 du 01/03/2015 : bon rendu général
- HTML2PDF version 4.03 du 27/05/2011 : rendu du texte correct, problème avec certains positionnements d’images
- domPDF version 0.6.0 beta2 de 02/2011 : problème d’encodage des caractères
Utilisation
Une étape supplémentaire suffit pour commencer à utiliser le plugin.
Ajoutez un lien hypertexte vers le squelette du plugin, typiquement dans votre squelette article.html. Voici à quoi doit ressembler ce lien pour un article :
[<a href="[(#URL_PAGE{spipdf}
|parametre_url{spipdf,spipdf_article}
|parametre_url{id_article,#ID_ARTICLE}
|parametre_url{nom_fichier,article_#ID_ARTICLE})]">
télécharger l'article au format PDF</a>]
Mise en page personnalisée
C’est tout l’intérêt du plugin : permettre une mise en page personnalisée sans connaître le PHP.
Pour obtenir un PDF sur mesure, vous pouvez :
- soit modifier le squelette qui se trouve dans le répertoire du plugin : spipdf_article.html
- soir créer votre propre squelette et modifier la balise #URL_PAGE pour qu’elle appelle bien votre squelette à la place de spipdf_article (remplacer spipdf_article par le nom de votre squelette)
Par exemple, vous avez dans votre répertoire squelette, un squelette plan_site_pdf.html que vous souhaitez utiliser pour générer une sortie PDF de votre plan de site.
Il vous suffira d’appeler ce squelette/PDF de la façon suivante :
[<a href="[(#URL_PAGE{spipdf}
|parametre_url{spipdf,plan_site_pdf}
|parametre_url{nom_fichier,plan_site_pdf})]">
télécharger le plan de site au format PDF</a>]
Ce qui donnera l’URL : http://monsite.tld/spip.php?page=spipdf&spipdf=plan_site_pdf.html
Liens vers des articles SPIP dans le PDF
Si vous utilisez des liens internes du type [->art2] dans vos articles,
il est nécessaire d’utiliser le filtre abs_url sur les balises
DESCRIPTIF, CHAPO, TEXTE, PS et NOTES pour que les liens dans votre PDF pointent bien sur votre site.
Nom de fichier personnalisé
Par défaut, les fichiers PDF se nommeront document.pdf.
Si vous souhaitez préciser un nom particulier pour votre fichier, vous devrez préciser, comme dans les exemples ci-dessus, le paramètre nom_fichier dans la balise #URL_PAGE.
Choix de la librairie de génération
Pour sélectionner l’une ou l’autre des librairies supportées, vous devez changer la valeur de l’attribut lib_pdf dans la balise
Les valeurs possibles sont mpdf / html2pdf / dompdf
Vous pouvez utiliser une librairie différente par type de squelette.
Format, orientation des pages et autres subtilités
Chaque librairies autorisent la mise en page directement depuis le squelette HTML mais pas de la même façon.
Pour plus de simplicité, le format (A4, A5, Letter...) est cependant gérés par le plugin depuis cette balise page pour toutes les librairies.
Pour le reste (marge, bordure, header, footer...) chaque outils à son propre fonctionnement mais tout ceci sans toucher au code du plugin.
mPDF
La librairie utilise le sélecteur CSS @page. Ceci est également explicité dans la documentation (en anglais) de la bibliothèque.
HTML2PDF
La librairie utilise les paramètres précisés via la balise
Vous trouverez plus d’informations sur le wiki de la librairie et plus particulièrement sur la section concernant la fameuse balise page.
dompdf
Le support étant expérimental, je n’ai pas plus d’informations pour l’instant à fournir. A voir sur le site de cette librairie.
Contraintes et bugs connus
Certaines balises HTML peuvent ne pas être gérées par le plugin
C’est notamment le cas de balises qui ne sont pas gérées par la librairie que vous avez choisi d’utiliser. Dans ce cas, vous devriez obtenir une erreur à la génération du PDF ou un affichage dégradé. Dans cette situation, 2 solutions :
- le HTML qui pose problème est dans votre squelette ? et bien... trouvez autre chose en attendant mieux (mais signalez-le quand même dans les commentaires)
- le HTML est généré par SPIP ? Signalez-le dans les commentaires pour une mise à jour du plugin
Certaines balises CSS ne sont pas gérées par le plugin
Bien entendu, dans ce cas, l’affichage au format PDF sera différent de l’affichage au format HTML. On notera par exemple que le positionnement float est géré en partie par mPDF et pas du tout par HTML2PDF.
Vous devrez palier à certaines contraintes de positionnement en utilisant des tableaux imbriqués (snif !)
Encore une fois, toutes ces contraintes sont explicitées sur les site et les forums des librairies respectives.
Changer l’encodage utilisé pour la génération de PDF
Le plugin génère les PDF en UTF-8. Certaines personnes ont rencontré des problèmes de génération des contenus dans cet encodage.
Pour changer ce comportement, et utiliser ISO-8859-15, vous devez changer la constante suivante dans votre fichier d’options :
define('SPIPDF_CHARSET', 'ISO-8859-15');
Aide au développement
Pour pré-visualiser la page au lieu de générer le PDF, vous pouvez ajouter le paramètre debug_spipdf à l’URL
Par exemple : spip.php?page=spipdf&spipdf=spipdf_article&id_article=1249&nom_fichier=article-1249&debug_spipdf
Discussions par date d’activité
2 discussions
Bonjour,
merci pour ce super plugin. J’ai cependant un petit souci : lors de la création du pdf, les styles de mon fichier perso.css ne sont pour la plupart pas appliqués, et je n’arrive pas à comprendre pourquoi.
Je précise que je n’ai apporté aucune modification aux fichiers du plugin ni au fichier de mon squelette (Escal).
Quelqu’un peut-il m’aider ? merci !
Bonjour,
Est-ce qu’il y a bien une ligne qui appelle ta feuille de style en haut de ton fichier squelettexx_pdf.html ?
dd
Bonjour,
J’utilise la dernière version du plugin sur un SPIP 4.2
C’est tout à fait pratique.
Pour améliorer la mise en page je voudrais que le PDF généré tienne compte des sauts de pages indiqués avec le raccourci SPIP :
----
et dans ma feuille de style j’ai
hr.spip { page-break-before:always; }
Cela fonctionne lorsque je lance une impression via mon navigateur (fichier > imprimer)
Mais pas avec mpdf qui ne semble pas en tenir compte.
Et sinon ce paragraphe spiPDF : générer des contenus sur mesure en PDF parle des autres librairies installées par défaut avec la dernière version du plugin ; mais je ne vois pas où, mais bon mpdf me suffit.
Merci
dd
Répondre à ce message
Savez-vous où se trouve le cache des fichiers PDF générés ? Car, après avoir fait des modifications dans mon article, quand je génère le PDF, il sort la version ancienne de l’article en PDF. Je pourrais vider le cache du site entier, mais j’aimerais pouvoir vider uniquement le cache des fichiers PDF. Car vider le cache de l’article ne suffit pas.
J’utilise aussi les plugins Cache Cool et Memoization, c’est peut-être plutôt de ce côté là qu’il faut aller voir. Mais j’ai cherché sur le serveur où diable pourraient être ces fichiers PDF en cache, et je ne les trouve pas. Merci pour votre aide !
Il y a de fortes chances que ce soit le cache de ton navigateur plutôt.
Répondre à ce message
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |