Author: buildbot
Date: Tue Apr 19 09:50:38 2016
New Revision: 986071
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles/scripting/scripting-sightly.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Apr 19 09:50:38 2016
@@ -1 +1 @@
-1739874
+1739883
Modified:
websites/staging/sling/trunk/content/documentation/bundles/scripting/scripting-sightly.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/bundles/scripting/scripting-sightly.html
(original)
+++
websites/staging/sling/trunk/content/documentation/bundles/scripting/scripting-sightly.html
Tue Apr 19 09:50:38 2016
@@ -120,12 +120,17 @@ h2:hover > .headerlink, h3:hover > .head
<li><a href="#modules">Modules</a></li>
<li><a href="#the-use-api">The Use-API</a><ul>
<li><a href="#sling-specific-use-api-extensions">Sling-specific Use-API
Extensions</a><ul>
-<li><a href="#sling-models-use-provider">Sling Models Use Provider</a></li>
+<li><a href="#sling-models-use-provider">Sling Models Use Provider</a><ul>
+<li><a href="#passing-parameters">Passing parameters</a></li>
+</ul>
+</li>
<li><a href="#java-use-provider">Java Use Provider</a><ul>
<li><a href="#resource-backed-java-classes">Resource-backed Java
classes</a></li>
+<li><a href="#passing-parameters_1">Passing parameters</a></li>
</ul>
</li>
<li><a href="#javascript-use-provider">JavaScript Use Provider</a><ul>
+<li><a href="#passing-parameters_2">Passing parameters</a></li>
<li><a href="#caveats">Caveats</a></li>
</ul>
</li>
@@ -247,6 +252,7 @@ h2:hover > .headerlink, h3:hover > .head
<p>Depending on the implementation the above code would either load the
implementation with the highest service ranking of <code>Model3</code> if
<code>org.example.models.Model3</code> is an interface, or would load the model
<code>org.example.models.Model3</code> if this is a concrete implementation.</p>
<p>It's important to note that this use provider will only load models that
are adaptable from <code>SlingHttpServletRequest</code> or
<code>Resource</code>.</p>
+<h4 id="passing-parameters">Passing parameters<a class="headerlink"
href="#passing-parameters" title="Permanent link">¶</a></h4>
<p>Passed parameters will be made available to the Sling Model as request
attributes. Assuming the following markup:</p>
<div class="codehilite"><pre> <span class="nt"><div</span> <span
class="err">data-sly-use.</span><span class="na">model3=</span><span
class="s">"</span><span class="cp">${</span><span
class="s">'org.example.models.Model3'</span> <span class="err">@</span>
<span class="n">colour</span><span class="o">=</span><span
class="s">'red'</span><span class="p">,</span> <span
class="n">path</span><span class="o">=</span><span
class="n">resource</span><span class="o">.</span><span
class="n">path</span><span class="cp">}</span><span
class="s">"</span><span class="nt">></span>
<span class="cp">${</span><span class="n">model3</span><span
class="o">.</span><span class="n">shine</span><span class="cp">}</span>
@@ -268,7 +274,7 @@ h2:hover > .headerlink, h3:hover > .head
<h3 id="java-use-provider">Java Use Provider<a class="headerlink"
href="#java-use-provider" title="Permanent link">¶</a></h3>
-<p>The Java Use Provider can be used to load objects exported by bundles or
backed by a <code>Resource</code>.</p>
+<p>The Java Use Provider can be used to load OSGi services, objects exported
by bundles or backed by a <code>Resource</code>.</p>
<h4 id="resource-backed-java-classes">Resource-backed Java classes<a
class="headerlink" href="#resource-backed-java-classes" title="Permanent
link">¶</a></h4>
<p>When objects are backed by <code>Resources</code> 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 - <code>_</code>.</p>
<p><strong>Example:</strong><br />
@@ -299,6 +305,80 @@ Assuming the following content structure
<p>The advantage of loading a bean using just the simple class name (e.g.
<code>data-sly-use.page="PageBean"</code>) is that an inheriting component can
overlay the <code>PageBean.java</code> file and provide a different logic. In
this case the package name of the <code>PageBean</code> class will
automatically be derived from the calling script's parent path (e.g.
<code>apps.my_project.components.page</code>) - 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.</p>
+<h4 id="passing-parameters_1">Passing parameters<a class="headerlink"
href="#passing-parameters_1" title="Permanent link">¶</a></h4>
+<p>Passed parameters will be made available to the Use object as request
attributes and, if the object implements the <a
href="https://github.com/apache/sling/blob/trunk/bundles/scripting/sightly/engine/src/main/java/org/apache/sling/scripting/sightly/pojo/Use.java";><code>org.apache.sling.scripting.sightly.pojo.Use</code></a>
interface, through the <code>javax.script.Bindings</code> passed to the
<code>init</code> method. Assuming the following markup:</p>
+<div class="codehilite"><pre> <span class="nt"><div</span> <span
class="err">data-sly-use.</span><span class="na">useObject=</span><span
class="s">"</span><span class="cp">${</span><span
class="s">'org.example.use.MyUseObject'</span> <span
class="err">@</span> <span class="n">colour</span><span class="o">=</span><span
class="s">'red'</span><span class="p">,</span> <span
class="n">year</span><span class="o">=</span><span class="mi">2016</span><span
class="cp">}</span><span class="s">"</span><span class="nt">></span>
+ <span class="cp">${</span><span class="n">useObject</span><span
class="o">.</span><span class="n">shine</span><span class="cp">}</span>
+ <span class="nt"></div></span>
+</pre></div>
+
+
+<p>the object implementing <code>Use</code> would be able to retrieve the
parameters using the following constructs:</p>
+<div class="codehilite"><pre> <span class="n">package</span> <span
class="n">org</span><span class="p">.</span><span class="n">example</span><span
class="p">.</span><span class="n">use</span><span class="p">.</span><span
class="n">MyUseObject</span><span class="p">;</span>
+
+ <span class="n">import</span> <span class="n">javax</span><span
class="p">.</span><span class="n">script</span><span class="p">.</span><span
class="n">Bindings</span><span class="p">;</span>
+
+ <span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span
class="n">commons</span><span class="p">.</span><span
class="n">osgi</span><span class="p">.</span><span
class="n">PropertiesUtil</span><span class="p">;</span>
+ <span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span
class="n">scripting</span><span class="p">.</span><span
class="n">sightly</span><span class="p">.</span><span
class="n">pojo</span><span class="p">.</span><span class="n">Use</span><span
class="p">;</span>
+
+ <span class="n">public</span> <span class="n">class</span> <span
class="n">MyUseObject</span> <span class="n">implements</span> <span
class="n">Use</span> <span class="p">{</span>
+
+ <span class="n">private</span> <span class="n">String</span> <span
class="n">colour</span><span class="p">;</span>
+ <span class="n">private</span> <span class="n">Integer</span> <span
class="n">year</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">init</span><span class="p">(</span><span class="n">Bindings</span>
<span class="n">bindings</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">colour</span> <span class="p">=</span> <span
class="n">PropertiesUtil</span><span class="p">.</span><span
class="n">toString</span><span class="p">(</span><span
class="n">bindings</span><span class="p">.</span><span
class="n">get</span><span class="p">(</span>"<span
class="n">colour</span>"<span class="p">),</span> ""<span
class="p">);</span>
+ <span class="n">year</span> <span class="p">=</span> <span
class="n">PropertiesUtil</span><span class="p">.</span><span
class="n">toInteger</span><span class="p">(</span><span
class="n">bindings</span><span class="p">.</span><span
class="n">get</span><span class="p">(</span>"<span
class="n">year</span>"<span class="p">),</span> <span
class="n">Calendar</span><span class="p">.</span><span
class="n">getInstance</span><span class="p">().</span><span
class="n">get</span><span class="p">(</span><span
class="n">Calendar</span><span class="p">.</span><span
class="n">YEAR</span><span class="p">));</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>or, if the object is adaptable from a <code>SlingHttpServletRequest</code>,
through its <code>AdapterFactory</code>:</p>
+<div class="codehilite"><pre><span class="n">package</span> <span
class="n">org</span><span class="p">.</span><span class="n">example</span><span
class="p">.</span><span class="n">use</span><span class="p">;</span>
+
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span class="n">scr</span><span
class="p">.</span><span class="n">annotations</span><span
class="p">.</span><span class="n">Component</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span class="n">scr</span><span
class="p">.</span><span class="n">annotations</span><span
class="p">.</span><span class="n">Properties</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span class="n">scr</span><span
class="p">.</span><span class="n">annotations</span><span
class="p">.</span><span class="n">Property</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span class="n">scr</span><span
class="p">.</span><span class="n">annotations</span><span
class="p">.</span><span class="n">Service</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span class="n">api</span><span
class="p">.</span><span class="n">SlingHttpServletRequest</span><span
class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span class="n">api</span><span
class="p">.</span><span class="n">adapter</span><span class="p">.</span><span
class="n">AdapterFactory</span><span class="p">;</span>
+
+<span class="p">@</span><span class="n">Component</span>
+<span class="p">@</span><span class="n">Service</span>
+<span class="p">@</span><span class="n">Properties</span><span
class="p">({</span>
+ <span class="p">@</span><span class="n">Property</span><span
class="p">(</span>
+ <span class="n">name</span> <span class="p">=</span> <span
class="n">AdapterFactory</span><span class="p">.</span><span
class="n">ADAPTABLE_CLASSES</span><span class="p">,</span>
+ <span class="n">value</span> <span class="p">=</span> <span
class="p">{</span>
+ "<span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">sling</span><span class="p">.</span><span class="n">api</span><span
class="p">.</span><span class="n">SlingHttpServletRequest</span>"
+ <span class="p">}</span>
+ <span class="p">),</span>
+ <span class="p">@</span><span class="n">Property</span><span
class="p">(</span>
+ <span class="n">name</span> <span class="p">=</span> <span
class="n">AdapterFactory</span><span class="p">.</span><span
class="n">ADAPTER_CLASSES</span><span class="p">,</span>
+ <span class="n">value</span> <span class="p">=</span> <span
class="p">{</span>
+ "<span class="n">org</span><span
class="p">.</span><span class="n">example</span><span class="p">.</span><span
class="n">use</span><span class="p">.</span><span
class="n">MyUseObject</span>"
+ <span class="p">}</span>
+ <span class="p">)</span>
+<span class="p">})</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">RequestAdapterFactory</span> <span class="n">implements</span> <span
class="n">AdapterFactory</span> <span class="p">{</span>
+
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="n">public</span> <span class="o"><</span><span
class="n">AdapterType</span><span class="o">></span> <span
class="n">AdapterType</span> <span class="n">getAdapter</span><span
class="p">(</span><span class="n">Object</span> <span
class="n">adaptable</span><span class="p">,</span> <span
class="n">Class</span><span class="o"><</span><span
class="n">AdapterType</span><span class="o">></span> <span
class="n">type</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span
class="n">type</span> <span class="o">==</span> <span
class="n">MyUseObject</span><span class="p">.</span><span
class="n">class</span> <span class="o">&&</span> <span
class="n">adaptable</span> <span class="n">instanceof</span> <span
class="n">SlingHttpServletRequest</span><span class="p">)</span> <span
class="p">{</span>
+ <span class="n">SlingHttpServletRequest</span> <span
class="n">request</span> <span class="p">=</span> <span class="p">(</span><span
class="n">SlingHttpServletRequest</span><span class="p">)</span> <span
class="n">adaptable</span><span class="p">;</span>
+ <span class="n">String</span> <span class="n">colour</span> <span
class="p">=</span> <span class="n">PropertiesUtil</span><span
class="p">.</span><span class="n">toString</span><span class="p">(</span><span
class="n">request</span><span class="p">.</span><span
class="n">getAttribute</span><span class="p">(</span>"<span
class="n">colour</span>"<span class="p">),</span> ""<span
class="p">);</span>
+ <span class="n">Integer</span> <span class="n">year</span> <span
class="p">=</span> <span class="n">PropertiesUtil</span><span
class="p">.</span><span class="n">toInteger</span><span class="p">(</span><span
class="n">request</span><span class="p">.</span><span
class="n">getAttribute</span><span class="p">(</span>"<span
class="n">year</span>"<span class="p">),</span> <span
class="n">Calendar</span><span class="p">.</span><span
class="n">getInstance</span><span class="p">().</span><span
class="n">get</span><span class="p">(</span><span
class="n">Calendar</span><span class="p">.</span><span
class="n">YEAR</span><span class="p">));</span>
+ <span class="o">/*</span>
+ <span class="o">*</span> <span class="k">for</span> <span
class="n">the</span> <span class="n">sake</span> <span class="n">of</span>
<span class="n">this</span> <span class="n">example</span> <span
class="n">we</span> <span class="n">assume</span> <span class="n">that</span>
<span class="n">MyUseObject</span> <span class="n">has</span> <span
class="n">this</span> <span class="n">constructor</span>
+ <span class="o">*/</span>
+ <span class="k">return</span> <span class="p">(</span><span
class="n">AdapterType</span><span class="p">)</span> <span class="n">new</span>
<span class="n">MyUseObject</span><span class="p">(</span><span
class="n">colour</span><span class="p">,</span> <span
class="n">year</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">null</span><span
class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
<h3 id="javascript-use-provider">JavaScript Use Provider<a class="headerlink"
href="#javascript-use-provider" title="Permanent link">¶</a></h3>
<p>The JavaScript Use Provider allows loading objects created through the
<code>use</code> function, by evaluating scripts passed to
<code>data-sly-use</code>.</p>
<p><strong>Example:</strong><br />
@@ -329,6 +409,29 @@ Assuming the following content structure
<p>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.</p>
+<h4 id="passing-parameters_2">Passing parameters<a class="headerlink"
href="#passing-parameters_2" title="Permanent link">¶</a></h4>
+<p>Passed parameters will be made available to the Use object as properties of
<code>this</code>. Assuming the following markup:</p>
+<div class="codehilite"><pre> <span class="nt"><div</span> <span
class="err">data-sly-use.</span><span class="na">useObject=</span><span
class="s">"</span><span class="cp">${</span><span
class="s">'useObject.js'</span> <span class="err">@</span> <span
class="n">colour</span><span class="o">=</span><span
class="s">'red'</span><span class="p">,</span> <span
class="n">year</span><span class="o">=</span><span class="mi">2016</span><span
class="cp">}</span><span class="s">"</span><span class="nt">></span>
+ <span class="cp">${</span><span class="n">useObject</span><span
class="o">.</span><span class="n">shine</span><span class="cp">}</span>
+ <span class="nt"></div></span>
+</pre></div>
+
+
+<p>the object would be able to access the parameters like:</p>
+<div class="codehilite"><pre> <span class="n">use</span><span
class="p">(</span><span class="k">function</span><span class="p">()</span>
<span class="p">{</span>
+ <span class="s">'use strict'</span><span class="p">;</span>
+
+ <span class="n">var</span> <span class="n">colour</span> <span
class="p">=</span> <span class="n">this</span><span class="p">.</span><span
class="n">colour</span> <span class="o">||</span> <span
class="s">''</span><span class="p">;</span>
+ <span class="n">var</span> <span class="n">year</span> <span
class="p">=</span> <span class="n">this</span><span class="p">.</span><span
class="n">year</span> <span class="o">||</span> <span class="n">new</span>
<span class="n">Date</span><span class="p">().</span><span
class="n">getFullYear</span><span class="p">();</span>
+
+ <span class="k">return</span> <span class="p">{</span>
+ <span class="n">colour</span><span class="p">:</span> <span
class="n">colour</span><span class="p">,</span>
+ <span class="n">year</span><span class="p">:</span> <span
class="n">year</span>
+ <span class="p">}</span>
+ <span class="p">});</span>
+</pre></div>
+
+
<h4 id="caveats">Caveats<a class="headerlink" href="#caveats" title="Permanent
link">¶</a></h4>
<p>The JavaScript files are evaluated by the <a
href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino";>Rhino</a>
scripting engine, through the
<code>org.apache.sling.scripting.javascript</code> implementation bundle.</p>
<p>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 (<code>===</code>) since comparisons between JavaScript
and Java objects with the same apparent value will return <code>false</code>
(this also applies to the strict not-equal operator - <code>!==</code>).</p>
@@ -503,7 +606,7 @@ Assuming the following content structure
</tr>
</table>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1739874 by radu on Tue, 19 Apr 2016 09:10:29 +0000
+ Rev. 1739883 by radu on Tue, 19 Apr 2016 09:50:25 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
