svn commit: r1739883 - /sling/site/trunk/content/documentation/bundles/scripting/scripting-sightly.mdtext

[ra...@apache.org]

Author: radu
Date: Tue Apr 19 09:50:25 2016
New Revision: 1739883

URL: http://svn.apache.org/viewvc?rev=1739883&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=1739883&r1=1739882&r2=1739883&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:50:25 2016
@@ -92,6 +92,8 @@ Depending on the implementation the abov
 
 It's important to note that this use provider will only load models that are adaptable from `SlingHttpServletRequest` or `Resource`.
 
+#### Passing parameters
+
 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}">
@@ -111,7 +113,7 @@ the model would retrieve the parameters
         }        
 
 ### Java Use Provider
-The Java Use Provider can be used to load objects exported by bundles or backed by a `Resource`.
+The Java Use Provider can be used to load OSGi services, objects exported by bundles or backed by a `Resource`.
 
 
 #### Resource-backed Java classes
@@ -143,6 +145,77 @@ or like:
         
 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
+Passed parameters will be made available to the Use object as request attributes and, if the object implements 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, through the `javax.script.Bindings` passed to the `init` method. Assuming the following markup:
+
+        <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`:
+
+    package org.example.use;
+
+    import org.apache.felix.scr.annotations.Component;
+    import org.apache.felix.scr.annotations.Properties;
+    import org.apache.felix.scr.annotations.Property;
+    import org.apache.felix.scr.annotations.Service;
+    import org.apache.sling.api.SlingHttpServletRequest;
+    import org.apache.sling.api.adapter.AdapterFactory;
+    
+    @Component
+    @Service
+    @Properties({
+            @Property(
+                    name = AdapterFactory.ADAPTABLE_CLASSES,
+                    value = {
+                            "org.apache.sling.api.SlingHttpServletRequest"
+                    }
+            ),
+            @Property(
+                    name = AdapterFactory.ADAPTER_CLASSES,
+                    value = {
+                            "org.example.use.MyUseObject"
+                    }
+            )
+    })
+    public class RequestAdapterFactory implements AdapterFactory {
+    
+        @Override
+        public <AdapterType> AdapterType getAdapter(Object adaptable, Class<AdapterType> type) {
+            if (type == MyUseObject.class && adaptable instanceof SlingHttpServletRequest) {
+                SlingHttpServletRequest request = (SlingHttpServletRequest) adaptable;
+                String colour = PropertiesUtil.toString(request.getAttribute("colour"), "");
+                Integer year = PropertiesUtil.toInteger(request.getAttribute("year"), Calendar.getInstance().get(Calendar.YEAR));
+                /*
+                 * for the sake of this example we assume that MyUseObject has this constructor
+                 */
+                return (AdapterType) new MyUseObject(colour, year);
+            }
+            return null;
+        }
+    }
+
 ### JavaScript Use Provider
 The JavaScript Use Provider allows loading objects created through the `use` function, by evaluating scripts passed to `data-sly-use`.
 
@@ -172,6 +245,27 @@ 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.
 
+#### Passing parameters
+Passed parameters will be made available to the Use object as properties of `this`. Assuming the following markup:
+
+        <div data-sly-use.useObject="${'useObject.js' @ colour='red', year=2016}">
+            ${useObject.shine}
+        </div>
+
+the object would be able to access the parameters like:
+
+        use(function() {
+            'use strict';
+            
+            var colour = this.colour || '';
+            var year = this.year || new Date().getFullYear();
+            
+            return {
+                colour: colour,
+                year: year
+            }
+        });
+
 #### 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.