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>
