Rendering Options – Customize HTML Rendering

Rendering options provide detailed control over how the rendering device processes content. Each device – PdfDevice, XpsDevice, DocDevice, and ImageDevice – has its own class of options: PdfRenderingOptions, XpsRenderingOptions, DocRenderingOptions, and ImageRenderingOptions. With these options, you can adjust page size, margins, and colors, as well as apply device-specific settings, such as adding a security password to PDF files. Customization is crucial for achieving the desired results, whether it involves reducing file size by adjusting image quality and resolution or enhancing readability through optimized page layout and text formatting.

In this article, Rendering Options in Aspose.HTML for Python via .NET are explored, showing how to customize the conversion of HTML content into output formats such as PDF, XPS, DOCX, and images. These options include general settings such as page size, background color, and resolution, as well as device-specific settings, including image compression, PDF security, and font embedding, which enable full control over the final output.

Here, you will find Python code examples that demonstrate the use of device-specific parameters. The use of general options will be covered in the “How-to Articles” chapter (in preparation).

To learn more about the rendering process, please read the Rendering Device article.

PDF Rendering Options

The PdfRenderingOptions class, along with general options, supports several specific parameters, such as jpeg_quality, document_info, encryption, form_field_behaviour, and is_tagged_pdf.

Property	Description
jpeg_quality	Specifies the quality of JPEG compression for images. The default value is 95.
document_info	This property contains information about the output PDF document.
encryption	This property gets or sets encryption details. If it is not set, then no encryption will be performed.
form_field_behaviour	This property specifies the behavior of form fields in the output PDF document.
is_tagged_pdf	If is_tagged_pdf = true, a tag structure will be added to the PDF document during rendering.

The form_field_behaviour property is used to specify the behavior of form fields in a PDF document. To learn what it means to flatten a PDF file and how to do it using the Aspose.HTML for Python via .NET library, please see the HTML to PDF conversion and PDF flattening section.

The following Python code demonstrates how to add encryption to a PDF output file using the PdfRenderingOptions class:

import os
import aspose.html as ah
import aspose.html.rendering as rn
import aspose.html.rendering.pdf as rp
import aspose.html.rendering.pdf.encryption as rpe

# Setup input and output directories
data_dir = "data/"
output_dir = "output/"
os.makedirs(output_dir, exist_ok=True)

# Prepare path to the source HTML file
document_path = os.path.join(data_dir, "document.html")

# Initialize an HTML document from the file
doc = ah.HTMLDocument(document_path)

# Create an instance of the HTML Renderer
renderer = rn.HtmlRenderer()

# Prepare path to save the converted PDF
save_path = os.path.join(output_dir, "convert-html-to-pdf-with-encryption.pdf")

# Create PDF rendering options and set password protection
options = rp.PdfRenderingOptions()
options.encryption = rpe.PdfEncryptionInfo(
    user_password="user_pwd",
    owner_password="owner_pwd",
    permissions=rpe.PdfPermissions.PRINT_DOCUMENT,
    encryption_algorithm=rpe.PdfEncryptionAlgorithm.RC4_128
)

# Create the PDF device with options and output path
device = rp.PdfDevice(options, save_path)

# Render HTML to PDF
renderer.render(device, doc)

The example above shows how to create a new PdfRenderingOptions instance and set encryption options for a PDF output file. To do this, you need to create a PdfEncryptionInfo object, which defines the encryption settings for the PDF file. The constructor takes four parameters:

• user_password and owner_password, which are required to open and work with the PDF file;
• permissions – a set of allowed permissions for a PDF file. In this case, PdfPermissions.PRINT_DOCUMENT is specified, which enables the user to print the document;
• encryption_algorithm – the encryption algorithm used to secure the PDF file. In this case, PdfEncryptionAlgorithm.RC4_128 is used, which is a 128-bit RC4 encryption algorithm.

Image Rendering Options

The ImageRenderingOptions class supports all general options and allows you to configure specific options, such as anti-aliasing, text rendering configuration, image format selection, and image compression.

Property	Description
compression	Sets Tagged Image File Format (TIFF) compression. By default, this property is LZW.
format	Sets the ImageFormat (JPG, PNG, BMP, TIFF, or GIF). By default, this property is PNG.
use_antialiasing	This property defines the rendering quality of the image by controlling the use of antialiasing. Antialiasing is enabled by default.
text	Gets a TextOptions object which is used for configuration of text rendering.

Let’s consider how to use a specialized ImageRenderingOptions object to set TIFF format and compression for the image:

import os
import aspose.html as ah
import aspose.html.rendering.image as ri

# Setup input and output directories
data_dir = "data/"
output_dir = "output/"
os.makedirs(output_dir, exist_ok=True)

# Prepare paths for input HTML and output TIFF file
document_path = os.path.join(data_dir, "html_file.html")
save_path = os.path.join(output_dir, "html_file.tiff")

# Initialize an HTML document from the file
doc = ah.HTMLDocument(document_path)

# Create rendering options for image format (TIFF in this case)
image_options = ri.ImageRenderingOptions(ri.ImageFormat.TIFF)
image_options.compression = ri.Compression.NONE

# Create an ImageDevice and specify options and output file
device = ri.ImageDevice(image_options, save_path)

# Render HTML to TIFF
doc.render_to(device)

XPS Rendering Options

XpsRenderingOptions inherit all settings from the base RenderingOptions class. You can configure page size, margins, background color, and other common options when generating XPS files.

import os
import aspose.html as ah
import aspose.html.rendering.xps as rx
import aspose.html.drawing as dr

# Setup input and output directories
data_dir = "data/"
output_dir = "output/"
os.makedirs(output_dir, exist_ok=True)

# Prepare a path to the source HTML file
document_path = os.path.join(data_dir, "document.html")

# Initialize the HTML document from the file
doc = ah.HTMLDocument(document_path)

# Create an instance of XPS Rendering Options
options = rx.XpsRenderingOptions()

# Set custom page size (5 x 2 inches)
options.page_setup.any_page = dr.Page(dr.Size(dr.Length.from_inches(5.0), dr.Length.from_inches(2.0)))

# Prepare a path to save the converted file
save_path = os.path.join(output_dir, "document-options.xps")

# Create an XpsDevice with the specified options and output file
device = rx.XpsDevice(options, save_path)

# Render HTML to XPS
doc.render_to(device)

DOC Rendering Options

The DocRenderingOptions class supports all general options and allows you to customize font_embedding_rule and document_format properties for the output file.

Property	Description
font_embedding_rule	This property gets or sets the font embedding rule. Available values are Full and None. The default value is None.
document_format	This property gets or sets the file format of the output document. The default value is DOCX.

The following example shows how to customize the rendering options for an output DOCX document by setting the page size and font embedding rule:

import os
import aspose.html as ah
import aspose.html.rendering.doc as rd
import aspose.html.drawing as dr

# Setup input and output directories
data_dir = "data/"
output_dir = "output/"
os.makedirs(output_dir, exist_ok=True)

# Prepare a path to the source HTML file
document_path = os.path.join(data_dir, "document.html")

# Initialize the HTML document from the file
doc = ah.HTMLDocument(document_path)

# Create an instance of DocRenderingOptions and set a custom page size
options = rd.DocRenderingOptions()
options.page_setup.any_page = dr.Page(dr.Size(dr.Length.from_inches(8.0), dr.Length.from_inches(10.0)))
options.font_embedding_rule = rd.FontEmbeddingRule.FULL

# Prepare a path to save the converted file
save_path = os.path.join(output_dir, "document-options.docx")

# Create a DocDevice with the specified options and output file
device = rd.DocDevice(options, save_path)

# Render HTML to DOCX
doc.render_to(device)

Aspose.HTML offers free online Converters that can convert HTML, XHTML, MHTML, EPUB, XML, and Markdown files to a range of popular formats. You can easily convert your HTML-based documents to PDF, XPS, DOCX, JPG, PNG, GIF, TIFF, and others. Just select a file, choose the format to convert, and you’re done.