Fine-Tuning Converters – Convert HTML, MHTML, EPUB, and SVG in Java

You can convert HTML to various popular formats in a few ways using Aspose.HTML for Java:

• By using the convertHTML() methods of the Converter class. This is the most common way to convert HTML into various formats.
• By using the renderTo(device) method of the HTMLDocument class or render() methods of the Renderer class. This alternative way to render HTML documents can give you more control over the HTML rendering process in your Java application.

Rendering Device

The rendering (output) device encapsulates a 2D drawing surface, whose API is implemented using the IDevice interface. Currently, Aspose.HTML for Java API implements a set of rendering devices – PdfDevice, XpsDevice, DocDevice and ImageDevice, which are used to generate PDF, XPS, DOCX, and Image file formats, respectively.

The next example shows how to use the PdfDevice to render HTML document into PDF file. The process occurs with default rendering options:

1. Load an HTML document.
2. Create an instance of the PdfDevice class using one of the PdfDevice() constructors.
3. Call the renderTo(device) method of the HTMLDocument class.

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize an HTML document from HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of the PdfDevice class and specify the output file to render
PdfDevice device = new PdfDevice("output.pdf");

// Render HTML to PDF
document.renderTo(device);

Rendering Options

Rendering options gives you additional control over the output device. Every rendering device PdfDevice, XpsDevice and ImageDevice has his own unique set of options and implemented with classes PdfRenderingOptions, XpsRenderingOptions, DocRenderingOptions and ImageRenderingOptions, respectively. For example, you can change the page size, adjust the margins and background color, reduce the file size by adjusting the image quality and resolution, set a security password if you use PdfDevice, etc.

Below is a demonstration of how to use PdfRenderingOptions to customize the page size during HTML to PDF rendering:

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize a HTML document from the HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of PdfRenderingOptions and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
PageSetup pageSetup = new PageSetup();
Page anyPage = new Page();
anyPage.setSize(
        new Size(
                Length.fromInches(5),
                Length.fromInches(2)
        )
);
pageSetup.setAnyPage(anyPage);
options.setPageSetup(pageSetup);

// Create a PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

// Render HTML to PDF
document.renderTo(device);

General Options

Rendering Options gives you additional control over the output device. The com.aspose.html.rendering package consists of numerous renderer objects and appropriate low-level options classes responsible for rendering documents into IDevice implementation. The RenderingOptions and CssOptions classes represent rendering options, or in other words, general rendering options.

General Options are valid for all rendering devices and all rendering processes from HTML to PDF, XPS, DOCX, and Images. Let’s look at some of them:

Horizontal and Vertical Resolution

The horizontal and vertical resolution settings are essential for achieving high-quality output when rendering HTML to other formats, for example, HTML to PDF. Horizontal and vertical resolutions are measured (get and set) in pixels per inch (dpi), with a default value of 300 dpi. This setting ensures crisp details and smooth rendering of elements such as text, images, and horizontal and vertical lines in PDF.

The following example shows how to control the resolution of the resulting PDF file, ultimately affecting its size and quality:

// Prepare HTML code and save it to a file
String code = "< style >\n" +
        "                p\n" +
        "        {\n" +
        "            background:\n" +
        "            blue;\n" +
        "        }\n" +
        "        @media(min - resolution:300dpi)\n" +
        "        {\n" +
        "            p\n" +
        "            {\n" +
        "                /* high resolution screen color */\n" +
        "                background:\n" +
        "                green\n" +
        "            }\n" +
        "        }\n" +
        "    </style >\n" +
        "    <p > Hello World !! </p >\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of the HTMLDocument class
HTMLDocument document = new HTMLDocument("document.html");

// Create options for low-resolution screens
PdfRenderingOptions options = new PdfRenderingOptions();
options.setHorizontalResolution(Resolution.to_Resolution(50d));
options.setVerticalResolution(Resolution.to_Resolution(50d));

// Create an instance of the PdfDevice
PdfDevice device = new PdfDevice(
        options,
        "output_resolution_50.pdf"
);

// Render HTML to PDF
document.renderTo(device);

// Create options for high-resolution screens
options = new PdfRenderingOptions();
options.setHorizontalResolution(Resolution.to_Resolution(300d));
options.setVerticalResolution(Resolution.to_Resolution(300d));

// Create an instance of PDF device
device = new PdfDevice(
        options,
        "output_resolution_300.pdf"
);

// Render HTML to PDF
document.renderTo(device);

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 or inline style sheet:

Linked Style Sheet

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

Inline Style Sheet

<style type="text/css">
@media print {
  body{ color: #000000; }
}
</style>

Aspose.HTML for Java 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:

// Prepare HTML code
String code = "<span>Hello, World!!</span>";

// Initialize an HTML document from the HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of the PdfRenderingOptions class
PdfRenderingOptions options = new PdfRenderingOptions();
// Set the 'screen' media-type
options.getCss().setMediaType(MediaType.Screen);

// Create a PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

// Render HTML to PDF
document.renderTo(device);

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

The Background Color setting is a critical feature for customizing the appearance of the rendered document. It allows developers to specify the color that will fill the background of each page in the output file. By default, this property is set to Transparent, which means that the background will have no visible fill unless explicitly specified. Customizing the background color can improve the readability of a document, meet branding requirements, or create visually appealing designs.

// Prepare HTML code and save it to a file
String code = "<p>Hello, World!!</p>";
try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of the HTMLDocument class
HTMLDocument document = new HTMLDocument("document.html");

// Initialize options with 'cyan' as a background-color
PdfRenderingOptions options = new PdfRenderingOptions();
options.setBackgroundColor(Color.getCyan());

// Create an instance of the PdfDevice class
PdfDevice device = new PdfDevice(options, "output.pdf");

// Render HTML to PDF
document.renderTo(device);

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.

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 use AdjustToWidestPage of the PageSetup class. The following example shows how to adjust the page size to the content.

// Prepare HTML code
String code = "    <style>\n" +
        "        div {\n" +
        "            page - break -after:always;\n" +
        "        }\n" +
        "    </style >\n" +
        "    <div style = 'border: 1px solid red; width: 400px' > First Page</div >\n" +
        "    <div style = 'border: 1px solid red; width: 600px' > Second Page</div >\n";
// Initialize an HTML document from HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of the PdfRenderingOptions class and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
options.getPageSetup().setAnyPage(new Page(new Size(500, 200)));

// Enable auto-adjusting for the page size
options.getPageSetup().setAdjustToWidestPage(true);

// Create an instance of the PdfDevice class and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

// Render HTML to PDF
document.renderTo(device);

PDF Options

The PdfRenderingOptions class gives developers extensive control over the rendering process when converting HTML to PDF. It allows customization of all general options and, in addition, it offers options specific to rendering only to PDF format – DocumentInfo, Encryption, FormFieldBehaviour, and JpegQuality.

The following example demonstrates the functionality of setting permissions for a PDF file.

// Prepare HTML code
String code = "<div>Hello, World!!</div>";

// Initialize an HTML document from the HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create the instance of the PdfRenderingOptions class
PdfRenderingOptions options = new PdfRenderingOptions();

// Set file permissions
options.setEncryption(
        new PdfEncryptionInfo(
                "user_pwd",
                "owner_pwd",
                PdfPermissions.PrintDocument,
                PdfEncryptionAlgorithm.RC4_128
        )
);

// Create a PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

// Render HTML to PDF
document.renderTo(device);

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:

// Prepare HTML code
String code = "<div>Hello, World!!</div>";

// Initialize an instance of the HTMLDocument class based on prepared code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of the ImageRenderingOptions class
ImageRenderingOptions options = new ImageRenderingOptions();
options.setFormat(ImageFormat.Jpeg);

// Disable smoothing mode
options.setSmoothingMode(SmoothingMode.None);

// Set the image resolution as 75 dpi
options.setVerticalResolution(Resolution.fromDotsPerInch(75));
options.setHorizontalResolution(Resolution.fromDotsPerInch(75));

// Create an instance of the ImageDevice class
ImageDevice device = new ImageDevice(options, "output.jpg");

// Render HTML to Image
document.renderTo(device);

Renderers

While the renderTo(device) method of the Document class 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 for Java 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 HTML documents:

// Prepare HTML code
String code1 = "<br><span style='color: green'>Hello, World!!</span>";
String code2 = "<br><span style='color: blue'>Hello, World!!</span>";
String code3 = "<br><span style='color: red'>Hello, World!!</span>";

// Create three HTML documents to merge later
HTMLDocument document1 = new HTMLDocument(code1, ".");
HTMLDocument document2 = new HTMLDocument(code2, ".");
HTMLDocument document3 = new HTMLDocument(code3, ".");

// Create an instance of HTML Renderer
HtmlRenderer renderer = new HtmlRenderer();

// Create an instance of the PdfDevice class
PdfDevice device = new PdfDevice("output.pdf");

// Merge all HTML documents to PDF
renderer.render(device, new HTMLDocument[]{document1, document2, document3});

Set Timeout

One more important feature that is available for renderers is the timeout setting. 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 an endless loop, you will wait indefinitely. The example below demonstrates how to use the render(device, timeout, documents) method with the timeout parameter:

// Prepare HTML code
String code = "< script >\n" +
        "        var count = 0;\n" +
        "        setInterval(function()\n" +
        "        {\n" +
        "            var element = document.createElement('div');\n" +
        "            var message = (++count) + '. ' + 'Hello World!!';\n" +
        "            var text = document.createTextNode(message);\n" +
        "            element.appendChild(text);\n" +
        "            document.body.appendChild(element);\n" +
        "        },1000);\n" +
        "</script >\n";

// Initialize an HTML document based on prepared HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of HTML Renderer
HtmlRenderer renderer = new HtmlRenderer();

// Create an instance of the PdfDevice class
PdfDevice device = new PdfDevice("output.pdf");

// Render HTML to PDF
renderer.render(device, 5, document);

Conclusion

Aspose.HTML for Java is a powerful and flexible library for rendering HTML, MHTML, EPUB, and SVG to various formats, such as PDF, XPS, DOCX, and images. The Converter class is fast and easy to use for simple tasks. However, if you need more control over rendering options, use the renderTo(device) method.

With a wide range of rendering options and configurable features, developers have full control over the output, including resolution, page settings, CSS media types, and device-specific configurations. The flexibility of the API, demonstrated by the ability to use multiple renderers, configure general and format-specific options, and even manage timeouts, makes it a great choice for creating high-quality, customized documents.