HTML5 Data Transfer Objects

##### Table of Contents

## 1 - Overview

Juneau supports generation and consumption of HTML5 documents and fragments through the use of DTOs (Data Transfer Objects).
It uses existing support for serializing and parsing POJOs to and from HTML to define these HTML objects.

### 1.1 - Generating HTML5

The Juneau HTML5 DTOs are simply beans with fluent-style setters that allow you to quickly construct HTML fragments as Java objects. These object can then be serialized to HTML using one of the existing HTML serializers, or to other languages such as JSON using the JSON serializers.

The {@link org.apache.juneau.dto.html5.HtmlBuilder} class is a utility class with predefined static methods that allow you to easily construct DTO instances in a minimal amount of code.

The following examples show how to create HTML fragments:

Java code | HTML
--- | ---
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object mytable = table( tr(th("c1"),th("c2")), tr(td("v1"),td("v2")) ); String html = HtmlSerializer.DEFAULT.serialize(mytable); | <table> <tr> <th>c1</th> <th>c2</th> </tr> <tr> <td>v1</td> <td>v2</td> </tr> </table>
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object mytable = table( caption("mytable"), colgroup( col()._class("foo"), col()._class("bar") ), thead(tr(th("c1"),th("c2"))), tbody(tr(td("v1"),td("v2"))), tfoot(tr(td("f1"),td("f2"))) ); String html = HtmlSerializer.DEFAULT.serialize(mytable); | <table> <caption>mytable</caption> <colgroup> <col class='foo'/> <col class='bar'/> </colgroup> <thead> <tr> <th>c1</th> <th>c2</th> </tr> </thead> <tbody> <tr> <td>v1</td> <td>v2</td> </tr> </tbody> <tfoot> <tr> <td>f1</td> <td>f2</td> </tr> </tfoot> </table>
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object mydiv = div().align("center").onmouseover("alert(\"boo!\");") .children( p("Juneau supports ", b(i("mixed")), " content!") ); String html = HtmlSerializer.DEFAULT.serialize(mydiv); | <div align='center' onmouseover='alert("boo!");'> <p>Juneau supports <b><i>mixed</i></b> content!</p> </table>
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object myform = form().action("/submit").method("POST") .children( "Position (1-10000): ", input("number").name("pos").value(1), br(), "Limit (1-10000): ", input("number").name("limit").value(100), br(), button("submit", "Submit"), button("reset", "Reset") ); String html = HtmlSerializer.DEFAULT.serialize(myform); | <form action='/submit' method='POST'> Position (1-10000): <input name='pos' type='number' value='1'/><br/> Limit (1-10000): <input name='pos' type='number' value='100'/><br/> <button type='submit'>Submit</button> <button type='reset'>Reset</button> </form>

### 1.2 - Parsing HTML5

Use the {@link org.apache.juneau.html.HtmlParser} to convert HTML5 documents back into their original POJOs:

// Get an HTML parser to convert our generated HTML5 documents back into POJOs. HtmlParser p = HtmlParser.DEFAULT; // Convert an HTML table back into a Table object. Table table = p.parse(tableHtml, Table.class);

HTML5 objects can also be constructed from the other media types using the appropriate parsers.

### 1.3 - HTML5 templates

If you're finding yourself reusing the same HTML5 DTO objects over and over that only differ slightly, you may want to consider using HTML5 templates. Broadly speaking, a template is simply a bean that gets swapped out with another more complex bean during serialization. Juneau doesn't have a built-in concept of a "template", but rather has features that allow them to be defined using existing swap support.

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 {@link org.apache.juneau.dto.html5.Form} bean. It takes advantage of the special `swap(BeanSession)` method that serializers will use to convert the object to a serialized form before serialization. The return type of this method can be any serializable type. In this case, we are defining a template for a reusable HTML form with two simple fields. This gets serialized as an HTML form.

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. */ public class FormTemplate { private String action; private int value1; private boolean value2; // Some constructor that initializes our fields. public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } // Special swap method that converts this template to a serializable bean, // in this case an HTML5 Form bean. public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

When serialized using the HTML or XML serializer, it produces the following:

<form action='myaction'> <input type='text' name='v1' value='123'/> <input type='text' name='v2' value='true'/> </form>

Support for parsing back into the template class can be accomplished by adding an unswap method or constructor.

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. * This time with parsing support. */ @Bean(beanDictionary=HtmlBeanDictionary.class) public class FormTemplate { private String action; private int value1; private boolean value2; // Our 'unswap' constructor public FormTemplate(Form f) { this.action = f.getAttr("action"); this.value1 = f.getChild(Input.class, 0) .getAttr(int.class, "value"); this.value2 = f.getChild(Input.class, 1) .getAttr(boolean.class, "value"); } public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

Refer to {@doc juneau-marshall.Transforms.SwapMethods} for information about defining swap methods on classes.

*** fín ***