Fine-Tuning Converters

Using the Converter.ConvertHTML methods is the most common way to convert HTML code into various formats. However, Aspose.HTML API also provides alternative ways to render HTML documents with that can give you more control over the rendering process in your C# application.

Output Device

The output device encapsulates a 2D drawing surface, whose API is implemented using the IDevice interface. Currently, API provides the following implementations: PdfDeviceXpsDevice and ImageDevice, which are used to generate PDF, XPS and Image file formats, respectively.

The next example shows how to use PdfDevice to render HTML document into PDF file:

  1. Create an instance of HTML document.
  2. Create an instance of PDF Output Device.
  3. Call HTMLDocument.RenderTo method with specified device.

Device Options

Rendering Options gives you additional control over the output device. You can change the page size, configure margins and colors, set a security password in case of PDF device, etc. Every output device PdfDeviceXpsDevice and ImageDevice has his own unique set of options and implemented with classes PdfRenderingOptionsXpsRenderingOptions and ImageRenderingOptions, respectively.

Following is a demonstration of how to use Rendering Options to customize the page-size:

General Options

Rendering Options gives you additional control over the output device. You can change the page size, configure margins and colors, set a security password in case of PDF device, etc. Every output device PdfDeviceXpsDevice and ImageDevice has his own unique set of options and implemented with classes PdfRenderingOptionsXpsRenderingOptions and ImageRenderingOptions, respectively.

Following is a demonstration of how to use Rendering Options to customize the page-size:

The next few pictures show the result of the rendering with 50 dpi and 300 dpi resolutions:

‘Hello World’ with blue background

‘Hello World’ with green background

CSS Media Type

CSS media-type is an important feature that specifies how a document is to be presented on different media: on the screen, on paper, with a braille device, etc. There are few ways to specify media-type for a style sheet, via linked style sheets:

Linked Style Sheet

 <link rel="stylesheet" type="text/css" media="print" href="style.css">

or, via inlining:

Inline Style Sheet

 <style type="text/css">

@media print {

  body{ color: #000000; }

}

</style>

Aspose.HTML API supports this feature, so you can convert HTML documents as they look on screen or on print with applying the corresponded media types and style sheets. Following example shows how to set up the media type:

 // Create an option class

var options = new PdfRenderingOptions();

// Set the 'screen' media-type

options.Css.MediaType = MediaType.Screen;

Background Color

A property that specifies the background color of the output drawing surface.

Page Setup

The page setup is a set of parameters that determine the layout of a printed page. Those parameters include everything from the page size, margins, and auto-resizing to @page priority rules. Using this set of parameters, you can easily set up an individual layout for every page.

The next example demonstrates how to create PDF with different page sizes for the left and right pages.

In some cases, the content of the HTML page could be wider than the page-size defined with options. If you don’t want to cut off the page content, you can try the PageSetup.AdjustToWidestPage property. The following example shows how to adjust the page size to the content. 

PDF Options

Using a specialized PdfRenderingOptions object, you can configure permissions for the PDF file. The next example demonstrates this feature.

Image Options

ImageRenderingOptions allows you to customize a wide range of setting from smoothing (antialiasing), image resolution, and formats to image compression.

Following example demonstrates how to change resolution and antialiasing for the resulted image.

XPS Options

XPS files generated by our library do not have any specific parameters. All parameters of XpsRenderingOptions are inherited from the base RenderingOptions class and described here.

Renderers

While the Document.RenderTo method gives you the ability to send a single document to the output rendering device, using the Renderer instances directly you can send multiple files at once. Aspose.HTML API provides the following implementation of renderers: HtmlRendererSvgRendererMhtmlRenderer and EpubRenderer, which are used to render HTML, SVG, MHTML and EPUB documents, respectively.

The next example demonstrates how to use HtmlRenderer to render multiple documents:

Timeout

One more important feature that is available for renderers is timeout. You can use it to specify how long you are ready to wait for all internal processes related to a document lifecycle to be completed, such as resource loading, active timers, etc. Sure, you can specify an infinite waiting period. However, if the document contains a script with the endless loop, you will wait indefinitely. The example below demonstrates how to use the timeout parameter: 

Running this example, you will get a document with five lines of ‘Hello World’ message, as it follows:

five lines of ‘Hello World’