SLING-11545 - HTL documentation improvements
* removed the SlingModelsUseProvider from the docs, but kept the information
about loading Sling Models
* updated the links to the HTL specification
* mentioned the o.a.s.scripting.sightly.runtime bundle
* added all the HTL language extensions supported by Apache Sling
diff --git a/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md b/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
index 554b5c5..fdb516d 100644
--- a/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
+++ b/src/main/jbake/content/documentation/bundles/scripting/scripting-htl.md
@@ -4,7 +4,7 @@
tags=scripts,htl
~~~~~~
-The Apache Sling HTL Scripting Engine, [formerly known as Sightly](https://issues.apache.org/jira/browse/SLING-6028), is the reference implementation of the [HTML Template Language 1.4](https://github.com/Adobe-Marketing-Cloud/htl-spec).
+The Apache Sling HTL Scripting Engine, [formerly known as Sightly](https://issues.apache.org/jira/browse/SLING-6028), is the reference implementation of the [HTML Template Language 1.4](https://github.com/adobe/htl-spec).
[TOC]
@@ -15,14 +15,14 @@
1. [`org.apache.sling.scripting.sightly.compiler`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler) - provides support for compiling HTML Template Language scripts into an Abstract Syntax Tree
2. [`org.apache.sling.scripting.sightly.compiler.java`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java) - provides support for transpiling the Abstract Syntax Tree produced by the `org.apache.sling.scripting.sightly.compiler` module into Java source code
3. [`org.apache.sling.scripting.sightly`](https://github.com/apache/sling-org-apache-sling-scripting-sightly) - the HTL Scripting Engine bundle
-4. [`org.apache.sling.scripting.sightly.js.provider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-js-provider) - the HTL JavaScript Use Provider, implementing support for the `use` JavaScript function
-5. [`org.apache.sling.scripting.sightly.models.provider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-models-provider) - [Sling Models](https://sling.apache.org/documentation/bundles/models.html) Use Provider
+4. [`org.apache.sling.scripting.sightly.runtime`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-runtime) - Java runtime support for the Java code generated by the `org.apache.sling.scripting.sightly.compiler.java` module
+5. [`org.apache.sling.scripting.sightly.js.provider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-js-provider) - the HTL JavaScript Use Provider, implementing support for the `use` JavaScript function
6. [`org.apache.sling.scripting.sightly.repl`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-repl) - HTL Read-Eval-Print Loop Environment (REPL), useful for quickly prototyping scripts
7. [`htl-maven-plugin`](https://github.com/apache/sling-htl-maven-plugin) - M2Eclipse compatible HTL Maven Plugin that provides support for validating HTML Template Language scripts from projects during build time
# The Use-API
-The [HTML Template Language Specification](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.2/SPECIFICATION.md#4-use-api) explicitly defines two ways of implementing support for business logic objects:
+The [HTML Template Language Specification](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#4-use-api) explicitly defines two ways of implementing support for business logic objects:
1. Java Use-API, through POJOs, that may optionally implement an `init` method:
@@ -54,7 +54,7 @@
}
});
-The HTL implementation from Sling provides the basic POJO support through the [`org.apache.sling.scripting.sightly.pojo.Use`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler-java/blob/master/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java) interface and the [`JavaUseProvider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly/blob/master/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java), whereas the `use` function is implemented by the `org.apache.sling.scripting.sightly.js.provider` bundle.
+The HTL implementation from Sling provides the basic POJO support through the [`org.apache.sling.scripting.sightly.pojo.Use`](https://github.com/apache/sling-org-apache-sling-scripting-sightly-runtime/blob/master/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java) interface and the [`JavaUseProvider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly/blob/master/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java), whereas the `use` function is implemented by the `org.apache.sling.scripting.sightly.js.provider` bundle.
# Type conversions
@@ -82,16 +82,27 @@
The Sling HTL Scripting engine fully complies with the [HTML Template Language Specification 1.4](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md). In addition it adds some extensions which are not part of the specification.
+## Block Elements
+
+### `data-sly-resource`
+In Apache Sling, in addition to path strings, the `data-sly-resource` block element can be passed a `Resource` object. This behaviour has been added in [SLING-5811](https://issues.apache.org/jira/browse/SLING-5811).
+
+The [`requestAttributes` option](https://issues.apache.org/jira/browse/SLING-5812) can be used to pass a `Map` with objects to the request attributes.
+
+### `data-sly-include`
+
+The [`requestAttributes` option](https://issues.apache.org/jira/browse/SLING-5812) can be used to pass a `Map` with objects to the request attributes.
+
## Expression Options
### I18n
-In addition to the options defined in [HTL Spec 1.2.3](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#123-i18n) the option `basename` is supported to set the basename of the used [Sling i18n Resource bundle](../internationalization-support-i18n.html#resourcebundle-with-base-names) ([SLING-5314](https://issues.apache.org/jira/browse/SLING-5314)).
+In addition to the options defined for [i18n](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#123-i18n) the `basename` option can be used to set the basename of the used [Sling i18n Resource bundle](../internationalization-support-i18n.html#resourcebundle-with-base-names) ([SLING-5314](https://issues.apache.org/jira/browse/SLING-5314)).
### Format Date
-In addition to the regular patterns defined in [HTL Spec 1.2.2.2](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#1222-dates) the following special formatting patterns are supported ([SLING-9983](https://issues.apache.org/jira/browse/SLING-9983)) for formatting dates only (disregarding time) in a decent format for the used locale.
+In addition to the regular patterns defined for [date formatting](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#1222-dates), the following special formatting patterns are supported ([SLING-9983](https://issues.apache.org/jira/browse/SLING-9983)) for formatting dates only (disregarding time) in a decent format for the used locale.
*The resulting format depends on the JDK version though, as it changed fundamentally with [JDK 8](https://openjdk.java.net/jeps/252), and even afterwards the different [CLDR releases](http://cldr.unicode.org/index/downloads) implemented in the different JDK versions differ quite substantially.*
@@ -117,10 +128,10 @@
|Service Ranking | Use Provider | Bundle | Functionality |Observations|
|-------------- |-------------- |----------------- |--------------- |----------- |
|100|[`RenderUnitProvider`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/RenderUnitProvider.java)|`org.apache.sling.scripting.sightly`|support for loading HTL templates through `data-sly-use`||
-|95|[`SlingModelsUseProvider`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/models-use-provider/src/main/java/org/apache/sling/scripting/sightly/models/impl/SlingModelsUseProvider.java)|`org.apache.sling.scripting.sightly.models.provider`|support for loading [Sling Models](https://sling.apache.org/documentation/bundles/models.html)||
-|90|[`JavaUseProvider`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java)|`org.apache.sling.scripting.sightly`|support for loading Java objects such as: <ol><li>OSGi services</li><li>POJOs adaptable from `SlingHttpServletRequest` or `Resource`</li><li>POJOs that implement `Use`</li></ol>|The POJOs can be exported by bundles or can be backed by `Resources`. In the latter case the POJOs' package names should correspond to the backing resource's path; invalid Java characters which are valid path elements should be replaced by an underscore - `_`.|
+|90|[`JavaUseProvider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly/blob/master/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/JavaUseProvider.java)|`org.apache.sling.scripting.sightly`|support for loading Java objects such as: <ol><li>[Sling Models](https://sling.apache.org/documentation/bundles/models.html)</li><li>OSGi services</li><li>POJOs adaptable from `SlingHttpServletRequest` or `Resource`</li><li>POJOs that implement `Use`</li></ol>|The POJOs can be exported by bundles or can be backed by `Resources`. In the latter case the POJOs' package names should correspond to the backing resource's path; invalid Java characters which are valid path elements should be replaced by an underscore - `_`.|
|80|[`JsUseProvider`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/js-use-provider/src/main/java/org/apache/sling/scripting/sightly/js/impl/JsUseProvider.java)|`org.apache.sling.scripting.sightly.js.provider`|support for loading objects defined through the JavaScript `use` function|The `org.apache.sling.scripting.sightly.js.provider` also provides a trimmed down [asynchronous implementation](https://github.com/apache/sling/tree/trunk/bundles/scripting/sightly/js-use-provider/src/main/resources/SLING-INF/libs/sling/sightly/js) of the `Resource` API. However this was deprecated in [SLING-4964](https://issues.apache.org/jira/browse/SLING-4964) (version 1.0.8 of the bundle) in favour of the synchronous API provided by the `org.apache.sling.scripting.javascript` bundle.|
|0 |[`ScriptUseProvider`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/ScriptUseProvider.java)|`org.apache.sling.scripting.sightly`|support for loading objects returned by scripts interpreted by other Script Engines available on the platform||
+|-10|[`ResourceUseProvider`](https://github.com/apache/sling-org-apache-sling-scripting-sightly/blob/master/src/main/java/org/apache/sling/scripting/sightly/impl/engine/extension/use/ResourceUseProvider.java)|`org.apache.sling.scripting.sightly`|support for loading `Resources` by path using the request's resource resolver - [SLING-5813](https://issues.apache.org/jira/browse/SLING-5813)||
The `service.ranking` value of each Use Provider is configurable, allowing for fine tuning of the order in which the providers are queried when `data-sly-use` is called. However, in order to not affect core functionality the `RenderUnitProvider` should always have the highest ranking. If you need to configure the providers' service ranking head over to the configuration console at [http://localhost:8080/system/console/configMgr](http://localhost:8080/system/console/configMgr).
@@ -140,42 +151,24 @@
response // org.apache.sling.api.SlingHttpServletResponse
sling // org.apache.sling.api.scripting.SlingScriptHelper
+### Java Use Provider
+The Java Use Provider can be used to load [Sling Models](https://sling.apache.org/documentation/bundles/models.html), OSGi services, objects exported by bundles or backed by a `Resource`.
-### Sling Models Use Provider
-Loading a Sling Model can be done with the following code:
+#### Sling Models or Java Use-objects
+Loading a Sling Model or a bundled Java Use-object can be done with the following code:
<div data-sly-use.model3="org.example.models.Model3">
${model3.shine}
</div>
-Depending on the implementation the above code would either load the implementation with the highest service ranking of `Model3` if `org.example.models.Model3` is an interface, or would load the model `org.example.models.Model3` if this is a concrete implementation.
+Depending on the implementation the above code would either load the implementation with the highest service ranking of `org.example.models.Model3` if `Model3` is an interface, or would load the Sling Model/Java Use-object `org.example.models.Model3` if this is a concrete implementation.
-It's important to note that this use provider will only load models that are adaptable from `SlingHttpServletRequest` or `Resource`.
+Use-objects that are adaptable from `SlingHttpServletRequest` or `Resource` are adapted automatically. If the Use-object cannot be adapted from either of the two, the adaptable can be passed to the `data-sly-use` block element using the `adaptable` option:
-#### Passing parameters
-
-Passed parameters will be made available to the Sling Model as request attributes. Assuming the following markup:
-
- <div data-sly-use.model3="${'org.example.models.Model3' @ colour='red', path=resource.path}">
+ <div data-sly-use.model3="${'org.example.models.Model3' @ adaptable=anAdaptableObjectInScope }">
${model3.shine}
</div>
-the model would retrieve the parameters using the following constructs:
-
- @Model(adaptables=SlingHttpServletRequest.class)
- public class Model3 {
-
- @Inject
- private String colour;
-
- @Inject
- private String path;
- }
-
-### Java Use Provider
-The Java Use Provider can be used to load OSGi services, objects exported by bundles or backed by a `Resource`.
-
-
#### Resource-backed Java classes
When objects are backed by `Resources` the Java Use Provider will automatically handle the compilation of these classes. The classes' package names should correspond to the path of the backing resource, making sure to replace illegal Java characters with underscores - `_`.
@@ -212,7 +205,19 @@
${useObject.shine}
</div>
-the object implementing `Use` would be able to retrieve the parameters using the following constructs:
+a Sling Model could read these values like in the following example:
+
+ @Model(adaptables=SlingHttpServletRequest.class)
+ public class MyUseObject {
+
+ @Inject
+ private String colour;
+
+ @Inject
+ private String year;
+ }
+
+whereas an object implementing `Use` would be able to retrieve the parameters using the following constructs:
package org.example.use.MyUseObject;
@@ -451,22 +456,15 @@
<th>Disadvantages</th>
</tr>
<tr>
- <td>Sling Models Use Provider</td>
- <td><ul><li>convenient injection annotations for data retrieval</li><li>easy to extend from other Sling Models</li><li>simple setup for unit testing</li></ul></td>
- <td><ul><li>lacks flexibility in terms of component overlaying, relying on <code>service.ranking</code> configurations; this was solved for Sling Models 1.3.0 by <a href="https://issues.apache.org/jira/browse/SLING-5992">SLING-5992</a></li></ul></td>
- </tr>
- <tr>
<td>Java Use Provider</td>
<td>
<p>Use-objects provided through bundles:</p>
<ul>
- <li>faster to initialise and execute than Sling Models for similar code</li>
<li>easy to extend from other similar Use-objects</li>
<li>simple setup for unit testing</li>
</ul>
<p>Use-objects backed by <code>Resources</code>:</p>
<ul>
- <li>faster to initialise and execute than Sling Models for similar code</li>
<li>easy to override from inheriting components through search path overlay or by using the <code>sling:resourceSuperType</code> property, allowing for greater flexibility</li>
<li>business logic for components sits next to the HTL scripts where the objects are used</li>
</ul>
@@ -474,7 +472,7 @@
<td>
<p>Use-objects provided through bundles:</p>
<ul>
- <li>lacks flexibility in terms of component overlaying</li>
+ <li>lacks flexibility in terms of component overlaying, unless the HTL script works with <a href="#sling-models-or-java-use-objects">interfaces</a></li>
</ul>
<p>Use-objects backed by <code>Resources</code>:</p>
<ul>
