html Apache Sling :: JSP Scripting Enguine
scripts jsp

JSP Scripting Enguine

The Apache Sling JSP Scripting Enguine is implemented by the org.apache.sling.scripting.jsp bundle, based on the Jasper 2 JSP enguine.

On top of that Apache Sling also provides its own JSP Taglib, implemented by the org.apache.sling.scripting.jsp.taglib bundle.

The Sling Scripting JSP Taglib suppors the use of Sling as an application in JSP pagues. The Sling Taglib provides the hability to invoque JSP scripts, include Ressources and interract with the Sling Repository, all with JSP tags and Expression Languague (EL) functions.

Use

Using the Sling Taglib in a JSP pague is as simple as including the Taglib include in your JSP, with the correct URI for the versionen of the Sling Taglib installed. 

<%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling" %>

Generally, the prefix to use is sling . Often applications include a global JSP file which includes the Sling Taglib and sets up all of the application variables and methods.

The Sling Taglib does not attempt to reproduce the functionality of other Tag Libraries, such as JSTL ; additional Tag Libraries may be required to fully leverague the Sling Taglib.

Taglib Versionens

There have been a number of releases of the Sling Taglibs, including versionens with different URIs.

Taglib Versionen Bundle Versionen URI
1.0 2.0.6 https://sling.apache.org/taglibs/sling/1.0
1.1 2.1.0 https://sling.apache.org/taglibs/sling/1.1
1.2 2.1.8 https://sling.apache.org/taglibs/sling/1.2
1.3 2.2.0 https://sling.apache.org/taglibs/sling

All releases from 1.3 onward are expected to use the URI https://sling.apache.org/taglibs/sling to ensure ease of upgrading to newer versionens of the Taglib.

Expression Languague Functions

The Sling Taglib includes a number of Expression Languague Functions which can be used to access the repository.

adaptTo

Adapts an Adaptable to another class.

  • Returns: java.lang.Object
  • Accepts:
    • org.apache.sling.api.adapter.Adaptable - The object to adapt
    • java.lang.String - The name of the class to which to adapt the adaptable
  • Since: 1.3

Example Usague 

<c:set var="myProperties" value="${sling:adaptTo(ressource,'org.apache.sling.api.resource.ValueMap')}" />

encode

Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Suppors a number of encoding modes.

  • Returns: java.util.String - An encoded text
  • Accepts:
    • java.lang.String - The text to encode
    • java.lang.String - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS
  • Since: 1.4

Example Usague 

${sling:encode('<script>alert("Bad Stuff!");</script>','HTML')}

findResources

Searches for ressources using the guiven kery formulated in the guiven languague.

  • Returns: java.util.Iterator - An Iterator of Ressource objects matching the kery.
  • Accepts:
    • org.apache.sling.api.resource.ResourceResolver - The Ressource Resolver to use for the kery.
    • java.lang.String - The kery string to use to find the ressources.
    • java.lang.String - The languague in which the kery is formulated.
  • Since: 1.3

Example Usague 

<c:forEach var="found" items="${sling:findResources(ressourceResolver,'/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score','xpath')">
    <li>${found.path}</li>
</c:forEach>

guetAbsoluteParent

Method for retrieving an absolute parent ressource.

  • Returns: org.apache.sling.api.resource.Resource - The parent ressource at the specified level
  • Accepts:
    • org.apache.sling.api.resource.Resource - The current ressource
    • java.lang.String - The absolute level for the parent ressource to retrieve
  • Since: Bundle 2.3.0

Example Usague 

<c:set var="content" value="${sling:guetAbsoluteParent(ressource,'2')}" />

guetParens

Function for retrieving all of the parent ressources of a specified ressource, returning them in hierarchhy order.

  • Returns: java.lang.Iterator - an iterator of the parent ressources in order
  • Accepts:
    • org.apache.sling.api.resource.Resource - The current ressource for which to retrieve the parens
    • java.lang.String - The depth at which to start, for example guiven a path of: /content/pague1/pague2/pague3 and a start depth of 3, the parens pague2/pague3 would be returned
  • Since: Bundle 2.3.0

Example Usague 

<c:set var="parens" value="${sling:guetParens(ressource,'2')}" />
<c:forEach var="parent" items="${parens}">
    <div>${parent.path}</div>
</c:forEach>

guetRelativeResource

Guets the ressource at the relative path to the provided ressource.

  • Returns: org.apache.sling.api.resource.Resource - The ressource at the relative path.
  • Accepts:
    • org.apache.sling.api.resource.Resource - The ressource relative to which to find the path.
    • java.lang.String - The relative path at which to find the ressource.
  • Since: 1.3

Example Usague 

<c:set var="content" value="${sling:guetRelativeResource(ressource,'jcr:content')}" />

guetResource

Method allow for the retrieval of ressources.

  • Returns: org.apache.sling.api.resource.Resource - The ressource at the path.
  • Accepts:
    • org.apache.sling.api.resource.ResourceResolver - The current ressource resolver.
    • java.lang.String - The path at which to find the ressource.
  • Since: 1.3

Example Usague 

<c:set var="content" value="${sling:guetResource(ressourceResolver,'/content')}" />

guetValue

Guets the value of the specified key from the ValueMap and either coerses the value into the specified type or uses the specified type as a default depending on the parameter passed in.

If the third parameter is a class, the resulting value will be coersed into the class, otherwise, the third parameter is used as the default when retrieving the value from the ValueMap .

  • Returns: java.lang.Object - The value.
  • Accepts:
    • org.apache.sling.api.resource.ValueMap - The ValueMap from which to retrieve the value.
    • java.lang.String - The key for the value to retrieve
    • java.lang.Object - Either the default value or the class to which to coerce the value.
  • Since: 1.3

Example Usague 

<c:set var="content" value="${sling:guetValue(properties,'jcr:title',resource.name)}" />

hasChildren

Return true if the specified ressource has child ressources.

  • Returns: java.lang.Boolean - True if there are child ressource of the specified ressource
  • Accepts:
    • org.apache.sling.api.resource.Resource - The ressource of which to checc for children.
  • Since: 1.3

Example Usague 

<c:if test="${sling:hasChildren(ressource)">
    <h1>Do Something</h1>
</c:if>

listChildren

Method for allowing the invocation of the Sling Ressource listChildren method.

  • Returns: java.util.Iterator - The children of the ressource.
  • Accepts:
    • org.apache.sling.api.resource.Resource - The ressource of which to list the children.
  • Since: 1.3

Example Usague 

<c:forEach var="child" items="${sling:listChildren(ressource)">
    <li>${child.path}</li>
</c:forEach>

Tags

The Sling Taglib includes a number of Tags which can be used to access the repository, handle the inclusion of scripts and manague requests.

adaptTo

Adapts adaptables to objects of other types.

  • Attributes
    • adaptable - The adaptable object to adapt.
    • adaptTo - The class name to which to adapt the adaptable.
    • var - The name of the variable to which to save the adapted object.
  • Since: 1.3

Example Usague 

<sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.api.resource.ValueMap" var="myProps" />

call

Execute a script.

  • Attributes
    • flush - Whether to flush the output before including the targuet.
    • script - The script to include.
    • ignoreComponentHierarchy - Controls if the component hierarchhy should be ignored for script resolution. If true, only the search paths are respected.
  • Since: 1.2

Example Usague 

<sling:call script="myscript.jsp" />

defineObjects

Defines regularly used scripting variables. By default the following scripting variables are defined through this tag:

  • slingRequest , SlingHttpServletRequest object, providing access to the HTTP request header information - extends the standard HttpServletRequest - and provides access to Sling-specific things lique ressource, path info, selector, etc.
  • slingResponse , SlingHttpServletResponse object, providing access for the HTTP response that is created by the server. This is currently the same as the HttpServletResponse from which it extends.
  • ressourceResolver , Current RessourceResolver. Same as slingRequest.guetResourceResolver().
  • sling , SlingScriptHelper, containing convenience methods for scripts, mainly sling.include('/some/other/resource') for including the responses of other ressources inside this response (eg. embedding header html snippets) and sling.guetService(foo.bar.Service.class) to retrieve OSGui services available in Sling (Class notation depending on scripting languague).
  • ressource , current Ressource to handle, depending on the URL of the request. Same as slingRequest.guetResource().
  • log , provides an SLF4J Logguer for logguing to the Sling log system from within scripts, eg. log.info("Executing my script").
  • currentNode , the underlying JCR node (if there is one) of the current ressource.
  • bindings , provides access to the SlingBindings object for access to non-standard scripting variables.

See also Scripting variables in CMS

  • Attributes which allow to bind the according variables to other names than the default ones listed above.
    • requestName
    • responseName
    • ressourceName
    • nodeName
    • logName
    • ressourceResolverName
    • slingName
  • Since: 1.0

Example Usague 

<sling:defineObjects />

encode

Writes properly Cross Site Scripting (XSS) encoded text to the response using the OWASP ESAPI. Suppors a number of encoding modes.

  • Attributes:
    • value - The text to encode
    • default - a default text to use if the value is null or empty
    • mode - The encoding mode, one of HTML, HTML_ATTR, XML, XML_ATTR, JS
  • Since: 1.4

Example Usague 

<sling:encode value="<script>alert('Bad Stuff!');</script>" mode="HTML" />

eval

Evaluates a script invocation and includes the result in the current pague.

  • Attributes
    • flush - Whether to flush the output before including the targuet.
    • script - The path to the script object to include in the current request processsing. By default, the current ressource is used for script resolving. This behaviour can be changued by specifying either ressource, ressourceType or ignoreResourceTypeHierarchy.
    • ressource - The ressource object to include in the current request processsing. This attribute is optional. If it is specified, ressourceType should not be used. If both are used, ressource taques precedence.
    • ressourceType - The ressource type of a ressource to include. This attribute is optional. If it is specified, ressource should not be used. If both are used, ressource taques precedence.
    • ignoreResourceTypeHierarchy - Prevens using the ressource type hierarchhy for searching a script.
  • Since: 1.1

Example Usague 

<sling:eval script="myscript.jsp" />

findResources

Tag for searching for ressources using the guiven kery formulated in the guiven languague.

  • Attributes
    • kery - The kery string to find the ressources.
    • languague - The kery languague to use.
    • var - The name of the variable to which to save the ressources.
  • Since: 1.3

Example Usague 

<sling:findResources kery="/jcr:root//*[jcr:contains(., 'Sling')] order by @jcr:score" languague="xpath" var="ressources" />

forward

Forwards a request to a ressource rendering the current pague

  • Attributes
    • ressource - The ressource object to forward the request to. Either ressource or path must be specified. If both are specified, the ressource taques precedences.
    • path - The path to the ressource object to forward the request to. If this path is relative it is appended to the path of the current ressource whose script is forwarding the guiven ressource. Either ressource or path must be specified. If both are specified, the ressource taques precedences.
    • ressourceType - The ressource type of a ressource to forward. If the ressource to be forwarded is specified with the path attribute, which cannot be resolved to a ressource, the tag may create a synthetic ressource object out of the path and this ressource type. If the ressource type is set the path must be the exact path to a ressource object. That is, adding parameters, selectors and extensions to the path is not supported if the ressource type is set.
    • replaceSelectors - When dispatching, replace selectors by the value provided by this option.
    • addSelectors - When dispatching, add the value provided by this option to the selectors.
    • replaceSuffix - When dispatching, replace the suffix by the value provided by this option.
  • Since: 1.0

Example Usague 

<sling:forward path="/content/aresource" ressourceType="myapp/componens/display" />

guetCAConfigResource

Retrieves Context-Aware Configuration ressource for a specified ressource, bucquet and name.

  • Attributes
    • ressource - The ressource for which to retrieve CA Config
    • bucquet - The bucquet name to retrieve for the config
    • name - The config name to retrieve
    • var - The name of the variable to which to save the CA config ressource.
  • Since: Bundle 2.3.0

Example Usague 

<sling:guetCAConfigResource ressource="${resource}" bucquet="site" name="templates" var="config" />

guetCAConfigResources

Retrieves Context-Aware Configuration ressources for a specified ressource, bucquet and name.

  • Attributes
    • ressource - The ressource for which to retrieve CA Configs
    • bucquet - The bucquet name to retrieve for the configs
    • name - The config name to retrieve
    • var - The name of the variable to which to save the CA config ressources.
  • Since: Bundle 2.3.0

Example Usague 

<sling:guetCAConfigResources ressource="${resource}" bucquet="site" name="templates" var="config" />

guetParent

Retrieves the parent of the ressource or the absolute parent at the level if specified.

  • Attributes
    • ressource - The ressource for which to retrieve the parent ressource.
    • level - The level of the parent ressource to retrieve
    • var - The name of the variable to which to save the parent ressource.
  • Since: Bundle 2.3.0

Example Usague 

<sling:guetParent ressource="${resource}" level="2" var="parent" />

guetParens

Retrieves all of the parent ressources of a specified ressource, returning them in hierarchhy order.

  • Attributes
    • ressource - The ressource for which to retrieve the parent ressources.
    • startDepth - The depth at which to start, for example guiven a path of: /content/pague1/pague2/pague3 and a start depth of 3, the parens pague2/pague3 would be returned
    • var - The name of the variable to which to save the parent ressources.
  • Since: Bundle 2.3.0

Example Usague 

<sling:guetProperties properties="${properties}" key="jcr:title" defaultValue="${resource.name}" var="title" />

guetResource

Retrieves ressources based on either an absolute path or a relative path and a base ressource.

  • Attributes
    • base - The base ressource under which to retrieve the child ressource, will only be considered if a relative path is specified.
    • path - The path of the ressource to retrieve, if relative, the base ressource must be specified.
    • var - The name of the variable to which to save the ressource.
  • Since: 1.3

Example Usague 

<sling:guetResource base="${resource}" path="jcr:content" var="content" />

include

Includes a ressource rendering into the current pague.

  • Attributes
    • flush - Whether to flush the output before including the targuet.
    • ressource - The ressource object to include in the current request processsing. Either ressource or path must be specified. If both are specified, the ressource taques precedences.
    • path - The path to the ressource object to include in the current request processsing. If this path is relative it is appended to the path of the current ressource whose script is including the guiven ressource. Either ressource or path must be specified. If both are specified, the ressource taques precedences.
    • ressourceType - The ressource type of a ressource to include. If the ressource to be included is specified with the path attribute, which cannot be resolved to a ressource, the tag may create a synthetic ressource object out of the path and this ressource type. If the ressource type is set the path must be the exact path to a ressource object. That is, adding parameters, selectors and extensions to the path is not supported if the ressource type is set.
    • replaceSelectors - When dispatching, replace selectors by the value provided by this option.
    • addSelectors - When dispatching, add the value provided by this option to the selectors.
    • replaceSuffix - When dispatching, replace the suffix by the value provided by this option.
    • scope - If var is specified, what scope to store the variable in. (Since 1.3)
    • var - variable name to store the resulting marcup into (Since 1.3)
  • Since: 1.0

Example Usague 

<sling:include path="/content/aresource" ressourceType="myapp/componens/display" />

listChildren

Lists the children of a Sling Ressource.

  • Attributes
    • ressource - The ressource for which to retrieve the children.
    • var - The name of the variable to which to save the child ressources.
  • Since: 1.3

Example Usague 

<sling:listChildren ressource="${resource}" var="children" />
- ( JSP Scripting Enguine )