juneau-doc/docs/Topics/06.juneau-rest-server/30.HtmlDocAnnotation/03.PredefinedWidgets.html - juneau - Git at Google

 <!--
 /***************************************************************************************************************************
  * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *  http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations under the License.
  ***************************************************************************************************************************/
  -->

 Predefined Widgets

 <p>
 	The {@link oajr.widget} package contains predefined reusable widgets.
 </p>
 <ul class='javatree'>
 	<li class='jp'>{@link oajr.widget}
 	<ul>
 		<li class='jac'>{@link oajr.widget.Widget}
 		<ul>
 			<li class='jac'>{@link oajr.widget.MenuItemWidget}
 			<ul>
 				<li class='jc'>{@link oajr.widget.ContentTypeMenuItem}
 				<li class='jc'>{@link oajr.widget.QueryMenuItem}
 				<li class='jc'>{@link oajr.widget.ThemeMenuItem}
 			</ul>
 			<li class='jc'>{@link oajr.widget.PoweredByJuneau}
 		</ul>
 		<li class='jc'>{@link oajr.widget.Tooltip}
 	</ul>
 </ul>

 <h5 class='topic'>MenuItemWidget</h5>
 <p>
 	{@link oajr.widget.MenuItemWidget} is an abstract class for rendering menu items with drop-downs.
 	It defines some simple CSS and Javascript for enabling drop-down menus in the nav section of the page (although
 	nothing keeps you from using it in an arbitrary location in the page).
 </p>
 <p>
 	The script specifies a <js>"menuClick(element)"</js> function that toggles the visibility of the next sibling of the element.
 </p>
 <p>
 	Subclasses implement the following two methods:
 </p>
 <ul class='javatree'>
 	<li class='jac'>{@link oajr.widget.MenuItemWidget}
 	<ul>
 		<li class='jm'>{@link oajr.widget.MenuItemWidget#getLabel(RestRequest,RestResponse) getLabel(RestRequest,RestResponse)} - The menu item label.
 		<li class='jm'>{@link oajr.widget.MenuItemWidget#getContent(RestRequest,RestResponse) getContent(RestRequest,RestResponse)} - The menu item content.
 	</ul>
 </ul>
 <p>
 	For example, to render a link that brings up a simple dialog in a div tag:
 </p>
 <p class='bpcode w800'>
 	<ja>@Override</ja>
 	<jk>public</jk> String getLabel() {
 		<jk>return</jk> <js>"my-menu-item"</js>;
 	};

 	<ja>@Override</ja>
 	<jk>public</jk> Div getLabel() {
 		<jk>return</jk> Html5Builder.<jsm>div</jsm>(<js>"Surprise!"</js>).style(<js>"color:red"</js>);
 	};
 </p>
 <p>
 	The HTML content returned by the {@link oajr.widget.MenuItemWidget#getHtml(RestRequest,RestResponse) getHtml(RestRequest,RestResponse)} method is added where the <js>"$W{...}"</js> is referenced in the page.
 </p>

 <h5 class='topic'>ContentTypeMenuItem</h5>
 <p>
 	{@link oajr.widget.ContentTypeMenuItem} is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in a variety of content types.
 </p>
 <p>
 	The variable it resolves is <js>"$W{ContentTypeMenuItem}"</js>.
 </p>
 <p>
 	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides a drop-down menu item for rendering all other supported content types in plain text:
 </p>
 <p class='bpcode w800'>
 	<ja>@RestMethod</ja>(
 		name=<jsf>GET</jsf>,
 		path=<js>"/"</js>,
 		widgets={
 			ContentTypeMenuItem.<jk>class</jk>,
 		},
 		htmldoc=<ja>@HtmlDoc</ja>(
 			navlinks={
 				<js>"up: ..."</js>,
 				<js>"options: ..."</js>,
 				<js>"$W{QueryMenuItem}"</js>,
 				<js>"$W{ContentTypeMenuItem}"</js>,
 				<js>"$W{ThemeMenuItem}"</js>,
 				<js>"source: ..."</js>
 			}
 		)
 	)
 	<jk>public</jk> Collection&lt;Pet&gt; getPets() {
 </p>
 <p>
 	It renders the following popup-box:
 </p>
 <img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png'>

 <h5 class='topic'>QueryMenuItem</h5>
 <p>
 	{@link oajr.widget.QueryMenuItem} is a predefined Widget that returns a menu-item drop-down form for entering search/view/sort arguments.
 </p>
 <p>
 	The variable it resolves is <js>"$W{QueryMenuItem}"</js>.
 </p>
 <p>
 	This widget is designed to be used in conjunction with the {@link oajr.converters.Queryable} converter, although implementations
 	can process the query parameters themselves if they wish to do so by using the {@link oajr.RequestQuery#getSearchArgs()}
 	method to retrieve the arguments and process the data themselves.
 </p>
 <p>
 	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides
 	search/view/sort capabilities against the collection of POJOs:
 <p class='bpcode w800'>
 	<ja>@RestMethod</ja>(
 		name=<jsf>GET</jsf>,
 		path=<js>"/"</js>,
 		widgets={
 			QueryMenuItem.<jk>class</jk>,
 		},
 		htmldoc=<ja>@HtmlDoc</ja>(
 			navlinks={
 				<js>"up: ..."</js>,
 				<js>"options: ..."</js>,
 				<js>"$W{QueryMenuItem}"</js>,
 				<js>"$W{ContentTypeMenuItem}"</js>,
 				<js>"$W{ThemeMenuItem}"</js>,
 				<js>"source: ..."</js>
 			}
 		),
 		converters=Queryable.<jk>class</jk>
 	)
 	<jk>public</jk> Collection&lt;Pet&gt; getPets() {
 </p>
 <p>
 	It renders the following popup-box:
 </p>
 <img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png'>
 <p>
 	Tooltips are provided by hovering over the field names.
 </p>
 <img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png'>

 <p>
 	When submitted, the form submits a GET request against the current URI with special GET search API query parameters.
 	(e.g. <js>"?s=column1=Foo*&amp;v=column1,column2&amp;o=column1,column2-&amp;p=100&amp;l=100"</js>).
 	The {@link oajr.converters.Queryable} class knows how to perform these filters against collections of POJOs.
 </p>

 <h5 class='topic'>ThemeMenuItem</h5>
 <p>
 	{@link oajr.widget.ThemeMenuItem} is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in the various default styles.
 </p>
 <p>
 	The variable it resolves is <js>"$W{ThemeMenuItem}"</js>.
 </p>
 <p>
 	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides
 	a drop-down menu item for rendering all other supported content types in plain text:
 </p>
 <p class='bpcode w800'>
 	<ja>@RestMethod</ja>(
 		name=<jsf>GET</jsf>,
 		path=<js>"/"</js>,
 		widgets={
 			ThemeMenuItem.<jk>class</jk>,
 		},
 		htmldoc=<ja>@HtmlDoc</ja>(
 			navlinks={
 				<js>"up: ..."</js>,
 				<js>"options: ..."</js>,
 				<js>"$W{QueryMenuItem}"</js>,
 				<js>"$W{ContentTypeMenuItem}"</js>,
 				<js>"$W{ThemeMenuItem}"</js>,
 				<js>"source: ..."</js>
 			}
 		)
 	)
 	<jk>public</jk> Collection&lt;Pet&gt; getPets() {
 </p>

 <h5 class='topic'>PoweredByJuneau</h5>
 <p>
 	{@link oajr.widget.PoweredByJuneau} is a predefined Widget that places a powered-by-Juneau message on a page.
 </p>
 <p>
 	The variable it resolves is <js>"$W{PoweredByJuneau}"</js>.
 </p>
 <p>
 	It produces a simple Apache Juneau icon floating on the right.
 	Typically it's used in the footer of the page, as shown below in the <c>AddressBookResource</c> from the examples:
 </p>
 <p class='bpcode w800'>
 	<ja>@Rest</ja>(
 		path=<js>"/addressBook"</js>,
 		widgets={
 			PoweredByJuneau.<jk>class</jk>
 		},
 		htmldoc=<ja>@HtmlDoc</ja>(
 			footer=<js>"$W{PoweredByJuneau}"</js>
 		)
 </p>
 <p>
 	It renders the following image:
 </p>
 <img class='bordered' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png'>

 <h5 class='topic'>Tooltip</h5>
 <p>
 	{@link oajr.widget.Tooltip} is a predefined template for adding tooltips to HTML5 bean constructs, typically in menu item widgets.
 </p>
 <p>
 	The following examples shows how tooltips can be added to a menu item widget.
 </p>
 <p class='bpcode w800'>
 	<jk>public class</jk> MyFormMenuItem <jk>extends</jk> MenuItemWidget {

 		<ja>@Override</ja>
 		<jk>public</jk> String getLabel(RestRequest req) <jk>throws</jk> Exception {
 			<jk>return</jk> <js>"myform"</js>;
 		}

 		<ja>@Override</ja>
 		<jk>public</jk> Object getContent(RestRequest req) <jk>throws</jk> Exception {
 			<jk>return</jk> div(
 				<jsm>form</jsm>().id(<js>"form"</js>).action(<js>"servlet:/form"</js>).method(<jsf>POST</jsf>).children(
 					<jsm>table</jsm>(
 						<jsm>tr</jsm>(
 							<jsm>th</jsm>(<js>"Field 1:"</js>),
 							<jsm>td</jsm>(<jsm>input</jsm>().name(<js>"field1"</js>).type(<js>"text"</js>)),
 							<jsm>td</jsm>(<jk>new</jk> Tooltip(<js>"(?)"</js>, <js>"This is field #1!"</js>, br(), <js>"(e.g. '"</js>, code(<js>"Foo"</js>), <js>"')"</js>))
 						),
 						<jsm>tr</jsm>(
 							<jsm>th</jsm>(<js>"Field 2:"</js>),
 							<jsm>td</jsm>(<jsm>input</jsm>().name(<js>"field2"</js>).type(<js>"text"</js>)),
 							<jsm>td</jsm>(<jk>new</jk> Tooltip(<js>"(?)"</js>, <js>"This is field #2!"</js>, br(), <js>"(e.g. '"</js>, code(<js>"Bar"</js>), <js>"')"</js>))
 						)
 					)
 				)
 			);
 		}
 	}
 </p>
	<!--
	/***************************************************************************************************************************
	* Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations under the License.
	***************************************************************************************************************************/
	-->

	Predefined Widgets

	<p>
	The {@link oajr.widget} package contains predefined reusable widgets.
	</p>
	<ul class='javatree'>
	<li class='jp'>{@link oajr.widget}
	<ul>
	<li class='jac'>{@link oajr.widget.Widget}
	<ul>
	<li class='jac'>{@link oajr.widget.MenuItemWidget}
	<ul>
	<li class='jc'>{@link oajr.widget.ContentTypeMenuItem}
	<li class='jc'>{@link oajr.widget.QueryMenuItem}
	<li class='jc'>{@link oajr.widget.ThemeMenuItem}
	</ul>
	<li class='jc'>{@link oajr.widget.PoweredByJuneau}
	</ul>
	<li class='jc'>{@link oajr.widget.Tooltip}
	</ul>
	</ul>

	<h5 class='topic'>MenuItemWidget</h5>
	<p>
	{@link oajr.widget.MenuItemWidget} is an abstract class for rendering menu items with drop-downs.
	It defines some simple CSS and Javascript for enabling drop-down menus in the nav section of the page (although
	nothing keeps you from using it in an arbitrary location in the page).
	</p>
	<p>
	The script specifies a <js>"menuClick(element)"</js> function that toggles the visibility of the next sibling of the element.
	</p>
	<p>
	Subclasses implement the following two methods:
	</p>
	<ul class='javatree'>
	<li class='jac'>{@link oajr.widget.MenuItemWidget}
	<ul>
	<li class='jm'>{@link oajr.widget.MenuItemWidget#getLabel(RestRequest,RestResponse) getLabel(RestRequest,RestResponse)} - The menu item label.
	<li class='jm'>{@link oajr.widget.MenuItemWidget#getContent(RestRequest,RestResponse) getContent(RestRequest,RestResponse)} - The menu item content.
	</ul>
	</ul>
	<p>
	For example, to render a link that brings up a simple dialog in a div tag:
	</p>
	<p class='bpcode w800'>
	<ja>@Override</ja>
	<jk>public</jk> String getLabel() {
	<jk>return</jk> <js>"my-menu-item"</js>;
	};

	<ja>@Override</ja>
	<jk>public</jk> Div getLabel() {
	<jk>return</jk> Html5Builder.<jsm>div</jsm>(<js>"Surprise!"</js>).style(<js>"color:red"</js>);
	};
	</p>
	<p>
	The HTML content returned by the {@link oajr.widget.MenuItemWidget#getHtml(RestRequest,RestResponse) getHtml(RestRequest,RestResponse)} method is added where the <js>"$W{...}"</js> is referenced in the page.
	</p>

	<h5 class='topic'>ContentTypeMenuItem</h5>
	<p>
	{@link oajr.widget.ContentTypeMenuItem} is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in a variety of content types.
	</p>
	<p>
	The variable it resolves is <js>"$W{ContentTypeMenuItem}"</js>.
	</p>
	<p>
	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides a drop-down menu item for rendering all other supported content types in plain text:
	</p>
	<p class='bpcode w800'>
	<ja>@RestMethod</ja>(
	name=<jsf>GET</jsf>,
	path=<js>"/"</js>,
	widgets={
	ContentTypeMenuItem.<jk>class</jk>,
	},
	htmldoc=<ja>@HtmlDoc</ja>(
	navlinks={
	<js>"up: ..."</js>,
	<js>"options: ..."</js>,
	<js>"$W{QueryMenuItem}"</js>,
	<js>"$W{ContentTypeMenuItem}"</js>,
	<js>"$W{ThemeMenuItem}"</js>,
	<js>"source: ..."</js>
	}
	)
	)
	<jk>public</jk> Collection<Pet> getPets() {
	</p>
	<p>
	It renders the following popup-box:
	</p>
	<img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png'>

	<h5 class='topic'>QueryMenuItem</h5>
	<p>
	{@link oajr.widget.QueryMenuItem} is a predefined Widget that returns a menu-item drop-down form for entering search/view/sort arguments.
	</p>
	<p>
	The variable it resolves is <js>"$W{QueryMenuItem}"</js>.
	</p>
	<p>
	This widget is designed to be used in conjunction with the {@link oajr.converters.Queryable} converter, although implementations
	can process the query parameters themselves if they wish to do so by using the {@link oajr.RequestQuery#getSearchArgs()}
	method to retrieve the arguments and process the data themselves.
	</p>
	<p>
	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides
	search/view/sort capabilities against the collection of POJOs:
	<p class='bpcode w800'>
	<ja>@RestMethod</ja>(
	name=<jsf>GET</jsf>,
	path=<js>"/"</js>,
	widgets={
	QueryMenuItem.<jk>class</jk>,
	},
	htmldoc=<ja>@HtmlDoc</ja>(
	navlinks={
	<js>"up: ..."</js>,
	<js>"options: ..."</js>,
	<js>"$W{QueryMenuItem}"</js>,
	<js>"$W{ContentTypeMenuItem}"</js>,
	<js>"$W{ThemeMenuItem}"</js>,
	<js>"source: ..."</js>
	}
	),
	converters=Queryable.<jk>class</jk>
	)
	<jk>public</jk> Collection<Pet> getPets() {
	</p>
	<p>
	It renders the following popup-box:
	</p>
	<img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png'>
	<p>
	Tooltips are provided by hovering over the field names.
	</p>
	<img class='bordered w800' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png'>

	<p>
	When submitted, the form submits a GET request against the current URI with special GET search API query parameters.
	(e.g. <js>"?s=column1=Foo*&v=column1,column2&o=column1,column2-&p=100&l=100"</js>).
	The {@link oajr.converters.Queryable} class knows how to perform these filters against collections of POJOs.
	</p>

	<h5 class='topic'>ThemeMenuItem</h5>
	<p>
	{@link oajr.widget.ThemeMenuItem} is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in the various default styles.
	</p>
	<p>
	The variable it resolves is <js>"$W{ThemeMenuItem}"</js>.
	</p>
	<p>
	An example of this widget can be found in the <c>PetStoreResource</c> in the examples that provides
	a drop-down menu item for rendering all other supported content types in plain text:
	</p>
	<p class='bpcode w800'>
	<ja>@RestMethod</ja>(
	name=<jsf>GET</jsf>,
	path=<js>"/"</js>,
	widgets={
	ThemeMenuItem.<jk>class</jk>,
	},
	htmldoc=<ja>@HtmlDoc</ja>(
	navlinks={
	<js>"up: ..."</js>,
	<js>"options: ..."</js>,
	<js>"$W{QueryMenuItem}"</js>,
	<js>"$W{ContentTypeMenuItem}"</js>,
	<js>"$W{ThemeMenuItem}"</js>,
	<js>"source: ..."</js>
	}
	)
	)
	<jk>public</jk> Collection<Pet> getPets() {
	</p>

	<h5 class='topic'>PoweredByJuneau</h5>
	<p>
	{@link oajr.widget.PoweredByJuneau} is a predefined Widget that places a powered-by-Juneau message on a page.
	</p>
	<p>
	The variable it resolves is <js>"$W{PoweredByJuneau}"</js>.
	</p>
	<p>
	It produces a simple Apache Juneau icon floating on the right.
	Typically it's used in the footer of the page, as shown below in the <c>AddressBookResource</c> from the examples:
	</p>
	<p class='bpcode w800'>
	<ja>@Rest</ja>(
	path=<js>"/addressBook"</js>,
	widgets={
	PoweredByJuneau.<jk>class</jk>
	},
	htmldoc=<ja>@HtmlDoc</ja>(
	footer=<js>"$W{PoweredByJuneau}"</js>
	)
	</p>
	<p>
	It renders the following image:
	</p>
	<img class='bordered' src='doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png'>

	<h5 class='topic'>Tooltip</h5>
	<p>
	{@link oajr.widget.Tooltip} is a predefined template for adding tooltips to HTML5 bean constructs, typically in menu item widgets.
	</p>
	<p>
	The following examples shows how tooltips can be added to a menu item widget.
	</p>
	<p class='bpcode w800'>
	<jk>public class</jk> MyFormMenuItem <jk>extends</jk> MenuItemWidget {

	<ja>@Override</ja>
	<jk>public</jk> String getLabel(RestRequest req) <jk>throws</jk> Exception {
	<jk>return</jk> <js>"myform"</js>;
	}

	<ja>@Override</ja>
	<jk>public</jk> Object getContent(RestRequest req) <jk>throws</jk> Exception {
	<jk>return</jk> div(
	<jsm>form</jsm>().id(<js>"form"</js>).action(<js>"servlet:/form"</js>).method(<jsf>POST</jsf>).children(
	<jsm>table</jsm>(
	<jsm>tr</jsm>(
	<jsm>th</jsm>(<js>"Field 1:"</js>),
	<jsm>td</jsm>(<jsm>input</jsm>().name(<js>"field1"</js>).type(<js>"text"</js>)),
	<jsm>td</jsm>(<jk>new</jk> Tooltip(<js>"(?)"</js>, <js>"This is field #1!"</js>, br(), <js>"(e.g. '"</js>, code(<js>"Foo"</js>), <js>"')"</js>))
	),
	<jsm>tr</jsm>(
	<jsm>th</jsm>(<js>"Field 2:"</js>),
	<jsm>td</jsm>(<jsm>input</jsm>().name(<js>"field2"</js>).type(<js>"text"</js>)),
	<jsm>td</jsm>(<jk>new</jk> Tooltip(<js>"(?)"</js>, <js>"This is field #2!"</js>, br(), <js>"(e.g. '"</js>, code(<js>"Bar"</js>), <js>"')"</js>))
	)
	)
	)
	);
	}
	}
	</p>