Generate HTML from Templates in Java

Use Converter.convertTemplate() to populate an HTML template with XML or JSON data. Define placeholders in the template, load the structured data with TemplateData, configure TemplateLoadOptions, and save or return the populated HTML document.

An HTML template is reusable markup containing placeholders for dynamic values. Aspose.HTML for Java matches template expressions with fields in an XML or JSON data source and substitutes the corresponding values. This workflow is useful for generated pages, reports, HTML email bodies, document fragments, and other server-side HTML generation tasks.

The convertTemplate() overloads accept an HTML template as a file path, URL, inline string, or HTMLDocument. Depending on the overload, the result is saved to an output path or returned as an HTMLDocument for further processing.

Understanding HTML Template Syntax

Template expressions use double curly braces to map values from the data source into the HTML markup. A field name can address a top-level value, while dot notation accesses nested values.

Data-Binding Expressions

A data-binding expression has the following form:

{{ data-binding expression }}

For example, the following XML data contains personal and address information.

XML data source

<Data>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<Address>
    <City>Chicago</City>
    <Street>Oakmound Drive</Street>
    <Number>100</Number>
</Address>
</Data>

The HTML template uses {{FirstName}} and {{LastName}} for top-level values. Expressions such as {{Address.Street}} use dot notation to read nested values.

HTML template

<table border=1>
    <tr>
        <th>Person</th>
        <th>Address</th>
    </tr>
    <tr>
        <td>{{FirstName}} {{LastName}}</td>
        <td>{{Address.Street}} {{Address.Number}}, {{Address.City}}</td>
    </tr>
</table>

Foreach Directive Expressions

Use a {{#foreach ... }} directive together with data-binding expressions to repeat markup for items in a collection. The next XML source contains several Person elements under Persons.

XML data source

<Data>
    <Persons>
        <Person>
                <FirstName>John</FirstName>
                <LastName>Doe</LastName>
                <Address>
                        <Number>100</Number>
                        <Street>Oakmound Drive</Street>
                        <City>Chicago</City>
                </Address>
                <Phone1>773-349-7747</Phone1>
                <Phone2>708-252-9790</Phone2>
        </Person>
        <Person>
                <FirstName>Jack</FirstName>
                <LastName>Fox</LastName>
                <Address>
                        <Number>355</Number>
                        <Street>Haul Road</Street>
                        <City>San Francisco</City>
                </Address>
                <Phone1>650-942-7641</Phone1>
            </Person>
            <Person>
                <FirstName>Sherlock</FirstName>
                <LastName>Holmes</LastName>
                <Address>
                        <Number>45</Number>
                        <Street>Baker str.</Street>
                        <City>London</City>
                </Address>
                <Phone1>012-5146-564</Phone1>
        </Person>
    </Persons>
</Data>

Assign the directive to the data_merge attribute. In this example, Persons.Person selects the repeated collection, and the expressions inside the table are evaluated for each Person item.

HTML template

<table border=1 data_merge='{{#foreach Persons.Person}}'>
    <tr>
        <th>Person</th>
        <th>Address</th>
    </tr>
    <tr>
        <td>{{FirstName}} {{LastName}}</td>
        <td>{{Address.Street}} {{Address.Number}}, {{Address.City}}</td>
    </tr>
</table>

The current implementation supports the foreach directive on DIV, OL, UL, and TABLE elements.

XML and JSON Data Sources

Template data can be stored in XML or JSON. Keep the structure and field names aligned with the expressions used by the HTML template. The following XML and JSON examples represent the same values.

XML data source

 <Data>
    <FirstName>John</FirstName>
    <LastName>Doe</LastName>
    <Address>
        <City>Chicago</City>
        <Street>Oakmound Drive</Street>
        <Number>100</Number>
    </Address>
</Data>

JSON data source

{
     "FirstName": "John",
     "LastName": "Doe",
     "Address": {
         "City": "Chicago",
         "Street": "Oakmound Drive",
         "Number": "100"
     }
 }

Convert an HTML Template to HTML

Follow these steps to populate an HTML template programmatically:

1. Prepare a valid XML or JSON data source.
2. Prepare an HTML template containing data-binding or foreach expressions.
3. Create a TemplateData object for the data source.
4. Create TemplateLoadOptions and configure name matching if required.
5. Call Converter.convertTemplate() with the template, data, options, and output destination.

The following example writes JSON data to data-source.json and reusable markup to template.html. It creates TemplateData and TemplateLoadOptions, then populates the template and saves the result as document.html.

// Populate an HTML template with structured JSON data using Java

// Prepare a JSON data-source and save it to a file
String data =
        "{\n" +
                "   'FirstName': 'John',\n" +
                "   'LastName': 'Smith',\n" +
                "   'Address': {\n" +
                "       'City': 'Dallas',\n" +
                "       'Street': 'Austin rd.',\n" +
                "       'Number': '200'\n" +
                "       }\n" +
                "}";
try (java.io.FileWriter fileWriter = new java.io.FileWriter("data-source.json")) {
    fileWriter.write(data);
}

// Prepare an HTML Template and save it to a file
String template =
        "<table border=1>\n" +
                "    <tr>\n" +
                "        <th>Person</th>\n" +
                "        <th>Address</th>\n" +
                "    </tr>\n" +
                "    <tr>\n" +
                "        <td>{{FirstName}} {{LastName}}</td>\n" +
                "        <td>{{Address.Street}} {{Address.Number}}, {{Address.City}}</td>\n" +
                "    </tr>\n" +
                "</table>\n";
try (java.io.FileWriter fileWriter = new java.io.FileWriter("template.html")) {
    fileWriter.write(template);
}

// Convert Template to HTML
com.aspose.html.converters.Converter.convertTemplate(
        "template.html",
        new com.aspose.html.converters.TemplateData("data-source.json"),
        new com.aspose.html.loading.TemplateLoadOptions(), "document.html"
);

Download complete Java examples and data files from GitHub.

Control Case-Sensitive Name Matching

TemplateLoadOptions controls whether template expressions and data item names are matched with case sensitivity. The default value of NamesAreCaseSensitive is true.

• Use setNamesAreCaseSensitive(true) when the case of every template expression must match the corresponding XML or JSON name.
• Use setNamesAreCaseSensitive(false) when differences such as FirstName and firstname should be ignored.

Validate the XML or JSON before conversion and keep field paths consistent with the template expressions. Case-insensitive matching can accommodate inconsistent capitalization, but it does not correct missing fields or an incorrect data hierarchy.

Related Resources

• Working with HTML Documents – create, edit, and save HTML documents in Java.
• HTML Converter – convert generated HTML to PDF, DOCX, XPS, images, MHTML, or Markdown.
• Converting Between Formats – explore other Java conversion workflows.

Other Platforms

• Working with HTML Templates in .NET