You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ra...@apache.org on 2022/08/17 08:33:34 UTC
[sling-site] branch master updated: SLING-11545 - HTL documentation improvements
This is an automated email from the ASF dual-hosted git repository.
radu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 09b4d654b SLING-11545 - HTL documentation improvements
09b4d654b is described below
commit 09b4d654b52d738dc265c2861dac3a544d4ffde8
Author: Radu Cotescu <ra...@apache.org>
AuthorDate: Wed Aug 17 10:32:14 2022 +0200
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
---
.../bundles/scripting/scripting-htl.md | 84 +++++++++++-----------
1 file changed, 41 insertions(+), 43 deletions(-)
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 554b5c588..fdb516d79 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 @@ status=published
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 @@ The Sling implementation is comprised of the following modules:
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 [HTML Template Language Specification](https://github.com/Adobe-Marketing-Cl
}
});
-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.j [...]
+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), [...]
# Type conversions
@@ -82,16 +82,27 @@ As the HTL Engine in Sling is a Java implementation even the objects provided by
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 @@ A full HTL installation provides the following Use Providers, in the order of th
|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 lat [...]
+|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> [...]
|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-u [...]
|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 @@ The following global objects are available to all Use objects, either as a reque
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.
-
-It's important to note that this use provider will only load models that are adaptable from `SlingHttpServletRequest` or `Resource`.
-
-#### Passing parameters
+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.
-Passed parameters will be made available to the Sling Model as request attributes. Assuming the following markup:
+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:
- <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 @@ Passed parameters will be made available to the Use object as request attributes
${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;
@@ -450,23 +455,16 @@ The following table summarises the pros and cons for each Use Provider, with the
<th>Advantages</th>
<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 @@ The following table summarises the pros and cons for each Use Provider, with the
<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>