Repository: incubator-juneau Updated Branches: refs/heads/master 1e968f3ac -> 34ff3c15a
Clean up javadocs Project: http://git-wip-us.apache.org/repos/asf/incubator-juneau/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-juneau/commit/34ff3c15 Tree: http://git-wip-us.apache.org/repos/asf/incubator-juneau/tree/34ff3c15 Diff: http://git-wip-us.apache.org/repos/asf/incubator-juneau/diff/34ff3c15 Branch: refs/heads/master Commit: 34ff3c15a93ca9a2fccc6c7a6078f8b6e938f01a Parents: 1e968f3 Author: JamesBognar <[email protected]> Authored: Sun Feb 5 13:54:48 2017 -0500 Committer: JamesBognar <[email protected]> Committed: Sun Feb 5 13:54:48 2017 -0500 ---------------------------------------------------------------------- .../org/apache/juneau/dto/atom/AtomBuilder.java | 8 +- .../org/apache/juneau/dto/atom/package.html | 30 ++--- .../org/apache/juneau/dto/html5/package.html | 122 +++++++++++++++++-- juneau-core/src/main/javadoc/overview.html | 44 ++++--- 4 files changed, 148 insertions(+), 56 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/34ff3c15/juneau-core/src/main/java/org/apache/juneau/dto/atom/AtomBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/dto/atom/AtomBuilder.java b/juneau-core/src/main/java/org/apache/juneau/dto/atom/AtomBuilder.java index f51eb45..60d578a 100644 --- a/juneau-core/src/main/java/org/apache/juneau/dto/atom/AtomBuilder.java +++ b/juneau-core/src/main/java/org/apache/juneau/dto/atom/AtomBuilder.java @@ -23,11 +23,11 @@ import java.util.*; * <jk>import static</jk> org.apache.juneau.dto.atom.AtomBuilder.*; * * Feed feed = - * feed(<js>"tag:juneau.sample.com,2013:1"</js>, <js>"Juneau ATOM specification"</js>, <js>"2013-05-08T12:29:29Z"</js>) - * .subtitle(text(<js>"html"</js>).children(<js>"A <em>lot</em> of effort went into making this effortless"</js>)) + * <jsm>feed</jsm>(<js>"tag:juneau.sample.com,2013:1"</js>, <js>"Juneau ATOM specification"</js>, <js>"2013-05-08T12:29:29Z"</js>) + * .subtitle(<jsm>text</jsm>(<js>"html"</js>).children(<js>"A <em>lot</em> of effort went into making this effortless"</js>)) * .links( - * link(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), - * link(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) + * <jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), + * <jsm>link</jsm>(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) * ); * </p> * <p> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/34ff3c15/juneau-core/src/main/java/org/apache/juneau/dto/atom/package.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/dto/atom/package.html b/juneau-core/src/main/java/org/apache/juneau/dto/atom/package.html index c68e8da..f3b032d 100644 --- a/juneau-core/src/main/java/org/apache/juneau/dto/atom/package.html +++ b/juneau-core/src/main/java/org/apache/juneau/dto/atom/package.html @@ -95,40 +95,34 @@ <jk>import static</jk> org.apache.juneau.dto.atom.AtomBuilder.*; Feed feed = - feed(<js>"tag:juneau.apache.org"</js>, <js>"Juneau ATOM specification"</js>, <js>"2016-01-02T03:04:05Z"</js>) - .subtitle(text(<js>"html"</js>).children(<js>"Describes <em>stuff</em> about Juneau"</js>)) + <jsm>feed</jsm>(<js>"tag:juneau.apache.org"</js>, <js>"Juneau ATOM specification"</js>, <js>"2016-01-02T03:04:05Z"</js>) + .subtitle(<jsm>text</jsm>(<js>"html"</js>).children(<js>"Describes <em>stuff</em> about Juneau"</js>)) .links( - link(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), - link(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) + <jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), + <jsm>link</jsm>(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) ) .rights(<js>"Copyright (c) 2016, Apache Foundation"</js>) .generator( - generator(<js>"Juneau"</js>).uri(<js>"http://juneau.apache.org/";</js>).version(<js>"1.0"</js>) + <jsm>generator</jsm>(<js>"Juneau"</js>).uri(<js>"http://juneau.apache.org/";</js>).version(<js>"1.0"</js>) ) .entries( - entry(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2016-01-02T03:04:05Z"</js>) + <jsm>entry</jsm>(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2016-01-02T03:04:05Z"</js>) .links( - link<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/2012/05/08/juneau.atom";</js>), - link(<js>"enclosure"</js>, <js>"audio/mpeg"</js>, <js>"http://www.sample.com/audio/juneau_podcast.mp3";</js>).length(1337) + <jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/2012/05/08/juneau.atom";</js>), + <jsm>link</jsm>(<js>"enclosure"</js>, <js>"audio/mpeg"</js>, <js>"http://www.sample.com/audio/juneau_podcast.mp3";</js>).length(1337) ) .published(<js>"2016-01-02T03:04:05Z"</js>) .authors( - person(<js>"James Bognar"</js>).uri(<js>"http://www.sample.com/";</js>).email(<js>"[email protected]"</js>) + <jsm>person</jsm>(<js>"James Bognar"</js>).uri(<js>"http://www.sample.com/";</js>).email(<js>"[email protected]"</js>) ) .contributors( - person(<js>"Barry M. Caceres"</js>) + <jsm>person</jsm>(<js>"Barry M. Caceres"</js>) ) .content( - content(<js>"xhtml"</js>) + <jsm>content</jsm>(<js>"xhtml"</js>) .lang(<js>"en"</js>) .base(<js>"http://www.apache.org/";</js>) - .children( - HtmlBuilder.div().child( - HtmlBuilder.p( - HtmlBuilder.i(<js>"[Update: Juneau supports ATOM.]"</js>) - ) - ) - ) + .text(<js>"<div><p><i>[Update: Juneau supports ATOM.]</i></p></div>"</js>) ) ); </p> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/34ff3c15/juneau-core/src/main/java/org/apache/juneau/dto/html5/package.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/dto/html5/package.html b/juneau-core/src/main/java/org/apache/juneau/dto/html5/package.html index 9523ea7..37d5ba1 100644 --- a/juneau-core/src/main/java/org/apache/juneau/dto/html5/package.html +++ b/juneau-core/src/main/java/org/apache/juneau/dto/html5/package.html @@ -60,6 +60,7 @@ <ol> <li><p><a class='doclink' href='#Serialize'>Generating HTML5</a></p> <li><p><a class='doclink' href='#Parse'>Parsing HTML5</a></p> + <li><p><a class='doclink' href='#Templates'>HTML5 Templates</a></p> </ol> </ol> @@ -100,9 +101,9 @@ <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; Object mytable = - table( - tr(th(<js>"c1"</js>),th(<js>"c2"</js>)), - tr(td(<js>"v1"</js>),td(<js>"v2"</js>)) + <jsm>table</jsm>( + <jsm>tr</jsm>(<jsm>th</jsm>(<js>"c1"</js>),<jsm>th</jsm>(<js>"c2"</js>)), + <jsm>tr</jsm>(<jsm>td</jsm>(<js>"v1"</js>),<jsm>td</jsm>(<js>"v2"</js>)) ); String html = HtmlSerializer.<jsf>DEFAULT</jsf>.serialize(mytable); @@ -125,15 +126,15 @@ <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; Object mytable = - table( - caption(<js>"mytable"</js>), - colgroup( - col()._class(<js>"foo"</js>), - col()._class(<js>"bar"</js>) + <jsm>table</jsm>( + <jsm>caption</jsm>(<js>"mytable"</js>), + <jsm>colgroup</jsm>( + <jsm>col</jsm>()._class(<js>"foo"</js>), + <jsm>col</jsm>()._class(<js>"bar"</js>) ), - thead(tr(th(<js>"c1"</js>),th(<js>"c2"</js>))), - tbody(tr(td(<js>"v1"</js>),td(<js>"v2"</js>))), - tfoot(tr(td(<js>"f1"</js>),td(<js>"f2"</js>))) + <jsm>thead</jsm>(<jsm>tr</jsm>(<jsm>th</jsm>(<js>"c1"</js>),<jsm>th</jsm>(<js>"c2"</js>))), + <jsm>tbody</jsm>(<jsm>tr</jsm>(<jsm>td</jsm>(<js>"v1"</js>),<jsm>td</jsm>(<js>"v2"</js>))), + <jsm>tfoot</jsm>(<jsm>tr</jsm>(<jsm>td</jsm>(<js>"f1"</js>),<jsm>td</jsm>(<js>"f2"</js>))) ); String html = HtmlSerializer.<jsf>DEFAULT</jsf>.serialize(mytable); @@ -188,6 +189,105 @@ </p> </div> + <!-- ======================================================================================================== --> + <a id="Templates"></a> + <h3 class='topic' onclick='toggle(this)'>1.3 - HTML5 templates</h3> + <div class='topic'> + <p> + 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. + </p> + <p> + 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 <code>swap(BeanSession)</code> 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. + </p> + <p class='bcode'> + <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; + + <jd>/** + * A simple HTML form template whose serialized form is an HTML5 Form object. + */</jd> + <jk>public class</jk> FormTemplate { + + <jk>private</jk> String <jf>action</jf>; + <jk>private int</jk> <jf>value1</jf>; + <jk>private boolean</jk> <jf>value2</jf>; + + <jc>// Some constructor that initializes our fields. </jc> + <jk>public</jk> FormTemplate(String action, <jk>int</jk> value1, <jk>boolean</jk> value2) { + <jk>this</jk>.<jf>action</jf> = action; + <jk>this</jk>.<jf>value1</jf> = value1; + <jk>this</jk>.<jf>value2</jf> = value2; + } + + <jc>// Special swap method that converts this template to a serializable bean, + // in this case an HTML5 Form bean. </jc> + <jk>public</jk> Form swap(BeanSession session) { + <jk>return</jk> <jsm>form</jsm>(<jf>action</jf>, + <jsm>input</jsm>(<js>"text"</js>).name(<js>"v1"</js>).value(<jf>value1</jf>), + <jsm>input</jsm>(<js>"text"</js>).name(<js>"v2"</js>).value(<jf>value2</jf>) + ); + } + } + </p> + <p> + When serialized using the HTML or XML serializer, it produces the following: + </p> + <p class='bcode'><xt> + <form <xa>action</xa>='myaction'> + <input <xa>type</xa>=<xs>'text'</xs> <xa>name</xa>=<xs>'v1'</xs> <xa>value</xa>=<xs>'123'</xs>/> + <input <xa>type</xa>=<xs>'text'</xs> <xa>name</xa>=<xs>'v2'</xs> <xa>value</xa>=<xs>'true'</xs>/> + </form> + </xt></p> + <p> + Support for parsing back into the template class can be accomplished by adding an unswap method or constructor. + </p> + <p class='bcode'> + <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; + + <jd>/** + * A simple HTML form template whose serialized form is an HTML5 Form object. + * This time with parsing support. + */</jd> + <ja>@Bean</ja>(beanDictionary=HtmlBeanDictionary.<jk>class</jk>) + <jk>public class</jk> FormTemplate { + + <jk>private</jk> String <jf>action</jf>; + <jk>private int</jk> <jf>value1</jf>; + <jk>private boolean</jk> <jf>value2</jf>; + + <jc>// Our 'unswap' constructor</jc> + <jk>public</jk> FormTemplate(Form f) { + <jk>this</jk>.<jf>action</jf> = f.getAttr(<js>"action"</js>); + <jk>this</jk>.<jf>value1</jf> = f.getChild(Input.<jk>class</jk>, 0).getAttr(<jk>int</jk>.<jk>class</jk>, <js>"value"</js>); + <jk>this</jk>.<jf>value2</jf> = f.getChild(Input.<jk>class</jk>, 1).getAttr(<jk>boolean</jk>.<jk>class</jk>, <js>"value"</js>); + } + + <jk>public</jk> FormTemplate(String action, <jk>int</jk> value1, <jk>boolean</jk> value2) { + <jk>this</jk>.<jf>action</jf> = action; + <jk>this</jk>.<jf>value1</jf> = value1; + <jk>this</jk>.<jf>value2</jf> = value2; + } + + <jk>public</jk> Form swap(BeanSession session) { + <jk>return</jk> <jsm>form</jsm>(<jf>action</jf>, + <jsm>input</jsm>(<js>"text"</js>).name(<js>"v1"</js>).value(<jf>value1</jf>), + <jsm>input</jsm>(<js>"text"</js>).name(<js>"v2"</js>).value(<jf>value2</jf>) + ); + } + } + </p> + <p> + Refer to <a class='doclink' href='../../../../../overview-summary.html#Core.SwapMethods'>Swap methods</a> for information about defining swap methods on classes. + </p> + </div> + </div> <p align="center"><i><b>*** fÃn ***</b></i></p> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/34ff3c15/juneau-core/src/main/javadoc/overview.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/javadoc/overview.html b/juneau-core/src/main/javadoc/overview.html index 1f11fbe..e94aa65 100644 --- a/juneau-core/src/main/javadoc/overview.html +++ b/juneau-core/src/main/javadoc/overview.html @@ -748,9 +748,10 @@ <div class='topic'> <p> Various methods can be defined on a class directly to affect how it gets serialized. + This can often be simpler than using <code>PojoSwaps</code>. </p> <p> - Objects normally serialized to <code>Strings</code> can be parsed back into their original objects by implementing + Objects serialized as <code>Strings</code> can be parsed back into their original objects by implementing one of the following methods on the class: </p> <ul> @@ -766,7 +767,7 @@ <li><code><jk>public</jk> T(String)</code> constructor. </ul> <p> - Note that these methods cover conversion from several built-in Java types, meaning these can be constructed directly by the parser from strings: + Note that these methods cover conversion from several built-in Java types, meaning the parsers can automatically construct these objects from strings: </p> <ul> <li><code>fromString(String)</code> - {@link java.util.UUID} @@ -805,12 +806,14 @@ <jk>private int</jk> <jf>value1</jf>; <jk>private boolean</jk> <jf>value2</jf>; + <jc>// Some constructor that initializes our fields. </jc> <jk>public</jk> FormTemplate(String action, <jk>int</jk> value1, <jk>boolean</jk> value2) { <jk>this</jk>.<jf>action</jf> = action; <jk>this</jk>.<jf>value1</jf> = value1; <jk>this</jk>.<jf>value2</jf> = value2; } + <jc>// Special swap method that converts this template to a serializable bean, <jk>public</jk> Form swap(BeanSession session) { <jk>return</jk> <jsm>form</jsm>(<jf>action</jf>, <jsm>input</jsm>(<js>"text"</js>).name(<js>"v1"</js>).value(<jf>value1</jf>), @@ -1543,10 +1546,11 @@ <td class='code'> <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; + Object mytable = - table( - tr(th(<js>"c1"</js>),th(<js>"c2"</js>)), - tr(td(<js>"v1"</js>),td(<js>"v2"</js>)) + <jsm>table</jsm>( + <jsm>tr</jsm>(<jsm>th</jsm>(<js>"c1"</js>),<jsm>th</jsm>(<js>"c2"</js>)), + <jsm>tr</jsm>(<jsm>td</jsm>(<js>"v1"</js>),<jsm>td</jsm>(<js>"v2"</js>)) ); String html = HtmlSerializer.<jsf>DEFAULT</jsf>.serialize(mytable); @@ -1597,40 +1601,34 @@ <jk>import static</jk> org.apache.juneau.dto.atom.AtomBuilder.*; Feed feed = - feed(<js>"tag:juneau.apache.org"</js>, <js>"Juneau ATOM specification"</js>, <js>"2016-01-02T03:04:05Z"</js>) - .subtitle(text(<js>"html"</js>).children(<js>"Describes <em>stuff</em> about Juneau"</js>)) + <jsm>feed</jsm>(<js>"tag:juneau.apache.org"</js>, <js>"Juneau ATOM specification"</js>, <js>"2016-01-02T03:04:05Z"</js>) + .subtitle(<jsm>text</jsm>(<js>"html"</js>).children(<js>"Describes <em>stuff</em> about Juneau"</js>)) .links( - link(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), - link(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) + <jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/";</js>).hreflang(<js>"en"</js>), + <jsm>link</jsm>(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom";</js>) ) .rights(<js>"Copyright (c) 2016, Apache Foundation"</js>) .generator( - generator(<js>"Juneau"</js>).uri(<js>"http://juneau.apache.org/";</js>).version(<js>"1.0"</js>) + <jsm>generator</jsm>(<js>"Juneau"</js>).uri(<js>"http://juneau.apache.org/";</js>).version(<js>"1.0"</js>) ) .entries( - entry(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2016-01-02T03:04:05Z"</js>) + <jsm>entry</jsm>(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2016-01-02T03:04:05Z"</js>) .links( - link<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/2012/05/08/juneau.atom";</js>), - link(<js>"enclosure"</js>, <js>"audio/mpeg"</js>, <js>"http://www.sample.com/audio/juneau_podcast.mp3";</js>).length(1337) + <jsm>link</jsm><js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/2012/05/08/juneau.atom";</js>), + <jsm>link</jsm>(<js>"enclosure"</js>, <js>"audio/mpeg"</js>, <js>"http://www.sample.com/audio/juneau_podcast.mp3";</js>).length(1337) ) .published(<js>"2016-01-02T03:04:05Z"</js>) .authors( - person(<js>"James Bognar"</js>).uri(<js>"http://www.sample.com/";</js>).email(<js>"[email protected]"</js>) + <jsm>person</jsm>(<js>"James Bognar"</js>).uri(<js>"http://www.sample.com/";</js>).email(<js>"[email protected]"</js>) ) .contributors( - person(<js>"Barry M. Caceres"</js>) + <jsm>person</jsm>(<js>"Barry M. Caceres"</js>) ) .content( - content(<js>"xhtml"</js>) + <jsm>content</jsm>(<js>"xhtml"</js>) .lang(<js>"en"</js>) .base(<js>"http://www.apache.org/";</js>) - .children( - HtmlBuilder.div().child( - HtmlBuilder.p( - HtmlBuilder.i(<js>"[Update: Juneau supports ATOM.]"</js>) - ) - ) - ) + .text(<js>"<div><p><i>[Update: Juneau supports ATOM.]</i></p></div>"</js>) ) ); </p>
