juneau-doc/docs/Topics/06.juneau-rest-server/31.HtmlDocAnnotation.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.
 ***************************************************************************************************************************/
 -->

@HtmlDocConfig

<p>
	The {@link oaj.html.annotation.HtmlDocConfig @HtmlDocConfig} annotation is used to customize the HTML 
	view of your serialized POJOs.
	It's used in the following locations:
</p>
<ul>
	<li>{@link oajr.annotation.Rest @Rest}-annotated classes. 
	<li>{@link oajr.annotation.RestMethod @RestMethod}-annotated methods.
</ul>
<p>
	The annotation itself is just a convenience for setting configuration properties set
	on the {@link oaj.html.HtmlDocSerializer} class.
	For example, the following two pieces of code are equivalent:
</p>
<p class='bpcode w800'>
	<jc>// Title defined via property.</jc>
	<ja>@Rest</ja>(
		properties={
			<ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>, value=<js>"My Resource Page"</js>)
		}
	)

	<jc>// Title defined via @HtmlDoc annotation.</jc>
	<ja>@Rest</ja>()
	<ja>@HtmlDocConfig</ja>(
		title=<js>"My Resource Page"</js>
	)
</p>
<p>
	The purpose of these annotation is to populate the HTML document view which by default consists of the following
	structure:
</p>
<p class='bpcode w800'>
	<xt>&lt;html&gt;
		&lt;head&gt;
			&lt;style <xa>type</xa>=<xs>'text/css'</xs>&gt;
				<xv>CSS styles and links to stylesheets</xv>
			&lt;/style&gt;
		&lt;/head&gt;
		&lt;body&gt;
			&lt;header&gt;
				<xv>Page header</xv>
			&lt;/header&gt;
			&lt;nav&gt;
				<xv>Navigation links</xv>
			&lt;/nav&gt;
			&lt;aside&gt;
				<xv>Side-bar text</xv>
			&lt;/aside&gt;
			&lt;article&gt;
				<xv>Contents of serialized object</xv>
			&lt;/article&gt;
			&lt;footer&gt;
				<xv>Footer message</xv>
			&lt;/footer&gt;
		&lt;/body&gt;
	&lt;/html&gt;</xt>
</p>
<p>
	The outline above is controlled by the {@link oaj.html.HtmlDocTemplate} interface
	which can be overridden via the {@link oajr.annotation.HtmlDoc#template @HtmlDoc(template)} annotation.
</p>
<p>
	The <l>HelloWorldResource</l> class was an example of the <l>@HtmlDoc</l> annotation in use:
</p>
<p class='bpcode w800'>
	<jd>/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */</jd>
	<ja>@Rest</ja>(
		path=<js>"/helloWorld"</js>
	)
	<ja>@HtmlDocConfig</ja>(
		navlinks={
			<js>"up: request:/.."</js>,
			<js>"options: servlet:/?method=OPTIONS"</js>
		},
		aside={
			<js>"&lt;div style='max-width:400px' class='text'&gt;"</js>,
			<js>"	&lt;p&gt;This page shows a resource that simply response with a 'Hello world!' message&lt;/p&gt;"</js>,
			<js>"	&lt;p&gt;The POJO serialized is a simple String.&lt;/p&gt;"</js>,
			<js>"&lt;/div&gt;"</js>
		}
	)
	<jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet {...}
</p>
<p>
	SVL variables can be used in any of these annotations:
</p>
<p class='bpcode w800'>
	<ja>@Rest</ja>(
		path=<js>"/helloWorld"</js>,
		<jc>// Register a config file.</jc>
		config=<js>"MyConfig.cfg"</js>
	)
	<ja>@HtmlDocConfig</ja>(
		navlinks={
			<js>"up: request:/.."</js>,
			<js>"options: servlet:/?method=OPTIONS"</js>,
			<jc>// Add a nav link to view the source code for this class.</jc>
			<js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
		},
		aside={
			<jc>// Localize our messages.</jc>
			<js>"&lt;div style='max-width:400px' class='text'&gt;"</js>,
			<js>"	&lt;p&gt;$L{localizedMessage1}&lt;/p&gt;"</js>,
			<js>"	&lt;p&gt;$L{localizedMessage2}&lt;/p&gt;"</js>,
			<js>"&lt;/div&gt;"</js>
		}
	)
	<jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet {...}
</p>