ÿþ<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>HTML to PDF Converter for .NET</title> <link href="styles/styles.css" rel="stylesheet" type="text/css"> <link href="styles/csharp.css" rel="stylesheet" type="text/css"> </head> <body> <div style="width: 1024px"> <table width="100%"> <tr> <td colspan="2" style="height: 62px"> <!-- Header --> <table style="width: 100%"> <tr> <td style="width: 707px"> </td> <td> <img src="images/logo.jpg" height="50" /> </td> </tr> </table> </td> </tr> <tr> <td style="width: 5%"> </td> <td style="width: 95%"> <!-- Content --> <table width="90%"> <tr> <td style="height: 189px;"> </td> </tr> <tr> <td style="height: 40px;"> <span class="doctitle">Winnovative HTML to PDF Converter for .NET</span>&nbsp; </td> </tr> <tr> <td style="height: 33px;"> </td> </tr> <tr> <td> <span class="title1">Developer s Manual</span><br /> </td> </tr> <tr> <td style="height: 77px"> </td> </tr> <tr> <td> <table> <tr> <td style="width: 73px"> </td> <td> <a href="http://www.winnovative-software.com"> <img style="border-style: none" src="images/html-to-pdf-box.jpg" height="500" /></a> </td> </tr> </table> </td> </tr> <tr> <td> </td> </tr> <tr> <td style="height: 22px"> </td> </tr> <tr style="page-break-before: always"> <td class="title1" style="height: 23px"> <a name="TOC" class="bookmark">Table of Contents</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <table> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#Introduction">1. Introduction </a> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#Installation">2. Installation </a> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#Requirements">3. Requirements </a> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#API">4. Converter API </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> <a class="title4" href="#PdfConverterClass">4.1 PdfConverter Class</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PdfConverterRenderMethods">4.1.1 PdfConverter Save/Render Methods</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PdfConverterConfiguration">4.1.2 PdfConverter Configuration Properties</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> <a class="title4" href="#ImgConverterClass">4.2 ImgConverter Class</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#ImgConverterRenderMethods">4.2.1 ImgConverter Save/Render Methods</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#ImgConverterConfiguration">4.2.2 ImgConverter Configuration Properties</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#Features">5. Features </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> <a class="title4" href="#HeaderAndFooter">5.1 Headers and Footers</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PredefinedHeaderAndFooter">5.1.1 Predefined Header and Footer Elements </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#CustomHeaderAndFooter">5.1.2 Custom Header and Footer Elements </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#SecurityOptions">5.2 Security Options</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#DocumentDescription">5.3 Document Description</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#PageBreaks">5.4 Automatic and Custom Page Breaks, Keep Together</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#LiveLinks">5.5 Live HTTP Links</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#MergeCapabilities">5.6 Merge Capabilities</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#ClientScripts">5.7 Enable/Disable Client Scripts and ActiveX from HTML Page</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#ServerAuthentication">5.8 Server Authentication</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#CustomPageSize">5.9 Custom PDF Page Size</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#Bookmarks">5.10 Bookmarks</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#InternalLinks">5.11 Internal Links in PDF</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#JpegCompression">5.12 Jpeg Compression of Images in PDF</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#HtmlMapping">5.13 Retrieve HTML Elements Mapping to PDF</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#RepeatTableHead">5.14 Repeat HTML Table Head on Each PDF Page </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#ExcludedRegion">5.15 Exclude a HTML Region from Conversion </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#SelectPdfStandard">5.16 Select PDF Standard</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#SelectColorSpace">5.17 Select Color Space</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#FineControl">5.18 Fine Control of HTML to PDF Conversion</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#ConversionSummary">5.19 Conversion Summary</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#PostConvert">5.20 Post Convert Customization of the Generated PDF Document</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4" class="title4"> <a class="title4" href="#Multithreading">5.21 Multithreading Support</a> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#AdvancedFeatures">6. Advanced Post Convert Customization of the Generated PDF Document </a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> <a class="title4" href="#PostConvertOverview">6.1 Post Convert Customization Overview</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td colspan="4"> <a class="title4" href="#CoordinatesSystem">6.2 Coordinates System and Graphic Units</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td class="title4" colspan="4"> <a class="title4" href="#DocumentClass">6.3 Document Class</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td class="title4" colspan="4"> <a class="title4" href="#PdfRenderers">6.4 PDF Renderers</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PdfPageClass">6.4.1 PdfPage Class</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#TemplateClass">6.4.2 Template Class</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#PredefinedTemplates">6.4.2.1 Predefined Templates</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#CustomTemplates">6.4.2.2 Custom Templates</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td class="title4" colspan="4"> <a class="title4" href="#PageElements">6.5 PDF Page Elements</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PageGraphicElements">6.5.1 Page Graphic Elements</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#HtmlToPdfElement">6.5.1.1 HTML to PDF Converter Element</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfPageBreaks">6.5.1.1.1 Page Breaks, Keep Together</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfLiveLinks">6.5.1.1.2 Live HTTP Links</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfClientScripts">6.5.1.1.3 Enable/Disable Client Scripts and ActiveX/Flash from HTML Page</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfAuthentication">6.5.1.1.4 Server Authentication</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfBookmarks">6.5.1.1.5 Bookmarks</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfInternalLinks">6.5.1.1.6 Internal Links in PDF</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="1"> <a class="title4" href="#HtmlToPdfHtmlMapping">6.5.1.1.7 Retrieve HTML Elements Mapping to PDF</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#HtmlToImageElement">6.5.1.2 HTML to Image Converter Element</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#RtfToPdfElement">6.5.1.3 RTF to PDF Converter Element</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#TextElement">6.5.1.4 Text Element And Fonts</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#ImageElement">6.5.1.5 Image Element</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#ShapeElements">6.5.1.6 Shape Elements</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="3"> <a class="title4" href="#PageInteractiveElements">6.5.2 Page Interactive Elements</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#DigitalSignatureElement">6.5.2.1 Digital Signature Element</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td style="width: 63px"> </td> <td class="title4" colspan="2"> <a class="title4" href="#OtherInteractiveElements">6.5.2.2 Other Interactive Page Elements</a> </td> </tr> <tr> <td style="width: 63px"> </td> <td class="title4" colspan="4"> <a class="title4" href="#Bookmarks">6.6 Bookmarks</a> </td> </tr> <tr> <td colspan="5" style="height: 30px"> <a class="contents" href="#Licensing">7. Licensing </a> </td> </tr> </table> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr style="page-break-before: always"> <td style="height: 23px" class="title2"> <a name="Introduction" class="bookmark">1. Introduction</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> The Winnovative HTML to PDF Converter for .NET consists in a .NET library that can be used directly in any .NET application (ASP.NET, Windows Forms, Console, Web Services, Windows Services, etc). The converter does not require any installation and it does not use any printer driver to perform conversion. It's just an assembly that you can directly link with your .NET application. The full HTML / CSS set is supported and the main goal of the converter is to preserve unchanged the original aspect of the converted HTML page.<br /> <br /> It can be used as general purpose tool for converting web pages and HTML code to PDF or as part of our Reporting Toolkit for .NET to easily create PDF reports directly from ASP.NET pages. If you think that the converted ASP.NET page can contain your preferred server controls like charts, barcodes, data bound control like data grids and repeaters you can realize how powerful this tool can be.<br /> <br /> The converter API offers methods to convert a web page from a specified URL to PDF or a specified HTML string. Additionally you can convert web pages and HTML code to images in any format supported by .NET framework (BMP, JPEG, PNG, GIF, etc).&nbsp;<br /> <br /> If you want to get started immediately without reading the next sections of this document this is something perfectly possible. First you have to add a reference to the converter library assembly <em><strong>wnvhtmlconvert.dll</strong></em> in your .NET or ASP.NET project. Then you have to add the following two lines of code in your application. The first one will import the converter namespace and the second one will call the converter to render the web page from the specified url as an array of bytes representing the resulted PDF document:<br /> <br /> <table> <tr> <td style="width: 89px"> </td> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="lnum">1: </span><span class="kwrd">using</span> Winnovative.WnvHtmlConvert; </pre> <pre><span class="lnum">2: </span><span class="kwrd">byte</span>[] pdfBytes = <span class="kwrd">new</span> PdfConverter().GetPdfFromUrlBytes(url);</pre> </div> </td> </tr> </table> <br /> Further you can save the PDF document bytes into a file on disk or you can send the bytes as a response to the client browser. We provide full sample applications, both in C# and VB.NET to exemplify both situations.<br /> <br /> The code above will produce a PDF document based on the default settings of the library which is enough for the most of the situations. However, the converter library offers a large number of parameters that you can set to customize the conversion process. You can add headers and footers with text and images to the resulted PDF document, specify page orientation, page size, compression level of the resulted PDF document, encrypt the resulted document and set user and owner password, set the permissions for printing&nbsp; </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title2"> <a name="Installation" class="bookmark">2. Installation</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; text-align: justify" dir="ltr"> The Winnovative HTML to PDF Converter for .NET 2.0 is delivered as a zip archive and it doesn't have an installer. You have to unzip the archive in a folder on the disk. Below is a brief description of the folders from the archive.<br /> <br /> <span class="subtitle2">2.1 Bin Folder</span><br /> <br /> <em>Bin</em> folder contains the .NET 2.0 assemblies you can use in your application and two prebuilt Windows Forms sample applications that you can use to quickly check if the converter can run correctly in your environment. <br /> <br /> <em>wnvhtmlconvert.dll</em> - is the HTML to PDF converter library that you can link in any .NET application, either Windows Forms or ASP.NET. <br /> <em>wnvhtmlconvert.xml</em> - is the HTML to PDF converter API reference in XML format for Visual Studio IntelliSense. <br /> <em>ConverterDemoApp.exe</em> - is a win32 application that can be used to convert a web page from a specified URL or HTML file from disk to PDF or Image<br /> <br /> <span class="subtitle2">2.1&nbsp; Doc Folder<br /> </span> <br /> <em>Doc</em> folder contains the HTML to PDF Converter manual and the API reference in chm and html format.<br /> <br /> <em>WnvHtmlConvert.chm</em> - contains the HTML to PDF converter library API reference<br /> <br /> <em>HTML folder</em> - contains the API reference both for the library and the ASP.NET control in html format<br /> <br /> <em>Developer's Manual.pdf and Developer's Manual.htm</em> - contain this manual in PDF and HTML formats<br /> <br /> <span class="subtitle2">2.1&nbsp; &nbsp;Samples Folder<br /> </span> <br /> <em>Samples</em> folder contains C# and VB.NET full sample applications to offer you ready to use code for ASP.NET, Windows Forms and console applications. Each sample has a solution file .sln that you can directly open in Visual Studio 2005 or in Visual Studio 2008. <br /> <br /> <em>AspNet_GettingStarted</em> - is an ASP.NET application which shows how to convert web pages and HTML code to PDF and images. The application uses the HTML to PDF Converter library with the default settings. <br /> <br /> <em>AspNet_InvoicesDemo</em> - is an ASP.NET application which shows how to dynamically generate PDF invoices from a ASP.NET page. The application uses the HTML to PDF Converter library to convert a HTML string to PDF. <br /> <br /> <em>AspNet_HtmlConvertDemo</em> - is an ASP.NET application which shows how to convert web pages and HTML code to PDF and images. The application uses the HTML to PDF Converter library and shows you how to set various conversion parameters like the headers and footers, page size, page orientation, compression level, etc. <br /> <br /> <em>HtmlElementsLocationInPdf</em> - is an ASP.NET application which shows how to retrieve the location in PDF of various HTML elements. <br /> <br /> <em>MultipleHtmlConversions</em> - is an ASP.NET application which shows how to convert many HTML document into the same PDF document. <br /> <br /> <em>TableOfContentsAndBookmarks</em> - is an ASP.NET application which shows how to automatically create a table of contents in the generated PDF document. <br /> <br /> <em>RepeatTableHeadOnEachPage</em> - is an ASP.NET application which shows how to automatically repeat the head of a HTML table on each PDF page where the table is rendered.. <br /> <br /> <em>WinForms_HtmlConverterFeaturesDemo</em> - is a Windows Forms application which shows how to convert web pages and HTML code to PDF and images. The application uses the HTML to PDF Converter library and shows you how to set various conversion parameters like the headers and footers, page size, page orientation, compression level, etc.<br /> <br /> <em>WinForms_NavigateAndConvertDemo</em> - is a Windows Forms application which shows how to convert web pages and HTML code to PDF while you are navigating in Internet. The application uses the HTML to PDF Converter library. Using this application it is possible to convert pages from websites requiring authentication at application level implemented with a custom login page.<br /> <br /> <em>WinForms_HtmlInHeaderAndFooter</em> - is a Windows Forms application which shows how to add HTML in header and footer of the rendered PDF document. Here you can also find code to add page numbers in footer.<br /> <br /> <em>WinForms_PrependAppendExternalPdfs</em> - is a C# Windows Forms application which shows how to convert many URLs into the same PDF document.<br /> <br /> <em>WinForms_HtmlElementsLocationInPdf</em> - is a C# Windows Forms application which shows how to retrieve the location in PDF of various HTML elements.<br /> <br /> <em>WinForms_MultipleHtmlConversions</em> - is a C# Windows Forms application which shows how to convert many HTML document into the same PDF document.<br /> <br /> <em>WinForms_TableOfContentsAndBookmarks</em> - is a C# Windows Forms application which shows how to automatically create a table of contents in the generated PDF document.<br /> <br /> <em>WinForms_RepeatTableHeadOnEachPage</em> - is a C# Windows Forms application which shows how to automatically repeat the head of a HTML table on each PDF page where the table is rendered.<br /> <br /> <em>Console_HtmlConvertDemo</em> - is a Console application which shows how to convert web pages and HTML code to PDF and images. The application uses the HTML to PDF Converter library and shows you how to set various conversion parameters like the headers and footers, page size, page orientation, compression level, etc.&nbsp;<br /> <br /> <em>Console_BatchConversion</em> - is a Console application which shows how to use the converter to convert to PDF documents all the HTML files from a specified folder and its subfolders&nbsp;<br /> <br /> <em>Console_MultithreadedPerformance</em> - is a Console application which can be used to measure the performance of the converter in a multithreaded environment.<br /> <br /> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title2"> <a name="Requirements" class="bookmark">3. Requirements and Recommendations</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The recommended hardware and software resources for successfully running the Winnovative HTML to PDF converter for .NET are listed below. Basically this is the environment we used for testing the product. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> <span class="subtitle2"></span><em>Operating System</em>: Windows XP, Windows 2003 Server, Windows Vista, Windows Server 2008, Windows 7, Windows Server 2008 R2<br /> <em>Hardware Architecture</em>: 32-bit, 64-bit<br /> <em>Free RAM</em>: 1GB<br /> Microsoft .NET Framework 2.0<br /> Full trust level when used in ASP.NET applications </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title2"> <a name="API" class="bookmark">4. Converter API</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter API is fully documented in the Doc/WnvHtmlConvert.chm . In order to use the converter library you have include the Winnovative.WnvHtmlConvert namespace in your application. The main classes in this namespace is the PdfConverter class and the ImgConverter class which expose the methods you can use to render a PDF document or an image from a URL or a HTML string. Below is a brief description of the main classes and properties of the converter. </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a class="bookmark" name="PdfConverterClass">4.1 PdfConverter Class</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> This class defines a set of methods to render a PDF document from a URL or from a HTML string. The conversion result can be a stream of bytes as byte[] object or a file on the disk. The PDF bytes can be further saved in a disk file or can be send a HTTP response to the client browser.&nbsp;<br /> <br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a class="bookmark" name="PdfConverterRenderMethods">4.1.1 PdfConverter Save/Render Methods</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The method below converts the URL specified as parameter to a PDF document returned as bytes array. The bytes array can be sent to a web browser from an ASP.NET application, saved in a file on disk or into a database or sent by email as an attachment. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetPdfFromUrlBytes ( <span class="kwrd">string</span> url )</pre> </div> </td> </tr> <tr> <td style="height: 23px"> To convert a HTML string to PDF you can use one of the following methods below. The first method simply renders the HTML string as a PDF document. The second one accepts an additional parameter <em>urlBase</em> which is the full URL of the page from where you have retrieved the HTML string. The<em> urlBase</em> parameter is a hint for the converter which is used to determine the full URL of the images and other external files like CSS and JavaScript referenced in the HTML string by a relative URL. If you don't set this parameter the images referenced by relative URLS won't appear in the document and the styles from external CSS files won't be applied to the rendered document. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetPdfBytesFromHtmlString (<span class="kwrd">string</span> htmlString)</pre> <pre><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetPdfBytesFromHtmlString (<span class="kwrd">string</span> htmlString,<span class="kwrd">string</span> urlBase)</pre> <pre class="alt">&nbsp;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The correspondent methods you can use to render the PDF document in disk file are listed below. These methods internally use the methods above to get the bytes array and then they simply save the bytes in the specified file on disk. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromUrlToFile (<span class="kwrd">string</span> url, <span class="kwrd">string</span> outFile)<br /></pre> <pre><span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStringToFile (<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> outFile)</pre> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStringToFile (<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> outFile, <span class="kwrd">string</span> urlBase)</pre> <pre>&nbsp;</pre> <pre class="alt">&nbsp;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The methods above first obtain the PDF document as a byte array and then simply return that array of bytes or save it in a file. There is a set of methods which can save the PDF document directly into a stream without storing it first in the memory. The name of these methods have the <i>ToStream</i> suffix instead of the <i>ToFile</i> suffix from the set of Save methods prototyped above: </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromUrlToStream(<span class="kwrd">string</span> url, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromUrlToStream(<span class="kwrd">string</span> url, <span class="kwrd">string</span> internalLinksDocUrl, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlFileToStream(<span class="kwrd">string</span> htmlFilePath, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlFileToStream(<span class="kwrd">string</span> htmlFilePath, <span class="kwrd">string</span> internalLinksDocUrl, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStringToStream(<span class="kwrd">string</span> htmlString, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStringToStream(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStringToStream(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream, Encoding streamEncoding, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase, Stream outPdfStream) <span class="kwrd">public</span> <span class="kwrd">void</span> SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl, Stream outPdfStream) </pre> </td> </tr> <tr> <td style="height: 23px"> There is also a set of methods returning a Document object that can be used to further modify the generated PDF document as described in the <a href="#PostConvert">Post Convert Customization of the Generated PDF Document</a> section by adding new PDF pages and new PDF elements to the document. The Document class and the elements that can be added to a Document object are defined in the <i>Winnovative.WnvHtmlConvert.PdfDocument</i> namespace. </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">public</span> Document GetPdfDocumentObjectFromUrl(<span class="kwrd">string</span> url) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromUrl(<span class="kwrd">string</span> url, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlFile(<span class="kwrd">string</span> htmlFilePath) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlFile(<span class="kwrd">string</span> htmlFilePath, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl) </pre> </td> </tr> <tr> <td style="height: 23px"> The generated Document object can be modified and then saved into memory, file or stream using one of the Save methods of the Doocument class. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a class="bookmark" name="PdfConverterConfiguration">4.1.2 PdfConverter Configuration Properties</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The conversion process and the aspect of the generated PDF document can be configured in many ways. You can set the PDF document page size (A4, A3, etc), orientation (Portrait or Landscape), compression level, encryption and passwords, document info (author, title, subject, etc), add headers and footers with page numbering, etc. The main properties of the converter are listed below. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> To set the license key you received after purchase and unlock the product you can use the <em>LicenseKey</em> property. If this property is not set with any value the converter will enter in demo mode. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">string</span> LicenseKey { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The <em>PageWidth</em> and <em>PageHeight</em> properties allows you to set the width and height of the virtual browser windows. The web page content is rendered based on the virtual browser width specified as a integer value in pixels. Setting these properties has the same effect as the effect produced when resizing a web page in a browser window to the specified dimensions. <br /> <br /> The default value of the PageWidth property is 1024 pixels. The default value of the PageHeight property is 0 pixels which means the height will be automatically determined. These values are producing good results in most of the cases but there are also some situations when you'll have to change these properties. You can also choose to let the converter autodetermine both the width and height of the virtual browser by setting both PageWidth and Page Height properties to 0.<br /> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">int</span> PageWidth { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">int</span> PageHeight { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The <em>PdfDocumentOptions</em> property allows you to change the aspect and properties of the rendered PDF document like setting the margins, add header and footer, embed true type fonts, generate a document with selectable texts and images or a document with an embedded image, enable or disable live links, pdf page size and page orientation, compression level, show or hide the headers and footers.&nbsp;<br /> <br /> This property exposes an object of <em>PdfDocumentOptions</em> type which is automatically created in the <em>PdfConverter</em> constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfDocumentOptions object. <br /> <br /> The main properties of the PdfDocumentOptions class are described in a later section.<br /> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> PdfDocumentOptions PdfDocumentOptions { get; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The <em>PdfSecurityOptions</em> class property allows you to change the permissions of the rendered PDF document like allow or disallow printing, etiding, etc and also to set user and owner passwords.<br /> <br /> This property exposes an object of <em>PdfSecurityOptions</em> type which is automatically created in the <em>PdfConverter</em> constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfDocumentOptions object. <br /> <br /> The main properties of the PdfDocumentOptions class are described in a later section.<br /> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> PdfSecurityOptions PdfSecurityOptions { get; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The <em>PdfDocumentInfo</em> property allows you to set the rendered PDF description like title, author, subject, keywords, etc. <br /> <br /> This property exposes an object of <em>PdfSecurityOptions</em> type which is automatically created in the <em>PdfConverter</em> constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfDocumentOptions object. <br /> <br /> The main properties of the PdfDocumentOptions class are described in a later section.<br /> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> PdfDocumentInfo PdfDocumentInfo { get; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The <em>PdfHeaderOptions</em> and <em>PdfFooterOptions</em> properties allows you to customize the aspect of the headers and footers added to the rendered PDF document. Note that the header and footer are visible in the resulted PDF document only if the corresponding <em>ShowHeader</em> and <em>ShowFooter</em> properties from the <em>PdfDocumentOptions</em> property are true.<br /> <br /> These properties expose objects of <em>PdfHeaderOptions</em> type and <em>PdfFooterOptions</em> type which are automatically created in the <em>PdfConverter</em> constructor. Therefore you don't have to set this property directly with a value from your code but you'll have to set the properties of the exposed PdfHeaderOptions and PdfFooterOptions object. <br /> <br /> The main properties of the PdfHeadersOptions and PdfFooterOptions classes are described in a later section.<br /> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> PdfHeaderOptions PdfHeaderOptions { get; }</pre> <pre><span class="kwrd">public</span> PdfFooterOptions PdfFooterOptions { get; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a class="bookmark" name="ImgConverterClass">4.2 ImgConverter Class</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> This class defines a set of methods to render a image from a URL or from a HTML string. The conversion result can be a stream of bytes as byte[] object or a file on the disk. The image bytes can be further saved in a disk file or can be send a HTTP response to the client browser.&nbsp;<br /> <br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a class="bookmark" name="ImgConverterRenderMethods">4.2.1 ImgConverter Save/Render Methods</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The method below retrieves the image bytes from a URL. There is also a similar method which produces an System.Drawing.Image object from a specified URL. The second parameter allows you to specify the format of the resulted image as a value from the System.Drawing.Imaging.ImageFormat enumeration.<br /> <br /> The URL must be anonymously accessible from the computer running your application otherwise a <em>'<span style="font-family: Arial">Get web page content cancelled or invalid URL supplied</span></em>' exception is thrown by the converter. The best way to debug this type of exception is to load the URL in the Internet Explorer browser running on the same machine with your application and see if the page is correctly loaded. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetImageFromUrlBytes (<span class="kwrd">string</span> url,ImageFormat format)</pre> <pre><span class="kwrd">public</span> Image GetImageFromUrl (<span class="kwrd">string</span> url,ImageFormat format)</pre> <pre class="alt">&nbsp;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> To convert a HTML string to image you can use one of the following methods below. The first method simply renders the HTML string as a Image object or as a byte[]. The second one accepts an additional parameter <em>urlBase</em> which is the full URL of the page from where you have retrieved the HTML string. The<em> urlBase</em> parameter is a hint for the converter which is used to determine the full URL of the images and other external files like CSS and JavaScript referenced in the HTML string by a relative URL. If you don't set this parameter the images referenced by relative URLS won't appear in the document and the styles from external CSS files won't be applied to the rendered image.<br /> <br /> You can notice there are similar methods producing a System.Drawing.Image object instead of a byte[]. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> Image GetImageFromHtmlString (<span class="kwrd">string</span> htmlString,ImageFormat format)</pre> <pre><span class="kwrd">public</span> Image GetImageFromHtmlString (<span class="kwrd">string</span> htmlString,ImageFormat format,<span class="kwrd">string</span> urlBase)</pre> <pre class="alt">&nbsp;</pre> <pre><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetImageBytesFromHtmlString (<span class="kwrd">string</span> htmlString,ImageFormat format)</pre> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">byte</span>[] GetImageBytesFromHtmlString (<span class="kwrd">string</span> htmlString,ImageFormat format,<span class="kwrd">string</span> urlBase)</pre> <pre>&nbsp;</pre> <pre class="alt">&nbsp;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The correspondent methods you can use to render the image in disk file are listed below. These methods internally use the methods above to get the bytes array and then they simply save the bytes in the specified file on disk. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">void</span> SaveImageFromUrlToFile (<span class="kwrd">string</span> url, ImageFormat format, <span class="kwrd">string</span> outFile)</pre> <pre>&nbsp;</pre> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">void</span> SaveImageFromHtmlStringToFile (<span class="kwrd">string</span> htmlString, ImageFormat format, <span class="kwrd">string</span> outFile)</pre> <pre><span class="kwrd">public</span> <span class="kwrd">void</span> SaveImageFromHtmlStringToFile (<span class="kwrd">string</span> htmlString, ImageFormat format, <span class="kwrd">string</span> outFile, <span class="kwrd">string</span> urlBase)</pre> <pre class="alt">&nbsp;</pre> <pre>&nbsp;</pre> </div> In the full API reference document you'll notice some other similar methods for converting a HTML stream to image or a HTML file to image file but they are derived from the methods described above and in the most of the cases you won't need them. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a class="bookmark" name="ImgConverterConfiguration">4.2.2 ImgConverter Configuration Properties</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The conversion process and the aspect of the generated image can be configured with the configuration properties below. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> To set the license key you received after purchase and unlock the product you can use the <em>LicenseKey</em> property. If this property is not set with any value the converter will enter in demo mode. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">string</span> LicenseKey { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The <em>PageWidth</em> and <em>PageHeight</em> properties allows you to set the width and height of the virtual browser windows. The web page content is rendered based on the virtual browser width specified as a integer value in pixels. Setting these properties has the same effect as the effect produced when resizing a web page in a browser window to the specified dimensions. <br /> <br /> The default value of the PageWidth property is 1024 pixels. The default value of the PageHeight property is 0 pixels which means the height will be automatically determined. These values are producing good results in most of the cases but there are also some situations when you'll have to change these properties. You can also choose to let the converter auto determine both the width and height of the virtual browser by setting both PageWidth and Page Height properties to 0.<br /> </td> </tr> <tr> <td style="height: 24px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">int</span> PageWidth { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">int</span> PageHeight { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title2"> <a name="Features" class="bookmark">5. Features</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> In this section will be described the main features of the converter with code samples for each feature. </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="HeaderAndFooter" class="bookmark">5.1 Headers and Footers</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 17px"> In order to show or hide the header or footer on the rendered document you have to set the ShowHeader and ShowFooter properties of the PdfDocumentOptions property of the PdfConverter class. For example, to add both footer and header to the generated document you can use the following code: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt">PdfConverter pdfConverter = <span class="kwrd">new</span> PdfConverter();</pre> <pre>pdfConverter.PdfDocumentOptions.ShowHeader = <span class="kwrd">true</span>;</pre> <pre class="alt">pdfConverter.PdfDocumentOptions.ShowFooter = <span class="kwrd">true</span>;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The aspect of the header and footer can be controlled with the PdfHeaderOptions and PdfFooterOptions properties of the PdfConverter object. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td class="title4" style="height: 23px"> <a name="PredefinedHeaderAndFooter" class="bookmark">5.1.1 Predefined Header and Footer Elements</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> For the header you can set a title and a subtitle, add a image in a specified position and draw a horizontal line under the header, change the text font and size, change the background color of the header. Below you can see a sample code to set the header options: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 17px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; pdfConverter.PdfHeaderOptions.HeaderBackColor = Color.WhiteSmoke;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderHeight = 50;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderText = <span class="str"> "Title"</span>;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderTextColor = Color.Black;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderTextFontType = PdfFontType.Helvetica;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderTextFontSize = 18;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderTextYLocation = 5;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderSubtitleText = <span class="str"> "Subtitle"</span>;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderSubtitleTextColor = Color.Black;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderSubtitleTextFontType = PdfFontType.Helvetica;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderSubtitleTextFontSize = 12;</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderTitleSubtitleYSpacing = 7;</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.HeaderImageLocation = <span class="kwrd">new</span> PointF(0, 0);</pre> <pre> pdfConverter.PdfHeaderOptions.HeaderImage = Image.FromFile(logoImageFullPath);</pre> <pre class="alt"> pdfConverter.PdfHeaderOptions.DrawHeaderLine = <span class="kwrd">true</span>;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> The dimensions are specified in points and a point is 1/72 inches. The A4 page size in points is 595x842. At a screen resolution of 96 dpi, a A4 PDF page has 794 pixels in width and 1123 pixels in height. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> For the footer you can set the text, to show or not the page numbering, the text that appears before the page number, the font text and color, the footer background color and to draw or not a line above the footer. Below you can see a sample code to set the footer options: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> pdfConverter.PdfFooterOptions.FooterText = <span class="str"> "Footer text"</span>;</pre> <pre> pdfConverter.PdfFooterOptions.FooterBackColor = Color.WhiteSmoke;</pre> <pre class="alt"> pdfConverter.PdfFooterOptions.FooterHeight = 40;</pre> <pre> pdfConverter.PdfFooterOptions.FooterTextColor = Color.Black;</pre> <pre class="alt"> pdfConverter.PdfFooterOptions.FooterTextFontType = PdfFontType.HelveticaOblique;</pre> <pre> pdfConverter.PdfFooterOptions.FooterTextFontSize = 8;</pre> <pre class="alt"> pdfConverter.PdfFooterOptions.DrawFooterLine = <span class="kwrd">true</span>;</pre> <pre> pdfConverter.PdfFooterOptions.PageNumberText = <span class="str">"Page"</span>;</pre> <pre class="alt"> pdfConverter.PdfFooterOptions.PageNumberTextColor = Color.Black;</pre> <pre> pdfConverter.PdfFooterOptions.PageNumberTextFontType = PdfFontType.HelveticaBold;</pre> <pre class="alt"> pdfConverter.PdfFooterOptions.PageNumberTextFontSize = 10;</pre> <pre> pdfConverter.PdfFooterOptions.ShowPageNumber = <span class="kwrd">true</span>;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The dimensions are specified in points and a point is 1/72 inches. The A4 page size in points is 595x842. At a screen resolution of 96 dpi, a A4 PDF page has 794 pixels in width and 1123 pixels in height. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td class="title4" style="height: 23px"> <a name="CustomHeaderAndFooter" class="bookmark">5.1.2 Custom Header and Footer Elements</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> Besides the predefined elements like title, subtitle, page numbering the converter allows you add any number of custom elements like HtmlToPdfArea, ImageArea and TextArea that can be added in any position in the header and footer. <br /> <br /> The <i>PdfHeaderOptions</i> and <i>PdfFooterOptions</i> define a property for each type of object. For example the <i>HtmlToPdfArea</i> property can be initialized with a <i>HtmlToPdfArea</i> object that will be automatically rendered in the header or footer when the PDF document is generated. The same for the <i>TextArea</i> and <i>ImageArea</i> properties. However, the number of possible custom elements is not limited to one element of each type, it is possible to add any number of HtmmlToPdfArea, TextArea and ImageArea elements to the header and footer using the following methods of <i>PdfHeaderOptions</i> and <i>PdfFooterOptions</i>: </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">public</span> <span class="kwrd">void</span> AddHtmlToPdfArea(HtmlToPdfArea htmlToPdfArea) <span class="kwrd">public</span> <span class="kwrd">void</span> AddImageArea(ImageArea imageArea) <span class="kwrd">public</span> <span class="kwrd">void</span> AddTextArea(TextArea textArea) </pre> </td> </tr> <tr> <td style="height: 23px"> The <i>Page Numbering</i> can also be added in position in the header and footer as a TextArea element containing &p; and &P; placeholders for current page number and total number of pages. </td> </tr> <tr> <td style="height: 23px"> Bellow is a complete example for adding HTML in header and footer and page numbering in footer. The code was taken from the Getting Started sample application for ASP.NET: </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">private</span> <span class="kwrd">void</span> AddHeader(PdfConverter pdfConverter) { <span class="kwrd">string</span> thisPageURL = HttpContext.Current.Request.Url.AbsoluteUri; <span class="kwrd">string</span> headerAndFooterHtmlUrl = thisPageURL.Substring(0, thisPageURL.LastIndexOf(<span class="str">'/'</span>)) + <span class="str">"/HeaderAndFooterHtml.htm"</span>; <span class="rem">//enable header</span> pdfConverter.PdfDocumentOptions.ShowHeader = <span class="kwrd">true</span>; <span class="rem">// set the header height in points</span> pdfConverter.PdfHeaderOptions.HeaderHeight = 60; <span class="rem">// set the header HTML area</span> pdfConverter.PdfHeaderOptions.HtmlToPdfArea = <span class="kwrd">new</span> HtmlToPdfArea(headerAndFooterHtmlUrl); pdfConverter.PdfHeaderOptions.HtmlToPdfArea.EmbedFonts = cbEmbedFonts.Checked; } <span class="kwrd">private</span> <span class="kwrd">void</span> AddFooter(PdfConverter pdfConverter) { <span class="kwrd">string</span> thisPageURL = HttpContext.Current.Request.Url.AbsoluteUri; <span class="kwrd">string</span> headerAndFooterHtmlUrl = thisPageURL.Substring(0, thisPageURL.LastIndexOf(<span class="str">'/'</span>)) + <span class="str">"/HeaderAndFooterHtml.htm"</span>; <span class="rem">//enable footer</span> pdfConverter.PdfDocumentOptions.ShowFooter = <span class="kwrd">true</span>; <span class="rem">// set the footer height in points</span> pdfConverter.PdfFooterOptions.FooterHeight = 60; <span class="rem">//write the page number</span> pdfConverter.PdfFooterOptions.TextArea = <span class="kwrd">new</span> TextArea(0, 30, <span class="str">"This is page &amp;p; of &amp;P; "</span>, <span class="kwrd">new</span> System.Drawing.Font(<span class="kwrd">new</span> System.Drawing.FontFamily(<span class="str">"Times New Roman"</span>), 10, System.Drawing.GraphicsUnit.Point)); pdfConverter.PdfFooterOptions.TextArea.EmbedTextFont = <span class="kwrd">true</span>; pdfConverter.PdfFooterOptions.TextArea.TextAlign = HorizontalTextAlign.Right; <span class="rem">// set the footer HTML area</span> pdfConverter.PdfFooterOptions.HtmlToPdfArea = <span class="kwrd">new</span> HtmlToPdfArea(headerAndFooterHtmlUrl); pdfConverter.PdfFooterOptions.HtmlToPdfArea.EmbedFonts = cbEmbedFonts.Checked; }</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="SecurityOptions" class="bookmark">5.2 Security Options</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> With the security options you have the possibility to allow or disallow printing, editing, copying, filling form fields, set a user password and an owner password. When you set a user password the PDF document is encrypted and that password will be asked by the PDF viewer in order to open the PDF document. When you set the owner password that password will be required when someone wants to change the PDF permissions. Below you can see a sample code which you can use to set the security options of the generated </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> pdfConverter.PdfSecurityOptions.CanCopyContent = <span class="kwrd">true</span>;</pre> <pre> pdfConverter.PdfSecurityOptions.CanEditContent = <span class="kwrd"> true</span>;</pre> <pre class="alt"> pdfConverter.PdfSecurityOptions.CanFillFormFields = <span class="kwrd">true</span>;</pre> <pre> pdfConverter.PdfSecurityOptions.CanPrint = <span class="kwrd">true</span>;</pre> <pre class="alt"> pdfConverter.PdfSecurityOptions.CanEditAnnotations = <span class="kwrd">true</span>;</pre> <pre> pdfConverter.PdfSecurityOptions.CanAssembleDocument = <span class="kwrd"> true</span>;</pre> <pre class="alt">&nbsp;</pre> <pre> pdfConverter.PdfSecurityOptions.KeySize = EncryptionKeySize.EncryptKey128Bit;</pre> <pre class="alt"> pdfConverter.PdfSecurityOptions.UserPassword = <span class="str">"winnovative"</span>;</pre> <pre> pdfConverter.PdfSecurityOptions.OwnerPassword = <span class="str">""</span>;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="DocumentDescription" class="bookmark">5.3 Document Description</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> You can set the document description like author, title, subject, keyword using the PdfDocumentInfo property. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> pdfConverter.PdfDocumentInfo.AuthorName = <span class="str"> "Winnovative"</span>;</pre> <pre> pdfConverter.PdfDocumentInfo.Title = <span class="str">"PDF Document Info"</span>;</pre> <pre class="alt"> pdfConverter.PdfDocumentInfo.Subject = <span class="str"> "HTML to PDF Converter"</span>;</pre> <pre> pdfConverter.PdfDocumentInfo.Keywords = <span class="str">"HTML, PDF, Converter"</span>;</pre> <pre class="alt"> pdfConverter.PdfDocumentInfo.CreatedDate = DateTime.Now;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="PageBreaks" class="bookmark">5.4 Automatic and Custom Page Breaks, Keep Together</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter supports the following CSS styles to control the page breaks: page-break-before:always, page-break-after:always and page-break-inside:avoid. For example, with the page-break-after:always style applied to a HTML element (image, text, etc) you instruct the converter to insert a page break right after that element is rendered.<br /> <br /> By default the converter always tries to avoid breaking the text between PDF pages. You can disable this behavior using the PdfConverter.AvoidTextBreak property. Also you can enable the converter to avoid breaking the images between PDF pages using the PdfConverter.AvoidImageBreak . By default this property is false.<br /> <br /> An advanced and very useful feature when creating PDF reports is the Keep Together feature which can be implemented with the page-break-inside:avoid style. This instructs the converter to avoid breaking the content of a group of HTML elements you want to keep together on the same page. If you think you can apply this style to a table, a table row or a div element you can easily understand the utility of this feature. <br /> <br /> Below is an example of using the page-break-inside:avoid style. The table contains a large number of rows, each row containing an image in the left and a text in the right and we don't want a row to span on two pages. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">&lt;</span><span class="html">table</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">tr</span> <span class="attr">style</span><span class="kwrd">="page-break-inside : avoid"</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">img</span> <span class="attr">width</span><span class="kwrd">="100"</span> <span class="attr">height</span><span class="kwrd">="100"</span> <span class="attr">src</span><span class="kwrd">="img1.jpg"</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> My text 1</pre> <pre> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">tr</span><span class="kwrd">&gt;</span></pre> <pre> </pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">tr</span> <span class="attr">style</span><span class="kwrd">="page-break-inside : avoid"</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">img</span> <span class="attr">width</span><span class="kwrd">="100"</span> <span class="attr">height</span><span class="kwrd">="100"</span> <span class="attr">src</span><span class="kwrd">="img2.jpg"</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> My text 2</pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;/</span><span class="html">tr</span><span class="kwrd">&gt;</span></pre> <pre class="alt"><span class="kwrd">&lt;/</span><span class="html">table</span><span class="kwrd">&gt;</span></pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="LiveLinks" class="bookmark">5.5 Live HTTP Links</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter can convert any HTTP link from the HTML document into a link in the PDF document. This works on links containing text, image or any other combination supported by the HTML code. This is the default behavior of the converter. If you don't want to get active links in the generated PDF document you can set PdfConverter.PdfDocumentOptions.<span class="identifier">LiveUrlsEnabled</span> = false. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="MergeCapabilities" class="bookmark">5.6 Merge Capabilities</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The HTML to PDF Converter provides you with the possibility to append a PDF file or a list of PDF files to the conversion result. This possibility is available with the AppendPDFFile and AppendPDFFIleArray properties from PdfDocumentOptions class. The properties must be set before calling the PDF render method. There also available similar properties to append PDF streams instead of files. The prototypes of these properties are: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">string</span> AppendPDFFile { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">string</span>[] AppendPDFFileArray { get; set; }</pre> <pre class="alt"><span class="kwrd">public</span> Stream AppendPDFStream { get; set; }</pre> <pre><span class="kwrd">public</span> Stream[] AppendPDFStreamArray { get; set; }</pre> <pre class="alt">&nbsp;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> For more details please take a look a the WinForms_ConvertAndMergePdf sample application. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="ClientScripts" class="bookmark">5.7 Enable/Disable Client Scripts and ActiveX from HTML Page</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The JavaScript code and ActiveX controls are disabled by default in the converted page during conversion to a PDF with selectable texts and objects and enabled when converting to image. If you have JavaScript code that modifies the web page on the client you can instruct the converter to execute that JavaScript code. You can activate scripts both when rendering an image or a PDF document. The properties from PdfConverter class which allow you to activate the scripts when converting to PDF file are: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">bool</span> ScriptsEnabled { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">bool</span> ScriptsEnabledInImage { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="ServerAuthentication" class="bookmark">5.8 Server Authentication</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter offers support for any type of server authentication. For example the converter can handle <em>IIS authentication</em> types like Integrated <em>Windows Authentication</em> and <em>Basic Authentication</em>. The authentication is disabled by default. To enable authentication you have to set the <em><strong>AuthenticationOptions</strong></em> property of the PdfConverter object. Below you can find sample code for setting the username and password for authentication when converting HTML to PDF: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> pdfConverter.AuthenticationOptions.Username = username;</pre> <pre> pdfConverter.AuthenticationOptions.Password = password;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The properties of <em>ImgConverter</em> class which allow you to handle the authentication when converting HTML to images are: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">string</span> AuthenticationPassword { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">string</span> AuthenticationUsername { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="CustomPageSize" class="bookmark">5.9 Custom PDF Page Size</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter can produce PDF documents with pages of any size. The page size is controlled by the <em><strong>PdfConverter.PdfDocumentOptions.PdfPageSize</strong></em> property of type PdfPageSize. You can set this property to standard values like A4,A3,etc or to Custom. In this case the PDF page size will be given by the <em><strong> PdfConverter.PdfDocumentOptions.CustomPdfPageSize</strong></em> property. Below is a sample code for setting the converter to produce PDF pages with the width of 200 points and height of 300 points. A point is 1/72 inch. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt">pdfConverter.PdfDocumentOptions.CustomPdfPageSize = <span class="kwrd"> new</span> SizeF(200,300);</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> &nbsp;By default the custom size is set to a width of 595 and a height of 842 points which is the size of the A4 portrait page. When the page orientation is set to landscape the width and height values are inverted. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="Bookmarks" class="bookmark">5.10 Bookmarks</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter can produce bookmarks in the generated PDF document for a list of specified HTML tags. The bookmarking is controlled by the pdfConverter.PdfBookmarkOptions property and is enabled only when a list of HTML tag names is specified by the <strong> <em>pdfConverter.PdfBookmarkOptions.TagNames</em></strong> property. For example, to enable bookmarking of the H1 and H2 tags you can use the following line of C# code: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode">pdfConverter.PdfBookmarkOptions.TagNames = <span class="kwrd"> new</span> <span class="kwrd">string</span>[] { <span class="str">"H1"</span>, <span class="str">"H2"</span> };</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The tags to be bookmarked can be further filtered by CSS class name using the <strong> <em>pdfConverter.PdfBookmarkOptions.ClassNameFilter</em></strong> property. For example, to filter only the H1 and H2 tags having the CSS class bookmark, the following line of C# can be added to the previous one: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode">pdfConverter.PdfBookmarkOptions.ClassNameFilter = <span class="str"> "bookmark"</span>;</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The ClassNameFilter property is case sensitive and the string value set for this property must textually match the class attribute of the HTML tag to be bookmarked. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="InternalLinks" class="bookmark">5.11 Internal Links in PDF</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter automatically converts the HTML links with anchors found in the HTML document to internal links in PDF. This features can be used to easily create table of contents in the generated PDF document.<br /> <br /> A HTML link with anchor consists in two HTML elements : a link defined with by a <b><i>&lt;a href=&quot;#target&quot;&gt;Internal Link&lt;/a&gt;</i></b> tag and the target of the link defined by a&nbsp; <b><i>&lt;a name=&quot;target&quot;&gt;Link Target&lt;/a&gt;</i></b> tag. When the HTML to PDF converter finds this construction it automatically generates an internal link in PDF from &quot;Internal Link&quot; to &quot;Link Target&quot;.<br /> <br /> The generation of internal links can be disabled using the PdfConverter.InternalLinksEnabled = false.<br /> <br /> There are a few things to ensure in order to get the internal links correctly generated in the PDF document. When converting an URL to PDF the URL must be fully qualified. For example if a website MyWebsite has a default.aspx page with internal links which is automatically served by the web server when the address <a href="http://MyWebsite"> http://MyWebsite</a> is typed in the web browser address bar, then converting directly the <a href="http://MyWebsite">http://MyWebsite</a> url might not produce the correct internal links because the converter is unable to determine the web page automatically served by the web server. Instead, when converting <a href="http://MyWebsite/default.aspx"> http://MyWebsite/default.aspx</a> the internal links will always be correctly generated. The PdfConverter has a property <i>InternalLinksDocUrl</i> which allows you to specify the fully qualified URL referenced by the internal links before calling the converter method.<br /> <br /> When converting a HTML string to PDF it is recommended to always pass the baseUrl and <i>internalLinksDocUrl</i> parameters to the method used to convert the HTML string to PDF. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="JpegCompression" class="bookmark">5.12 JPEG Compression of Images in PDF</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="style1"> The converter automatically compresses the images generated in PDF using the JPEG compression algorithm to highly reduce the size of the generated PDF document. The JPEG compression reduces the quality of the images. When the JPEG compression level is increased the quality of the images in the PDF decreases. <br /> <br /> The PdfConverter.PdfDocumentOptions.JpegCompressionLevel property defines the current level used for JPEG compression on a scale from 0 to 100. When the compression level is 0 the compression is the worst and the image quality is the best. The default JPEG compression level used by the converter is 10 which offers a good balance between the images quality and the size of the generated PDF document.<br /> <br /> If you want to obtain the best image quality it is possible to completely disable the JPEG compression of the images by setting the PdfConverter.PdfDocumentOptions.JpegCompressionEnabled to false. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="HtmlMapping" class="bookmark">5.13 Retrieve HTML Elements Mapping to PDF</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> This is a very powerful feature of the converter which allows you to obtain the position in the generated PDF document for any HTML element. Knowing the position in the generated PDF document of any element from the HTML document allows you to create bookmarks for elements from the HTML document, create internal links between HTML elements, place texts or images over the HTML elements or assign a digital signature to a certain element from HTML.<br /> <br /> This feature can accessed using the PdfConverter.HtmlElementsMappingOptions property. This property allows you defined a list with HTML IDs of the HTML elements to for which you want to retrieve position using the <i>HtmlElementIds</i> property or a list with the HTML tag names of the HTML elements for which you want to retrieve position using the <i>HtmlTagNames</i> property. <br /> <br /> The HtmlElementsMappingOptions property must be set before calling the converter method.<br /> <br /> The HTML elements mapping is returned in the PdfConverter.HtmlElementsMappingOptions.HtmlElementsMappingResult. The HtmlElementsMapping result is a collection of HtmlElementMapping objects which offers the PDF page index where the element was mapped by the converter and the rectangle where the element was rendered inside that page, the element HTML ID, the element tag name, the element text and the element outer HTML code.&nbsp; <br /> <br /> A code sample showing how to use this feature to highlight a specified list of HTML elements in the generated PDF document is presented in the <a href="#AdvancedFeatures"> Advanced Post Convert Customization of the Generated PDF Document </a>section. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="RepeatTableHead" class="bookmark">5.14 Repeat HTML Table Head on Each PDF Page</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> The converter can be instructed to repeat the head of a HTML table on each PDF page where this table is rendered using the <b>display:table-header-group</b> style for the <b>thead</b> element of a HTML table. You can repeat the table head of any HTML table having a thead element if you define the following CSS style in your document: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> thead {display: table-header-group;}</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> This feature is useful for long HTML tables spanning on many PDF pages such that the reader of the document can always know to which column belongs the data in a PDF page. The <i>RepeatHtmlTableOnEachPage</i> sample contains a complete example for this feature. You can have anything in the repeated table head, from text and images to any other HTML code. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="ExcludedRegion" class="bookmark">5.15 Exclude a HTML Region from Conversion</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> The converter can be instructed to exclude HTML regions from the generated PDF document like HTML DIVs or tables. The HTML elements to be excluded can be identified by the HTML IDs of the elements or by the HTML tag names of the elements. The <i>PdfConverter.HtmlExcludedRegionsOptions</i> object of <i>HtmlExcludedRegionsOptions</i> type is used to specify the excluded regions. The <i>HtmlExcludedRegionsOptions</i> class has two properties <br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">public</span> <span class="kwrd">string</span>[] HtmlElementIds { get; set; } <span class="kwrd">public</span> <span class="kwrd">string</span>[] HtmlTagNames { get; set; }</pre> <br /> that can be used to define the HTML elements excluded by ID or by tag name. <br /> <br /> In the example below the HTML elements with ID "printRegion1" or "printRegion2" and all the "H1" elements will not be rendered in the generated PDF: <br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> pdfConverter.HtmlExcludedRegionsOptions.HtmlElementIds = <span class="kwrd">new</span> <span class="kwrd">string</span>[] { <span class="str">"printRegion1"</span>, <span class="str">"printRegion2"</span> }; pdfConverter.HtmlExcludedRegionsOptions.HtmlTagNames = <span class="kwrd">new</span> <span class="kwrd">string</span>[] { <span class="str">"H1"</span> };</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="SelectPdfStandard" class="bookmark">5.16 Select PDF Standard (PDF/A, PDF/X, PDF/SiqQ)</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> By default the converter can generate PDF documents in conformance with PDF 1.4 standard. This standard is accepted by Adobe Reader 5.0 and the later versions of the Adobe Reader.<br /> <br /> Using the <i>PdfConverter.PdfStandardSubset</i> property the converter can be instructed to generate PDF documents in conformance with PDF/A, PDF/X and PDF/SiqQ and standards. These standards impose additional restrictions to the generate document. <br /> <br /> The PDF/A-1b standard (ISO 19005-1), used for long-term archiving of PDF documents, requires that all the true type fonts used by the document to be embedded in the document, the http links are disabled, the document does not use transparent objects, the document information properties are disabled. <br /> <br /> PDF/X-1a:2003 standard (ISO 15930-4), used to facilitate graphics exchange, requires that all the true type fonts used by the document to be embedded in the document, the http links are disabled, all the graphics are in CMYK color space, the document does not use transparent objects. <br /> <br /> PDF/SiqQ is a standard used by Adobe to ensure that a digitally signed document does not contain items that could alter its appearance when viewed in different environments. A PDF/SiqQ compliant document requires that all the true type fonts used by the document to be embedded in the document and the http links to be disabled. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="SelectColorSpace" class="bookmark">5.17 Select Color Space (RGB, CMYK, Grayscale)</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> By default the converter uses the RGB color space to draw graphics and images. Using the <i>PdfConverter.ColorSpace</i> property it is possible to instruct the converter to use the CMYK or Grayscale color space when the PDF document is rendered. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="FineControl" class="bookmark">5.18 Fine Control of HTML to PDF Conversion</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> <table> <tr> <td dir="ltr"> <p> The HTML to PDF Converter allows a very fine control of the PDF rendering process. The default settings of the converter should be acceptable for majority of the situations but sometimes more control and customizations is necessary. This section offers a summary of the main properties of the converter that can be set to control the rendering of the PDF document.</p> <p style="font-size: 14px"> <strong style="font-size: 12px">PDF Document Page Orientation</strong></p> <p> You can set the PDF document page orientation to Portrait or Landscape. By default the document page is A4 size Portrait orientation. To change the page orientation to Landscape you have to set the PdfConverter.PdfDocumentOptions.PdfPageOrientation property in HTML to PDF Converter or you can set the PDF page orientation when you create a PDF page with PDF Creator.</p> <p> With HTML to PDF Converter for .NET library you can set the landscape orientation with:</p> <p> <em>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; PdfConverter.PdfDocumentOptions.PdfPageOrientation = PDFPageOrientation.Landscape</em></p> <p style="font-size: 14px"> <strong style="font-size: 12px">PDF Document Page Size</strong></p> <p> You can set the PDF page size to a standard size like A4, A3, etc or you can set the PDF page size to a custom value. The custom page size width and height are specified in points (1 point is 1/72 inches).</p> <p> With the HTML to PDF Converter for .NET library you can set the PDF page size to a standard value with:</p> <p> <em>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; PdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4</em></p> <p> or a custom value with:</p> <p> <em>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; PdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.Custom<br /> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp; PdfConverter.PdfDocumentOptions.CustomPdfPageSize = new SizeF(widthInPoints, heightInPoints)</em></p> <p style="font-size: 14px"> <strong style="font-size: 12px">HTML to PDF Converter Virtual Display</strong></p> <p> The converter internally uses a virtual display where to render the HTML page very similar to what the web browser does on the screen. This virtual display is different from display of your computer and it has a resolution of 96 dpi given by the Windows DPI scaling. The web page elements dimensions are usually measured in pixels and this is the reason why the virtual display of the converter is also specified in pixels. These are the only dimensions used by the converter which are expressed in pixels. All the other dimensions are specified in points (1 point is 1/72 inches). However, given the resolution of the virtual display, the dimensions in pixels of your web page can be easily converted to dimensions expressed in points . The converter API offers the <i>UnitsConverter</i> class which can be used to convert dimensions from pixels to points and from points to pixels.</p> <p> You can specify the virtual display width and height in pixels using the <em>PdfConverter.PageWidth</em> and <em>PdfConverter.PageHeight</em> properties or you can specify the same values as parameters when you construct the <em>PdfConverter</em> object. </p> <p> By default the virtual display width is set to 1024 pixels which should be sufficient to display the majority of the web pages. If the web page you are converting cannot be completely displayed in this width then you can increase this value or you can set the <em>PageWidth</em> to 0 to allow the converter to automatically determine your web page width from the HTML elements width. The <em>PageHeight</em> property is 0 by default which means the virtual display will be automatically resized to display the whole HTML page. There are situations when the converter cannot automatically determine the web page height for example when the web page is a frame set. In this case you can manually set the PageHeight to certain value in pixels such that the page is displayed in the way you expect.</p> <p> <strong style="font-size: 12px">HTML Content Resizing in PDF Page</strong></p> <p> After the HTML content is displayed in the virtual display the virtual display content will be transfered into PDF as you would take a picture of the virtual display and put that picture into a PDF document. The PDF documents pages have a fixed size in points. For example, the A4 page with portrait orientation is 595 points in width and 842 points in height. If the virtual display width is more than 595 points then the rendered HTML content would be shrinked to fit the PDF page width and display the whole HTML content in the PDF document. If the virtual display width is less than 595 points then the rendered HTML content will not be resized and will be rendered in the top left corner of the PDF page at real size.</p> <p> The dimension of the A4 portrait page in virtual device pixels is 793x1122 pixels. This means that at a default virtual display width of 1024 pixels the HTML content will be shrunk to fit the PDF page. This is the reason why you can see smaller fonts and images in PDF than they are in the source HTML document.</p> <p> The FitWidth property in PdfConverter.PdfDocumentOptions can be used to specify if the HTML content is resized to fit the PDF page width. The default value is true which makes the HTML content to be resized if necessary to fit the PDF page width. When false, the HTML content will not be resized and it will be rendered at the real size in PDF (the size it has in the virtual display at the current virtual display resolution). </p> <p> The FitHeight property in PdfConverter.PdfDocumentOptions is similar to FitWidth and can be used to force the converter to fit all the HTML content into the height of the PDF page. If both FitWidth and FitHeight are true then the HTML content will fit both the width and height of the PDF page. </p> <p> When the FitWidth property is false the HTML content could be wider than the PDF page width and the therefore the HTML content will be cut off to the right in PDF. In this case, in order to get the whole content in PDF you have to set a wider page for the PDF document. You can first try to set landscape orientation for the PDF page by setting PdfConverter.PdfDocumentOptions.PdfPageOrientation = PDFPageOrientation.Landscape. If this not enough you can choose a wider standard page like A3 or A2. You can even set a custom size for the PDF page as described in a section above. You can set the PdfConvert.PdfDocumentOptions.PdfPageSize=PdfPageSize.Custom and in this case the custom size of the PDF page will be taken from PdfConverter.PdfDocumentOptions.CustomPdfPageSize property. </p> <p> The PdfConverter.PdfDocumentOptions.AutoSizePdfPage property was added to control the PDF page width. It has effect only when the FitWidth property is false. When FitWidth is false and AutoSizePdfPage is true, the PDF page width will be automatically resized to a custom value such that all the HTML content is displayed in PDF at real size.</p> <p> If you don't want to resize the PDF page but you want to keep it A4 portrait for example, then you have to decrease the virtual display width. If your page can be correctly and entirely displayed in 793 pixels (which is the width of the A4 portrait page in pixels) you can set this value for PdfConverter.PageWidth property and you should get the whole HTML rendered at real size in PDF.</p> <p> The HTML content can appear as not centered in the PDF page when the HTML content can be normally displayed at a width less than 1024 pixels. In this case there will normally be an empty space in the right side of the virtual display. When the virtual display content is transfered to PDF the content will appear as not centered in PDF. You can also solve this if you set the PdfConverter.PageWidth to a value of 793 pixels or less. </p> <p style="font-size: 14px"> <strong style="font-size: 12px">Single PDF Page Conversion</strong></p> <p> The HTML to PDF Converter offers also the possibility to produce the whole HTML content into a single PDF page automatically resized to display the whole content. To get this behavior you have to set the PdfConverter.PdfDocumentOptions.SinglePage property on true. When FitWidth is also true the PDF page width will be preserved, otherwise the PDF page width will be automatically resized to display the whole HTML content.</p> <p> &nbsp;</p> </td> </tr> </table> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="ConversionSummary" class="bookmark">5.19 Conversion Summary</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> The <i>PdfConverter.ConversionSummary</i> property returns an object populated after the call of one of the render methods described in <a href="#PdfConverterRenderMethods"> PdfConverter Render Methods</a> section with a set of data that can be used to display details about the conversion that has just finished or to further customize the generated PDF document as described in the <a href="#PostConvert">Post Convert Customization of the Generated PDF Document</a> section.<br /> <br> The most important properties of the ConversionSummary object are the <i>PdfPageCount</i> which represents the total number of pages rendered by the converter and the <i>RenderedPagesRectangles</i> which gives for each rendered PDF page the bounding rectangle for the content rendered in that page.<br /> <br /> For example, if you want to add more elements at the end of the generated PDF document after a conversion, you can find where the conversion ended from the last rectangle of the <i>RenderedPagesRectangles</i> array. For this important scenario two explicit properties were also added to the conversion summary: <i>LastPageIndex</i> and <i>LastPageRectangle</i> giving the zero based index of the last redered page and the bounding rectangle of the content rendered in this last page. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="PostConvert" class="bookmark">5.20 Post Convert Customization of the Generated PDF Document</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px; direction: ltr;"> The converter offers a set of render methods described in <a href="#PostConvertOverview"> Post Convert Customization Overview</a> section returning the internal <i>Document</i> object created by the converter. The object resulted after conversion is an instance of the <i>Winnovative.WnvHtmlConvert.PdfDocument.Document</i> class. This Document object offers access to the collection of pages of PDF document. You can iterate over the document pages, add new pages to the document, append external PDF documents or add new elements like text and images to the document pages. After modification the document can be saved to a file or to a stream using one of the Save methods of the Document class. <br /> <br /> The chaper <a href="#AdvancedFeatures">Advanced Post Convert Customization of the Generated PDF Document</a> contains a detailed description of the classes and methods available in the <i>Winnovative.WnvHtmlConvert.PdfDocument</i> namespace. <br /> <br /> Below is a complete example of how to convert many HTML document into the same PDF document using post convert customization of the Document object. The code is taken from the <i>WinForms_MultipleHtmlConversions</i> sample. Each additional HTML to PDF conversion is represented by a HtmlToPdfElement object that can be added in any position in a PDF page. The first conversion is performed by the call to <i>pdfConverter.GetPdfDocumentObjectFromUrl</i>, the next two conversions (the conversion of another URL and the conversion of a HTML string) are achieved by adding two <i>HtmlToPdfElement</i> objects to the document pages: </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">using</span> System; <span class="kwrd">using</span> System.Collections.Generic; <span class="kwrd">using</span> System.ComponentModel; <span class="kwrd">using</span> System.Data; <span class="kwrd">using</span> System.Drawing; <span class="kwrd">using</span> System.Text; <span class="kwrd">using</span> System.Windows.Forms; <span class="kwrd">using</span> Winnovative.WnvHtmlConvert; <span class="kwrd">using</span> Winnovative.WnvHtmlConvert.PdfDocument; <span class="kwrd">namespace</span> WinForms_ConvertMultipleURLsToPdf { <span class="kwrd">public</span> <span class="kwrd">partial</span> <span class="kwrd">class</span> ConvertMultipleURLsToPdf : Form { <span class="kwrd">public</span> ConvertMultipleURLsToPdf() { InitializeComponent(); } <span class="kwrd">private</span> <span class="kwrd">void</span> btnConvert_Click(<span class="kwrd">object</span> sender, EventArgs e) { <span class="kwrd">try</span> { PdfConverter pdfConverter = <span class="kwrd">new</span> PdfConverter(); <span class="rem">// add header and footer</span> <span class="kwrd">if</span> (cbAddHeader.Checked) AddHeader(pdfConverter); <span class="kwrd">if</span> (cbAddFooter.Checked) AddFooter(pdfConverter); <span class="rem">// call the converter and get a Document object from URL</span> Document pdfDocument = pdfConverter.GetPdfDocumentObjectFromUrl(textBoxURL1.Text.Trim()); <span class="rem">// get the conversion summary object from the event arguments</span> ConversionSummary conversionSummary = pdfConverter.ConversionSummary; <span class="rem">// the PDF page where the previous conversion ended</span> PdfPage lastPage = pdfDocument.Pages[conversionSummary.LastPageIndex]; <span class="rem">// the last rectangle in the last PDF page where the previous conversion ended</span> RectangleF lastRectangle = conversionSummary.LastPageRectangle; <span class="rem">// the result of adding an element to a PDF page</span> <span class="rem">// ofers the index of the PDF page where the rendering ended </span> <span class="rem">// and the bounding rectangle of the rendered content in the last page</span> AddElementResult addResult = <span class="kwrd">null</span>; <span class="rem">// the converter for the second URL</span> HtmlToPdfElement htmlToPdfURL2 = <span class="kwrd">null</span>; <span class="kwrd">if</span> (cbStartOnNewPage.Checked) { <span class="rem">// render the HTML from the second URL on a new page after the first URL</span> PdfPage newPage = pdfDocument.Pages.AddNewPage(); htmlToPdfURL2 = <span class="kwrd">new</span> HtmlToPdfElement(0, 0, textBoxURL2.Text); addResult = newPage.AddElement(htmlToPdfURL2); } <span class="kwrd">else</span> { <span class="rem">// render the HTML from the second URL immediately after the first URL</span> htmlToPdfURL2 = <span class="kwrd">new</span> HtmlToPdfElement(lastRectangle.Left, lastRectangle.Bottom, textBoxURL2.Text); addResult = lastPage.AddElement(htmlToPdfURL2); } <span class="rem">// the PDF page where the previous conversion ended</span> lastPage = pdfDocument.Pages[addResult.EndPageIndex]; <span class="rem">// add a HTML string after all the rendered content</span> HtmlToPdfElement htmlStringToPdf = <span class="kwrd">new</span> HtmlToPdfElement(addResult.EndPageBounds.Left, addResult.EndPageBounds.Bottom, <span class="str">"&lt;b&gt;&lt;i&gt;The rendered content ends here&lt;/i&gt;&lt;/b&gt;"</span>, <span class="kwrd">null</span>); lastPage.AddElement(htmlStringToPdf); <span class="rem">// save the PDF bytes in a file on disk</span> <span class="kwrd">string</span> outFilePath = System.IO.Path.Combine(Application.StartupPath, <span class="str">"Result.pdf"</span>); <span class="rem">// save the PDF document to a file on disk</span> <span class="kwrd">try</span> { pdfDocument.Save(outFilePath); } <span class="kwrd">finally</span> { <span class="rem">// close the Document to realease all the resources</span> pdfDocument.Close(); } <span class="rem">// open the generated PDF document in an external viewer</span> DialogResult dr = MessageBox.Show(<span class="str">"Open the rendered file in an external viewer?"</span>, <span class="str">"Open Rendered File"</span>, MessageBoxButtons.YesNo); <span class="kwrd">if</span> (dr == DialogResult.Yes) { System.Diagnostics.Process.Start(outFilePath); } } <span class="kwrd">catch</span> (Exception ex) { MessageBox.Show(ex.Message); <span class="kwrd">return</span>; } } <span class="kwrd">private</span> <span class="kwrd">void</span> AddHeader(PdfConverter pdfConverter) { <span class="kwrd">string</span> headerAndFooterHtmlUrl = System.IO.Path.Combine(Application.StartupPath, <span class="str">@"..\..\HeaderAndFooterHtml.htm"</span>); <span class="rem">//enable header</span> pdfConverter.PdfDocumentOptions.ShowHeader = <span class="kwrd">true</span>; <span class="rem">// set the header height in points</span> pdfConverter.PdfHeaderOptions.HeaderHeight = 60; <span class="rem">// set the header HTML area</span> pdfConverter.PdfHeaderOptions.HtmlToPdfArea = <span class="kwrd">new</span> HtmlToPdfArea(0, 0, -1, pdfConverter.PdfHeaderOptions.HeaderHeight, headerAndFooterHtmlUrl, 1024, -1); pdfConverter.PdfHeaderOptions.HtmlToPdfArea.FitHeight = <span class="kwrd">true</span>; } <span class="kwrd">private</span> <span class="kwrd">void</span> AddFooter(PdfConverter pdfConverter) { <span class="kwrd">string</span> headerAndFooterHtmlUrl = System.IO.Path.Combine(Application.StartupPath, <span class="str">@"..\..\HeaderAndFooterHtml.htm"</span>); <span class="rem">//enable footer</span> pdfConverter.PdfDocumentOptions.ShowFooter = <span class="kwrd">true</span>; <span class="rem">// set the footer height in points</span> pdfConverter.PdfFooterOptions.FooterHeight = 60; <span class="rem">//write the page number</span> pdfConverter.PdfFooterOptions.TextArea = <span class="kwrd">new</span> TextArea(0, 30, <span class="str">"This is page &amp;p; of &amp;P; "</span>, <span class="kwrd">new</span> System.Drawing.Font(<span class="kwrd">new</span> System.Drawing.FontFamily(<span class="str">"Times New Roman"</span>), 10, System.Drawing.GraphicsUnit.Point)); pdfConverter.PdfFooterOptions.TextArea.EmbedTextFont = <span class="kwrd">true</span>; pdfConverter.PdfFooterOptions.TextArea.TextAlign = HorizontalTextAlign.Right; <span class="rem">// set the footer HTML area</span> pdfConverter.PdfFooterOptions.HtmlToPdfArea = <span class="kwrd">new</span> HtmlToPdfArea(0, 0, -1, pdfConverter.PdfFooterOptions.FooterHeight, headerAndFooterHtmlUrl, 1024, -1); pdfConverter.PdfFooterOptions.HtmlToPdfArea.FitHeight = <span class="kwrd">true</span>; } } }</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="Multithreading" class="bookmark">5.21 Multithreading Support</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The multithreading support was one of the key factors in the design of the HTML to PDF library because most of the applications today are multithreaded applications. An ASP.NET application is a very good example of multithreaded application because at each request a user makes for a web page the ASP.NET subsystem from IIS creates a new thread in the worker process to execute the page and to return the result to the browser. Because many of the web applications today are ASP.NET applications you can easily understand how important is for a library to perform correctly and reliably in a multithreaded environment. <br /> <br /> The render and save methods of the PdfConverter object can be safely called from multiple threads of an application and all the memory and resources used by the converter are automatically disposed after each conversion. The library was designed and carefully tested to not leak any memory or system resources after a conversion. Because of this the library can be safely used in services running a very long period without interruption and in highly loaded systems.<br /> <br /> To demonstrate this, we have created the <i>Console_MultithreadedPerformance</i> sample that you can use to test the behavior and the performance of the converter in a multithreaded application. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title2"> <a name="AdvancedFeatures" class="bookmark">6. Advanced Post Convert Customization of the Generated PDF Document </a> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="PostConvertOverview" class="bookmark">6.1 Post Convert Customization Overview</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The <i>PdfConverter</i> class offers a set of render methods producing the internal <i>Document</i> object created by the converter. </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">public</span> Document GetPdfDocumentObjectFromUrl(<span class="kwrd">string</span> url) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromUrl(<span class="kwrd">string</span> url, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlFile(<span class="kwrd">string</span> htmlFilePath) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlFile(<span class="kwrd">string</span> htmlFilePath, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlString(<span class="kwrd">string</span> htmlString, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase) <span class="kwrd">public</span> Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream, Encoding streamEncoding, <span class="kwrd">string</span> urlBase, <span class="kwrd">string</span> internalLinksDocUrl) </pre> </td> </tr> <tr> <td> The object resulted after conversion is an instance of the <i>Winnovative.WnvHtmlConvert.PdfDocument.Document</i> class. This <i>Document</i> object offers access to the collection of pages of PDF document. You can iterate over the document pages, add new pages to the document, append external PDF documents or add new elements like text and images to the document pages. After modification the document can be saved to a file or to a stream using one of the Save methods of the Document class. The classes and methods that can be used to customize the generated PDF document are available in the <i>Winnovative.WnvHtmlConvert.PdfDocument</i> namespace.<br /> <br /> </td> </tr> <tr> <td> The most important class defined in the in the <i>Winnovative.WnvHtmlConvert.PdfDocument</i> is the <i>Document</i> class. When the <i>Document</i> object is returned by one of the render methods above it already contains the PDF pages generated by the converter from the URL or from the HTML string being converted. The collection of PDF pages can be accessed with <i>Document.Pages</i> property. New pages with the desired size, orientation and margins can be added to the collection of pages and new elements can be added to any page in the collection. <br /> <br /> Below in this chapter we offer a detailed description of the elements that can be added to a page of the PDF document. You can add a <i>HtmlToPdfElement</i> which makes possible multiple conversions in the same PDF document, a <i>HtmlToImage</i> element which embeds the image of a HTML document into the PDF document, a <i>RtfToPdfElement</i> which embeds a RTF formatted text into the PDF document, you can add new texts and images, shapes, digital signatures, bookmarks, templates, watermarks, file attachments and notes. <br /> <br /> In the code sample below taken from the <i>WinForms_HtmlElementsLocationInPdf</i> demo application, all the <em>H1</em> and <em>IMG</em> elements and the elements with the ID <em>ID1</em> and <em>ID2</em> will be highlighted with a green rectangle in the generated PDF:<br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode"> <span class="kwrd">using</span> System; <span class="kwrd">using</span> System.Collections.Generic; <span class="kwrd">using</span> System.ComponentModel; <span class="kwrd">using</span> System.Data; <span class="kwrd">using</span> System.Drawing; <span class="kwrd">using</span> System.Text; <span class="kwrd">using</span> System.Windows.Forms; <span class="kwrd">using</span> Winnovative.WnvHtmlConvert; <span class="kwrd">using</span> Winnovative.WnvHtmlConvert.PdfDocument; <span class="kwrd">namespace</span> WinForms_HtmlElementsLocationInPdf { <span class="kwrd">public</span> <span class="kwrd">partial</span> <span class="kwrd">class</span> HtmlElementsLocationInPdf : Form { <span class="kwrd">public</span> HtmlElementsLocationInPdf() { InitializeComponent(); } <span class="kwrd">private</span> <span class="kwrd">void</span> btnConvert_Click(<span class="kwrd">object</span> sender, EventArgs e) { <span class="kwrd">try</span> { PdfConverter pdfConverter = <span class="kwrd">new</span> PdfConverter(); <span class="rem">// inform the converter about the HTML elements for which we want the location in PDF</span> <span class="rem">// in this sample we want the location of IMG, H1 and H2 elements</span> pdfConverter.HtmlElementsMappingOptions.HtmlTagNames = <span class="kwrd">new</span> <span class="kwrd">string</span>[] { <span class="str">"IMG"</span>, <span class="str">"H1"</span>, <span class="str">"H2"</span> }; <span class="rem">// add an addtional list of the HTML IDs of the HTML elements for which to retrieve position in PDF</span> pdfConverter.HtmlElementsMappingOptions.HtmlElementIds = <span class="kwrd">new</span> <span class="kwrd">string</span>[] { <span class="str">"id1"</span>, <span class="str">"id2"</span> }; <span class="rem">// call the converter and get a Document object from URL</span> Document pdfDocument = pdfConverter.GetPdfDocumentObjectFromUrl(textBoxURL.Text.Trim()); <span class="rem">// iterate over the HTML elements locations and hightlight each element with a green rectangle</span> <span class="kwrd">foreach</span> (HtmlElementMapping elementMapping <span class="kwrd">in</span> pdfConverter.HtmlElementsMappingOptions.HtmlElementsMappingResult) { <span class="rem">// because a HTML element can span over many PDF pages the mapping </span> <span class="rem">// of the HTML element in PDF document consists in a list of rectangles,</span> <span class="rem">// one rectangle for each PDF page where this element was rendered</span> <span class="kwrd">foreach</span> (HtmlElementPdfRectangle elementLocationInPdf <span class="kwrd">in</span> elementMapping.PdfRectangles) { <span class="rem">// get the PDF page</span> PdfPage pdfPage = pdfDocument.Pages[elementLocationInPdf.PageIndex]; RectangleF pdfRectangleInPage = elementLocationInPdf.Rectangle; <span class="rem">// create a RectangleElement to highlight the HTML element</span> RectangleElement highlightRectangle = <span class="kwrd">new</span> RectangleElement(pdfRectangleInPage.X, pdfRectangleInPage.Y, pdfRectangleInPage.Width, pdfRectangleInPage.Height); highlightRectangle.ForeColor = Color.Green; pdfPage.AddElement(highlightRectangle); } } <span class="rem">// save the PDF bytes in a file on disk</span> <span class="kwrd">string</span> outFilePath = System.IO.Path.Combine(Application.StartupPath, <span class="str">"Result.pdf"</span>); <span class="kwrd">try</span> { pdfDocument.Save(outFilePath); } <span class="kwrd">finally</span> { <span class="rem">// close the Document to realease all the resources</span> pdfDocument.Close(); } <span class="rem">// open the generated PDF document in an external viewer</span> DialogResult dr = MessageBox.Show(<span class="str">"Open the rendered file in an external viewer?"</span>, <span class="str">"Open Rendered File"</span>, MessageBoxButtons.YesNo); <span class="kwrd">if</span> (dr == DialogResult.Yes) { System.Diagnostics.Process.Start(outFilePath); } } <span class="kwrd">catch</span> (Exception ex) { MessageBox.Show(ex.Message); <span class="kwrd">return</span>; } } } }</pre> <br /> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="CoordinatesSystem" class="bookmark">6.2 Coordinates System and Graphic Units</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> The PDF document uses the point ( 1/72 inch ) as a graphic unit. All the coordinates and sizes are expected to be specified in points. Sometimes, when the size of an element (e.g. image) is known in pixels it is useful to convert pixels in points. The HTML to PDF Converter API offers the <em>UnitsConverter</em> class to convert pixels in points and points in pixels. Here are the prototypes of these static functions from the UnitsConverter class:<br /> <br /> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> <span class="kwrd">public</span> <span class="kwrd">static</span> <span class="kwrd">float</span> PointsToPixels(<span class="kwrd">float</span> points)</pre> <pre> <span class="kwrd">public</span> <span class="kwrd">static</span> <span class="kwrd">float</span> PixelsToPoints(<span class="kwrd">float</span> pixels)</pre> </div> </td> </tr> <tr> <td style="height: 23px; text-align: justify"> <br /> The coordinates system origin is located in the top left corner. The positive X coordinates go to right and the positive Y coordinates go down like in the .NET Windows Forms graphics. </td> </tr> <tr> <td style="height: 26px; text-align: justify"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="DocumentClass" class="bookmark">6.3 Document Class</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 26px"> This class represents a PDF document in the HTML to PDF Converter framework. A Document object can be received as result of one of the render methods described in the . When creating a Document object from an existing PDF document, the existing PDF document is passed to the Document class constructor as the path of the .pdf file on disk or as a stream containing the PDF document image. In either case the resulted Document object can be further modified. There are also <em>Document</em> constructors accepting a password when creating a <em>Document</em> object form a password protected PDF document. Here are the <em>Document</em> class constructors:<br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre> <span class="kwrd">public</span> Document(Stream pdfStream)</pre> <pre class="alt"> <span class="kwrd">public</span> Document(<span class="kwrd">string</span> pdfFileName)</pre> <pre> <span class="kwrd">public</span> Document(Stream pdfStream, <span class="kwrd">string</span> pdfPassword)</pre> <pre class="alt"> <span class="kwrd">public</span> Document(<span class="kwrd">string</span> pdfFileName, <span class="kwrd">string</span> pdfPassword)</pre> </div> <br /> <br /> The <em>Document</em> class offers access to the PDF pages collection, PDF fonts collection, bookmarks, templates and viewer preferences. For example you can add a new page to the document pages collection using &nbsp;the <em>AddPage()</em> method, adding a new font to the fonts collection using the <em>AddFont()</em> methodor adding a new template using the <em>AddTemplate</em>() method. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="PdfRenderers" class="bookmark">6.4 PDF Renderers</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> A <em>PDF renderer</em> is an object capable of rendering PDF elements into the final PDF document. Currently the HTML to PDF Converter API defines two types of renderers derived from the ElementsRenderer abstract class: the <em>PdfPage</em> class which renders elements in a PDF page and the <em>Template </em>class which renders the elements in a template area repeated on each page of the PDF document. Both renderers are capable to render the same graphic elements types like HTML to PDF converter elements, shape elements texts and images but additionally the PdfPage renderer can render other interactive elements like PDF links, digital signature elements, attachments, text notes &nbsp;that cannot be rendered by a <em>Template</em> renderer.<br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="PdfPageClass" class="bookmark">6.4.1 PdfPage Class</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The <em>PdfPage class</em> represents a page in the PDF document. A PdfPage class object can be instantiated using the <em>Document.AddPage()</em> interface. When calling the <em>AddPage()</em> method without parameters a page with the default margins, size and orientation is created. The margins are inherited from the Document.Margins property. The default orientation is portrait when adding the first page to the document or the previous page orientation is inherited if there was a previous page in document. The default size is A4 when adding the first page or the previous page size if there was a previous page in document. However, any of these properties can be specified when using other overloadings of the AddPage() method. <br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="TemplateClass" class="bookmark">6.4.2 Template Class</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The <em>Template class </em>represents a content which is repeated on each page of the PDF document. The templates can be used to create headers and footers, watermarks or any other content that needs to be repeated on each page of the PDF document. <br /> <br /> A Template can render all the graphic elements (e.g HTML to PDF converter, texts, images, shapes) a PdfPage can render but it cannot render interactive elements like PDF links, attachments, text notes. A Template class object can be instantiated using the <em>Document.AddTemplate()</em> interface. <br /> <br /> There two logical types of templates in HTML to PDF Converter: predefined templates like header and footer and custom templates. Both predefined and custom are instances of the Template class but the predefined templates dimensions are for example considered when calculating the available client area in a PDF page. <br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="PredefinedTemplates" class="bookmark">6.4.2.1 Predefined Templates</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The predefined templates are the document header, footer. The predefined templates are automatically docked to the corresponding side of the PDF page. <br /> <br /> For example the predefined header is automatically docked to the top of the PDF page which means the header location is the top left corner and the width of the header template is the width of the page. Also if a predefined header was set, the available client area in PDF page will start right under the header. Similar, if a predefined footer was set, it will be docked to the bottom of page and the available client area in PDF will end right above the footer template. &nbsp;It is recommended to set the predefined templates before starting to add elements to the document. <br /> <br /> The HTML to PDF Converter API allows you to access the headers and footers for of the PDF document created by the converter for customizations but it doesn't allow you to change the header or footer template. The headers and footers can be created using the PdfConverter class interface. <br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="CustomTemplates" class="bookmark">6.4.2.2 Custom Templates</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The custom templates can be used to add watermarks or any other content that must be repeated in the same position on each page. In the code sample below, taken from the ModifyExistingPdf sample, a watermark containing a text and an image is added to an existing document: <br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre> <span class="rem">// get the first page the PDF document</span></pre> <pre class="alt"> PdfPage firstPage = document.Pages[0];</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="kwrd">string</span> logoImagePath = System.IO.Path.Combine(Server.MapPath(<span class="str">"~"</span>), <span class="str">@"img\logo.jpg"</span>);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// display image in the available space in page and with a auto determined height to keep the aspect ratio</span></pre> <pre> ImageElement imageElement1 = <span class="kwrd">new</span> ImageElement(0, 0, logoImagePath);</pre> <pre class="alt"> AddElementResult addResult = firstPage.AddElement(imageElement1);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// add image border</span></pre> <pre> <span class="rem">// add a border to watermark</span></pre> <pre class="alt"> RectangleElement imageBorderRectangleElement = <span class="kwrd"> new</span> RectangleElement(1, 1, addResult.EndPageBounds.Width,</pre> <pre> addResult.EndPageBounds.Height);</pre> <pre class="alt"> firstPage.AddElement(imageBorderRectangleElement);</pre> <pre>&nbsp;</pre> <pre class="alt"> System.Drawing.Image logoImg = System.Drawing.Image.FromFile(logoImagePath);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// calculate the watermark location</span></pre> <pre>&nbsp;</pre> <pre class="alt"> System.Drawing.SizeF imageSizePx = logoImg.PhysicalDimension;</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// transform from pixels to points</span></pre> <pre> <span class="kwrd">float</span> imageWidthPoints = UnitsConverter.PixelsToPoints(imageSizePx.Width);</pre> <pre class="alt"> <span class="kwrd">float</span> imageHeightPoints = UnitsConverter.PixelsToPoints(imageSizePx.Height);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="kwrd">float</span> watermarkXLocation = (firstPage.ClientRectangle.Width - imageWidthPoints)/2;</pre> <pre> <span class="kwrd">float</span> watermarkYLocation = firstPage.ClientRectangle.Height / 4;</pre> <pre class="alt">&nbsp;</pre> <pre> <span class="rem">// add a template watermark to the document repeated on each document page</span></pre> <pre class="alt"> <span class="rem">// the watermark size is equal to image size in points</span></pre> <pre> Template watermarkTemplate = document.AddTemplate(<span class="kwrd">new</span> System.Drawing.RectangleF(watermarkXLocation, watermarkYLocation, </pre> <pre class="alt"> imageWidthPoints, imageHeightPoints + 20));</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// add a standard font to the document</span></pre> <pre> PdfFont watermarkTextFont = document.AddFont(StdFontBaseFamily.HelveticaBold);</pre> <pre class="alt"> watermarkTextFont.Size = 10;</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// Add a text element to the watermark. You can add any other graphic element to a template</span></pre> <pre> TextElement watermarkTextElement = <span class="kwrd">new</span> TextElement(3, 0, <span class="str">"This is Watermark Text"</span>, watermarkTextFont);</pre> <pre class="alt"> watermarkTextElement.ForeColor = System.Drawing.Color.Red;</pre> <pre> watermarkTextElement.Transparency = 100;</pre> <pre class="alt"> watermarkTemplate.AddElement(watermarkTextElement);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// add an image to the watermak</span></pre> <pre> ImageElement watermarkImageElement = <span class="kwrd">new</span> ImageElement(0, 20, logoImg);</pre> <pre class="alt"> watermarkImageElement.Transparency = 100;</pre> <pre> watermarkTemplate.AddElement(watermarkImageElement);</pre> <pre class="alt">&nbsp;</pre> <pre> <span class="rem">// add a border to watermark</span></pre> <pre class="alt"> RectangleElement watermarkRectangleElement = <span class="kwrd"> new</span> RectangleElement(0, 0, watermarkTemplate.ClientRectangle.Width, </pre> <pre> watermarkTemplate.ClientRectangle.Height);</pre> <pre class="alt"> watermarkTemplate.AddElement(watermarkRectangleElement);</pre> <pre>&nbsp;</pre> <pre class="alt"> <span class="rem">// dispose the image</span></pre> <pre> logoImg.Dispose();</pre> <pre class="alt">&nbsp;</pre> </div> <br /> <br /> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title3"> <a name="PageElements" class="bookmark">6.5 PDF Page Elements</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" dir="ltr"> A PDF page element represents anything that can be added to a renderer and it implements the <em>PageElement</em> abstract class. The HTML to PDF Converter defines two types of page elements: graphic elements that are inheriting the <em>PageGraphicElement</em> class and interactive page elements inheriting directly the <em>PageElement</em> class. <br /> <br /> The graphic elements have common properties like fore color, back color, transparency, rotation angle. Examples of graphic elements are HTML to PDF Converter element, RTF to PDF Converter element, text element, image element, shapes elements. Examples of interactive page elements are internal link element, url link element, text note element, file attachment element.<br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="PageGraphicElements" class="bookmark">6.5.1 Page Graphic Elements</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The page graphic elements inherit the <em>PageGraphicElement</em> class. This class defines the following properties and methods that can be used to change the aspect of the element:&nbsp;<br /> <br /> <em>ForeColor</em> - this properties defines the color used to draw a shape for example the color of a line when drawing a line element or the text color when drawing a text<br /> <em>BackColor</em> - this property defines the background color of a graphic element, for example the background color of rectangle when rendering a rectangle element<br /> <em>Gradient</em> - this property defines a gradient color to be used when filling a shape like a rectangle element<br /> <em>Rotate(<span class="parameter">rotateAngle</span>) - </em>this method is used to rotate clockwise the coordinates system with a specified angle before rendering the graphic element. <br /> <em>Transparency</em> - this property is used to set the graphic element transparency. It is expected a value between 0 and 100 for the transparency. 0 means completely transparent and 100 means completely opaque.<br /> <em>LineStyle</em> - property is used to set the line width, dash style, line join style, line cap style for the graphic elements rendering lines like rectangle element,&nbsp; ellipse element, line element.<br /> <br /> In the next sections each of the graphic elements will be described in detail.<br /> <br /> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfElement" class="bookmark">6.5.1.1 HTML to PDF Converter Element</a> </td> </tr> <tr> <td style="height: 23px" dir="ltr"> <br /> The integrated HTML to PDF Converter is implemented by the <em>HtmlToPdfElement</em> graphic element. It offers the possibility to specify the position and the size of the PDF content rendered from HTML and the possibility to add many HTML to PDF conversions to same document. <br /> <br /> A very useful feature is the possibility to know the size of the rendered content in each page when the rendered content spans on many pages. The information about the last rendered page can be taken from the <em>AddElementResult</em> object returned after adding the element to a renderer like a page or template. <br /> <br /> The HtmlToPdfElement offer many constructors that basically calls the following two constructors with more or less default values for converting a URL or a HTML string to PDF:<br /> <br /> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> <span class="kwrd">public</span> HtmlToPdfElement(<span class="kwrd">float</span> x, <span class="kwrd">float</span> y, <span class="kwrd">float</span> width, <span class="kwrd">float</span> height, </pre> <pre> <span class="kwrd">string</span> urlToConvert, <span class="kwrd">int</span> htmlViewerWidth, <span class="kwrd">int</span> htmlViewerHeight)</pre> <pre class="alt">&nbsp;</pre> <pre> <span class="kwrd">public</span> HtmlToPdfElement(<span class="kwrd">float</span> x, <span class="kwrd">float</span> y, <span class="kwrd">float</span> width, <span class="kwrd">float</span> height, </pre> <pre class="alt"> <span class="kwrd">string</span> htmlStringToConvert, <span class="kwrd">string</span> htmlStringBaseURL,</pre> <pre> <span class="kwrd">int</span> htmlViewerWidth, <span class="kwrd">int</span> htmlViewerHeight)</pre> </div> <br /> The variours constructor parameters are explined below. <br /> <br /> The first constructor creates a URL to PDF converter element at the specified <em>x </em>and <em>y</em> coordinates with the specified <em>width</em> and <em>height</em>. The virtual browser width and height in pixels are specified by the <em>htmlViewerWidth</em> and <em>htmlViewerHeight</em> parameters. <br /> <br /> <param name="x" /> <em>x</em> - The x position in points where the rendered content will be placed&nbsp;<br /> <em>y- </em>The y position in points where the rendered content will be placed <br /> <param name="width" /> <em>width - </em>The destination width in points for the rendered content. If the specified with is negative, the destination width will be given by the available width in page or template<br /> <param name="height" /> <em>height</em> - The destination height in points for the rendered content. If the specified height is negative, the destination height will be auto determined so all the content can be rendered. Please note that the specified height is the effective height that will be rendered in the PDF document and does not include for example the empty spaces introduced by custom or automatic page breaks.&nbsp;<br /> <em>urlToConvert</em> - The URL to convert to PDF <br /> <param name="htmlViewerWidth" /> <em>htmlViewerWidth</em> - The virtual browser width in pixels. The default value is 1024 pixels. The effect of this parameter is similar with viewing the HTML page in a browser window with the specified width. When this parameter is negative, the converter will try to auto-determine the HTML page width from the HTML body element width. <br /> <param name="htmlViewerHeight" /> <em>htmlViewerHeight</em> - The virtual browser height in pixels. The default value is 0 which means the height will be auto-determined. The effect of this parameter is similar with viewing the HTML page in a browser window with the specified width and height. When this paramter is negative, the converter will try to auto-determine the HTML page height from the HTML body element height.<br /> <br /> The second constructor creates a HTML string to PDF converter element at the specified <em>x</em> and <em>y </em>coordinates with the specified <em>width</em> and <em>height</em>. The virtual browser width and height in pixels is specified by the <em>htmlViewerWidth</em> and <em>htmlViewerHeight</em> parameters.<br /> <br /> <em>htmlStringToConvert</em> - The HTML string convert to PDF.<br /> <em>htmlStringBaseURL</em> - The full URL of the page from where this string was taken used to resolve the images and CSS files referenced by a relative URL in the HTML string. This parameter is optional and the default value is NULL. When this parameter is NULL no base URL will be used. This paramter has effect only if the specified HTML string contains a HEAD element<base href="baseURL" />.<br /> <br /> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfPageBreaks" class="bookmark">6.5.1.1.1 Page Breaks, Keep Together in HtmlToPdfElement</a> </td> </tr> <tr> <td style="height: 23px" class="title3"> </td> </tr> <tr> <td style="height: 23px"> The converter supports the following CSS styles to control the page breaks: page-break-before:always, page-break-after:always and page-break-inside:avoid. For example, with the page-break-after:always style applied to a HTML element (image, text, etc) you instruct the converter to insert a page break right after that element is rendered.<br /> <br /> By default the converter always tries to avoid breaking the text between PDF pages. You can disable this behavior using the PdfConverter.AvoidTextBreak property. Also you can enable the converter to avoid breaking the images between PDF pages using the PdfConverter.AvoidImageBreak . By default this property is false.<br /> <br /> An advanced and very useful feature when creating PDF reports is the Keep Together feature which can be implemented with the page-break-inside:avoid style. This instructs the converter to avoid breaking the content of a group of HTML elements you want to keep together on the same page. If you think you can apply this style to a table, a table row or a div element you can easily understand the utility of this feature. <br /> <br /> Below is an example of using the page-break-inside:avoid style. The table contains a large number of rows, each row containing an image in the left and a text in the right and we don't want a row to span on two pages. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">&lt;</span><span class="html">table</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">tr</span> <span class="attr">style</span><span class="kwrd">="page-break-inside : avoid"</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">img</span> <span class="attr">width</span><span class="kwrd">="100"</span> <span class="attr">height</span><span class="kwrd">="100"</span> <span class="attr">src</span><span class="kwrd">="img1.jpg"</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> My text 1</pre> <pre> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">tr</span><span class="kwrd">&gt;</span></pre> <pre> </pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">tr</span> <span class="attr">style</span><span class="kwrd">="page-break-inside : avoid"</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">img</span> <span class="attr">width</span><span class="kwrd">="100"</span> <span class="attr">height</span><span class="kwrd">="100"</span> <span class="attr">src</span><span class="kwrd">="img2.jpg"</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre class="alt"> <span class="kwrd">&lt;</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> My text 2</pre> <pre class="alt"> <span class="kwrd">&lt;/</span><span class="html">td</span><span class="kwrd">&gt;</span></pre> <pre> <span class="kwrd">&lt;/</span><span class="html">tr</span><span class="kwrd">&gt;</span></pre> <pre class="alt"><span class="kwrd">&lt;/</span><span class="html">table</span><span class="kwrd">&gt;</span></pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfLiveLinks" class="bookmark">6.5.1.1.2 Live HTTP Links in HtmlToPdfElement</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter can convert any HTTP link from the HTML document into a link in the PDF document. This works on links containing text, image or any other combination supported by the HTML code. This is the default behavior of the converter. If you don't want to get active links in the generated PDF document you can set <em>HtmlToPdfElement.<span class="identifier">LiveUrlsEnabled</span> = false</em>. </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfClientScripts" class="bookmark">6.5.1.1.3 Enable/Disable Client Scripts and ActiveX/Flash from HTML Page</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" dir="ltr"> The JavaScript code and ActiveX/Flash controls are disabled by default in the converted page during conversion to a PDF. If you have JavaScript code that modifies the web page on the client you can instruct the converter to execute that JavaScript code. You can activate the <em>JavaScript</em> code . The properties from HtmlToPdfElement class which allow you to activate the scripts and ActiveX/Flash when converting to PDF file are: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"><span class="kwrd">public</span> <span class="kwrd">bool</span> ScriptsEnabled { get; set; }</pre> <pre><span class="kwrd">public</span> <span class="kwrd">bool</span> ActiveXEnabled { get; set; }</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfAuthentication" class="bookmark">6.5.1.1.4 Server Authentication in HtmlToPdfElement</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter offers support for any type of web server authentication. For example the converter can handle <em>IIS authentication</em> types like Integrated <em>Windows Authentication</em> and <em>Basic Authentication</em>. The authentication is disabled by default. To enable authentication you have to set the <em><strong>AuthenticationOptions</strong></em> property of the <em>HtmlToPdfElement</em> object. Below you can find sample code for setting the username and password for authentication when converting HTML to PDF: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td> <!-- code formatted by http://manoli.net/csharpformat/ --> <!-- code formatted by http://manoli.net/csharpformat/ --> <div class="csharpcode"> <pre class="alt"> htmlToPdfElement.AuthenticationOptions.Username = username;</pre> <pre> htmlToPdfElement.AuthenticationOptions.Password = password;</pre> </div> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px" class="title4"> <a name="HtmlToPdfBookmarks" class="bookmark">6.5.1.1.5 Bookmarks in HtmlToPdfElement</a> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The converter can produce bookmarks in the generated PDF document for a list of specified HTML tags. The bookmarking is controlled by the HtmlToPdfElement.PdfBookmarkOptions property and is enabled only when a list of HTML tag names is specified by the <strong> <em>HtmlToPdfElement.PdfBookmarkOptions.TagNames</em></strong> property. For example, to enable bookmarking of the H1 and H2 tags you can use the following line of C# code: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode">htmlToPdfElement.PdfBookmarkOptions.TagNames = <span class="kwrd"> new</span> <span class="kwrd">string</span>[] { <span class="str">"H1"</span>, <span class="str">"H2"</span> };</pre> </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 23px"> The tags to be bookmarked can be further filtered by CSS class name using the <strong> <em>HtmlToPdfElement.PdfBookmarkOptions.ClassNameFilter</em></strong> property. For example, to filter only the H1 and H2 tags having the CSS class bookmark, the following line of C# can be added to the previous one: </td> </tr> <tr> <td style="height: 23px"> </td> </tr> <tr> <td style="height: 24px"> <!-- code formatted by http://manoli.net/csharpformat/ --> <pre class="csharpcode">htmlToPdfElement.PdfBookmarkOptions.ClassNameFilter = <span class="str">"bookmark"</span>;</pre> </td> </tr> <tr> <td style="height: