juneau-doc/docs/Topics/06.juneau-rest-server/31.HtmlDocAnnotation/02.Widgets.html

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

Widgets

<p>
	The {@link oajr.widget.Widget} class allows you to add arbitrary HTML, CSS, and Javascript
	to HTML pages.
	<br>They are registered in the following locations:
</p>
<ul class='javatree'>
	<li class='ja'>{@link oajr.annotation.HtmlDoc#widgets() HtmlDoc(widgets)}
	<li class='jm'>{@link oajr.RestContextBuilder#widgets(Class...)}
	<li class='jm'>{@link oajr.RestContextBuilder#widgets(Widget...)}
	<li class='jf'>{@link oajr.RestContext#REST_widgets}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestMethod</ja>(
		widgets={
			MyWidget.<jk>class</jk>
		}
		htmldoc=<ja>@HtmlDoc</ja>(
			navlinks={
				<js>"$W{MyWidget}"</js>
			},
			aside={
				<js>"Check out this widget:  $W{MyWidget}"</js>
			}
		)
	)
</p>
<p>
	The <l>Widget</l> class is composed of the following methods:
</p>
<ul class='javatree'>
	<li class='jac'>{@link oajr.widget.Widget}
	<ul>
		<li class='jm'>{@link oajr.widget.Widget#getHtml(RestRequest,RestResponse) getHtml(RestRequest,RestResponse)}
		<li class='jm'>{@link oajr.widget.Widget#getStyle(RestRequest,RestResponse) getStyle(RestRequest,RestResponse)}
		<li class='jm'>{@link oajr.widget.Widget#getScript(RestRequest,RestResponse) getScript(RestRequest,RestResponse)}
	</ul>
</ul>
<p>
	The HTML content returned by the {@link oajr.widget.Widget#getHtml(RestRequest,RestResponse) getHtml(RestRequest,RestResponse)}
	method is added wherever the <js>"$W{...}"</js> variable is used.
</p>
<p>
	The CSS returned by {@link oajr.widget.Widget#getScript(RestRequest,RestResponse) getScript(RestRequest,RestResponse)}
	is added to the style section in the page header.
</p>
<p>	
	The Javascript returned by {@link oajr.widget.Widget#getScript(RestRequest,RestResponse) getScript(RestRequest,RestResponse)}
	is added to the script section in the page header.
</p>
<p>
	The following examples shows how to associate a widget with a REST method and then have it rendered in the links
	and aside section of the page.
	It shows an example of a widget that renders an image located in the <c>htdocs</c> static files
	directory in your classpath (see {@link oajr.annotation.Rest#staticFiles() @Rest(staticFiles)}):
</p>
<p class='bpcode w800'>
	<jk>public class</jk> MyWidget <jk>extends</jk> Widget {

		<ja>@Override</ja> <jc>/* Widget */</jc>
		<jk>public</jk> String getHtml(RestRequest req) <jk>throws</jk> Exception {
			UriResolver r = req.getUriResolver(); <jc>// API used for resolving URIs.</jc>
			<jk>return</jk> <js>"&lt;img class='myimage' onclick='myalert(this)' src='"</js>+r.resolve(<js>"servlet:/htdocs/myimage.png"</js>)+<js>"'&gt;"</js>;
		}

		<ja>@Override</ja> <jc>/* Widget */</jc>
		<jk>public</jk> String getScript(RestRequest req) <jk>throws</jk> Exception {
			<jk>return</jk> <js>""</js>
				+ <js>"\n function myalert(imageElement) {"</js>
				+ <js>"\n 	alert('cool!');"</js>
				+ <js>"\n }"</js>;
		}

		<ja>@Override</ja> <jc>/* Widget */</jc>
		<jk>public</jk> String getStyle(RestRequest req) <jk>throws</jk> Exception {
			<jk>return</jk> <js>""</js>
				+ <js>"\n .myimage {"</js>
				+ <js>"\n 	border: 10px solid red;"</js>
				+ <js>"\n }"</js>;
		}
	}
</p>
<p>
	The <l>Widget</l> class also defines the following two convenience methods for loading Javascript and CSS
	files from the classpath or file system.
</p>
<ul class='javatree'>
	<li class='jac'>{@link oajr.widget.Widget}
	<ul>
		<li class='jm'>{@link oajr.widget.Widget#getClasspathResourceAsString(String) getClasspathResourceAsString(String)}
		<li class='jm'>{@link oajr.widget.Widget#getClasspathResourceAsString(String,Locale) getClasspathResourceAsString(String,Locale)}
	</ul>
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jk>public class</jk> MyWidget <jk>extends</jk> Widget {

		...

		<ja>@Override</ja> <jc>/* Widget */</jc>
		<jk>public</jk> String getScript(RestRequest req) <jk>throws</jk> Exception {
			<jk>return</jk> getClasspathResourceAsString(<js>"MyWidget.js"</js>);
		}

		<ja>@Override</ja> <jc>/* Widget */</jc>
		<jk>public</jk> String getStyle(RestRequest req) <jk>throws</jk> Exception {
			<jk>return</jk> getClasspathResourceAsString(<js>"MyWidget.css"</js>);
		}
	}
</p>
<ul class='seealso'>
	<li class='jf'>{@link oajr.RestContext#REST_widgets}
</ul>