<!--
/***************************************************************************************************************************
 * 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>