Beautify your pdf's with the Joomla PrettyPDF component

Out of the box Joomla frontend is able to dynamically generate a pdf-file of the content item shown. This, however, is not really presentative for your business because it lacks your housestyle items like font, colors, templates and logos.

Now PrettyPDF comes to the rescue and more! PrettyPDF offers you control of fonts, colors, housestyle templates and allows you to even add promotional material to the generated pdf-file.

How does PrettyPDF work?

PrettyPDF replaces the standard Joomla pdf.php file in the /includes directory. This is done upon installation when the Joomla installer is allowed to overwrite this file. Before pdf.php is overwritten with the PrettyPDF version, a backup is made of the original file and saved for possible later restore.

When the installer was not able to overwrite the pdf.php file, you must set the proper access rights to pdf.php and use the re-install option from the PrettyPDF control panel.

PrettyPDF can generate any Joomla content-item to a pdf-file, this means it can not generate content from other components like virtuemart, easyfaq or others.

Installation of the PrettyPDF component

The installation of the component is straight foreward. Install the component through the Joomla installer, but make sure that the /includes/pdf.php file has the permissions to be overwritten by the PrettyPDF installer.

Here follows a walk-through through the installation process.

First, go to the Joomla components installer and use the browse button to select the Pretty PDF component zip-file to install.

When all went fine, the installer reports a succesfull installation:

The installation is now finished and you can continue to the configuration of PrettyPDF.

PrettyPDF Control Panel

Navigate to the Components->JRE PrettyPDF menu entry to go to the PrettyPDF control panel:

Here you have four configuration options, two installation / de-installation options for controlling the original pdf.php file and a link to our website to get support through our forum or service mailbox or check if a new version is available.

PrettyPDF - PDF Generation Configuration

This configuration page lets you control the content-to-pdf generation. You can define how the content-item title has to be displayed, what standard text font to use, how list bullets will look like and if the images, links and included tables need to be displayed.

The character encoding can be chosen to support non-western characters. A full description is given below.

The table rendering needs some extra attention. If you disable table rendering (which is the default) all table-cells content is rendered one cell after the other, without columns.
Because the rendering of html tables is not trivial, the current code can do the rendering, but not perfect. Therefore we advice you to first test the generated pdf output when enabling this option.

The <h1> up to <h6> tags generation can be controlled together with the white space below these heading-tags.

The fontsizes smaller than the minimum defined will be ignored to avoid unusable rendered pdf files. This as some editors insert font size=1 into the html and have the proper fontsize be set through the CSS definitions, which are not used by PrettyPDF.

PrettyPDF - PDF Template Configuration

Here you can configure the template pdf to be used and what margins need to be used for the template pages.
The template generation can use a first-page-template and an other-pages-template. This will give you the oppertunity to construct an openings page that includes a large logo and contact information and to not have this overwritten with your content, you set the top margin below these spacious logos and information. You can have all the following pages using a different template and set the top margin higher than the first page to have more space dedicated to your content.

The template pdf can be previewed using the pdf-logo behind the dropdown box.

PrettyPDF - PDF Header/Footer Configuration

These parameters lets you control the header and footer generation for the pdf-file. The format allows generic html tags, except for tables. Next to the html tags that you can use, there are several parameters that you can use as well:

• {author} : shows the author alias of the content item (not the creator)
  
• {createdate} : shows the creation date in the default format 'Y-M-d'. You can also define your own date formatting using the php date formatting referenced below.
• {currentdate} : shows the current date in the default format 'Y-M-d'. You can also define your own date formatting using the php date formatting referenced below.
• {currenturl} : shows the url of the current content.
• {date} : shows the last modified date in the default format 'Y-M-d'. You can also define your own date formatting using the php date formatting referenced below.
• {pageno} shows the current page number.
• {sitename} : shows the sitename as configured in the global configuration of Joomla.
• {title} : shows the title of the content item.
• {siteurl} : shows the url as configured in the global configuration of Joomla.

The date formatting as used in php, is described here.

The footer Y position is notated as a negative number calculated from the bottom of the page, so -15 means 15 points above the bottom of the page.

PrettyPDF - Replacements Configuration

Here you can configure any mambot or tag replacements that are specific for your Joomla website. Did you install any mambots to enhance your website, but don't want these mambot-codes to show in the pdf generation? Here you can let PrettyPDF remove or replace these codes from your content before the pdf-file is generated.

For example, if you do not want your mospagebreaks to be rendered to a forced new page in your pdf's, just enter "{mospagebreak*}=", and PrettyPDF removes these mambot statements before the page is generated to a pdf-file.

PrettyPDF - Promotional Pages Configuration

The promotional pages configuration gives you the possibility to add 'commercials' or other generic information of you business or website to the generated pdf-file. You can use it as a products display, licence or copyright information attention or any way you can think of. You can select the pdf-file to be used which can be previewed using the pdf icon.

With the 'Position promotion pages', you define where PrettyPDF must add a promotional pdf-page in the generated pdf-file. The page used from the promotional pdf-file is picked at random when more than one page is available in the promotional pdf-file.
You can define the page number on which the promotional pdf-page has to be inserted. If you define '1', the generated pdf-file will have it's first page taken from the promotional pdf-file. When using the word 'last', the final page of the generated pdf-file will be a promotional page, no matter how much pages the generated pdf-file will have.
The entry field accepts multiple values, separated with commas, e.a. '1,3,last'.

PrettyPDF - Manage the PDF Cache

Here you can enable and configure pdf-file caching. By default the cache is NOT enabled to avoid directory cluttering.

If you have installed the JoomlAtWork Performance Booster, Cache component, the cache directory is pre-filled with the caching directory used by the Cache component.

Make sure the cache file separator character is not existing in the directory path, this will interfere with the cache house-hold.

The cache strategy has four possible settings, these are:

• Refresh once a day : once a pdf is generated, it will be cached and expire the following day at 00:00 hours.
• Refresh on modification : the generated pdf will be serviced from the cache untill PrettyPDF sees that the modification date/time of the content in the database is different from the generated pdf.
• Refresh once a day and on modification : this is a combination of the previous strategies. Which ever comes first will expire the cached pd-file.
• Refresh after x-times browser request : PrettyPDF will use a counter to track the number of times the cached pdf-file is sent to a requesting browser. Once the counter reaches the number supplied, PrettyPDF generates the pdf-file again.

You can use the refresh button in the top-right corner to see any changes in the cached files list at the bottom of the page.

The delete button at the right side, just above the cached files list, will remove all cached pdf-files from the cache directory.

Can you give me an example of the output?

The image below is a generated version of this page with all default settings. You can see the promotion pages at page 2 and the last page. You can also see the usage of a first-page template and the other-pages template being different from each other.

How can I create a PDF Template or Promotion pdf?

Because you need a pdf-file for both the template and the promotion pdf-file, you have to build one. This can be done in several ways, with several price-tags to it, ranging from free to a lot of money.

The easiest way in our opinion, is to use OpenOffice. The OpenOffice Writer contains the menu entry File->Export as PDF...
Create a new document, build your template with logos, texts, borders etc and simply export it to a pdf-file.

How do I add a PDF Template or Promotion pdf?

The pdf-files that you can choose from the pull-down menus are all located in the components subdirectory 'assets'. To be exact (starting from your Joomla installation directory) '/administrator/components/com_jreprettypdf/assets'.

Use you preferred ftp-program to upload the pdf-files to this location, and you can select the pdf-files from the pull-down menus.

Re-install the PrettyPDF pdf.php file

When the first installation was not succesfull you can re-install the needed pdf.php with this option. This may be required when the pdf.php could not be replaced at the time of installation of the component. This may be caused by permissions not set correctly.

Restore the original Joomla pdf.php file

At installation time, a backup of the orginal pdf.php file is made. With this option you can restore the orginal pdf.php when needed.

De-installation of the component.

When you de-install the component the orginal pdf.php is automatically restored.

Where are the configuration settings stored?

All settings that can be entered through the administrator interface are stored in the file:
(starting from your Joomla installation directory) '/administrator/components/com_jreprettypdf/jre_config.php'.

It is adviced to make a proper backup of this file when a lot of effort is put into the configuration of PrettyPDF.

Character encoding usage

If you want to use PrettyPDF for a non-western characters Joomla installation, please read this section.

PrettyPDF supports other character encoded websites starting from version 1.3. Including these extra font definitions will however, bloat the component too much. Therefor you can download the additional character encoded font definitions seperately from this page .

The zip file contains several encodings, which are:

• cp1250 (Central Europe)
• cp1251 (Cyrillic)
• cp1252 (Western Europe)
• cp1254 (Turkish)
  
• ISO-8859-2 (Central Europe)
• ISO-8859-5 (Cyrillic)
• ISO-8859-9 (Turkish)
  

More can be added when requested.

As an example, we'll demonstrate the usage of the additional character encodings in PrettyPDF using a Russian Joomla installation. The Russian website uses the cp1251 encoding, as determined from the html source (see the download page ) and the zip-file is installed accordingly.

As you can see in the screen shots below, in the 'PDF Generation Configuration' administrator screen, cp1251 is selected from the selectbox. The Russian Joomla site displays the standard Joomla content page and the generated pdf-file is shown as well. Please click on the image for a larger version. The generated pdf is also available here as it was generated.

Another one using the Turkish character set cp1254:

Known issues with PrettyPDF

The currently known issues with PrettyPDF are:

• Table rendering - this is still in alpha stage and far from complete. Test before enable in production.

Release history

April 12, 2008 - v1.8

• Added variable page orientation based upon content trigger
• Added configurable page construction
• Fixed <HR> tag rendering bug
  

April 5, 2008 - v1.7

• Fixed \ being removed in text
  
• Big image stays on page when page was still empty
  
• Fixed Unsupported image type
• Fixed space handling in image url's
• Added support for transparent PNG images
  

September 20, 2007 - v1.6.11

• Fixed image location bug
  
• Fixed forced image alignment bug

August 18, 2007 - v1.6.10

• Fixed Joomla 1.0.13 bug
  
• Uses local image location instead of url's
• Can use iconv() to support other characater sets for the pdf-filename generation
  

July 5, 2007 - v1.6.9

• Fixed additional fonts loading bug
• Fixed relative include
• Added extra png variable check

July 1, 2007 - v1.6.8

• Fixed > and < bug
• Fixed order of replacements error

June 23, 2007 - v1.6.7

• Fixed some small bugs
  

June 17, 2007 - v1.6.6

• Fixed a sometimes failing relative file include
  

May 13, 2007 - v1.6.5

• Fixed not displaying right-aligned images

April 28, 2007 - v1.6.4

• Fixed minor bug (not released)

April 7, 2007 - v1.6.3

• Fixed Template preview and delete icon bug for certain installations

March 20, 2007 - v1.6.2

• Fixed WAMPP control panel not showing

March 3, 2007 - v1.6.1

• Fixed gif-image display error
  
• Fixed no-images bug
• Fixed html image size definition showing too much white space bug
  

February 16, 2007 - v1.6

• Added tag/mambot replacement functionality
  
• HR width bug fixed
  

February 9, 2007 - v1.5.1

• Fixed minor bugs
  

February 8, 2007 - v1.5

• Added after h1 - h6 space control
  

February 4, 2007 - v1.4

• Fixed mospagebreak bug
• Added h1 - h6 tags control
  
• Added minimum font size support
• Minimizes empty line generation
  

Januari 31, 2007 - v1.3

• Fixed some minor bugs
• Added image alignment control
• Added character encoding selection to support non-western language installations
  

Januari 10, 2007 - v1.2.1

• Fixed unwanted header / footer link creation

Januari 8, 2007 - v1.2

• Added caching functionality
• Fixed repeating content issue
• Fixed javascript error in admin screen
  

December 30, 2006 - v1.1

• Bug fix in gif image handling (thanks Dan!)
  

December 28, 2006 - v1.0

• First release
  

PrettyPDF^(TM) is a trademark of JoomlAtWork.