org.apache.juneau.rest.annotation.HtmlDoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of juneau-all
Apache Juneau UberJar
There is a newer version: 9.0.1
// ***************************************************************************************************************************
// * 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.                                              *
// ***************************************************************************************************************************
package org.apache.juneau.rest.annotation;

import org.apache.juneau.*;
import org.apache.juneau.html.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.rest.widget.*;

/**
 * Contains all the configurable annotations for the {@link HtmlDocSerializer}.
 *
 * 
 * Used with {@link RestResource#htmldoc()} and {@link RestMethod#htmldoc()} to customize the HTML view of serialized
 * POJOs.
 *
 * 

 * All annotations specified here have no effect on any serializers other than {@link HtmlDocSerializer} and is
 * provided as a shorthand method of for specifying configuration properties.
 *
 * 

 * For example, the following two methods for defining the HTML document title are considered equivalent:
 * 

 * 	@RestResource(
 * 		properties={
 * 			@Property(name=HTMLDOC_title, value="My Resource Page")
 * 		}
 * 	)
 *
 * 	@RestResource(
 * 		htmldoc=@HtmlDoc(
 * 			title="My Resource Page"
 * 		)
 * 	)
 * 
 *
 * 
 * The purpose of these annotation is to populate the HTML document view which by default consists of the following
 * structure:
 * 

 * 	<html>
 * 		<head>
 * 			<style type='text/css'>
 * 				CSS styles and links to stylesheets
 * 			</style>
 * 		</head>
 * 		<body>
 * 			<header>
 * 				Page header
 * 			</header>
 * 			<nav>
 * 				Page links
 * 			</nav>
 * 			<aside>
 * 				Side-bar page links
 * 			</aside>
 * 			<article>
 * 				Contents of serialized object
 * 			</article>
 * 			<footer>
 * 				Footer message
 * 			</footer>
 * 		</body>
 * 	</html>
 * 
 */
public @interface HtmlDoc {

	/**
	 * Sets the HTML header section contents.
	 *
	 * 
	 * The format of this value is HTML.
	 *
	 * 

	 * The page header normally contains the title and description, but this value can be used to override the contents
	 * to be whatever you want.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			header={
	 * 				"<p>This is my REST interface</p>"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		A value of "NONE" can be used to force no header.
	 * 	

	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#header(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class if not overridden.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] header() default {};

	/**
	 * Sets the links in the HTML nav section.
	 *
	 * 
	 * The value is an array of strings with two possible values:
	 * 

	 * 	A key-value pair representing a hyperlink label and href:
	 * 		
"google: http://google.com"
	 * 	
Arbitrary HTML.
	 * 
	 *
	 * 
	 * The page links are positioned immediately under the title and text.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			navlinks={
	 * 				"up: request:/..",
	 * 				"options: servlet:/?method=OPTIONS"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		This field can also use URIs of any support type in {@link UriResolver}.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#navlinks(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent links can be included by adding the literal "INHERIT" as a value.
	 * 		
Use the syntax "key[index]: value" or "[index]: value" to specify an index location
	 * 		to place a link inside the list of parent links.
	 * 
	 */
	String[] navlinks() default {};

	/**
	 * Sets the HTML nav section contents.
	 *
	 * 
	 * The format of this value is HTML.
	 *
	 * 

	 * The nav section of the page contains the links.
	 *
	 * 

	 * The format of this value is HTML.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			nav={
	 * 				"<p>Custom nav content</p>"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		When a value is specified, the {@link #navlinks()} value will be ignored.
	 * 	

	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#nav(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] nav() default {};

	/**
	 * Sets the HTML aside section contents.
	 *
	 * 
	 * The format of this value is HTML.
	 *
	 * 

	 * The aside section typically floats on the right side of the page.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			aside={
	 * 				"<p>Custom aside content</p>"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#aside(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] aside() default {};

	/**
	 * Sets the HTML footer section contents.
	 *
	 * 
	 * The format of this value is HTML.
	 *
	 * 

	 * The footer section typically floats on the bottom of the page.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			footer={
	 * 				"<p>Custom footer content</p>"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#footer(Object[])} methods.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] footer() default {};

	/**
	 * Sets the HTML CSS style section contents.
	 *
	 * 
	 * The format of this value is CSS.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			style={
	 * 				".red{color:red;}",
	 * 				".blue{color:blue;}"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#style(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] style() default {};

	/**
	 * Sets the CSS URL in the HTML CSS style section.
	 *
	 * 
	 * The format of this value is a URL.
	 *
	 * 

	 * Specifies the URL to the stylesheet to add as a link in the style tag in the header.
	 *
	 * 

	 * The format of this value is CSS.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			stylesheet="http://someOtherHost/stealTheir.css"
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}") and can use URL protocols
	 * 		defined by {@link UriResolver}.
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#stylesheet(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 
	 */
	String[] stylesheet() default {};

	/**
	 * Sets the HTML script section contents.
	 *
	 * 
	 * The format of this value is Javascript.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			script={
	 * 				"alert('Hello!')"
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		Multiple values are combined with newlines into a single string.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#script(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 	

	 * 		The parent value can be included by adding the literal "INHERIT" as a value.
	 * 
	 */
	String[] script() default {};

	/**
	 * Adds arbitrary content to the HTML <head> element on the page.
	 *
	 * 
	 * The format of this value is HTML.
	 *
	 * 
Example:
	 * 
	 * 	@RestResource(
	 * 		htmldoc=@HtmlDoc(
	 * 			head={
	 * 				// Add a shortcut link in the browser tab
	 * 				"",
	 *
	 * 				// Reload the page every 5 seconds 
	 * 				""
	 * 			}
	 * 		)
	 * 	)
	 * 
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		This field can contain variables (e.g. "$L{my.localized.variable}").
	 * 		
See {@link RestContext#getVarResolver()} for the list of supported variables.
	 * 	

	 * 		A value of "NONE" can be used to force no value.
	 * 	

	 * 		The head content from the parent can be included by adding the literal "INHERIT" as a value.
	 * 	

	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#head(Object[])} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 
	 */
	String[] head() default {};

	/**
	 * Shorthand method for forcing the rendered HTML content to be no-wrap.
	 *
	 * 
	 * This only applies to the rendered data portion of the page.
	 */
	boolean nowrap() default false;

	/**
	 * Specifies the text to display when serializing an empty array or collection.
	 */
	String noResultsMessage() default "no results";

	/**
	 * Specifies the template class to use for rendering the HTML page.
	 *
	 * 

	 * By default, uses {@link HtmlDocTemplateBasic} to render the contents, although you can provide your own custom
	 * renderer or subclasses from the basic class to have full control over how the page is rendered.
	 *
	 * 
Other Notes
	 * 
	 * 	
	 * 		The programmatic equivalent to this annotation is the {@link HtmlDocBuilder#template(Class)} method.
	 * 	

	 * 		On methods, this value is inherited from the @HtmlDoc annotation on the servlet/resource class.
	 * 	

	 * 		On servlet/resource classes, this value is inherited from the @HtmlDoc annotation on the
	 * 		parent class.
	 * 
	 */
	Class template() default HtmlDocTemplate.class;

	/**
	 * Defines widgets that can be used in conjunction with string variables of the form "$W{name}"to quickly
	 * generate arbitrary replacement HTML.
	 *
	 * Other Notes
	 * 
	 * 	
	 * 		Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
	 * 
	 */
	Class[] widgets() default {};
}