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 2016/04/18 13:37:55 UTC
svn commit: r1739747 -
/sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
Author: radu
Date: Mon Apr 18 11:37:55 2016
New Revision: 1739747
URL: http://svn.apache.org/viewvc?rev=1739747&view=rev
Log:
CMS commit to sling by radu
Modified:
sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
Modified: sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext?rev=1739747&r1=1739746&r2=1739747&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext Mon Apr 18 11:37:55 2016
@@ -16,7 +16,7 @@ Notice: Licensed to the Apache Softwa
specific language governing permissions and limitations
under the License.
-The Apache Sling Sightly Scripting Engine is the Java reference implementation of the [Sightly HTML Templating Language](https://github.com/Adobe-Marketing-Cloud/sightly-spec).
+The Apache Sling Sightly Scripting Engine is the reference implementation of the [Sightly HTML Templating Language](https://github.com/Adobe-Marketing-Cloud/sightly-spec).
[TOC]
@@ -75,6 +75,158 @@ A full Sightly installation provides the
|-------------- |-------------- |----------------- |--------------- |----------- |
|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 Sightly 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||
-|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 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||
+|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 - `_`.|
+|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||
+
+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).
+
+### Sling Models Use Provider
+Loading a Sling Model 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`.
+
+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}">
+ ${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 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 - `_`.
+
+**Example:**
+Assuming the following content structure:
+
+ âââ apps
+ âââ my-project
+ âââ components
+ âââ page
+ âââ PageBean.java
+ âââ page.html
+
+`page.html` could load `PageBean` either like:
+
+ <!DOCTYPE html>
+ <html data-sly-use.page="apps.my_project.components.page.PageBean">
+ ...
+ </html>
+
+or like:
+
+ <!DOCTYPE html>
+ <html data-sly-use.page="PageBean">
+ ...
+ </html>
+
+The advantage of loading a bean using just the simple class name (e.g. `data-sly-use.page="PageBean"`) is that an inheriting component can overlay the `PageBean.java` file and provide a different logic. In this case the package name of the `PageBean` class will automatically be derived from the calling script's parent path (e.g. `apps.my_project.components.page`) - the bean doesn't even have to specify it. However, keep in mind that loading a bean this way is slower than providing the fully qualified class name, since the provider has to check if there is a backing resource. At the same time, loading an object using its fully qualified class name will not allow overriding it by inheriting components.
+
+### JavaScript Use Provider
+The JavaScript Use Provider allows loading objects created through the `use` function, by evaluating scripts passed to `data-sly-use`.
+
+**Example:**
+Assuming the following content structure:
+
+ âââ apps
+ âââ my-project
+ âââ components
+ âââ page
+ âââ page.html
+ âââ page.js
+
+`page.html` could load `page.js` either like:
+
+ <!DOCTYPE html>
+ <html data-sly-use.page="/apps/my-project/components/page/page.js">
+ ...
+ </html>
+
+or like:
+
+ <!DOCTYPE html>
+ <html data-sly-use.page="page.js">
+ ...
+ </html>
+
+Similar to the Java Use Provider, loading the script using a relative path allows inheriting components to overlay just the Use script, without having to also overlay the calling Sightly script.
+
+The JavaScript files are evaluated by the [Rhino](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino) scripting engine, through the `org.apache.sling.scripting.javascript` implementation bundle. Since these scripts are evaluated server-side, by compiling JavaScript to Java, you need to pay attention when comparing objects using the strict equal operator (`===`) since comparisons between JavaScript and Java objects with the same apparent value will return `false` (this also applies to the strict not-equal operator - `!==`).
+
+### Script Use Provider
+The Script Use Provider allows loading objects evaluated by other script engines available on the platform. The same loading considerations as for the Java and JavaScript Use Providers apply.
+
+### Picking the best Use Provider for a project
+The following table summarises the pros and cons for each Use Provider, with the obvious exception of the Render Unit Use Provider.
+
+<table>
+ <tr>
+ <th>Use Provider</th>
+ <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</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 Sightly scripts where the objects are used</li>
+ </ul>
+ </td>
+ <td>
+ <p>Use-objects backed by <code>Resources</code>:</p>
+ <ul>
+ <li>cannot extend other Java objects</li>
+ <li>the Java project might need a different setup to allow running unit tests, since the objects will be deployed like content</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>JavaScript Use Provider</td>
+ <td>
+ <ul>
+ <li>allows JavaScript developers to develop component logic</li>
+ </ul>
+ </td>
+ <td>
+ <ul>
+ <li>harder to test and debug, relying mostly on end-to-end testing</li>
+ <li>slower to execute than both Sling Models and Java Use-API objects</li>
+ </ul>
+ </td>
+ </tr>
+</table>