Package org.apache.juneau.html.annotation

Annotation Interface HtmlDocConfig

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
@ContextApply(SerializerApply.class)
public @interface HtmlDocConfig

Annotation for specifying config properties defined in HtmlSerializer, HtmlParser, and HtmlDocSerializer.

Used primarily for specifying bean configuration properties on REST classes and methods.

See Also:

• HTML Basics

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String[]	aside	Aside section contents.
String	asideFloat	Float aside section contents.
String[]	footer	Footer section contents.
String[]	head	Additional head section content.
String[]	header	Header section contents.
String[]	nav	Nav section contents.
String[]	navlinks	Page navigation links.
String	noResultsMessage	No-results message.
String	nowrap	Prevent word wrap on page.
int	rank	Optional rank for this config.
String	resolveBodyVars	Resolve $ variables in serialized pojo.
String[]	script	Javascript code.
String[]	style	CSS style code.
String[]	stylesheet	Stylesheet import URLs.
Class<? extends HtmlDocTemplate>	template	HTML document template.
Class<? extends HtmlWidget>[]	widgets	HTML Widgets.

Element Details

rank

int rank

Optional rank for this config.

Can be used to override default ordering and application of config annotations.

Returns:

The annotation value.

Default:

0

aside

String[] aside

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:

• HtmlDocSerializer.Builder.aside(String...)

Returns:

The annotation value.

Default:

{}

asideFloat

String asideFloat

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:

• HtmlDocSerializer.Builder.asideFloat(AsideFloat)

Returns:

The annotation value.

Default:

"DEFAULT"

footer

String[] footer

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:

• HtmlDocSerializer.Builder.footer(String...)

Returns:

The annotation value.

Default:

{}

head

String[] head

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:

• HtmlDocSerializer.Builder.head(String...)

Returns:

The annotation value.

Default:

{}

header

String[] header

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:

• HtmlDocSerializer.Builder.header(String...)

Returns:

The annotation value.

Default:

{}

nav

String[] nav

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 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:

• HtmlDocSerializer.Builder.nav(String...)

Returns:

The annotation value.

Default:

{}

navlinks

String[] navlinks

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 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:

• HtmlDocSerializer.Builder.navlinks(String...)

Returns:

The annotation value.

Default:

{}

noResultsMessage

String noResultsMessage

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:

• HtmlDocSerializer.Builder.noResultsMessage(String)

Returns:

The annotation value.

Default:

""

nowrap

String nowrap

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:

• HtmlDocSerializer.Builder.nowrap()

Returns:

The annotation value.

Default:

""

resolveBodyVars

String resolveBodyVars

Resolve $ variables in serialized pojo.

• "true"
• "false" (default)

Notes:

• Supports SVL Variables (e.g. "$L{my.localized.variable}").

See Also:

• HtmlDocSerializer.Builder.resolveBodyVars()

Returns:

The annotation value.

Default:

""

script

String[] script

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:

• HtmlDocSerializer.Builder.script(String...)

Returns:

The annotation value.

Default:

{}

style

String[] style

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:

• HtmlDocSerializer.Builder.style(String...)

Returns:

The annotation value.

Default:

{}

stylesheet

String[] stylesheet

Stylesheet import URLs.

Adds a link to the specified stylesheet URL.

Note that this stylesheet is controlled by the @Rest.stylesheet() annotation.

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:

• HtmlDocSerializer.Builder.stylesheet(String...)

Returns:

The annotation value.

Default:

{}

template

Class<? extends HtmlDocTemplate> template

HTML document template.

Specifies the template to use for serializing the page.

By default, the 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:

• HtmlDocSerializer.Builder.template(Class)

Returns:

The annotation value.

Default:

org.apache.juneau.html.HtmlDocTemplate.Void.class

widgets

Class<? extends HtmlWidget>[] widgets

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 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

Returns:

The annotation value.

Default:

{}