org.apache.juneau.html.annotation.HtmlDocConfig Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * 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.html.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.html.*;
import org.apache.juneau.svl.*;
/**
* Annotation for specifying config properties defined in {@link HtmlSerializer}, {@link HtmlParser}, and {@link HtmlDocSerializer}.
*
*
* Used primarily for specifying bean configuration properties on REST classes and methods.
*
*
See Also:
* - HTML Details
*
*/
@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
@ContextApply(HtmlDocConfigAnnotation.SerializerApply.class)
public @interface HtmlDocConfig {
/**
* Optional rank for this config.
*
*
* Can be used to override default ordering and application of config annotations.
*
* @return The annotation value.
*/
int rank() default 0;
//-------------------------------------------------------------------------------------------------------------------
// HtmlDocSerializer
//-------------------------------------------------------------------------------------------------------------------
/**
* Aside section contents.
*
*
* Allows you to specify the contents of the aside section on the HTML page.
* The aside section floats on the right of the page for providing content supporting the serialized content of
* the page.
*
*
Example:
*
* @HtmlDocConfig (
* aside={
* "<ul>" ,
* " <li>Item 1" ,
* " <li>Item 2" ,
* " <li>Item 3" ,
* "</ul>"
* }
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#aside(String...)}
*
*
* @return The annotation value.
*/
String[] aside() default {};
/**
* Float aside section contents.
*
*
* Allows you to position the aside contents of the page around the main contents.
*
*
* By default, the aside section is floated to the right.
*
*
Example:
*
* @HtmlDocConfig (
* aside={
* "<ul>" ,
* " <li>Item 1" ,
* " <li>Item 2" ,
* " <li>Item 3" ,
* "</ul>"
* },
* asideFloat="TOP"
* )
*
*
*
* "RIGHT"
* "LEFT"
* "TOP"
* "BOTTOM"
* "DEFAULT" (defaults to "RIGHT" )
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* On servlet/resource classes, this value is inherited from the @HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#asideFloat(AsideFloat)}
*
*
* @return The annotation value.
*/
String asideFloat() default "DEFAULT";
/**
* Footer section contents.
*
*
* Allows you to specify the contents of the footer section on the HTML page.
*
*
Example:
*
* @HtmlDocConfig (
* footer={
* "<b>This interface is great!</b>"
* }
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#footer(String...)}
*
*
* @return The annotation value.
*/
String[] footer() default {};
/**
* Additional head section content.
*
*
* Adds the specified HTML content to the head section of the page.
*
*
Example:
*
* @HtmlDocConfig (
* head={
* "<link rel='icon' href='$U{servlet:/htdocs/mypageicon.ico}'>"
* }
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* 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.
* -
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#head(String...)}
*
*
* @return The annotation value.
*/
String[] head() default {};
/**
* Header section contents.
*
*
* Allows you to override the contents of the header section on the HTML page.
* The header section normally contains the title and description at the top of the page.
*
*
Example:
*
* @HtmlDocConfig (
* header={
* "<h1>My own header</h1>"
* }
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* A value of
"NONE" can be used to force no header.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class if not overridden.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#header(String...)}
*
*
* @return The annotation value.
*/
String[] header() default {};
/**
* Nav section contents.
*
*
* Allows you to override the contents of the nav section on the HTML page.
* The nav section normally contains the page links at the top of the page.
*
*
Example:
*
* @HtmlDocConfig (
* nav={
* "<p class='special-navigation'>This is my special navigation content</p>"
* }
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* When {@link #navlinks()} is also specified, this content is placed AFTER the navigation links.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#nav(String...)}
*
*
* @return The annotation value.
*/
String[] nav() default {};
/**
* Page navigation links.
*
*
* Adds a list of hyperlinks immediately under the title and description but above the content of the page.
*
*
* This can be used to provide convenient hyperlinks when viewing the REST interface from a browser.
*
*
* 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.
*
*
*
* Relative URLs are considered relative to the servlet path.
* For example, if the servlet path is "http://localhost/myContext/myServlet" , and the
* URL is "foo" , the link becomes "http://localhost/myContext/myServlet/foo" .
* Absolute ("/myOtherContext/foo" ) and fully-qualified ("http://localhost2/foo" ) URLs
* can also be used in addition to various other protocols specified by {@link UriResolver} such as
* "servlet:/..." .
*
*
Example:
*
* @HtmlDocConfig (
* navlinks={
* "api: servlet:/api" ,
* "stats: servlet:/stats" ,
* "doc: doc"
* }
* )
* public class AddressBookResource extends BasicRestServlet {
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* 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.
* -
* Supports URIs (e.g.
"servlet:/..." , "request:/..." ).
* -
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#navlinks(String...)}
*
*
* @return The annotation value.
*/
String[] navlinks() default {};
/**
* No-results message.
*
*
* Allows you to specify the string message used when trying to serialize an empty array or empty list.
*
*
Example:
*
* @HtmlDocConfig (
* noResultsMessage="<b>This interface is great!</b>"
* )
*
*
* Notes:
* -
* Format: HTML
*
-
* A value of
"NONE" can be used to represent no value to differentiate it from an empty string.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#noResultsMessage(String)}
*
*
* @return The annotation value.
*/
String noResultsMessage() default "";
/**
* Prevent word wrap on page.
*
*
* Adds "* {white-space:nowrap}" to the CSS instructions on the page to prevent word wrapping.
*
*
* "true"
* "false" (default)
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#nowrap()}
*
*
* @return The annotation value.
*/
String nowrap() default "";
/**
* Resolve $ variables in serialized pojo.
*
*
* "true"
* "false" (default)
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#resolveBodyVars()}
*
*
* @return The annotation value.
*/
String resolveBodyVars() default "";
/**
* Javascript code.
*
*
* Adds the specified Javascript code to the HTML page.
*
*
Example:
*
* @HtmlDocConfig (
* script={
* "alert('hello!');"
* }
* )
*
*
* Notes:
* -
* Format: Javascript
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#script(String...)}
*
*
* @return The annotation value.
*/
String[] script() default {};
/**
* CSS style code.
*
*
* Adds the specified CSS instructions to the HTML page.
*
*
Example:
*
* @HtmlDocConfig (
* style={
* "h3 { color: red; }" ,
* "h5 { font-weight: bold; }"
* }
* )
*
*
* Notes:
* -
* Format: CSS
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* A value of
"NONE" can be used to force no value.
* -
* The parent value can be included by adding the literal
"INHERIT" as a value.
* -
* Multiple values are combined with newlines into a single string.
*
-
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#style(String...)}
*
*
* @return The annotation value.
*/
String[] style() default {};
/**
* Stylesheet import URLs.
*
*
* Adds a link to the specified stylesheet URL.
*
*
* Note that this stylesheet is controlled by the @Rest .stylesheet()
Notes:
* -
* Format: URL
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#stylesheet(String...)}
*
*
* @return The annotation value.
*/
String[] stylesheet() default {};
/**
* HTML document template.
*
*
* Specifies the template to use for serializing the page.
*
*
* By default, the {@link BasicHtmlDocTemplate} class is used to construct the contents of the HTML page, but
* can be overridden with your own custom implementation class.
*
*
Example:
*
* @HtmlDocConfig (
* template=MySpecialDocTemplate.class
* )
*
*
* Notes:
* -
* On methods, this value is inherited from the
@HtmlDocConfig annotation on the servlet/resource class.
* -
* On servlet/resource classes, this value is inherited from the
@HtmlDocConfig annotation on the
* parent class.
*
*
* See Also:
* - {@link org.apache.juneau.html.HtmlDocSerializer.Builder#template(Class)}
*
*
* @return The annotation value.
*/
Class template() default HtmlDocTemplate.Void.class;
/**
* HTML Widgets.
*
*
* Defines widgets that can be used in conjunction with string variables of the form "$W{name}" to quickly
* generate arbitrary replacement text.
*
*
* Widgets resolve the following variables:
*
*
* -
*
"$W{name}" - Contents returned by {@link HtmlWidget#getHtml(VarResolverSession)}.
*
*
*
* 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:
*
*
* @HtmlDocConfig (
* widgets={
* MyWidget.class
* }
* navlinks={
* "$W{MyWidget}"
* },
* aside={
* "Check out this widget: $W{MyWidget}"
* }
* )
*
*
* Notes:
* -
* Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
*
-
* Values are appended to the existing list.
*
*
* See Also:
* - Widgets
*
*
* @return The annotation value.
*/
Class[] widgets() default {};
}