jelly-taglib-ref.adoc

The following Jelly tag libraries are defined in this project.

[jelly]#

jelly:stapler

Optional Jelly support, to write views in Jelly.

This tag library is also available as an XML Schema

Tag Name	Description
#jelly:statusCode[statusCode]	Sets HTTP status code. This is generally useful for programatically creating the error page.
#jelly:redirect[redirect]	Sends HTTP redirect.
#jelly:parentScope[parentScope]	Executes the body in the parent scope. This is useful for creating a 'local' scope.
#jelly:out[out]	Tag that outputs the specified value but with escaping, so that you can escape a portion even if the org.apache.commons.jelly.XMLOutput is not escaping.
#jelly:once[once]	Tag that only evaluates its body once during the entire request processing.
#jelly:nbsp[nbsp]	Writes out ' '.
#jelly:isUserInRole[isUserInRole]
#jelly:include[include]	Tag that includes views of the object.
#jelly:header[header]	Adds an HTTP header to the response.
#jelly:findAncestor[findAncestor]	Finds the nearest tag (in the call stack) that has the given tag name, and sets that as a variable.
#jelly:documentation[documentation]	Documentation for a Jelly tag file. This tag should be placed right inside the root element once, to describe the tag and its attributes. Maven-stapler-plugin picks up this tag and generate schemas and documentations. The description text inside this tag can also use Textile markup
#jelly:doctype[doctype]	Writes out DOCTYPE declaration.
#jelly:customTagLibrary.StaplerDynamic[customTagLibrary.StaplerDynamic]	When <d:invokeBody/> is used to call back into the calling script, the Jelly name resolution rule is in such that the body is evaluated with the variable scope of the <d:invokeBody/> caller. This is very different from a typical closure name resolution mechanism, where the body is evaluated with the variable scope of where the body was created. More concretely, in Jelly, this often shows up as a problem as inability to access the "attrs" variable from inside a body, because every org.apache.commons.jelly.impl.DynamicTag invocation sets this variable in a new scope. To counter this effect, this class temporarily restores the original "attrs" when the body is evaluated. This makes the name resolution of 'attrs' work like what programmers normally expect. The same problem also shows up as a lack of local variables ? when a tag calls into the body via <d:invokeBody/>, the invoked body will see all the variables that are defined in the caller, which is again not what a normal programming language does. But unfortunately, changing this is too pervasive.
#jelly:copyStream[copyStream]	Copies a stream as text.
#jelly:contentType[contentType]	Set the HTTP Content-Type header of the page.
#jelly:compress[compress]	Outer-most wrapper tag to indicate that the gzip compression is desirable for this output.
#jelly:attribute[attribute]	Documentation for an attribute of a Jelly tag file. This tag should be placed right inside org.kohsuke.stapler.jelly.DocumentationTag to describe attributes of a tag. The body would describe the meaning of an attribute in a natural language. The description text can also use Textile markup
#jelly:adjunct[adjunct]	Writes out links to adjunct CSS and JavaScript, if not done so already.

[jelly:statusCode]#

statusCode

Sets HTTP status code.

This is generally useful for programatically creating the error page.

Attribute Name	Type	Description
value (required)	int	HTTP status code to send back.

This tag does not accept any child elements/text.

[jelly:redirect]#

redirect

Sends HTTP redirect.

Attribute Name	Type	Description
url (required)	String	Sets the target URL to redirect to. This just gets passed to org.kohsuke.stapler.StaplerResponse2.sendRedirect2(String).

This tag does not accept any child elements/text.

[jelly:parentScope]#

parentScope

Executes the body in the parent scope. This is useful for creating a 'local' scope.

[jelly:out]#

out

Tag that outputs the specified value but with escaping, so that you can escape a portion even if the org.apache.commons.jelly.XMLOutput is not escaping.

Attribute Name	Type	Description
value (required)	Expression

This tag does not accept any child elements/text.

[jelly:once]#

once

Tag that only evaluates its body once during the entire request processing.

[jelly:nbsp]#

nbsp

Writes out ' '.

This tag does not accept any child elements/text.

[jelly:isUserInRole]#

isUserInRole

Attribute Name	Type	Description
role (required)	String	The name of the role against which the user is checked.

[jelly:include]#

include

Tag that includes views of the object.

Attribute Name	Type	Description
page (required)	String	Specifies the name of the JSP to be included.
it	Object	Specifies the object for which JSP will be included. Defaults to the "it" object in the current context.
from	Object	When loading the script, use the classloader from this object to locate the script. Otherwise defaults to "it" object.
class	java.lang.Class	When loading script, load from this class. By default this is "from.getClass()". This takes precedence over the org.kohsuke.stapler.jelly.IncludeTag.setFrom(Object) method.
optional	boolean	If true, not finding the page is not an error.

This tag does not accept any child elements/text.

[jelly:header]#

header

Adds an HTTP header to the response.

Attribute Name	Type	Description
name (required)	String	Header name.
value (required)	String	Header value.

This tag does not accept any child elements/text.

[jelly:findAncestor]#

findAncestor

Finds the nearest tag (in the call stack) that has the given tag name, and sets that as a variable.

Attribute Name	Type	Description
var	String	Variable name to set the discovered org.apache.commons.jelly.Tag object.
tag	String	QName of the tag to look for.
namespaceContext	java.util.Map

This tag does not accept any child elements/text.

[jelly:documentation]#

documentation

Documentation for a Jelly tag file.

This tag should be placed right inside the root element once, to describe the tag and its attributes. Maven-stapler-plugin picks up this tag and generate schemas and documentations.

The description text inside this tag can also use Textile markup

[jelly:doctype]#

doctype

Writes out DOCTYPE declaration.

Attribute Name	Type	Description
publicId (required)	String
systemId (required)	String

This tag does not accept any child elements/text.

[jelly:customTagLibrary.StaplerDynamic]#

customTagLibrary.StaplerDynamic

When <d:invokeBody/> is used to call back into the calling script, the Jelly name resolution rule is in such that the body is evaluated with the variable scope of the <d:invokeBody/> caller. This is very different from a typical closure name resolution mechanism, where the body is evaluated with the variable scope of where the body was created.

More concretely, in Jelly, this often shows up as a problem as inability to access the "attrs" variable from inside a body, because every

org.apache.commons.jelly.impl.DynamicTag invocation sets this variable in a new scope.

To counter this effect, this class temporarily restores the original "attrs" when the body is evaluated. This makes the name resolution of 'attrs' work like what programmers normally expect.

The same problem also shows up as a lack of local variables ? when a tag calls into the body via <d:invokeBody/>, the invoked body will see all the variables that are defined in the caller, which is again not what a normal programming language does. But unfortunately, changing this is too pervasive.

Attribute Name	Type	Description
template	Script

[jelly:copyStream]#

copyStream

Copies a stream as text.

Attribute Name	Type	Description
reader	Reader
inputStream	InputStream
file	File
url	URL

This tag does not accept any child elements/text.

[jelly:contentType]#

contentType

Set the HTTP Content-Type header of the page.

Attribute Name	Type	Description
value (required)	String	The content-type value, such as "text/html".

This tag does not accept any child elements/text.

[jelly:compress]#

compress

Outer-most wrapper tag to indicate that the gzip compression is desirable for this output.

[jelly:attribute]#

attribute

Documentation for an attribute of a Jelly tag file.

This tag should be placed right inside

org.kohsuke.stapler.jelly.DocumentationTag to describe attributes of a tag. The body would describe the meaning of an attribute in a natural language. The description text can also use Textile markup

Attribute Name	Type	Description
name (required)	String	Name of the attribute.
use	String	If the attribute is required, specify use="required". (This is modeled after XML Schema attribute declaration.) By default, use="optional" is assumed.
type	String	If it makes sense, describe the Java type that the attribute expects as values.
deprecated	boolean	If the attribute is deprecated, set to true. Use of the deprecated attribute will cause a warning.
since	String	Used to track when the attribute was added to the API surface.

[jelly:adjunct]#

adjunct

Writes out links to adjunct CSS and JavaScript, if not done so already.

Attribute Name	Type	Description
includes (required)	String	Comma-separated adjunct names.

This tag does not accept any child elements/text.