Stapler - Jelly Taglib references

The following Jelly tag libraries are defined in this project.

## jelly:stapler

Optional Jelly support, to write views in Jelly.

This tag library is also available as an XML Schema

Tag Name | Description
--- | ---
statusCode | Sets HTTP status code. This is generally useful for programatically creating the error page.
redirect | Sends HTTP redirect.
parentScope | Executes the body in the parent scope. This is useful for creating a 'local' scope.
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.
once | Tag that only evaluates its body once during the entire request processing.
nbsp | Writes out '&nbsp;'.
isUserInRole |
include | Tag that includes views of the object.
header | Adds an HTTP header to the response.
findAncestor | Finds the nearest tag (in the call stack) that has the given tag name, and sets that as a variable.
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
doctype | Writes out DOCTYPE declaration.
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 couner 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.
copyStream | Copies a stream as text.
contentType | Set the HTTP Content-Type header of the page.
compress | Outer-most wrapper tag to indicate that the gzip compression is desirable for this output.
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
adjunct | Writes out links to adjunct CSS and JavaScript, if not done so already.

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

### 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.StaplerResponse.sendRedirect2(String).

This tag does not accept any child elements/text.

### parentScope

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

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

### once

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

### nbsp

Writes out '&nbsp;'.

This tag does not accept any child elements/text.

### isUserInRole

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

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

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

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

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

### doctype

Writes out DOCTYPE declaration.

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

This tag does not accept any child elements/text.

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

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

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

### compress

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

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

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