You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2016/04/19 11:50:38 UTC
svn commit: r986071 - in /websites/staging/sling/trunk/content: ./
documentation/bundles/scripting/scripting-sightly.html
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