Author: radu
Date: Tue Apr 19 09:10:29 2016
New Revision: 1739874
URL: http://svn.apache.org/viewvc?rev=1739874&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=1739874&r1=1739873&r2=1739874&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
(original)
+++
sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
Tue Apr 19 09:10:29 2016
@@ -74,7 +74,7 @@ A full Sightly installation provides the
|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 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||
+|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 - `_`.|
|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||
@@ -172,7 +172,105 @@ or like:
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 - `!==`).
+#### Caveats
+
+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 primitive 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 - `!==`).
+
+Assuming the following Sightly script:
+
+ <ol data-sly-use.obj="logic.js" data-sly-list="${obj}">
+ <li>
+ Code <code>${item.code}</code> evaluates to
<code>${item.result}</code>
+ </li>
+ </ol>
+
+and the following JavaScript file:
+
+ use(function() {
+
+ return [
+ {
+ code: 'new java.lang.String("apples") === "apples"',
+ result: new java.lang.String("apples") === "apples"
+ },
+ {
+ code: 'new java.lang.String("apples") == "apples"',
+ result: new java.lang.String("apples") == "apples"
+ },
+ {
+ code: 'new java.lang.String("apples") !== "apples"',
+ result: new java.lang.String("apples") !== "apples"
+ },
+ {
+ code: 'new java.lang.String("apples") != "apples"',
+ result: new java.lang.String("apples") != "apples"
+ },
+ {
+ code: 'new java.lang.Integer(1) === 1',
+ result: new java.lang.Integer(1) === 1
+ },
+ {
+ code: 'new java.lang.Integer(1) == 1',
+ result: new java.lang.Integer(1) == 1
+ },
+ {
+ code: 'new java.lang.Integer(1) !== 1',
+ result: new java.lang.Integer(1) !== 1
+ },
+ {
+ code: 'new java.lang.Integer(1) != 1',
+ result: new java.lang.Integer(1) != 1
+ },
+ {
+ code: 'java.lang.Boolean.TRUE === true',
+ result: java.lang.Boolean.TRUE === true
+ },
+ {
+ code: 'java.lang.Boolean.TRUE == true',
+ result: java.lang.Boolean.TRUE == true
+ },
+ {
+ code: 'java.lang.Boolean.TRUE !== true',
+ result: java.lang.Boolean.TRUE !== true
+ },
+ {
+ code: 'java.lang.Boolean.TRUE != true',
+ result: java.lang.Boolean.TRUE != true
+ }
+ ];
+ });
+
+the output would be:
+
+ 1. Code new java.lang.String("apples") === "apples" evaluates to false
+ 2. Code new java.lang.String("apples") == "apples" evaluates to true
+ 3. Code new java.lang.String("apples") !== "apples" evaluates to true
+ 4. Code new java.lang.String("apples") != "apples" evaluates to false
+ 5. Code new java.lang.Integer(1) === 1 evaluates to false
+ 6. Code new java.lang.Integer(1) == 1 evaluates to true
+ 7. Code new java.lang.Integer(1) !== 1 evaluates to true
+ 8. Code new java.lang.Integer(1) != 1 evaluates to false
+ 9. Code java.lang.Boolean.TRUE === true evaluates to false
+ 10. Code java.lang.Boolean.TRUE == true evaluates to true
+ 11. Code java.lang.Boolean.TRUE !== true evaluates to true
+ 12. Code java.lang.Boolean.TRUE != true evaluates to false
+
+Evaluations of Java objects in JavaScript constructs where the operand is
automatically type coerced will work, but Rhino might complain about the Java
objects not correctly calling the Rhino helper function `Context.javaToJS()`.
In order to avoid these warnings it's better to explicitly perform your
comparisons like in the following example:
+
+ if (myObject) {
+ ...
+ }
+ // should be replaced by
+ if (myObject != null) {
+ ...
+ }
+
+ myObject ? 'this' : 'that'
+ //should be replaced by
+ myObject != null ? 'this' : 'that'
+
### 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.
@@ -230,7 +328,7 @@ The following table summarises the pros
</td>
<td>
<ul>
- <li>harder to test and debug, relying mostly on end-to-end
testing</li>
+ <li>harder to test and debug, relying mostly on end-to-end
testing and console logging</li>
<li>slower to execute than both Sling Models and Java Use-API
objects</li>
</ul>
</td>
