Source

EEI_Tcpdf /

Filename Size Date modified Message
config
helpers
language
libraries
models
vendor
282 B
1.5 KB
14.1 KB
1.1 KB
114 B
33.5 KB

EEI_Tcpdf Addon Plugin

Easy create pdf file at runtime directly from your ExpressionEngine web template.


DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Requirements

  • ExpressionEngine 2 (tested with EE from version 2.0.0 to 2.3.0)
  • PHP 5.2.*
  • Latest TCPDF library Official website

Installation

Complete installation does not take more then 10 minutes even if you are not a seasoned developer (FPDI classes used for pdf templates is yet included).

(1) Addon plugin

  • Download the latest source code and unzip the file
  • Put the folder eei_tcpdf in the right third parties folder (example: ./system/expressionengine/third_party/eei_tcpdf)
  • Login on your EE Control Panel and check if this plugin is correctly installed (Addons > Plugins)
  • Open with your favorite text editor (Textmate / Notepad++ / etc.) the plugin configuration file - eg. expressionengine/third_party/eei_tcpdf/config/eei_tcpdf.php - and add the reference related to Tcpdf library full physical path installation, example:

# File: expressionengine/third_party/eei_tcpdf/config/eei_tcpdf.php
# (this on non windows box)
# $config['eei_tcpdf_lib_path'] = '/var/www/tcpdf'  
# (this on windows box)
# $config['eei_tcpdf_lib_path'] = 'C:\www\tcpdf'

$config['eei_tcpdf_lib_path'] = '/var/www/tcpdf';

# NO TRAILING SLASH
  • Also be sure that this folder is web browsable by setting a related Apache alias or IIS virtual folder. The final virtual path should look as http://example.com/tcpdf
  • Open with your favorite text editor (Textmate / Notepad++ / etc.) the EE configuration file usually located in ./system/expressionengine/config/config.php and enable hooks setting the related variable to TRUE, example:

$config['enable_hooks'] = TRUE;

  • Open with your favorite text editor (Textmate / Notepad++ / etc.) the hooks configuration file usually located in ./system/expressionengine/config/hooks.php and add the EEI_Tcpdf hook:

$hook['display_override'] = array(
  'class'    => 'EEI_Tcpdf',
  'function' => 'output',
  'filename' => 'pi.eei_tcpdf.php',
  'filepath' => 'third_party/eei_tcpdf'
);

/* --- OR --- */

// if there's still another hook for the same "hook point"
$hook['display_override'][] = array(
  'class'    => 'EEI_Tcpdf',
  'function' => 'output',
  'filename' => 'pi.eei_tcpdf.php',
  'filepath' => 'third_party/eei_tcpdf'
);
  • Optional: put your own website logo on ../tcpdf/images directory (best 350x120 pixels) - please note that you can use a different image by setting the plugin parameter "dfolder" (see below).
  • Optional: put your page image texture on ./tcpdf/images directory (at this moment just A4 page format is supported) or on the directory specified by the plugin parameter "dfolder" (see below).

(2) Tcpdf library

If you don't have yet a current TCPDF library installed on your server follow this simple steps. NB: for further information about this step please check the Official website

  • Download the TCPDF lib. from http://sourceforge.net/projects/tcpdf/files/
  • Untar/Unzip the file and store the library where you prefer (eg: /var/lib/tcpdf or c:/tcpdf)
  • Make sure this folder is web browsable by setting a virtual alias or directory (see your web server documentation for more information about this task). The final URL should looks like http://example.com/tcpdf please note: you can also have installed your tcpdf library package in your main htdocs folder
  • Finally be sure that the ../tcpdf/cache folder is web server writeable

Note: if you have any troubles installing the TCPDF library please refer to your server System Administrator.

Usage

Create a new template and use the html/ee tags as usual, just add the plugin tag "params" to print out as PDF, example:

<h1>hello world</h1> <p>This is <b>Awesome!</b>(or not?)</p> <img src="http://example.com/image.jpg" /> {exp:eei_tcpdf:params logo="age38dev.jpg" language="eng" title="This is the title" author="My Name" subject="Hi Man" keywords="Some Words"}

Please note that you can put the {exp:ee_tcpdf:params} in any part of your template, even in conditional statements:

{if segment_2 == 'example'} <h1>Example</h1> {exp:eei_tcpdf:params logo="age38dev.jpg" language="eng" title="This is the title" author="My Name" subject="Hi Man" keywords="Some Words"} {if:else} <h1>Test</h1> {/if}

You can also protect your file with PDF standard security:

<h1>PDF file protected</h1> <p>Look at the documentation for more info</p> {exp:eei_tcpdf:params logo="age38dev.jpg" language="eng" allow-perms="print,copy" allow-pswd="foobar" allow-owner="bar-foo" title="This is the title" author="My Name" subject="Hi Man" keywords="Some Words"}

Using pdf templates:

<h1>hello world</h1> {exp:eei_tcpdf:params lang="eng" pdf-template="example.pdf"} {!-- before use this configure $config['eei_tcpdf_template_basedir'], see below --}

Or put a background image to the pdf produced:

<h1>hello world</h1> {exp:eei_tcpdf:params lang="eng" background-img="test-texture.jpg"}

You can temporary disable the PDF print out by simple using EE comment syntax. Please check by yourself which HTML tags and format "translation" is supported by TCPDF lib.

Tag parameters

Although the idea behind EEI_Tcpdf is to offer its functionalities with minimal efforts, you can easy fit your needs customizing the tag parameters. Below the full parameter list:

Meta info

Layout

Runtime configuration

Security


<a name="author">author</a>

[optional] The author document, by default the webmaster name (means: $config['webmaster_name'])

<a name="title">title</a>

[optional] The document title, by default the website name (means: $config['site_name'])

<a name="subject">subject</a>

[optional] The document subject, by default the string "PDF file"

<a name="keywords">keywords</a>

[optional] The document keywords, by default the string "PDF file"

<a name="orientation">orientation</a>

[optional] "P" as portrait, "L" as landscape ... by default the first one

<a name="unit">unit</a>

[optional] Unit of measure for this document, by default "mm"

<a name="format">format</a>

[optional] Standard measures for this document, by default "A4"

<a name="language">language</a>

[optional] Related to some strings used in the pdf creation, default "eng" (also available: "ita", "ger" and "bra")

<a name="font-family">font-family</a>

[optional] The document font, by default "times" (check on CP plugin page which fonts are available). This can be set per each document

<a name="font-size">font-size</a>

[optional] The font size for this document, the default one is "12"

<a name="logo">logo</a>

[optional] The image to use as a logo into the document header, by default the tcpdf_logo.jpg file

<a name="save">save</a>

[optional] You can choose to force download the document ('y') or just print out ('n'), by default just print out

<a name="dfolder">dfolder</a>

[optional] If you want to use a logo or a texture from a different location (I mean: different from standard image folder shipped with TCPDF library) this parameter allows you to indicate in which physical relative path (relative from EE installation) it's located, example: assets/images (note the no trailing slash) means a full physical path on *nix like /var/www/ee/assets/images or in Windows C:\www\ee\assets\images

<a name="cache">cache</a>

[optional] If it is set to "y" it means the pdf file produced will be cached (use this parameter to increase the performance, but then you're satisfied by the result)

<a name="fsave-path">fsave-path</a>

[optional] If you need to save the pdf produced on server side, the related values specify the full path w/o trailing slash (example: /some/where/writable)

<a name="fsave-name">fsave-name</a>

[optional] If you need to save the pdf produced on server side the related values specify the filename with it extension (example: my_dear_file.pdf). Please note: if the file /some/where/writable/my_dear_file.pdf already exists, it will be renamed (with a temporary name) and then recreated

<a name="fsave-type">fsave-type</a>

[optional] If you need to save the pdf produced on server side, the related values specify the server side behavior after file creation (valid values are: "FD" means the file is save on server side and then the file is forced to download; "FI" means the file is save on server side and then it's print out; "http://example.com/segment_1/segment_2" means the file is save on server side and then the web client is redirect to "http://example.com/segment_1/segment_2")

<a name="header">header</a>

[optional] If it is set to "n" it means no header page is print out

<a name="footer">footer</a>

[optional] If it is set to "n" it means no footer page is print out

<a name="background-img">background-img</a>

[optional] Indicate the image file to use as document texture (at this moment only A4 format is supported). The image file must be placed on default TCPDF lib. image folder or where indicate by parameter "dfolder" (see above). Note: when you use this parameter you can't use "pdf-template".

<a name="pdf-template">pdf-template</a>

[optional] Indicate which pdf file to use as template, example: test.pdf Note: (1) when you use this parameter you can't use "background-img" (2) before use this parameter open the file third_party/eei_tcpdf/config/eei_tcpdf.php with your favourite text editor and change the value of $config['eei_tcpdf_template_basedir'] to specify where base folder of pdf template is located on your filesystem (use full path without trailing slash).

<a name="margin-left">margin-left</a>

[optional] Allows to define the content margin left, the default is "15"

<a name="margin-right">margin-right</a>

[optional] Allows to define the content margin right, the default is "15"

<a name="allow-perms">allow-perms</a>

[optional] In conjunction with the parameter tag "allow-pswd" it allows to set the file protection as 'print', 'modify', 'copy', 'annot-forms', 'fill-forms', 'extract', 'assemble', 'print-high' (values must be separated by comma, example: "print,copy")

<a name="allow-pswd">allow-pswd</a>

[optional] In conjunction with the parameter tag "allow-perms" it allows to specify a PDF password to protect the file

Please note that "protecting a document requires to encrypt it, which increases the processing time a lot. This can cause a PHP time-out in some cases, especially if the document contains images or fonts." (source: TCPDF lib. documentation).

<a name="allow-owner">allow-owner</a>

[optional] It allows to specify a master password to get a full access of the PDF file

<a name="allow-mode">allow-mode</a>

[optional] Specify the encryption strength: 0 = RC4 40 bit; 1 = RC4 128 bit; 2 = AES 128 bit; 3 = AES 256 bit. The default value is to "1"


Notes

This is a simple "wrapper" of TCPDF lib. of Nicola Asuni (http://www.tcpdf.org) which easily publishes pdf file from templates of ExpressionEngine. It uses a very few original functionalities of TCPDF in the aim to satisfy small & medium requirements, should you look for more options please refer to the TCPDF library. Also remember that this package does not contain the TCPDF library, but you can get the last one directly from http://sourceforge.net/projects/tcpdf/files/.

For more info about FPDI look at its official website: http://www.setasign.de/products/pdf-php-solutions/fpdi/

Finally:

  • This plugin is in Beta state, this means it's not production ready ... use at your own risk!
  • In case of troubles please activate the log using EE debug feature ($config['log_threshold'] = 4)
  • For further settings or to start your modification please see the plugin code or refer to the very good TCPDF documentation available at http://www.tcpdf.org or here: FPDI Manuals
  • Send all your comments, ideas, code improvements, etc. to eei.addons@age38dev.com

Credits and licence