Author: buildbot
Date: Mon Apr 18 11:38:10 2016
New Revision: 985991
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 Mon Apr 18 11:38:10 2016
@@ -1 +1 @@
-1739545
+1739747
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
Mon Apr 18 11:38:10 2016
@@ -114,12 +114,22 @@ h2:hover > .headerlink, h3:hover > .head
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
-<p>The Apache Sling Sightly Scripting Engine is the Java reference
implementation of the <a
href="https://github.com/Adobe-Marketing-Cloud/sightly-spec";>Sightly HTML
Templating Language</a>.</p>
+<p>The Apache Sling Sightly Scripting Engine is the reference implementation
of the <a href="https://github.com/Adobe-Marketing-Cloud/sightly-spec";>Sightly
HTML Templating Language</a>.</p>
<div class="toc">
<ul>
<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></li>
+<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="#java-use-provider">Java Use Provider</a><ul>
+<li><a href="#resource-backed-java-classes">Resource-backed Java
classes</a></li>
+</ul>
+</li>
+<li><a href="#javascript-use-provider">JavaScript Use Provider</a></li>
+<li><a href="#script-use-provider">Script Use Provider</a></li>
+<li><a href="#picking-the-best-use-provider-for-a-project">Picking the best
Use Provider for a project</a></li>
+</ul>
+</li>
</ul>
</li>
</ul>
@@ -205,14 +215,14 @@ h2:hover > .headerlink, h3:hover > .head
<td><a
href="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";><code>JavaUseProvider</code></a></td>
<td><code>org.apache.sling.scripting.sightly</code></td>
<td>support for loading Java objects such as: <ol><li>OSGi
services</li><li>POJOs adaptable from <code>SlingHttpServletRequest</code> or
<code>Resource</code></li><li>POJOs that implement
<code>Use</code></li></ol></td>
-<td>The POJOs can be be exported by bundles or can be backed by
<code>Resources</code>. 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 (<code>_</code>).</td>
+<td>The POJOs can be exported by bundles or can be backed by
<code>Resources</code>. 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 - <code>_</code>.</td>
</tr>
<tr>
<td>80</td>
<td><a
href="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";><code>JsUseProvider</code></a></td>
<td><code>org.apache.sling.scripting.sightly.js.provider</code></td>
<td>support for loading objects defined through the JavaScript
<code>use</code> function</td>
-<td></td>
+<td>The <code>org.apache.sling.scripting.sightly.js.provider</code> also
provides a trimmed down <a
href="https://github.com/apache/sling/tree/trunk/bundles/scripting/sightly/js-use-provider/src/main/resources/SLING-INF/libs/sling/sightly/js";>asynchronous
implementation</a> of the <code>Resource</code> API. However this was
deprecated in <a
href="https://issues.apache.org/jira/browse/SLING-4964";>SLING-4964</a> (version
1.0.8 of the bundle) in favour of the synchronous API provided by the
<code>org.apache.sling.scripting.javascript</code> bundle.</td>
</tr>
<tr>
<td>0</td>
@@ -223,8 +233,156 @@ h2:hover > .headerlink, h3:hover > .head
</tr>
</tbody>
</table>
+<p>The <code>service.ranking</code> value of each Use Provider is
configurable, allowing for fine tuning of the order in which the providers are
queried when <code>data-sly-use</code> is called. However, in order to not
affect core functionality the <code>RenderUnitProvider</code> should always
have the highest ranking. If you need to configure the providers' service
ranking head over to the configuration console at <a
href="http://localhost:8080/system/console/configMgr";>http://localhost:8080/system/console/configMgr</a>.</p>
+<h3 id="sling-models-use-provider">Sling Models Use Provider<a
class="headerlink" href="#sling-models-use-provider" title="Permanent
link">¶</a></h3>
+<p>Loading a Sling Model can be done with the following code:</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">"org.example.models.Model3"</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>
+ <span class="nt"></div></span>
+</pre></div>
+
+
+<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>
+<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>
+ <span class="nt"></div></span>
+</pre></div>
+
+
+<p>the model would retrieve the parameters using the following constructs:</p>
+<div class="codehilite"><pre> <span class="p">@</span><span
class="n">Model</span><span class="p">(</span><span
class="n">adaptables</span><span class="p">=</span><span
class="n">SlingHttpServletRequest</span><span class="p">.</span><span
class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">class</span> <span
class="n">Model3</span> <span class="p">{</span>
+
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">String</span> <span
class="n">colour</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Inject</span>
+ <span class="n">private</span> <span class="n">String</span> <span
class="n">path</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<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>
+<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 />
+Assuming the following content structure:</p>
+<div class="codehilite"><pre> âââ <span class="n">apps</span>
+ âââ <span class="n">my</span><span class="o">-</span><span
class="n">project</span>
+ âââ <span class="n">components</span>
+ âââ <span class="n">page</span>
+ âââ <span class="n">PageBean</span><span
class="p">.</span><span class="n">java</span>
+ âââ <span class="n">page</span><span
class="p">.</span><span class="n">html</span>
+</pre></div>
+
+
+<p><code>page.html</code> could load <code>PageBean</code> either like:</p>
+<div class="codehilite"><pre> <span class="cp"><!DOCTYPE html></span>
+ <span class="nt"><html</span> <span
class="na">data-sly-use.page=</span><span
class="s">"apps.my_project.components.page.PageBean"</span><span
class="nt">></span>
+ ...
+ <span class="nt"></html></span>
+</pre></div>
+
+
+<p>or like:</p>
+<div class="codehilite"><pre> <span class="cp"><!DOCTYPE html></span>
+ <span class="nt"><html</span> <span
class="na">data-sly-use.page=</span><span
class="s">"PageBean"</span><span class="nt">></span>
+ ...
+ <span class="nt"></html></span>
+</pre></div>
+
+
+<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>
+<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 />
+Assuming the following content structure:</p>
+<div class="codehilite"><pre> âââ <span class="n">apps</span>
+ âââ <span class="n">my</span><span class="o">-</span><span
class="n">project</span>
+ âââ <span class="n">components</span>
+ âââ <span class="n">page</span>
+ âââ <span class="n">page</span><span
class="p">.</span><span class="n">html</span>
+ âââ <span class="n">page</span><span
class="p">.</span><span class="n">js</span>
+</pre></div>
+
+
+<p><code>page.html</code> could load <code>page.js</code> either like:</p>
+<div class="codehilite"><pre> <span class="cp"><!DOCTYPE html></span>
+ <span class="nt"><html</span> <span
class="na">data-sly-use.page=</span><span
class="s">"/apps/my-project/components/page/page.js"</span><span
class="nt">></span>
+ ...
+ <span class="nt"></html></span>
+</pre></div>
+
+
+<p>or like:</p>
+<div class="codehilite"><pre> <span class="cp"><!DOCTYPE html></span>
+ <span class="nt"><html</span> <span
class="na">data-sly-use.page=</span><span
class="s">"page.js"</span><span class="nt">></span>
+ ...
+ <span class="nt"></html></span>
+</pre></div>
+
+
+<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>
+<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. 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
(<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>
+<h3 id="script-use-provider">Script Use Provider<a class="headerlink"
href="#script-use-provider" title="Permanent link">¶</a></h3>
+<p>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.</p>
+<h3 id="picking-the-best-use-provider-for-a-project">Picking the best Use
Provider for a project<a class="headerlink"
href="#picking-the-best-use-provider-for-a-project" title="Permanent
link">¶</a></h3>
+<p>The following table summarises the pros and cons for each Use Provider,
with the obvious exception of the Render Unit Use Provider.</p>
+<table>
+ <tr>
+ <th>Use Provider</th>
+ <th>Advantages</th>
+ <th>Disadvantages</th>
+ </tr>
+ <tr>
+ <td>Sling Models Use Provider</td>
+ <td><ul><li>convenient injection annotations for data
retrieval</li><li>easy to extend from other Sling Models</li><li>simple setup
for unit testing</li></ul></td>
+ <td><ul><li>lacks flexibility in terms of component overlaying,
relying on <code>service.ranking</code> configurations</li></ul></td>
+ </tr>
+ <tr>
+ <td>Java Use Provider</td>
+ <td>
+ <p>Use-objects provided through bundles:</p>
+ <ul>
+ <li>faster to initialise and execute than Sling Models for
similar code</li>
+ <li>easy to extend from other similar Use-objects</li>
+ <li>simple setup for unit testing</li>
+ </ul>
+ <p>Use-objects backed by <code>Resources</code>:</p>
+ <ul>
+ <li>faster to initialise and execute than Sling Models for
similar code</li>
+ <li>easy to override from inheriting components through search
path overlay or by using the <code>sling:resourceSuperType</code> property,
allowing for greater flexibility</li>
+ <li>business logic for components sits next to the Sightly
scripts where the objects are used</li>
+ </ul>
+ </td>
+ <td>
+ <p>Use-objects backed by <code>Resources</code>:</p>
+ <ul>
+ <li>cannot extend other Java objects</li>
+ <li>the Java project might need a different setup to allow
running unit tests, since the objects will be deployed like content</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>JavaScript Use Provider</td>
+ <td>
+ <ul>
+ <li>allows JavaScript developers to develop component
logic</li>
+ </ul>
+ </td>
+ <td>
+ <ul>
+ <li>harder to test and debug, relying mostly on end-to-end
testing</li>
+ <li>slower to execute than both Sling Models and Java Use-API
objects</li>
+ </ul>
+ </td>
+ </tr>
+</table>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1739323 by radu on Fri, 15 Apr 2016 15:45:32 +0000
+ Rev. 1739747 by radu on Mon, 18 Apr 2016 11:37:55 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
