PDF Creator for Umbraco Version 2.

0
Copyright 2011, Ferguson Moriyama Limited. All rights reserved

1 2

Introduction .................................................................................................................................... 3 Prerequisites ................................................................................................................................... 4 2.1 2.2 2.3 2.4 Requirements .......................................................................................................................... 4 Downloading ........................................................................................................................... 4 Evaluation ............................................................................................................................... 4 Purchasing a License ............................................................................................................... 4

3 4

Installing .......................................................................................................................................... 5 Upgrading ........................................................................................................................................ 6 4.1 Differences from version 1.x ................................................................................................... 6

Uninstalling ..................................................................................................................................... 7 5.1 5.2 Uninstalling PDF Creator 2.0 ................................................................................................... 7 Uninstalling PDF Creator 1.x ................................................................................................... 7

Using PDF Creator for Umbraco ...................................................................................................... 8 6.1 6.2 6.3 6.4 Getting Started with FO .......................................................................................................... 8 Making a template output PDF ............................................................................................... 8 Viewing the FO source of your template ................................................................................ 8 Example templates.................................................................................................................. 8 Razor Helpers .................................................................................................................. 9

6.4.1 6.5

Processing Rich text editor (TinyMCE) content ...................................................................... 9 Processing with XSLT ....................................................................................................... 9 Processing with Razor ................................................................................................... 10

6.5.1 6.5.2 6.6 6.7 6.8 6.9

Forcing the browser to initiate a PDF download .................................................................. 11 Setting Document Metadata ................................................................................................ 11 Securing the generated PDF.................................................................................................. 12 XSLT Extension functions ...................................................................................................... 12 RichTextToXml .............................................................................................................. 12 AppendResponseHeader .............................................................................................. 12 SetResponseContentType ............................................................................................. 12 GetWebRootPath .......................................................................................................... 13

6.9.1 6.9.2 6.9.3 6.9.4 6.10 7 8

FO Compliance ...................................................................................................................... 13

Support.......................................................................................................................................... 14 License........................................................................................................................................... 14

PDF Creator for Umbraco 2.0

Page 2

1 Introduction
PDF Creator for Umbraco allows the creation of PDF documents from Umbraco using FO. FO is a language for formatting XML data for output to screen, paper or other media.

Figure 1 High level overview of PDF creator for Umbraco

PDF Creator intercepts requests for FO generated by Umbraco templates and renders the FO to a PDF modifying the response to the browser as appropriate.

Figure 2 Technical Overview

PDF Creator for Umbraco 2.0

Page 3

2 Prerequisites
2.1 Requirements
PDF Creator 2.0 for Umbraco will work with Umbraco version 4.5.2 or later running on the .NET Framework version 4 or later. Previous versions of Umbraco are not supported. Please contact Ferguson Moriyama to obtain a legacy version for your platform.

2.2 Downloading
PDF Creator for Umbraco can be downloaded from our.umbraco.org: http://our.umbraco.org/projects/website-utilities/pdf-creator

2.3 Evaluation
PDF Creator for Umbraco can be installed and used for free in an Umbraco instance using the domain name localhost or any domain ending in .local. Other domains will require a license.

2.4 Purchasing a License

A license is required per top level domain even if you have several domains hosted on a single server. License purchase is available online at: http://our.umbraco.org/projects/website-utilities/pdf-creator PDF Creator for Umbraco uses 3rd party commercial components licenses for these components are included in the license fee. No additional purchase is required.

PDF Creator for Umbraco 2.0

Page 4

3 Installing
In the developer section of the Umbraco GUI: Expand the Packages node of the navigation tree. Click on Install local package. Click on the Choose File button in the right pane and locate your downloaded version of PDF Creator for Umbraco. Check the checkbox labelled I understand the security risks associated with installing a local package. Click on the Load Package button. Confirm any further prompts.

Figure 3: Installer process

Note: PDF Creator can also be installed via the Umbraco package repository.

PDF Creator for Umbraco 2.0

Page 5

4 Upgrading
Please note that there are breaking changes between version 1 and 2 of PDF creator please see the Differences from version 1.x section of this document for details of how to update your templates. To upgrade from a version 1.x of PDF creator to 2.0 follow the instructions for Uninstalling PDF Creator 1.0 and then follow the Installing section of this document.

4.1 Differences from version 1.x

PDF Creator for Umbraco 2 differs from 1.x in the following ways: No custom Macro required just use standard Umbraco templates to output FO. Use any template language not just XSLT. To tell the browser to render PDF add a header to the HTTP response in your template. See the Making a template output PDF section of this document for more details. The XSLT helper function to turn Rich Text editor contents into XML has been renamed from PDF:RteToHtml() to FergusonMoriyama.Pdf.XsltHelper:RichTextToXml() Performance and memory usage has been significantly improved due to upgraded PDF generating DLL and buffered output. You can now tell the browser to force a download rather than opening the PDF see the Forcing the browser to initiate a PDF download section of this document for details.

PDF Creator for Umbraco 2.0

Page 6

5 Uninstalling
5.1 Uninstalling PDF Creator 2.0
To uninstall PDF Creator for Umbraco 2.0 remove the following sections from your web.config file: In //Configuration/System.Web/ httpModules
<add name="PdfModule" type="FergusonMoriyama.Pdf.Application.Module.PdfModule, FergusonMoriyama.Pdf" />

In //Configuration/system.webServer/modules
<add name="PdfModule" type="FergusonMoriyama.Pdf.Application.Module.PdfModule, FergusonMoriyama.Pdf" />

You should then delete the following files: /bin/ibex40.dll /bin/FergusonMoriyama.Pdf.dll /App_Code/Pdf.cshtml /App_Code/PdfHelper.cshtml

You may optionally clean up any Umbraco templates that you created to generate PDF files. Note you may uninstall using the Umbraco package uninstaller though this may remove files that could prevent other packages purchased from the Umbraco Deli from working. You will also need to perform the web.config changes detailed above manually.

5.2 Uninstalling PDF Creator 1.x

To uninstall PDF Creator for Umbraco 1.0 delete the following files from your Umbraco web root: /usercontrols/PdfXslFo.ascx /bin/ibex35.dll /bin/UmbracoIbexXslFo.dll /media/FergusonMoriyama/logo-large.gif

You can also delete the Macro and template called PDF XSL FO. Note you may uninstall using the Umbraco package uninstaller though this may remove files that could prevent other packages purchased from the Umbraco Deli from working.

PDF Creator for Umbraco 2.0

Page 7

6 Using PDF Creator for Umbraco

This manual assumes that you are familiar with using Umbraco templates to generate HTML. If you are not then we recommend the material at: http://umbraco.com/help-and-support/video-tutorials/ PDF Creator for Umbraco uses standard Umbraco templates to output FO which are then rendered as PDF files. You may create FO using XSLT, Razor or any other supported Umbraco template technology.

6.1 Getting Started with FO

The following references are available when learning how to write FO: http://www.xmlpdf.com/documentation.html http://www.w3schools.com/xslfo/default.asp Note: This manual does not teach FO, it is a W3C standard with plenty of resources online.

6.2 Making a template output PDF

To tell PDF Creator for Umbraco to output a PDF your template should set the content type of the HTTP response to text/xml and set an HTTP header called X-Pdf-Render with a value of true. You can do this in a Razor template by adding the following code:
@{ Response.ContentType = "text/xml"; Response.AppendHeader("X-Pdf-Render", "true"); }

For XSLT templates you can use the XSLT extension functions provided to achieve the same outcome:
<xsl:value-of select="FergusonMoriyama.Pdf.XsltHelper:SetResponseContentType('text/xml')"/> <xsl:value-of select="FergusonMoriyama.Pdf.XsltHelper:AppendResponseHeader('X-Pdf-Render', 'true')"/>

6.3 Viewing the FO source of your template

To view the FO that is being output by your template (to facilitate debugging) temporarily remove the X-Pdf-Render header from the HTTP response you can accomplish this by commenting out the code detailed in the previous section: Making a template output PDF

6.4 Example templates

PDF creator for Umbraco ships with several example templates. These are accessible in the settings section of Umbraco. Expand the Templates node and the samples are provided underneath the master template [PDF] Master. [PDF] Razor Example Uses Razor to output a simple PDF using FO.

PDF Creator for Umbraco 2.0

Page 8

[PDF] Razor Hello World A hello world PDF created using Razor. [PDF] Razor Helper Example A Razor generated PDF which extracts the use of FO to Razor helpers allowing you to write PDFs as Razor code. [PDF] XSLT Example Uses XSLT to output a simple PDF using FO. [PDF] XSLT Hello World A hello world PDF created using XSLT.

6.4.1 Razor Helpers

PDF Creator provides two Razor Helper files in the /App_Code folder of your Umbraco site: Pdf.cshtml PdfHelper.cshtml

These files are provided for your use and you are encouraged to modify them though you should keep backup copies of the originals. The Razor helpers will output FO fragments and are intended to abstract the complexity of FO while you learn. To call Razor helpers you use the .cshtml filename as a namespace prefix e.g.:
@PdfHelper.StartArea("body")

Where StartArea is a helper defined in PdfHelper.cshtml.

6.5 Processing Rich text editor (TinyMCE) content

XSL-FO cannot interpret HTML content therefore rich text editor content must be converted to FO. PDF Creator for Umbraco provides XSLT and Razor helper functions to convert Rich Text editor HTML to XML for processing. Note: The contents of your rich text editor must be valid XML when surrounded by a wrapping root element.

6.5.1 Processing with XSLT

Note the mechanism detailed in this section is implemented in the XSLT example templates that are installed with PDF Creator for Umbraco. Parse your RTE content to XML using the provided extension function:
<xsl:variable name="xhtml" select="FergusonMoriyama.Pdf.XsltHelper:RichText ToXml($currentPage/bodyText)"/> <xsl:apply-templates select="$xhtml"/>

PDF Creator for Umbraco 2.0

Page 9

Youll then need to write a template to match each HTML element in your rich text editor HTML and output the equivalent FO:
<xsl:template match="a"> <fo:basic-link color="blue" text-decoration="underline" external-destination="url('{@href}')"> <xsl:apply-templates/> </fo:basic-link> </xsl:template> <xsl:template match="em"> <fo:inline font-style="italic"> <xsl:apply-templates/> </fo:inline> </xsl:template>

The example above illustrates templates that match HTML anchor (a) and emphasis (em) tags. These are provided in the example XSLT installed with PDF Creator for Umbraco.

6.5.2 Processing with Razor

First use the provided helper method to begin parsing your rich text content:
@Pdf.RenderRichText(@Model.BodyText)

Note: the helper method is in /App_Code/Pdf.cshtml Look at the ParseElement helper function and note how it calls another Razor helper for each HTML tag that it matches.
@helper ParseElement(XmlNode node) { switch (node.Name) { case "p": @Pargraph(node) break; case "strong": @Bold(node) break; case "em": @Italic(node) break;

If you wish to parse more HTML elements than are already defined in the helper function then youll need to add a case to the switch statement and add an appropriate helper method.

PDF Creator for Umbraco 2.0

Page 10

A helper method just outputs the equivalent FO for an HTML tag for example when the strong tag is matched in the parsed rich text HTML the Bold helper is called to output the FO equivalent.
@helper Bold(XmlNode node) { <fo:inline font-weight="bold"> @ParseRichText(node.ChildNodes) </fo:inline> }

Note that any helpers you write to process Rich Text should make a recursive call to ParseRichText in order that child nodes are processed.

6.6 Forcing the browser to initiate a PDF download

To force the browser to initiate a PDF download (as opposed to opening the PDF in the browser) you can set a header called X-Pdf-Force-Download in the HTTP response the value of which should be the filename you wish to use. You can accomplish this in a Razor template by using the following code:
Response.AppendHeader("X-Pdf-Force-Download", "darren.pdf");

In XSLT templates you can use the following extension method:

<xsl:value-of select="FergusonMoriyama.Pdf.XsltHelper:AppendResponseHeader('X-PdfForce-Download', 'hello.pdf')"/>

6.7 Setting Document Metadata

You may set standard metadata on your PDF using the following tag:
<ibex:properties title="@Model.Name" author="@Model.WriterName" subject="" keywords="metat,bacon,sheep" creator="PDF Creator for Umbraco" />

All attributes are optional and can be excluded from the tag is not used. The following razor helpers are provided to write this tag:
@helper MetaData(string title) @helper MetaData(string title, string author) @helper MetaData(string title, string author, string subject, string keywords, string creator)

The Razor helpers may be modified in /App_Code/PdfHelper.cshtml to suit your requirements.

PDF Creator for Umbraco 2.0

Page 11

6.8 Securing the generated PDF

To secure your PDF you may use the following tag below the <fo:root/> element of your FO output:
<ibex:security deny-print="true" deny-extract="true" denymodify="true" user-password="" owner-password=""/>

All attributes are optional and can be excluded from the tag is not used. The following Razor helpers are provided to write this tag:
@helper Secure() @helper Secure(string user, string password)

The Razor helpers set all attributes to true but may be modified in /App_Code/PdfHelper.cshtml to suit your requirements.

6.9 XSLT Extension functions

XSLT extension functions are in the FergusonMoriyama.Pdf.XsltHelper namespace. To use these in existing XSLT files add the following namespace declaration to your <xsl:stylesheet/> tag:
xmlns:FergusonMoriyama.Pdf.XsltHelper="urn:FergusonMoriyama.Pdf.XsltHelper"

Note: Umbraco will add this to new XSLT files automatically once PDF Creator for Umbraco is installed.

6.9.1 RichTextToXml
The RichTextToXml function parses content from rich text areas, turning it into XML and returning an XPathNodeIterator over that XML.
public static XPathNodeIterator RichTextToXml(string html)

Note: For this function to work the value passed in must be valid XML when wrapped with a top level element.

6.9.2 AppendResponseHeader
The AppendResponseHeader function adds and header to the HTTP response.
public static void AppendResponseHeader(string name, string value)

6.9.3 SetResponseContentType
The SetResponseContentType function sets the content type header of the HTTP response.
public static void SetResponseContentType(string type)

PDF Creator for Umbraco 2.0

Page 12

6.9.4 GetWebRootPath
The GetWebRootPath function returns the document root of the current Umbraco website
public static string GetWebRootPath()

Note: This is useful when using the <fo:external-graphic/> tag to embed images in your PDFs as a full path to the image is required and Umbraco typically stores a path relative to the web root.

6.10 FO Compliance
Please see http://www.xmlpdf.com/compliance.html for details of PDF Creator for Umbraco compliance with the XSL 1.1 Standard.

PDF Creator for Umbraco 2.0

Page 13

7 Support
Ferguson Moriyama provides support for PDF Creator for Umbraco our.umbraco.org support forums at: http://our.umbraco.org/projects/xsl-pdf-creator

8 License
UMBRACO DELI PACKAGE LICENSE AGREEMENT This UMBRACO DELI PACKAGE is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. This UMBRACO DELI PACKAGE is licensed, not sold. Definitions UMBRACO DELI PACKAGE refers to the software products provided by the Umbraco Deli Vendor and not directly from Umbraco I/S. The Umbraco Deli Vendor information can be found by referencing the Umbraco Deli Package information. End User License Agreement This End User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and the Umbraco Deli Vendor and not Umbraco I/S with regard to the copyrighted Software (herein referred to as "UMBRACO DELI PACKAGE" or "SOFTWARE") provided with this EULA. The UMBRACO DELI PACKAGE includes computer software, the associated media, any printed materials, and any "online" or electronic documentation. Use of any software and related documentation ("Software") provided to you by the Umbraco Deli Vendor and not Umbraco I/S in whatever form or media, will constitute your acceptance of these terms, unless separate terms are provided by the software supplier, in which case certain additional or different terms may apply. If you do not agree with the terms of this EULA, do not download, install, copy or use the Software. By installing, copying or otherwise using the UMBRACO DELI PACKAGE, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, the Umbraco Deli Vendor is unwilling to license the UMBRACO DELI PACKAGE to you. 1. Eligible Licensees. This Software is available for license solely to SOFTWARE owners, with no right of duplication or further distribution, licensing, or sub-licensing. IF YOU DO NOT OWN THE SOFTWARE, THEN DO NOT DOWNLOAD, INSTALL, COPY OR USE THE SOFTWARE. 2. License Grant. The Umbraco Deli Vendor and not Umbraco I/S grants to you a personal, non-transferable and non-exclusive right to use the copy of the Software provided with this EULA. You agree you will not copy the Software except as necessary to use it on a single Umbraco site. You agree that you may not copy the written materials accompanying the Software. Modifying, translating, renting, copying, transferring or assigning all or part of the

PDF Creator for Umbraco 2.0

Page 14

Software, or any rights granted hereunder, to any other persons and removing any proprietary notices, labels or marks from the Software is strictly prohibited. Furthermore, you hereby agree not to create derivative works based on the Software. You may not transfer this Software. 3. Copyright. The Software is licensed, not sold. You acknowledge that no title to the intellectual property in the Software is transferred to you. You further acknowledge that title and full ownership rights to the Software will remain the exclusive property of the Umbraco Deli Vendor and you will not acquire any rights to the Software, except as expressly set forth above. All copies of the Software will contain the same proprietary notices as contained in or on the Software. All title and copyrights in and to the UMBRACO DELI PACKAGE, the accompanying printed materials, and any copies of the UMBRACO DELI PACKAGE, are owned by the Umbraco Deli Vendor and not Umbraco I/S. The UMBRACO DELI PACKAGE is protected by copyright laws and international treaty provisions. You may not copy the printed materials accompanying the UMBRACO DELI PACKAGE. 4. Reverse Engineering. You agree that you will not attempt, and if you are a corporation, you will use your best efforts to prevent your employees and contractors from attempting to reverse compile, modify, translate or disassemble the Software in whole or in part. Any failure to comply with the above or any other terms and conditions contained herein will result in the automatic termination of this license and the reversion of the rights granted hereunder to the Umbraco Deli Vendor. 5. Disclaimer of Warranty. The Software is provided "AS IS" without warranty of any kind. The Umbraco Deli Vendor and Umbraco I/S disclaims and makes no express or implied warranties and specifically disclaim the warranties of merchantability, fitness for a particular purpose and non-infringement of third-party rights. The entire risk as to the quality and performance of the Software is with you. The Umbraco Deli Vendor does not warrant that the functions contained in the Software will meet your requirements or that the operation of the Software will be uninterrupted or error-free. The Umbraco Deli Vendor and not Umbraco I/S IS NOT OBLIGATED TO PROVIDE ANY UPDATES TO THE SOFTWARE. 6. Limitation of Liability. The Umbraco Deli Vendor's entire liability and your exclusive remedy under this EULA shall not exceed the price paid for the Software, if any. In no event shall the Umbraco Deli Vendor or Umbraco I/S be liable to you for any consequential, special, incidental or indirect damages of any kind arising out of the use or inability to use the software, even if the Umbraco Deli Vendor and Umbraco I/S or its supplier has been advised of the possibility of such damages, or any claim by a third party. 7. Rental. You may not loan, rent, or lease the SOFTWARE. 8. Upgrades. If the SOFTWARE is an upgrade from an earlier release or previously released version, you now may use that upgraded product only in accordance with this EULA. If the

PDF Creator for Umbraco 2.0

Page 15

UMBRACO DELI PACKAGE is an upgrade of a software program which you licensed as a single product, the UMBRACO DELI PACKAGE may be used only as part of that single product package and may not be separated for use on more than Umbraco site. 9. Product Support. Product support for the UMBRACO DELI PACKAGE IS provided by the Umbraco Deli Vendor and not Umbraco I/S. For product support, please contact the Umbraco Deli Vendor using the appropriate online support request forms. 10. No Liability for Consequential Damages. In no event shall the Umbraco Deli Vendor or Umbraco I/S be liable for any damages whatsoever (including, without limitation, incidental, direct, indirect special and consequential damages, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use or inability to use this "Your Company" product, even if the Umbraco Deli Vendor and Umbraco I/S has been advised of the possibility of such damages. Because some states/countries do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you. 11. Indemnification By You. If you distribute the Software in violation of this Agreement, you agree to indemnify, hold harmless and defend the Umbraco Deli Vendor and Umbraco I/S from and against any claims or lawsuits, including attorney's fees that arise or result from the use or distribution of the Software in violation of this Agreement. Umbraco I/S Lindholm havnevej 31 DK-5800 Nyborg Denmark

PDF Creator for Umbraco 2.0

Page 16