Fine-Tuning Converters

Using the Converter.ConvertHTML method 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 Java 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: PdfDevice, XpsDevice 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:

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

 1// Prepare an HTML code
 2String code = "<span>Hello World!!</span>";
 3
 4// Initialize the HTML document from the HTML code
 5com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
 6try {
 7    // Create the PDF Device and specify the output file to render
 8    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice("output.pdf");
 9    try {
10        // Render HTML to PDF
11        document.renderTo(device);
12    } finally {
13        if (device != null) {
14            device.dispose();
15        }
16    }
17} finally {
18    if (document != null) {
19        document.dispose();
20    }
21}

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 PdfDevice, XpsDevice and ImageDevice has his own unique set of options and implemented with classes PdfRenderingOptions, XpsRenderingOptions and ImageRenderingOptions, respectively.

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

 1// Prepare an HTML code
 2String code = "<span>Hello World!!</span>";
 3
 4// Initialize the HTML document from the HTML code
 5com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
 6try {
 7    // Create the instance of PdfRenderingOptions and set a custom page-size
 8    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
 9    com.aspose.html.rendering.PageSetup pageSetup = new com.aspose.html.rendering.PageSetup();
10    com.aspose.html.drawing.Page anyPage = new com.aspose.html.drawing.Page();
11    anyPage.setSize(
12            new com.aspose.html.drawing.Size(
13                    com.aspose.html.drawing.Length.fromInches(5),
14                    com.aspose.html.drawing.Length.fromInches(2)
15            )
16    );
17    pageSetup.setAnyPage(anyPage);
18    options.setPageSetup(pageSetup);
19
20    // Create the PDF Device and specify options and output file
21    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(options, "output.pdf");
22    try {
23        // Render HTML to PDF
24        document.renderTo(device);
25    } finally {
26        if (device != null) {
27            device.dispose();
28        }
29    }
30} finally {
31    if (document != null) {
32        document.dispose();
33    }
34}

General Options

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

 1// Prepare an HTML code and save it to the file.
 2String code = "< style >\n" +
 3              "                p\n" +
 4              "        {\n" +
 5              "            background:\n" +
 6              "            blue;\n" +
 7              "        }\n" +
 8              "        @media(min - resolution:300dpi)\n" +
 9              "        {\n" +
10              "            p\n" +
11              "            {\n" +
12              "                /* high resolution screen color */\n" +
13              "                background:\n" +
14              "                green\n" +
15              "            }\n" +
16              "        }\n" +
17              "    </style >\n" +
18              "    <p > Hello World !! </p >\n";
19
20try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
21    fileWriter.write(code);
22}
23
24// Create an instance of HTML document
25com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument("document.html");
26try {
27    // Create options for low-resolution screens
28    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
29    options.setHorizontalResolution(com.aspose.html.drawing.Resolution.to_Resolution(50d));
30    options.setVerticalResolution(com.aspose.html.drawing.Resolution.to_Resolution(50d));
31
32    // Create an instance of PDF device
33    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(
34            options,
35            "output_resolution_50.pdf"
36    );
37    try {
38        // Render HTML to PDF
39        document.renderTo(device);
40    } finally {
41        if (device != null) {
42            device.dispose();
43        }
44    }
45
46    // Create options for high-resolution screens
47    options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
48    options.setHorizontalResolution(com.aspose.html.drawing.Resolution.to_Resolution(300d));
49    options.setVerticalResolution(com.aspose.html.drawing.Resolution.to_Resolution(300d));
50
51    // Create an instance of PDF device
52    device = new com.aspose.html.rendering.pdf.PdfDevice(
53            options,
54            "output_resolution_300.pdf"
55    );
56    try {
57        // Render HTML to PDF
58        document.renderTo(device);
59    } finally {
60        if (device != null) {
61            device.dispose();
62        }
63    }
64} finally {
65    if (document != null) {
66        document.dispose();
67    }
68}

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

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

or, via inlining:

Inline Style Sheet

1 <style type="text/css">
2
3@media print {
4
5  body{ color: #000000; }
6
7}
8
9</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:

1 // Create an option class
2 var options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
3
4 // Set the 'screen' media-type
5 options.getCss().setMediaType(com.aspose.html.rendering.MediaType.Screen);

Please note that the default value of the CssOptions.MediaType is Print. It means that the document will be converting with applying style sheets related to the printing device and looks like on paper (you can use print preview of your browser to see the difference). If you want the document to look the way it is rendered on screen, you should use MediaType.Screen.

Background Color

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

 1// Prepare an HTML code and save it to the file.
 2String code = "<p>Hello World!!</p>";
 3try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
 4    fileWriter.write(code);
 5}
 6
 7// Create an instance of HTML document
 8com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument("document.html");
 9try {
10    // Initialize options with 'cyan' as a background-color
11    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
12
13    options.setBackgroundColor(com.aspose.html.drawing.Color.getCyan());
14
15    // Create an instance of PDF device
16    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(options, "output.pdf");
17    try {
18        // Render HTML to PDF
19        document.renderTo(device);
20    } finally {
21        if (device != null) {
22            device.dispose();
23        }
24    }
25} finally {
26    if (document != null) {
27        document.dispose();
28    }
29}

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.

 1// Prepare an HTML code
 2String code = "<style>\n" +
 3              "    div { page-break-after: always; }\n" +
 4              "</style>\n" +
 5              "< div > First Page</div >\n" +
 6              "<div > Second Page</div >\n" +
 7              "<div > Third Page</div >\n" +
 8              "<div > Fourth Page</div >\n";
 9
10// Initialize the HTML document from the HTML code
11com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
12try {
13    // Create the instance of Rendering Options and set a custom page-size
14    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
15    options.getPageSetup().setLeftRightPage(
16            new com.aspose.html.drawing.Page(new com.aspose.html.drawing.Size(400, 200)),
17            new com.aspose.html.drawing.Page(new com.aspose.html.drawing.Size(400, 100))
18    );
19
20    // Create the PDF Device and specify options and output file
21    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(options, "output.pdf");
22    try {
23        // Render HTML to PDF
24        document.renderTo(device);
25    } finally {
26        if (device != null) {
27            device.dispose();
28        }
29    }
30} finally {
31    if (document != null) {
32        document.dispose();
33    }
34}

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.

 1// Prepare an HTML code
 2String code = "    <style>\n" +
 3              "        div {\n" +
 4              "            page - break -after:always;\n" +
 5              "        }\n" +
 6              "    </style >\n" +
 7              "    <div style = 'border: 1px solid red; width: 400px' > First Page</div >\n" +
 8              "    <div style = 'border: 1px solid red; width: 600px' > Second Page</div >\n";
 9// Initialize the HTML document from the HTML code
10com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
11try {
12    // Create the instance of Rendering Options and set a custom page-size
13    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
14    options.getPageSetup().setAnyPage(new com.aspose.html.drawing.Page(new com.aspose.html.drawing.Size(500, 200)));
15
16    // Enable auto-adjusting for the page size
17    options.getPageSetup().setAdjustToWidestPage(true);
18
19    // Create the PDF Device and specify options and output file
20    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(options, "output.pdf");
21    try {
22        // Render HTML to PDF
23        document.renderTo(device);
24    } finally {
25        if (device != null) {
26            device.dispose();
27        }
28    }
29} finally {
30    if (document != null) {
31        document.dispose();
32    }
33}

PDF Options

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

 1// Prepare an HTML code
 2String code = "<div>Hello World!!</div>";
 3// Initialize the HTML document from the HTML code
 4com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
 5try {
 6    // Create the instance of Rendering Options
 7    com.aspose.html.rendering.pdf.PdfRenderingOptions options = new com.aspose.html.rendering.pdf.PdfRenderingOptions();
 8
 9    // Set the permissions to the file
10    options.setEncryption(
11            new com.aspose.html.rendering.pdf.encryption.PdfEncryptionInfo(
12                    "user_pwd",
13                    "owner_pwd",
14                    com.aspose.html.rendering.pdf.encryption.PdfPermissions.PrintDocument,
15                    com.aspose.html.rendering.pdf.encryption.PdfEncryptionAlgorithm.RC4_128
16            )
17    );
18
19    // Create the PDF Device and specify options and output file
20    com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice(options, "output.pdf");
21    try {
22        // Render HTML to PDF
23        document.renderTo(device);
24    } finally {
25        if (device != null) {
26            device.dispose();
27        }
28    }
29} finally {
30    if (document != null) {
31        document.dispose();
32    }
33}

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.

 1// Prepare an HTML code
 2String code = "<div>Hello World!!</div>";
 3
 4// Initialize an instance of HTML document based on prepared code
 5com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
 6try {
 7    // Create an instance of Rendering Options
 8    com.aspose.html.rendering.image.ImageRenderingOptions options = new com.aspose.html.rendering.image.ImageRenderingOptions();
 9    options.setFormat(com.aspose.html.rendering.image.ImageFormat.Jpeg);
10    // Disable smoothing mode
11    options.setSmoothingMode(com.aspose.html.drawing.SmoothingMode.None);
12    // Set the image resolution as 75 dpi
13    options.setVerticalResolution(com.aspose.html.drawing.Resolution.fromDotsPerInch(75));
14    options.setHorizontalResolution(com.aspose.html.drawing.Resolution.fromDotsPerInch(75));
15
16    // Create an instance of Image Device
17    com.aspose.html.rendering.image.ImageDevice device = new com.aspose.html.rendering.image.ImageDevice(options, "output.jpg");
18    try {
19        // Render HTML to Image
20        document.renderTo(device);
21    } finally {
22        if (device != null) {
23            device.dispose();
24        }
25    }
26} finally {
27    if (document != null) {
28        document.dispose();
29    }
30}

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.

 1// Prepare an HTML code
 2String code = "<span>Hello World!!</span>";
 3
 4// Initialize the HTML document from the HTML code
 5com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
 6try {
 7    // Create the instance of XpsRenderingOptions and set a custom page-size
 8    com.aspose.html.rendering.xps.XpsRenderingOptions options = new com.aspose.html.rendering.xps.XpsRenderingOptions();
 9    com.aspose.html.drawing.Page anyPage = new com.aspose.html.drawing.Page();
10    anyPage.setSize(
11            new com.aspose.html.drawing.Size(
12                    com.aspose.html.drawing.Length.fromInches(5),
13                    com.aspose.html.drawing.Length.fromInches(2)
14            )
15    );
16    options.getPageSetup().setAnyPage(anyPage);
17
18    // Create the XPS Device and specify options and output file
19    com.aspose.html.rendering.xps.XpsDevice device = new com.aspose.html.rendering.xps.XpsDevice(options, "output.xps");
20    try {
21        // Render HTML to XPS
22        document.renderTo(device);
23    } finally {
24        if (device != null) {
25            device.dispose();
26        }
27    }
28} finally {
29    if (document != null) {
30        document.dispose();
31    }
32}

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: HtmlRenderer, SvgRenderer, MhtmlRenderer 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:

 1// Prepare an HTML code
 2String code1 = "<br><span style='color: green'>Hello World!!</span>";
 3String code2 = "<br><span style='color: blue'>Hello World!!</span>";
 4String code3 = "<br><span style='color: red'>Hello World!!</span>";
 5
 6// Create three HTML documents to merge later
 7com.aspose.html.HTMLDocument document1 = new com.aspose.html.HTMLDocument(code1, ".");
 8com.aspose.html.HTMLDocument document2 = new com.aspose.html.HTMLDocument(code2, ".");
 9com.aspose.html.HTMLDocument document3 = new com.aspose.html.HTMLDocument(code3, ".");
10try {
11    // Create an instance of HTML Renderer
12    com.aspose.html.rendering.HtmlRenderer renderer = new com.aspose.html.rendering.HtmlRenderer();
13    try {
14        // Create an instance of PDF device
15        com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice("output.pdf");
16        try {
17            // Merge all HTML documents into PDF
18            renderer.render(device, new com.aspose.html.HTMLDocument[]{document1, document2, document3});
19        } finally {
20            if (device != null) {
21                device.dispose();
22            }
23        }
24    } finally {
25        if (renderer != null) {
26            renderer.dispose();
27        }
28    }
29} finally {
30    if (document1 != null) {
31        document1.dispose();
32    }
33    if (document2 != null) {
34        document2.dispose();
35    }
36    if (document3 != null) {
37        document3.dispose();
38    }
39}

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:

 1// Prepare an HTML code
 2String code = "< script >\n" +
 3              "        var count = 0;\n" +
 4              "        setInterval(function()\n" +
 5              "        {\n" +
 6              "            var element = document.createElement('div');\n" +
 7              "            var message = (++count) + '. ' + 'Hello World!!';\n" +
 8              "            var text = document.createTextNode(message);\n" +
 9              "            element.appendChild(text);\n" +
10              "            document.body.appendChild(element);\n" +
11              "        },1000);\n" +
12              "</script >\n";
13
14// Initialize an HTML document based on prepared HTML code
15com.aspose.html.HTMLDocument document = new com.aspose.html.HTMLDocument(code, ".");
16try {
17    // Create an instance of HTML Renderer
18    com.aspose.html.rendering.HtmlRenderer renderer = new com.aspose.html.rendering.HtmlRenderer();
19    try {
20        // Create an instance of PDF device
21        com.aspose.html.rendering.pdf.PdfDevice device = new com.aspose.html.rendering.pdf.PdfDevice("output.pdf");
22        try {
23            // Render HTML to PDF
24            renderer.render(device, 5, document);
25        } finally {
26            if (device != null) {
27                device.dispose();
28            }
29        }
30    } finally {
31        if (renderer != null) {
32            renderer.dispose();
33        }
34    }
35} finally {
36    if (document != null) {
37        document.dispose();
38    }
39}

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

five lines of ‘Hello World’

HTML Template HTML Navigation