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/20 10:49:50 UTC
svn commit: r1740066 -
/sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext
Author: radu
Date: Wed Apr 20 08:49:50 2016
New Revision: 1740066
URL: http://svn.apache.org/viewvc?rev=1740066&view=rev
Log:
added title to the Sightly scripting page
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=1740066&r1=1740065&r2=1740066&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext Wed Apr 20 08:49:50 2016
@@ -1,3 +1,5 @@
+Title: Sightly Scripting Engine
+
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]
@@ -21,7 +23,7 @@ The [Sightly HTML Templating Language Sp
* Initialises the Use bean.
*
* @param bindings All bindings available to the Sightly scripts.
- **/
+ **/
public void init(javax.script.Bindings bindings);
@@ -37,14 +39,14 @@ The [Sightly HTML Templating Language Sp
*/
use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
// implement processing
-
+
// define this Use object's behaviour
return {
propertyName: propertyValue
functionName: function () {}
}
});
-
+
The Sightly implementation from Sling provides the basic POJO support through the [`org.apache.sling.scripting.sightly.pojo.Use`](https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java) interface and the [`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), whereas the `use` function is implemented by the `org.apache.sling.scripting.sightly.js.provider` bundle.
However, the Sling implementation provides a few extensions to the Use-API.
@@ -86,7 +88,7 @@ Loading a Sling Model can be done with t
<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`.
@@ -98,18 +100,18 @@ Passed parameters will be made available
<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 OSGi services, objects exported by bundles or backed by a `Resource`.
@@ -118,7 +120,7 @@ The Java Use Provider can be used to loa
#### 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:**
+**Example:**
Assuming the following content structure:
âââ apps
@@ -127,21 +129,21 @@ Assuming the following content structure
âââ 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.
#### Passing parameters
@@ -150,26 +152,26 @@ Passed parameters will be made available
<div data-sly-use.useObject="${'org.example.use.MyUseObject' @ colour='red', year=2016}">
${useObject.shine}
</div>
-
+
the object implementing `Use` would be able to retrieve the parameters using the following constructs:
package org.example.use.MyUseObject;
-
+
import javax.script.Bindings;
import org.apache.sling.commons.osgi.PropertiesUtil;
import org.apache.sling.scripting.sightly.pojo.Use;
public class MyUseObject implements Use {
-
+
private String colour;
private Integer year;
-
+
public void init(Bindings bindings) {
colour = PropertiesUtil.toString(bindings.get("colour"), "");
year = PropertiesUtil.toInteger(bindings.get("year"), Calendar.getInstance().get(Calendar.YEAR));
}
- }
+ }
or, if the object is adaptable from a `SlingHttpServletRequest`, through its `AdapterFactory`:
@@ -181,7 +183,7 @@ or, if the object is adaptable from a `S
import org.apache.felix.scr.annotations.Service;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.adapter.AdapterFactory;
-
+
@Component
@Service
@Properties({
@@ -199,7 +201,7 @@ or, if the object is adaptable from a `S
)
})
public class RequestAdapterFactory implements AdapterFactory {
-
+
@Override
public <AdapterType> AdapterType getAdapter(Object adaptable, Class<AdapterType> type) {
if (type == MyUseObject.class && adaptable instanceof SlingHttpServletRequest) {
@@ -218,7 +220,7 @@ or, if the object is adaptable from a `S
### JavaScript Use Provider
The JavaScript Use Provider allows loading objects created through the `use` function, by evaluating scripts passed to `data-sly-use`.
-**Example:**
+**Example:**
Assuming the following content structure:
âââ apps
@@ -227,14 +229,14 @@ Assuming the following content structure
âââ 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>
@@ -255,7 +257,7 @@ Besides the global objects available to
sightly // the namespace object under which the asynchronous Resource-API implemented by
// org.apache.sling.scripting.sightly.js.provider is made available to consumers
use // the use function
-
+
With the exception of the `console` and `use` objects, all the other global objects implemented by the JavaScript Use Provider are present in order to support the asynchronous Resource-API implemented by `org.apache.sling.scripting.sightly.js.provider`. However, this was deprecated starting with version 1.0.8 - see [SLING-4964](https://issues.apache.org/jira/browse/SLING-4964).
#### Passing parameters
@@ -269,10 +271,10 @@ the object would be able to access the p
use(function() {
'use strict';
-
+
var colour = this.colour || '';
var year = this.year || new Date().getFullYear();
-
+
return {
colour: colour,
year: year
@@ -296,7 +298,7 @@ Assuming the following Sightly script:
and the following JavaScript file:
use(function() {
-
+
return [
{
code: 'new java.lang.String("apples") === "apples"',
@@ -373,7 +375,7 @@ Evaluations of Java objects in JavaScrip
if (myObject != null) {
...
}
-
+
myObject ? 'this' : 'that'
//should be replaced by
myObject != null ? 'this' : 'that'
@@ -387,7 +389,7 @@ The following table summarises the pros
<table>
<tr>
- <th>Use Provider</th>
+ <th>Use Provider</th>
<th>Advantages</th>
<th>Disadvantages</th>
</tr>