PDF Press for ExpressionEngine® User Guide


Author: Patrick Pohler

Version: 2.2

URL: http://www.anecka.com/pdf_press


Thank you for your purchase! If you have any questions about the module, please email us at contact@anecka.com


Table of Contents

  1. Prerequisites
  2. Installation Instructions
  3. Module Tags
  4. Formatting the PDF File
  5. Setting Presets & Security
  6. PDF Preview
  7. Overriding the DOMPDF Settings
  8. Unicode
  9. Tips & Troubleshooting
  10. Support
  11. Changelog

1. Prerequisites

Make sure your system meets the following requirements:


2. Installation Instructions

  1. Copy the third_party/pdf_press folder to system/expressionengine/third_party/

  2. Install the module by going to Add-Ons > Modules, look for PDF Press and click Install

  3. That's it! Go to the PDF Press module’s Control Panel (Add-Ons > Modules > PDF Press > Configuration) and verify that your environment is configured to generate PDFs.


3. Module Tags

PDF Press has two tags, each will generate a PDF from an ExpressionEngine template.

Tag {exp:pdf_press:save_to_pdf}

The save_to_pdf tag generates a link to download the template as a PDF, it contains the following parameters:

Example:

<a href="{exp:pdf_press:save_to_pdf path='site/projects' attachment='0' filename='projects.pdf'}">Download Project Case Studies</a>

This will create a link to open a PDF titled "projects.pdf" in the browser using the site/projects template


Tag {exp:pdf_press:parse_pdf}

Sometimes you'll want to create a PDF with a member only or logged in page. For this you want to use parse_pdf

{exp:pdf_press:parse_pdf}
    <html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <title>Parse Test</title>
    </head>
    <body>
        {if logged_in}
            {exp:channel:entries channel="Projects"}
                <p><strong>{title}</strong></p>
            {/exp:channel:entries}
        {if:else}
            <p>Not logged in</p>
        {/if}
    </body>
    </html>
{/exp:pdf_press:parse_pdf}

As you can guess, this tag, instead of creating a link to download/open a PDF, it will create a PDF using whatever HTML & EE tags that are inside the parse_pdf tag-pair. It has all of the same parameters as save_to_pdf (except for path)


4. Formatting the PDF File

Formatting the PDF file is as simple as creating a special CSS file and referencing it in the <head> tag in your template. Use the media attribute and set it to "pdf". This will cause the PDF Press to use the stylesheet (and it will be ingnored in your browser)

<link href="{site_url}css/pdf.css" rel="stylesheet" media="pdf">

If you want to hide your main stylesheet from PDF Press (which is very useful, CSS frameworks such as Bootstrap or Foundation can drastically slow down PDF Press), just set the media attribute to "screen."

<link href="{site_url}css/site_only.css" rel="stylesheet" media="screen">
<link href="{site_url}css/pdf.css" rel="stylesheet" media="pdf">

5. Setting Presets

Setting Presets are a new feature in 2.0. Presets are a great way to save time, they allow you to set all of the options passed as parameters in the save_to_pdf & parse_pdf tags in the Control Panel. You can then re-use those settings in your template by just passing the short code into the "key" parameter.

{exp:save_to_pdf key="product_settings"}

Presets also let you securely set a variety of security settings for your PDFs. You can enable encryption, set a owner password, user password and then control if users can save, print, or modify PDFs.

You can access the Setting Presets by going to Add-Ons > Modules > PDF Press > Setting Presets


6. PDF Preview

A helpful tool you can use to develop your PDF templates is the PDF Preview tab. You can find it under Add-Ons > Modules > PDF Press > PDF Preview

Specify the size, orientation and an ExpressionEngine template path (ex. site/test) and click Submit. The PDF (or other output if there’s an error) will be displayed below in an iframe. In order for the PDF Preview to work, you MUST have the JQuery Module installed.


7. Overriding the DOMPDF Settings

PDF Press uses the DOMPDF library (https://github.com/dompdf/dompdf) to generate the PDF file. Sometimes the default settings that ship with DOMPDF aren’t right for your needs. Fortunately it’s very easy to override the default settings by modifying the following file:

third_party\pdf_press\dompdf_config.custom.inc.php

8. Unicode

PDF Press uses the DOMPDF library, which supports a wide variety of unicode character sets. In order to properly render unicode in your PDF, there are a few configuration steps you'll need to do.

To start, you'll need to install a font for your unicode charset. Log into your Control Panel and go to Add-Ons > Modules > PDF Press > Fonts.

Under Install New Fonts upload any .ttf file that contains characters for your language. I found a set called fireflysung for this example. Give the font a name, select the .ttf file from your computer can click Install it.

In a few seconds the page should refresh and you should see your font in the installed fonts list.

Unicode should already be set by default, but you can double check the following configuration file in

/third_party/pdf_press/dompdf_config.custom.inc.php

Open the file and make sure the following line is uncommented and set to TRUE

define("DOMPDF_UNICODE_ENABLED", true);

Finally all you need to do now is setup your template. Any Unicode characters you want to render should have the font-family set to the font you’ve uploaded in Step 1. Here’s an example using “fireflysung."

{exp:pdf_press:parse_pdf}
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> 
        <title>Unicode Test</title>
    </head>
    <body>
        <p style="font-family:fireflysung">螢火飛字型</p> 
    </body>
</html>
{/exp:pdf_press:parse_pdf}

Also make sure you’ve set the “Content-Type” to “utf-8” in your html template’s <head> tag.

Note about Right to Left support

Some languages are formatted right to left, to enabled this support we’ve added a new CSS attribute: “direction: rtl” just include this attribute in your template

Example:

{exp:pdf_press:parse_pdf}
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> 
        <title>Unicode Test</title>
    </head>
    <body>
        <p style="font-family:fireflysung;direction: rtl;">螢火飛字型</p> 
    </body>
</html>
{/exp:pdf_press:parse_pdf}

9. Tips & Troubleshooting

PHP Errors

The DOMPDF library is VERY STRICT when it parses the HTML & CSS of your template. If you are having trouble getting your PDF to generate and you're getting PDF errors, run your HTML & CSS through a validator, such as the W3C Validation Service (http://validator.w3.org). We recommend starting with very basic HTML template & CSS first, then add only the styles you need for your PDF.

Garbled Text

On some environments, you might see a bunch of garbled text on your screen instead of your PDF. Some webservers ignore the "Content-Type: application/pdf" header set by PDF Press and will instead use "text/html".

If you run into this issue you can use our "PDF" template type. Just go to the Template Manager, edit the preferences for your template and choose "PDF" for the template type.

PDF Preview

You can troubleshoot your template using the PDF Preview tab in the Control Panel. Just go to Add-Ons > Modules > PDF Press > PDF Preview

Debug Settings

You can troubleshoot the PDF document by setting the following settings in third_party\pdf_press\dompdf_config.custom.inc.php:

define("DEBUG_LAYOUT", true);
define("DEBUG_LAYOUT_LINES", true);
define("DEBUG_LAYOUT_BLOCKS", true);
define("DEBUG_LAYOUT_INLINE", true);

10. Support

If you have any questions or concerns visit our offical support forum on Devot-ee


11. Changelog

2.2

  1. Fix bug installing PDF Press on Windows
  2. Fix error when saving new pre-sets & bug when editing
  3. Change paper_sizes to array to single dimension
  4. URLs when Force Query String are set to 'y'
  5. Fix notices on font-view
  6. Fix php errors on PDF Preview
  7. Add PDF template type to fix header issue

2.0

  1. Added Setting Presets
  2. Updated docs to use Markdown
  3. Created Fonts tab to improve unicode support
  4. Fix error when downloading PDFs using save_to_pdf, some webservers ignore "Content-Type" and go by the filename, change order of filename so that it's last in the URL
  5. Added encryption & security settings in the Presets

1.0.3

  1. Add ability to parse globals in parse_pdf method

1.0.2

  1. Add guide for Unicode, "direction:rtl" css attribute for right to left languages
  2. Add parse_pdf method for creating PDF files between a tag pair

1.0.1

  1. Switch to use CURL if allow_url_fopen is disabled.

1.0

  1. Friendly error message for DOMPDF errors

0.8

  1. Resolved bug with relative to root paths
  2. Added PDF Preview tab to MCP
  3. Added new parameters to {exp:pdf_press:save_to_pdf_form} & {exp:pdf_press:save_to_pdf} tags
  4. Updated DOMPDF library

0.0.4 - Initial Release

Initial Release of PDF Press to beta users