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/19 11:10:29 UTC
svn commit: r1739874 -
/sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
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>