Skip to main content

How Do I Reference Images in My HTML Output Instead of Embedding in Java Engine?

When outputting to HTML, users can embed images as Base64-encoded data via an Import Tag or reference images by file locations pointing to the source. This article explains how to explicitly select either output method.

Default Behavior​

The template used in all the examples below contains an Import Tag that imports an image from a URL.

The following code snippet shows our default behavior:

File fileReport = new File("out/report_default.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);
            
// Nothing specified yet
         
report.processSetup();
          
DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));
            
report.processData(datasource, "images");
            
report.processComplete();
template.close();
reportStream.close();

This code creates the following HTML output. Images default to being embedded inside the HTML as Base64-encoded images:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="data:image/png;base64,/9j[...]42Q==" width="1024" height="768" /><br></p>
</div></body>
</html>

The same default output can be achieved by explicitly specifying embedding using the setEmbedImages method:

File fileReport = new File("out/report_true.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Explicitly specify to embed images in output
report.setEmbedImages(true);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

Referencing Image Locations in HTML Output​

Alternatively, specify a location for the images to be saved as output is generated, and then reference these image locations in the HTML. Use two methods:

  1. ProcessHtmlAPI.setImagePath(String s, String s2, String s3): specify the location to save images, the relative location from the HTML output to reference images, and the prefix to use for saved images. Read more here.
  2. ProcessHtmlAPI.setEmbedImages(boolean b): set to false to use the specified image paths to save and reference images. Read more here.

The final code looks like this:

File fileReport = new File("out/report_false.html");
FileInputStream template = new FileInputStream("data/image.docx");
FileOutputStream reportStream = new FileOutputStream(fileReport);
ProcessHtmlAPI report = new ProcessHtml(template, reportStream);

// Specify to use file reference instead of embedding images.
// Save images to the relative path "out/images"
// Since the HTML output is to the relative path "out" the relative image location to the HTML file is just "images"
// Prefix the saved image names with "outputImage"
report.setImagePath("out/images", "images", "outputImage");
// Explicitly override default functionality
report.setEmbedImages(false);

report.processSetup();

DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/images.xml"));

report.processData(datasource, "images");

report.processComplete();
template.close();
reportStream.close();

The output HTML references the image at the relative "images" location, and the image is saved with the specified prefix and an appended identifier:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en">
<style type="text/css">
p {
font-family:Calibri;
font-size:11.0pt;
color:#000000;
margin-top:0.0pt;
margin-bottom:8.0pt;
line-height:1.08;
margin-right:0.0pt;
border:0 none;
text-align:left;
text-indent:0.0pt;
}
IMG.centered{
    display: block;
    margin-left: auto;
    margin-right: auto
}IMG.right{
    float:right;
}IMG.left{
    float:left;
}
#container {
    width:624px;
    margin:0px auto;
}
</style>
</head>
<body><div id="container">
<p><br><img src="images/outputImage1724012377056703473.jpg" width="1024" height="768" /><br></p>
</div></body>
</html>