You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by gp...@apache.org on 2015/10/27 20:09:24 UTC
svn commit: r1710870 [2/3] - /deltaspike/site/trunk/content/documentation/
Modified: deltaspike/site/trunk/content/documentation/jsf.html
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/documentation/jsf.html?rev=1710870&r1=1710869&r2=1710870&view=diff
==============================================================================
--- deltaspike/site/trunk/content/documentation/jsf.html (original)
+++ deltaspike/site/trunk/content/documentation/jsf.html Tue Oct 27 19:09:24 2015
@@ -247,7 +247,6 @@ table.CodeRay td.code>pre{padding:0}
<li ><a href="../community.html">Community</a></li>
<!-- <li><a href="./support.html">Support</a></li> -->
<li ><a href="../news.html">News</a></li>
- <li ><a href="../migration-guide.html">Migration</a></li>
</ul>
</div>
<!--/.nav-collapse -->
@@ -479,10 +478,10 @@ directly.</p>
<div class="sect4">
<h5 id="_configuration">Configuration</h5>
<div class="sect5">
-<h6 id="_change_windowhandler_html">Change windowhandler.html</h6>
+<h6 id="_reduce_windowhandler_html_flickering">Reduce windowhandler.html flickering</h6>
<div class="paragraph">
-<p>To customize the look and feel of the windowhandler.html, you can simply
-provide a own via:</p>
+<p>Per default we only overwrite the onclick events of all links on the current page to make a 'screenshot' between requests.
+We also provide a mechanism to store the 'screenshot' on ajax requests (e.g. Post-Redirect-Get via p:remoteCommand or other components) or on every button onclick:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -490,339 +489,308 @@ provide a own via:</p>
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClientWindowConfig</span> <span class="directive">extends</span> DefaultClientWindowConfig
{
<span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">String</span> getClientWindowHtml()
+ <span class="directive">public</span> <span class="type">boolean</span> isClientWindowStoreWindowTreeEnabledOnAjaxRequest()
{
- <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content"><html><body>Loading...</body></html></span><span class="delimiter">"</span></span>;
+ <span class="keyword">return</span> <span class="predefined-constant">true</span>;
}
-}</code></pre>
+
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> <span class="type">boolean</span> isClientWindowStoreWindowTreeEnabledOnButtonClick()
+ {
+ <span class="keyword">return</span> <span class="predefined-constant">true</span>;
+ }
+}
+
+====== Change windowhandler.html
+
+To customize the look and feel of the windowhandler.html, you can simply
+provide a own via:
+
+[source,java]</code></pre>
</div>
</div>
<div class="paragraph">
-<p>If you didn’t copy the JS logic from our default windowhandler.html or
-if you would like to always show your custom html instead the 'screenshot', you should disable logic via:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Specializes</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClientWindowConfig</span> <span class="directive">extends</span> DefaultClientWindowConfig
+<p>@Specializes
+public class MyClientWindowConfig extends DefaultClientWindowConfig
{
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">String</span> isClientWindowStoreWindowTreeEnabled()
+ @Override
+ public String getClientWindowHtml()
{
- <span class="keyword">return</span> <span class="predefined-constant">false</span>;
+ return "<html><body>Loading…​</body></html>";
}
-}</code></pre>
-</div>
+}</p>
</div>
+<div class="listingblock">
+<div class="content">
+<pre>If you didn't copy the JS logic from our default windowhandler.html or
+if you would like to always show your custom html instead the 'screenshot', you should disable logic via:
+
+[source,java]</pre>
</div>
-<div class="sect5">
-<h6 id="_minimize_windowhandler_html_streaming">Minimize windowhandler.html streaming</h6>
-<div class="paragraph">
-<p>It’s possible to reduce the windowhandler.html streaming if we overwrite the onclick event of all links to mark the next request as 'valid'.
-The onclick handler appends a request token to the URL and creates a cookie for the request token.</p>
</div>
<div class="paragraph">
-<p>You can enable this via:</p>
+<p>@Specializes
+public class MyClientWindowConfig extends DefaultClientWindowConfig
+{
+ @Override
+ public boolean isClientWindowStoreWindowTreeEnabledOnLinkClick()
+ {
+ return false;
+ }</p>
</div>
-<div class="listingblock">
+<div class="literalblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Specializes</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClientWindowConfig</span> <span class="directive">extends</span> DefaultClientWindowConfig
+<pre>@Override
+public boolean isClientWindowStoreWindowTreeEnabledOnAjaxRequest()
{
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">String</span> isClientWindowTokenizedRedirectEnabled()
+ return false;
+}</pre>
+</div>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre> @Override
+ public boolean isClientWindowStoreWindowTreeEnabledOnButtonClick()
{
- <span class="keyword">return</span> <span class="predefined-constant">true</span>;
+ return false;
}
-}</code></pre>
-</div>
+}</pre>
</div>
</div>
+<div class="listingblock">
+<div class="content">
+<pre>====== Minimize windowhandler.html streaming
+
+It's possible to reduce the windowhandler.html streaming if we overwrite the onclick event of all links to mark the next request as 'valid'.
+The onclick handler appends a request token to the URL and creates a cookie for the request token.
+
+You can enable this via:
+
+[source,java]</pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_lazy">LAZY</h4>
<div class="paragraph">
-<p>Always appends the windowId to all, from JSF generated, URLs. On the
+<p>@Specializes
+public class MyClientWindowConfig extends DefaultClientWindowConfig
+{
+ @Override
+ public String isClientWindowTokenizedRedirectEnabled()
+ {
+ return true;
+ }
+}</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>==== LAZY
+
+Always appends the windowId to all, from JSF generated, URLs. On the
first GET request without a windowId, it will generate a new windowId
and redirect, with the windowId in the URL, to the same view again. The
-current windowId will be stored in the <code>window.name</code> variable on the
+current windowId will be stored in the `window.name` variable on the
client side. For all further requests, a lazy check will be performed to
-check if the windowId in the URL is matching with the <code>window.name</code>. If
+check if the windowId in the URL is matching with the `window.name`. If
it is not matching, the view will be refreshed with the right windowId in
-the URL.</p>
-</div>
-<div class="sect4">
-<h5 id="_advantage_2">Advantage</h5>
-<div class="ulist">
-<ul>
-<li>
-<p>No windowhandler.html / loading screen required</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_disadvantage_2">Disadvantage</h5>
-<div class="ulist">
-<ul>
-<li>
-<p>It could happen that 2 tabs will share the same windowId for 1 request
-because the <code>LAZY</code> mode will check lazily, after rendering the view, if
-the windowId matches the <code>window.name</code>. Therefore it could happen that
-@ViewAccessScoped or other scopes will unintentionally be destroyed.</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_workflow_example">Workflow Example</h5>
-<div class="paragraph">
-<p>First GET request with windowId</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Renders the view</p>
-</li>
-<li>
-<p>Stores the windowId as <code>window.name</code> on the client side</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>First GET request without windowId</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Redirect to the same view with a new windowId in the URL</p>
-</li>
-<li>
-<p>Renders the view</p>
-</li>
-<li>
-<p>Stores the windowId as <code>window.name</code> on the client side</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Further GET request with windowId</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Renders the view</p>
-</li>
-<li>
-<p>Checks if the requested windowId matches the <code>window.name</code></p>
-</li>
-<li>
-<p>If it does not match, reload the URL with the right windowId taken
-from <code>window.name</code></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Further GET request without windowId</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Redirect to the same view with a new windowId in the URL</p>
-</li>
-<li>
-<p>Renders the view</p>
-</li>
-<li>
-<p>If it does not match, reload the URL with the right windowId taken
-from <code>window.name</code></p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_none">NONE</h4>
-<div class="paragraph">
-<p>Any window or browser tab detection will be disabled for the current
+the URL.
+
+
+===== Advantage
+
+* No windowhandler.html / loading screen required
+
+===== Disadvantage
+
+* It could happen that 2 tabs will share the same windowId for 1 request
+because the `LAZY` mode will check lazily, after rendering the view, if
+the windowId matches the `window.name`. Therefore it could happen that
+@ViewAccessScoped or other scopes will unintentionally be destroyed.
+
+
+===== Workflow Example
+
+First GET request with windowId
+
+* Renders the view
+* Stores the windowId as `window.name` on the client side
+
+
+First GET request without windowId
+
+* Redirect to the same view with a new windowId in the URL
+* Renders the view
+* Stores the windowId as `window.name` on the client side
+
+
+Further GET request with windowId
+
+* Renders the view
+* Checks if the requested windowId matches the `window.name`
+* If it does not match, reload the URL with the right windowId taken
+from `window.name`
+
+
+Further GET request without windowId
+
+* Redirect to the same view with a new windowId in the URL
+* Renders the view
+* If it does not match, reload the URL with the right windowId taken
+from `window.name`
+
+
+==== NONE
+
+Any window or browser tab detection will be disabled for the current
request. Scopes like @WindowScoped, @GroupedConversationScoped or
@ViewAccessScoped will not work. This is also the default mode if the
current request does not support Javascript or if the user agent is a
-bot/crawler.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_delegated">DELEGATED</h4>
-<div class="paragraph">
-<p>Delegates the complete window handling to the new JSF 2.2 ClientWindow
-(if not disabled).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_custom">CUSTOM</h4>
-<div class="paragraph">
-<p>Enables to use an complete own
-<code>org.apache.deltaspike.jsf.spi.scope.window.ClientWindow</code>
-implementation.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_configuration_2">Configuration</h3>
-<div class="sect3">
-<h4 id="_ds_windowid">ds:windowId</h4>
-<div class="paragraph">
-<p>The component <code>ds:windowId</code>
-(<code>xmlns:ds="http://deltaspike.apache.org/jsf"</code>) is required to enable
+bot/crawler.
+
+
+==== DELEGATED
+
+Delegates the complete window handling to the new JSF 2.2 ClientWindow
+(if not disabled).
+
+
+==== CUSTOM
+
+Enables to use an complete own
+`org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
+implementation.
+
+
+=== Configuration
+
+==== ds:windowId
+
+The component `ds:windowId`
+(`xmlns:ds="http://deltaspike.apache.org/jsf"`) is required to enable
the full control of the DeltaSpike window handling. It will import and
-render the required script parts for both <code>LAZY</code> and <code>CLIENTWINDOW</code>
+render the required script parts for both `LAZY` and `CLIENTWINDOW`
mode. The best way, to apply it for all views, is to add this component
-to all of your templates.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ds_disableclientwindow">ds:disableClientWindow</h4>
-<div class="paragraph">
-<p>Similiar to JSF 2.2' <code>disableClientWindow</code> attribute,
-<code>ds:disableClientWindow</code> provides the ability to disable the rendering
-of the windowId to all links of all child components:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><ds:disableClientWindow></span>
- <span class="tag"><h:link</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">Link without windowId</span><span class="delimiter">"</span></span> <span class="attribute-name">outcome</span>=<span class="string"><span class="delimiter">"</span><span class="content">target.xhtml</span><span class="delimiter">"</span></span> <span class="tag">/></span>
-<span class="tag"></ds:disableClientWindow></span>
-<span class="tag"><h:link</span> <span class="attribute-name">value</span>=<span class="string"><span class="delimiter">"</span><span class="content">Link with windowId</span><span class="delimiter">"</span></span> <span class="attribute-name">outcome</span>=<span class="string"><span class="delimiter">"</span><span class="content">target.xhtml</span><span class="delimiter">"</span></span><span class="tag">/></span></code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_number_of_active_windows">Number of Active Windows</h4>
-<div class="paragraph">
-<p>By default, DeltaSpike allows <code>1024</code> active windows per session. Anyway, this number is reduced inside this JSF module to <code>64</code> for JSF applications. Once that the limit number of active windows is reached, DeltaSpike will drop the oldest active window.</p>
+to all of your templates.
+
+
+==== ds:disableClientWindow
+
+Similiar to JSF 2.2' `disableClientWindow` attribute,
+`ds:disableClientWindow` provides the ability to disable the rendering
+of the windowId to all links of all child components:
+
+[source,xml]</pre>
</div>
-<div class="paragraph">
-<p>You can change the default value by setting the property <code>deltaspike.scope.window.max-count</code> using <a href="configuration.html#_configsources_provided_by_default">DeltaSpike configuration mechanism</a>.</p>
</div>
<div class="paragraph">
-<p>You can also provide this value via:</p>
+<p><ds:disableClientWindow>
+ <h:link value="Link without windowId" outcome="target.xhtml" />
+</ds:disableClientWindow>
+<h:link value="Link with windowId" outcome="target.xhtml"/></p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Specializes</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClientWindowConfig</span> <span class="directive">extends</span> DefaultClientWindowConfig
+<pre>==== Number of Active Windows
+
+By default, DeltaSpike allows `1024` active windows per session. Anyway, this number is reduced inside this JSF module to `64` for JSF applications. Once that the limit number of active windows is reached, DeltaSpike will drop the oldest active window.
+
+You can change the default value by setting the property `deltaspike.scope.window.max-count` using <<configuration.adoc#_configsources_provided_by_default, DeltaSpike configuration mechanism>>.
+
+You can also provide this value via:
+
+[source,java]
+-----------------------------------------------------------------------------------
+@Specializes
+public class MyClientWindowConfig extends DefaultClientWindowConfig
{
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="type">int</span> getMaxWindowContextCount()
+ @Override
+ public int getMaxWindowContextCount()
{
- <span class="comment">// return the max active windows per session</span>
+ // return the max active windows per session
}
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_switch_mode">Switch Mode</h4>
-<div class="paragraph">
-<p>To switch the mode, just provide a
-<code>org.apache.deltaspike.jsf.api.config.JsfModuleConfig</code> and overwrite
-<code>#getDefaultWindowMode</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Specializes</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyJsfModuleConfig</span> <span class="directive">extends</span> JsfModuleConfig
+}
+-----------------------------------------------------------------------------------
+
+==== Switch Mode
+
+To switch the mode, just provide a
+`org.apache.deltaspike.jsf.api.config.JsfModuleConfig` and overwrite
+`#getDefaultWindowMode`:
+
+[source,java]
+---------------------------------------------------------------------------
+@Specializes
+public class MyJsfModuleConfig extends JsfModuleConfig
{
- <span class="annotation">@Override</span>
- <span class="directive">public</span> ClientWindowConfig.ClientWindowRenderMode getDefaultWindowMode()
+ @Override
+ public ClientWindowConfig.ClientWindowRenderMode getDefaultWindowMode()
{
- <span class="comment">//...</span>
+ //...
}
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_provide_a_custom_clientwindow">Provide a Custom ClientWindow</h4>
-<div class="paragraph">
-<p>If you would like to provide an custom
-<code>org.apache.deltaspike.jsf.spi.scope.window.ClientWindow</code>
-implementation, you can just do it, for example, via CDI alternatives:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ApplicationScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClientWindow</span> <span class="directive">implements</span> ClientWindow
+}
+---------------------------------------------------------------------------
+
+
+==== Provide a Custom ClientWindow
+
+If you would like to provide an custom
+`org.apache.deltaspike.jsf.spi.scope.window.ClientWindow`
+implementation, you can just do it, for example, via CDI alternatives:
+
+[source,java]
+---------------------------------------------------
+@ApplicationScoped
+public class MyClientWindow implements ClientWindow
{
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Do not forget to set the <code>ClientWindowRenderMode</code> to 'CUSTOM' via the
-<code>JsfModuleConfig</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Specializes</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyJsfModuleConfig</span> <span class="directive">extends</span> JsfModuleConfig
+ //...
+}
+---------------------------------------------------
+
+Do not forget to set the `ClientWindowRenderMode` to 'CUSTOM' via the
+`JsfModuleConfig`:
+
+[source,java]
+---------------------------------------------------------------------------
+@Specializes
+public class MyJsfModuleConfig extends JsfModuleConfig
{
- <span class="annotation">@Override</span>
- <span class="directive">public</span> ClientWindowConfig.ClientWindowRenderMode getDefaultWindowMode()
+ @Override
+ public ClientWindowConfig.ClientWindowRenderMode getDefaultWindowMode()
{
- <span class="keyword">return</span> ClientWindowConfig.ClientWindowRenderMode.CUSTOM;
+ return ClientWindowConfig.ClientWindowRenderMode.CUSTOM;
}
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_based_scopes">Based Scopes</h3>
-<div class="ulist">
-<ul>
-<li>
-<p>@WindowScoped</p>
-</li>
-<li>
-<p>@ViewAccessScoped</p>
-</li>
-<li>
-<p>@GroupedConversationScoped</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_scopes">Scopes</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="__windowscoped">@WindowScoped</h3>
-<div class="paragraph">
-<p>The window-scope is like a session per window. That means that the data
+}
+---------------------------------------------------------------------------
+
+=== Based Scopes
+
+* @WindowScoped
+* @ViewAccessScoped
+* @GroupedConversationScoped
+
+
+== Scopes
+
+=== @WindowScoped
+
+The window-scope is like a session per window. That means that the data
is bound to a window/tab and it not shared between windows (like the
session scope does). Usually you need the window-scope instead of the
session-scope. There areis not a lot of use-cases which need shared data
-between windows.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@WindowScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">PreferencesBean</span> <span class="directive">implements</span> <span class="predefined-type">Serializable</span>
+between windows.
+
+[source,java]
+----------------------------------------------------
+@WindowScoped
+public class PreferencesBean implements Serializable
{
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="__viewaccessscoped">@ViewAccessScoped</h3>
-<div class="paragraph">
-<p>In case of conversations you have to un-scope beans manually (or they
+ //...
+}
+----------------------------------------------------
+
+
+=== @ViewAccessScoped
+
+In case of conversations you have to un-scope beans manually (or they
will be terminated automatically after a timeout). However, sometimes
you need beans with a lifetime which is as long as needed and as short
as possible - which are terminated automatically (as soon as possible).
@@ -831,122 +799,86 @@ as the bean is referenced by a page - th
next page (if it is used again the bean will be forwarded again). It is
important that it is based on the view-id of a page (it is not based on
the request) so, for example, Ajax requests do not trigger a cleanup if the
-request does not access all view-access scoped beans of the page. That’s
-also the reason for the name @<em>View</em>AccessScoped.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ViewAccessScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">WizardBean</span> <span class="directive">implements</span> <span class="predefined-type">Serializable</span>
+request does not access all view-access scoped beans of the page. That's
+also the reason for the name @__View__AccessScoped.
+
+[source,java]
+-----------------------------------------------
+@ViewAccessScoped
+public class WizardBean implements Serializable
{
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-@ViewAccessScoped beans are best used in conjunction with the
-<code>CLIENTWINDOW</code> window handling, which ensures a clean browser-tab
+ //...
+}
+-----------------------------------------------
+
+TIP: @ViewAccessScoped beans are best used in conjunction with the
+`CLIENTWINDOW` window handling, which ensures a clean browser-tab
separation without touching the old windowId. Otherwise a 'open in new
tab' on a page with a @ViewAccessScoped bean might cause the termination
(and re-initialization) of that bean.
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="__groupedconversationscoped">@GroupedConversationScoped</h3>
-<div class="paragraph">
-<p>See (Grouped-)Conversations</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="__viewscoped">@ViewScoped</h3>
-<div class="paragraph">
-<p>DeltaSpike provides an CDI context for the JSF 2.0/2.1
+
+=== @GroupedConversationScoped
+
+See (Grouped-)Conversations
+
+=== @ViewScoped
+
+DeltaSpike provides an CDI context for the JSF 2.0/2.1
@javax.faces.bean.ViewScoped. You can simply annotate your bean with
-@javax.faces.bean.ViewScoped and @Named.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_jsf_2_0_scopes">JSF 2.0 Scopes</h3>
-<div class="paragraph">
-<p>JSF 2.0 introduced new annotations as well as a new scope - the View
+@javax.faces.bean.ViewScoped and @Named.
+
+=== JSF 2.0 Scopes
+
+JSF 2.0 introduced new annotations as well as a new scope - the View
Scope. DeltaSpike allows to use all the CDI mechanisms in beans annotated
-with:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>javax.faces.bean.ApplicationScoped</p>
-</li>
-<li>
-<p>javax.faces.bean.SessionScoped</p>
-</li>
-<li>
-<p>javax.faces.bean.RequestScoped</p>
-</li>
-<li>
-<p>javax.faces.bean.ViewScoped</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Furthermore, the managed-bean annotation (javax.faces.bean.ManagedBean)
-is mapped to @Named from CDI.</p>
-</div>
-<div class="paragraph">
-<p>All these annotations are mapped automatically. So you will not face
+with:
+
+* javax.faces.bean.ApplicationScoped
+* javax.faces.bean.SessionScoped
+* javax.faces.bean.RequestScoped
+* javax.faces.bean.ViewScoped
+
+Furthermore, the managed-bean annotation (javax.faces.bean.ManagedBean)
+is mapped to @Named from CDI.
+
+All these annotations are mapped automatically. So you will not face
issues, if you import a JSF 2 annotation instead of the corresponding
-CDI annotation.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_integration_with_deltaspike_type_safe_messages">Integration with DeltaSpike Type-safe Messages</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>You can use <a href="core.html#_messages_i18n">DeltaSpike type-safe messages</a>
-with JSF to provide i18n messages and test to an JSF appplicaton.</p>
-</div>
-<div class="paragraph">
-<p>JSF module is also capable to use messages provided through in
+CDI annotation.
+
+== Integration with DeltaSpike Type-safe Messages
+
+You can use <<core.adoc#_messages_i18n,DeltaSpike type-safe messages>>
+with JSF to provide i18n messages and test to an JSF appplicaton.
+
+JSF module is also capable to use messages provided through in
faces-config.xml file. The element allows you to override JSF default
messages (Section 2.5.2.4 of the JSF specification contains the list of
-all JSF default messages that could be override.).</p>
-</div>
-<div class="paragraph">
-<p>DeltaSpike can also reuse the same file to provide type-safe messages so
-you do not have to use the naming convention nor <code>@MessageContextConfig</code>.
+all JSF default messages that could be override.).
+
+DeltaSpike can also reuse the same file to provide type-safe messages so
+you do not have to use the naming convention nor `@MessageContextConfig`.
If there is a config for supported locales it will be checked as well
-and fallback to the configured default locale.</p>
-</div>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@MessageBundle</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SimpleMessage</span>
+and fallback to the configured default locale.
+
+.Example
+[source,java]
+------------------------------------------------------------------------------------------------------------
+@MessageBundle
+public interface SimpleMessage
{
- <span class="annotation">@MessageTemplate</span>(<span class="string"><span class="delimiter">"</span><span class="content">{welcome_to_deltaspike}</span><span class="delimiter">"</span></span>)
- <span class="predefined-type">String</span> welcomeToDeltaSpike();
+ @MessageTemplate("{welcome_to_deltaspike}")
+ String welcomeToDeltaSpike();
}
-<span class="annotation">@Model</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">PageBean</span>
+@Model
+public class PageBean
{
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> SimpleMessage messages;
+ @Inject
+ private SimpleMessage messages;
- <span class="directive">public</span> <span class="type">void</span> actionMethod(){
- FacesContext.getCurrentInstance().addMessage(<span class="predefined-constant">null</span>,<span class="keyword">new</span> FacesMessage(messages.welcomeToDeltaSpike()));
+ public void actionMethod(){
+ FacesContext.getCurrentInstance().addMessage(null,new FacesMessage(messages.welcomeToDeltaSpike()));
}
}
@@ -963,1479 +895,1254 @@ org/apache/deltaspike/example/message/Si
...
-<span class="comment">//content (as usual in message bundle files):</span>
+//content (as usual in message bundle files):
welcome_to_deltaspike=Welcome to DeltaSpike
-<span class="comment">//Overrided JSF messages</span>
-javax.faces.component.UIInput.REQUIRED = {<span class="integer">0</span>}: Please enter a value</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="title">Faces-config.xml File</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><faces-config></span>
- <span class="tag"><application></span>
- <span class="tag"><message-bundle></span>org.apache.deltaspike.example.message.SimpleMessage<span class="tag"></message-bundle></span>
- <span class="tag"></application></span>
-<span class="tag"></faces-config></span></code></pre>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_type_safe_view_configs">Type-safe View-Configs</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_intro">Intro</h3>
-<div class="paragraph">
-<p>Type-safe view-configs are static configs which can be used in
+//Overrided JSF messages
+javax.faces.component.UIInput.REQUIRED = {0}: Please enter a value
+------------------------------------------------------------------------------------------------------------
+
+.Faces-config.xml File
+[source,xml]
+--------------------------------------------------------------------------------------------
+<faces-config>
+ <application>
+ <message-bundle>org.apache.deltaspike.example.message.SimpleMessage</message-bundle>
+ </application>
+</faces-config>
+--------------------------------------------------------------------------------------------
+
+== Type-safe View-Configs
+
+=== Intro
+
+Type-safe view-configs are static configs which can be used in
combination with every view-technology which is based on Java. Currently
DeltaSpike itself provides an integration for JSF, however, the basic
concepts are independent of it. (Since DeltaSpike provides the default
integration only for JSF, the whole documentation for view-configs is
-located here.)</p>
-</div>
-<div class="paragraph">
-<p>Thanks to features like multiple (meta-data-)inheritance via interfaces,
+located here.)
+
+Thanks to features like multiple (meta-data-)inheritance via interfaces,
it provides a powerful approach to bind meta-data to one or multiple
views. In case of the JSF integration it is possible to provide, for example,
type-safe meta-data for security, navigation, callbacks for
view-controllers. Beyond configuring view (/pages) via this concept,
it is also possible to use the (view-)config classes for type-safe
navigation. Since it is standard Java, you can benefit from any Java-IDE and
-you do not need special IDE-Addons to use it efficiently.</p>
-</div>
-<div class="paragraph">
-<p>Even the concepts provided by modules (of DeltaSpike itself) are based
+you do not need special IDE-Addons to use it efficiently.
+
+Even the concepts provided by modules (of DeltaSpike itself) are based
on the basic API provided by the Core. So it is possible to introduce
-custom concepts the same way DeltaSpike itself does.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_motivation">Motivation</h3>
-<div class="paragraph">
-<p>Instead of learning the concepts and rules of view-configs provided by
+custom concepts the same way DeltaSpike itself does.
+
+=== Motivation
+
+Instead of learning the concepts and rules of view-configs provided by
DeltaSpike, it might be easier for simple demos to just type some
simple(r) strings. So why should you use something which is slightly
-more work <strong>initially</strong>?</p>
-</div>
-<div class="paragraph">
-<p><strong>The short answer is:</strong> It gives a good return in case of real applications (especially beyond simple demos).</p>
-</div>
-<div class="paragraph">
-<p><strong>The long answer is:</strong> You can benefit from it from the first second:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>It is type-safe</p>
-<div class="ulist">
-<ul>
-<li>
-<p>the Java compiler ensures that you do not have typos at the final usages (and the rest can be checked during bootstrapping of the application)</p>
-</li>
-<li>
-<p>you can benefit from the auto.complete features of any modern Java IDE.</p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>If you change the name of a file/folder, you need only one (easy) code-change in a single place and your (standard Java-) IDE will do the rest for you (= update all usages) without a special plug-in</p>
-</li>
-<li>
-<p>It is possible to restrict the navigation target → you can ensure that the navigation target is still the intended one (e.g. after a refactoring)</p>
-</li>
-<li>
-<p>You can configure meta-data in a central place (which can get inherited via <strong>multiple</strong> inheritance based on Java interfaces)</p>
-</li>
-<li>
-<p>Easier for developers to find usages</p>
-</li>
-<li>
-<p>Allows easy(er) refactorings and maintenance</p>
-</li>
-<li>
-<p>You can use your IDE more efficiently especially in large projects (there are some users who initially switched to it, because their tools for displaying the config they had before open large config files very slowly…​)</p>
-</li>
-<li>
-<p>Modern Java IDEs show inheritance of interfaces and classes in a nice way. Since the view-config is based on standard classes and interfaces, you can benefit from it easily.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Advantages which are planned for later (= currently not supported):</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>It is possible to check if the configured folders and files really exist during/after the bootstrapping phase of the application (currently it is not implemented, but it is possible to do it).</p>
-</li>
-<li>
-<p>It is also easy(er) for tools (IDE plugins,…​) to validate it</p>
-</li>
-<li>
-<p>It is possible to validate the config (if the corresponding path (view or folder) really exists (after v0.5 it is done out-of-the-box)</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>If you are still not convinced, you just have to try it. You will see how your daily workflow benefits from it pretty soon.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_bean_discovery_mode_annotated">Bean-discovery-mode Annotated</h3>
-<div class="paragraph">
-<p>CDI 1.1 introduced a concept called bean-discovery-mode. If you would
-like to use the mode <code>annotated</code>, please have a look at the tip at
-@ViewConfigRoot</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_basic_api_usages">Basic API Usages</h3>
-<div class="paragraph">
-<p>While reading this section keep the following simple rules in mind:
+more work **initially**?
+
+*The short answer is:* It gives a good return in case of real applications (especially beyond simple demos).
+
+*The long answer is:* You can benefit from it from the first second:
+
+* It is type-safe
+** the Java compiler ensures that you do not have typos at the final usages (and the rest can be checked during bootstrapping of the application)
+** you can benefit from the auto.complete features of any modern Java IDE.
+* If you change the name of a file/folder, you need only one (easy) code-change in a single place and your (standard Java-) IDE will do the rest for you (= update all usages) without a special plug-in
+* It is possible to restrict the navigation target -> you can ensure that the navigation target is still the intended one (e.g. after a refactoring)
+* You can configure meta-data in a central place (which can get inherited via *multiple* inheritance based on Java interfaces)
+* Easier for developers to find usages
+* Allows easy(er) refactorings and maintenance
+* You can use your IDE more efficiently especially in large projects (there are some users who initially switched to it, because their tools for displaying the config they had before open large config files very slowly...)
+* Modern Java IDEs show inheritance of interfaces and classes in a nice way. Since the view-config is based on standard classes and interfaces, you can benefit from it easily.
+
+Advantages which are planned for later (= currently not supported):
+
+* It is possible to check if the configured folders and files really exist during/after the bootstrapping phase of the application (currently it is not implemented, but it is possible to do it).
+* It is also easy(er) for tools (IDE plugins,...) to validate it
+* It is possible to validate the config (if the corresponding path (view or folder) really exists (after v0.5 it is done out-of-the-box)
+
+If you are still not convinced, you just have to try it. You will see how your daily workflow benefits from it pretty soon.
+
+=== Bean-discovery-mode Annotated
+
+CDI 1.1 introduced a concept called bean-discovery-mode. If you would
+like to use the mode `annotated`, please have a look at the tip at
+@ViewConfigRoot
+
+=== Basic API Usages
+
+While reading this section keep the following simple rules in mind:
Meta-data gets inherited along the path of Java inheritance
File-/Folder- paths are build based on nesting classes and interfaces
-Usually users do not need to be aware of all descriptors, SPIs,…​ which
-are described by this documentation.</p>
-</div>
-<div class="paragraph">
-<p>There are a lot of possibilities to configure views and some of them are
+Usually users do not need to be aware of all descriptors, SPIs,... which
+are described by this documentation.
+
+There are a lot of possibilities to configure views and some of them are
optional. The following examples show some of them in combination with
-features provided by the JSF- and Security-Module of DeltaSpike.</p>
-</div>
-<div class="paragraph">
-<p>The following example shows the minimal syntax for providing a config
-for a view (/page).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MyPage</span> <span class="directive">implements</span> ViewConfig
+features provided by the JSF- and Security-Module of DeltaSpike.
+
+The following example shows the minimal syntax for providing a config
+for a view (/page).
+
+[source,java]
+-----------------------------------------
+public class MyPage implements ViewConfig
{
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Since it is a class (and not an interface), it is automatically recognized as
+}
+-----------------------------------------
+
+Since it is a class (and not an interface), it is automatically recognized as
config for a page (and not a folder) and the default settings get
applied during bootstrapping. In case of JSF you can use it for
-navigation, for example, via action-methods.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> ViewConfig> toNextPage()
+navigation, for example, via action-methods.
+
+[source,java]
+-----------------------------------------------
+public Class<? extends ViewConfig> toNextPage()
{
- <span class="keyword">return</span> MyPage.class;
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This leads to a forward to <code>/myPage.xhtml</code>. Information like base-path,
+ return MyPage.class;
+}
+-----------------------------------------------
+
+This leads to a forward to `/myPage.xhtml`. Information like base-path,
file- (and folder-)name/s, file-extension, navigation mode,
-view-params,…​ can be customized with the corresponding
+view-params,... can be customized with the corresponding
(meta-data-)annotations. One of those annotations provided by the JSF
-module (which is optional) is <code>@View</code>. That means the following example
-leads to the same as the first one.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@View</span> <span class="comment">//optional</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyPage</span> <span class="directive">implements</span> ViewConfig
+module (which is optional) is `@View`. That means the following example
+leads to the same as the first one.
+
+[source,java]
+-----------------------------------------
+@View //optional
+public class MyPage implements ViewConfig
{
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>But it is also possible to reflect the folder structure via nesting of
-interfaces and classes. An example for it is:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span>
+}
+-----------------------------------------
+
+But it is also possible to reflect the folder structure via nesting of
+interfaces and classes. An example for it is:
+
+[source,java]
+------------------------------------------
+public interface Pages
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> ViewConfig { }
+ class Index implements ViewConfig { }
- <span class="type">interface</span> <span class="class">AdminArea</span> <span class="directive">extends</span> ViewConfig
+ interface AdminArea extends ViewConfig
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Admin { }
+ class Index implements Admin { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>In case of the JSF integration it leads to the following view-ids:
-/pages/index.xhtml /pages/adminArea/index.xhtml</p>
-</div>
-<div class="paragraph">
-<p>Like the optional <code>@View</code> for pages represented by the classes, it is
-possible to use the optional <code>@Folder</code> annotation for directories
-represented by the (nested) interfaces.</p>
-</div>
-<div class="paragraph">
-<p>Furthermore, it is possible to inherit meta-data along with the normal
-inheritance.</p>
-</div>
-<div class="paragraph">
-<p>In the following example <code>Pages.Admin.Index</code>, <code>Pages.Admin.Home</code> and
-<code>Pages.Admin.Statistics.Home</code> inherit the meta-data from <code>Pages.Admin</code>
+}
+------------------------------------------
+
+In case of the JSF integration it leads to the following view-ids:
+/pages/index.xhtml /pages/adminArea/index.xhtml
+
+Like the optional `@View` for pages represented by the classes, it is
+possible to use the optional `@Folder` annotation for directories
+represented by the (nested) interfaces.
+
+Furthermore, it is possible to inherit meta-data along with the normal
+inheritance.
+
+In the following example `Pages.Admin.Index`, `Pages.Admin.Home` and
+`Pages.Admin.Statistics.Home` inherit the meta-data from `Pages.Admin`
because they implement the interface whereas
-<code>Pages.Admin.Statistics.Index</code> does not. However, <code>Pages.Admin.Home</code>
-overrides <code>View#navigation</code>. During the bootstrapping process the
+`Pages.Admin.Statistics.Index` does not. However, `Pages.Admin.Home`
+overrides `View#navigation`. During the bootstrapping process the
meta-data gets merged and at runtime you only see the final result
-(which is cached).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span>
+(which is cached).
+
+[source,java]
+------------------------------------------------------
+public interface Pages
{
- <span class="annotation">@View</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">home</span><span class="delimiter">"</span></span>, extension = JSP)
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> ViewConfig { }
+ @View(name = "home", extension = JSP)
+ class Index implements ViewConfig { }
- <span class="annotation">@View</span>(navigation = REDIRECT, viewParams = INCLUDE)
- <span class="type">interface</span> <span class="class">Admin</span> <span class="directive">extends</span> ViewConfig
+ @View(navigation = REDIRECT, viewParams = INCLUDE)
+ interface Admin extends ViewConfig
{
- <span class="type">interface</span> <span class="class">Statistics</span>
+ interface Statistics
{
- <span class="annotation">@View</span> <span class="comment">//optional</span>
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> ViewConfig { }
+ @View //optional
+ class Index implements ViewConfig { }
- <span class="type">class</span> <span class="class">Home</span> <span class="directive">implements</span> Admin { }
+ class Home implements Admin { }
}
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Admin { }
+ class Index implements Admin { }
- <span class="annotation">@View</span>(navigation = FORWARD)
- <span class="type">class</span> <span class="class">Home</span> <span class="directive">implements</span> Admin { }
+ @View(navigation = FORWARD)
+ class Home implements Admin { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>In this case <code>Pages.Admin.Statistics</code> is just an interface to reflect
+}
+------------------------------------------------------
+
+In this case `Pages.Admin.Statistics` is just an interface to reflect
the folder structure. For sure it is also possible that it extends an
existing view-config interface and other folders and/or pages inherit
-its meta-data (like <code>Pages.Admin</code>).</p>
-</div>
-<div class="paragraph">
-<p>Furthermore, inheritance can be used to ensure navigation to the correct
+its meta-data (like `Pages.Admin`).
+
+Furthermore, inheritance can be used to ensure navigation to the correct
area in the application. In the following example the return type of the
action-method (and therefore the compiler of Java) ensures that the
-navigation target of this method is within the admin-area.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> Pages.Admin> toNextPage()
+navigation target of this method is within the admin-area.
+
+[source,java]
+------------------------------------------------
+public Class<? extends Pages.Admin> toNextPage()
{
- <span class="keyword">return</span> Pages.Admin.Index.class;
-}</code></pre>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_file_view_and_folder_folder_paths">File (@View) and Folder (@Folder) Paths</h4>
-<div class="paragraph">
-<p><code>@View</code> as well as <code>@Folder</code> are optional annotations. <code>@Folder</code> is only
+ return Pages.Admin.Index.class;
+}
+------------------------------------------------
+
+==== File (@View) and Folder (@Folder) Paths
+
+`@View` as well as `@Folder` are optional annotations. `@Folder` is only
needed for using a different folder-name or for marking folder configs
if they do not inherit from
-<code>org.apache.deltaspike.core.api.config.view.ViewConfig</code> <strong>nor</strong> have a
+`org.apache.deltaspike.core.api.config.view.ViewConfig` *nor* have a
view-config for a page nested into them (like Pages.Wizard1.Step1). If
it is not used explicitly, it gets added automatically (so you can query
the meta-data at runtime even in cases you haveis not placed the
-annotations explicitly). <code>@View</code> allows to customize a bit more and it
+annotations explicitly). `@View` allows to customize a bit more and it
also gets added automatically if it is not used explicitly. Whereas
-<code>@Folder</code> gets added to all nested interfaces (above a view-config class
-- like Pages and Pages.Wizard1), <code>@View</code> only gets added to classes
+`@Folder` gets added to all nested interfaces (above a view-config class
+- like Pages and Pages.Wizard1), `@View` only gets added to classes
which in-/directly inherit from
-<code>org.apache.deltaspike.core.api.config.view.ViewConfig</code> (like
-Pages.Wizard1.Step1).</p>
-</div>
-<div class="paragraph">
-<p>That means at runtime the following two configs lead to the same.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span>
+`org.apache.deltaspike.core.api.config.view.ViewConfig` (like
+Pages.Wizard1.Step1).
+
+That means at runtime the following two configs lead to the same.
+
+[source,java]
+---------------------------------------------
+public interface Pages
{
- <span class="type">interface</span> <span class="class">Wizard1</span>
+ interface Wizard1
{
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> ViewConfig { }
+ class Step1 implements ViewConfig { }
}
}
-<span class="comment">//leads to the same as</span>
+//leads to the same as
-<span class="annotation">@Folder</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span>
+@Folder
+public interface Pages
{
- <span class="annotation">@Folder</span>
- <span class="type">interface</span> <span class="class">Wizard1</span>
+ @Folder
+ interface Wizard1
{
- <span class="annotation">@View</span>
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> ViewConfig { }
+ @View
+ class Step1 implements ViewConfig { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The example above leads to the following paths:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>/pages/</p>
-</li>
-<li>
-<p>/pages/wizard1</p>
-</li>
-<li>
-<p>/pages/wizard1/step1.xhtml</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>To customize it you can use <code>@Folder#name</code>, <code>@View#basePath</code>,
-<code>@View#name</code> and <code>@View#extension</code> (or you register custom
-`NameBuilder`s inline or globally).</p>
-</div>
-<div class="sect4">
-<h5 id="__folder_name">@Folder#name</h5>
-<div class="paragraph">
-<p>The rules are pretty simple. You will get what you write. There are only
-two additional features:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>You do not have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)</p>
-</li>
-<li>
-<p>With "." at the beginning (e.g. "./") you can keep the path before.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The following example</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="type">interface</span> <span class="class">Pages</span>
+}
+---------------------------------------------
+
+The example above leads to the following paths:
+
+* /pages/
+* /pages/wizard1
+* /pages/wizard1/step1.xhtml
+
+To customize it you can use `@Folder#name`, `@View#basePath`,
+`@View#name` and `@View#extension` (or you register custom
+`NameBuilder`s inline or globally).
+
+===== @Folder#name
+
+The rules are pretty simple. You will get what you write. There are only
+two additional features:
+
+* You do not have to care about duplicated '/' (e.g. /folder1//folder2/step1.xhtml would get corrected auto. to /folder1/folder2/step1.xhtml)
+* With "." at the beginning (e.g. "./") you can keep the path before.
+
+The following example
+
+[source,java]
+---------------------------------------------------------------------------------
+interface Pages
{
- <span class="annotation">@Folder</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">/w1/</span><span class="delimiter">"</span></span>)
- <span class="type">interface</span> <span class="class">Wizard1</span>
+ @Folder(name = "/w1/")
+ interface Wizard1
{
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> ViewConfig { }
+ class Step1 implements ViewConfig { }
}
- <span class="annotation">@Folder</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">./w2/</span><span class="delimiter">"</span></span>)
- <span class="type">interface</span> <span class="class">Wizard2</span> <span class="directive">extends</span> ViewConfig
+ @Folder(name = "./w2/")
+ interface Wizard2 extends ViewConfig
{
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> Wizard2 { } <span class="comment">//ViewConfig is inherited indirectly</span>
+ class Step1 implements Wizard2 { } //ViewConfig is inherited indirectly
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>leads to the following paths:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>/pages/</p>
-</li>
-<li>
-<p>/w1/</p>
-</li>
-<li>
-<p>/w1/step1.xhtml</p>
-</li>
-<li>
-<p>/pages/w2/step1.xhtml</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect4">
-<h5 id="__view">@View</h5>
-<div class="paragraph">
-<p>The same naming rules apply to <code>@View#basePath</code>. However, it is only
-valid to be used at view-config nodes which represent pages (→ classes
-and not interfaces). On interfaces always use <code>@Folder</code>
-(<code>@View#basePath</code> will get ignored there).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="type">interface</span> <span class="class">Pages</span>
+}
+---------------------------------------------------------------------------------
+
+leads to the following paths:
+
+* /pages/
+* /w1/
+* /w1/step1.xhtml
+* /pages/w2/step1.xhtml
+
+===== @View
+
+The same naming rules apply to `@View#basePath`. However, it is only
+valid to be used at view-config nodes which represent pages (-> classes
+and not interfaces). On interfaces always use `@Folder`
+(`@View#basePath` will get ignored there).
+
+[source,java]
+---------------------------------------------
+interface Pages
{
- <span class="type">interface</span> <span class="class">Wizard1</span>
+ interface Wizard1
{
- <span class="annotation">@View</span> <span class="comment">//optional</span>
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> ViewConfig { }
+ @View //optional
+ class Step1 implements ViewConfig { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step2</span> <span class="directive">implements</span> ViewConfig { }
+ @View(basePath = "/")
+ class Step2 implements ViewConfig { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">./</span><span class="delimiter">"</span></span>) <span class="comment">//or just "."</span>
- <span class="type">class</span> <span class="class">Step3</span> <span class="directive">implements</span> ViewConfig { }
+ @View(basePath = "./") //or just "."
+ class Step3 implements ViewConfig { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">/w1/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step4</span> <span class="directive">implements</span> ViewConfig { }
+ @View(basePath = "/w1/")
+ class Step4 implements ViewConfig { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">./w1/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step5</span> <span class="directive">implements</span> ViewConfig { }
+ @View(basePath = "./w1/")
+ class Step5 implements ViewConfig { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>leads to the following paths:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>/pages</p>
-</li>
-<li>
-<p>/pages/wizard1/</p>
-</li>
-<li>
-<p>/pages/wizard1/step1.xhtml</p>
-</li>
-<li>
-<p>/step2.xhtml</p>
-</li>
-<li>
-<p>/pages/wizard1/step3.xhtml</p>
-</li>
-<li>
-<p>/w1/step4.xhtml</p>
-</li>
-<li>
-<p>/pages/wizard/w1/step5.xhtml</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>and depending on additional meta-data you would like to inherit (e.g.
-<code>@View(navigation = REDIRECT)</code>), you can also use:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@View</span>(navigation = REDIRECT)
-<span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
+}
+---------------------------------------------
+
+leads to the following paths:
+
+* /pages
+* /pages/wizard1/
+* /pages/wizard1/step1.xhtml
+* /step2.xhtml
+* /pages/wizard1/step3.xhtml
+* /w1/step4.xhtml
+* /pages/wizard/w1/step5.xhtml
+
+and depending on additional meta-data you would like to inherit (e.g.
+`@View(navigation = REDIRECT)`), you can also use:
+
+[source,java]
+------------------------------------------
+@View(navigation = REDIRECT)
+interface Pages extends ViewConfig
{
- <span class="type">interface</span> <span class="class">Wizard1</span> <span class="directive">extends</span> Pages
+ interface Wizard1 extends Pages
{
- <span class="annotation">@View</span>
- <span class="type">class</span> <span class="class">Step1</span> <span class="directive">implements</span> Wizard1 { }
+ @View
+ class Step1 implements Wizard1 { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step2</span> <span class="directive">implements</span> Wizard1 { }
+ @View(basePath = "/")
+ class Step2 implements Wizard1 { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">./</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step3</span> <span class="directive">implements</span> Wizard1 { }
+ @View(basePath = "./")
+ class Step3 implements Wizard1 { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">/w1/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step4</span> <span class="directive">implements</span> Wizard1 { }
+ @View(basePath = "/w1/")
+ class Step4 implements Wizard1 { }
- <span class="annotation">@View</span>(basePath = <span class="string"><span class="delimiter">"</span><span class="content">./w1/</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Step5</span> <span class="directive">implements</span> Wizard1 { }
+ @View(basePath = "./w1/")
+ class Step5 implements Wizard1 { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>It leads to the same paths, but in addition <code>@View#navigation</code> gets
-inherited along the inheritance path.</p>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_navigation_parameters">Navigation Parameters</h4>
-<div class="paragraph">
-<p>Since the view-config is static, an approach to add parameters is
+}
+------------------------------------------
+
+It leads to the same paths, but in addition `@View#navigation` gets
+inherited along the inheritance path.
+
+==== Navigation Parameters
+
+Since the view-config is static, an approach to add parameters is
needed. The following part shows different possibilities to add
parameters which end up in the final URL after '?' (in case of the
integration with JSF). It is not needed to add all (types of) parameters
that way. Some get added automatically based on special meta-data (e.g.
-<code>@View#navigation</code> and <code>@View#viewParams</code>). Instead of adding
-<code>"faces-redirect=true"</code> manually it is done for you as soon as you are
-using <code>@View(navigation = REDIRECT)</code>. The same goes for
-<code>"includeViewParams=true"</code> and <code>@View(viewParams = INCLUDE)</code>.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_static_configuration_via_navigationparameter">Static Configuration via @NavigationParameter</h4>
-<div class="paragraph">
-<p>In some cases, it is needed to add an information in any case. So you can
-annotate the view-config class with <code>@NavigationParameter</code>. Supported
-values are static strings or EL-expressions.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
-{
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param1</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">staticValue1</span><span class="delimiter">"</span></span>)
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Pages { }
-
- <span class="annotation">@NavigationParameter</span>.List({
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param1</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">staticValue1</span><span class="delimiter">"</span></span>),
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param2</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">#{myBean.property1}</span><span class="delimiter">"</span></span>)
+`@View#navigation` and `@View#viewParams`). Instead of adding
+`"faces-redirect=true"` manually it is done for you as soon as you are
+using `@View(navigation = REDIRECT)`. The same goes for
+`"includeViewParams=true"` and `@View(viewParams = INCLUDE)`.
+
+==== Static Configuration via @NavigationParameter
+
+In some cases, it is needed to add an information in any case. So you can
+annotate the view-config class with `@NavigationParameter`. Supported
+values are static strings or EL-expressions.
+
+[source,java]
+---------------------------------------------------------------------------
+public interface Pages extends ViewConfig
+{
+ @NavigationParameter(key = "param1", value = "staticValue1")
+ class Index implements Pages { }
+
+ @NavigationParameter.List({
+ @NavigationParameter(key = "param1", value = "staticValue1"),
+ @NavigationParameter(key = "param2", value = "#{myBean.property1}")
})
- <span class="type">class</span> <span class="class">Overview</span> <span class="directive">implements</span> Pages { }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Instead of using parameters in any case, it is also possible to configure
-them statically for particular methods:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Model</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">PageBean</span>
+ class Overview implements Pages { }
+}
+---------------------------------------------------------------------------
+
+Instead of using parameters in any case, it is also possible to configure
+them statically for particular methods:
+
+[source,java]
+-----------------------------------------------------------------------
+@Model
+public class PageBean
{
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param2</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">#{myBean.property1}</span><span class="delimiter">"</span></span>)
- <span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> ViewConfig> actionMethod1()
+ @NavigationParameter(key = "param2", value = "#{myBean.property1}")
+ public Class<? extends ViewConfig> actionMethod1()
{
- <span class="keyword">return</span> SimplePageConfig.class;
+ return SimplePageConfig.class;
}
- <span class="annotation">@NavigationParameter</span>.List({
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param1</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">staticValue1</span><span class="delimiter">"</span></span>),
- <span class="annotation">@NavigationParameter</span>(key = <span class="string"><span class="delimiter">"</span><span class="content">param2</span><span class="delimiter">"</span></span>, value = <span class="string"><span class="delimiter">"</span><span class="content">staticValue2</span><span class="delimiter">"</span></span>)
+ @NavigationParameter.List({
+ @NavigationParameter(key = "param1", value = "staticValue1"),
+ @NavigationParameter(key = "param2", value = "staticValue2")
})
- <span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> ViewConfig> actionMethod2()
+ public Class<? extends ViewConfig> actionMethod2()
{
- <span class="keyword">return</span> SimplePageConfig.class;
+ return SimplePageConfig.class;
}
-}</code></pre>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_dynamic_configuration_via_navigationparametercontext">Dynamic Configuration via NavigationParameterContext</h5>
-<div class="paragraph">
-<p>Instead of using parameters in a static fashion (as shown above), it is
+}
+-----------------------------------------------------------------------
+
+===== Dynamic Configuration via NavigationParameterContext
+
+Instead of using parameters in a static fashion (as shown above), it is
also possible to add them dynamically (e.g. in case of special
-conditions).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Named</span>
-<span class="annotation">@SessionScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">PageBean</span>
+conditions).
+
+[source,java]
+--------------------------------------------------------------------------------------
+@Named
+@SessionScoped
+public class PageBean
{
- <span class="directive">private</span> <span class="type">int</span> currentValue = -<span class="integer">10</span>;
+ private int currentValue = -10;
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> NavigationParameterContext navigationParameterContext;
+ @Inject
+ private NavigationParameterContext navigationParameterContext;
- <span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> ViewConfig> actionMethod()
+ public Class<? extends ViewConfig> actionMethod()
{
currentValue++;
- <span class="keyword">if</span> (currentValue >= <span class="integer">0</span>)
+ if (currentValue >= 0)
{
- <span class="local-variable">this</span>.navigationParameterContext.addPageParameter(<span class="string"><span class="delimiter">"</span><span class="content">cv</span><span class="delimiter">"</span></span>, <span class="local-variable">this</span>.currentValue);
+ this.navigationParameterContext.addPageParameter("cv", this.currentValue);
}
- <span class="keyword">return</span> SimplePageConfig.class;
+ return SimplePageConfig.class;
}
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_security_integration_via_secured">Security Integration via @Secured</h4>
-<div class="paragraph">
-<p>This annotation is a custom view-meta-data provided by the
+}
+--------------------------------------------------------------------------------------
+
+==== Security Integration via @Secured
+
+This annotation is a custom view-meta-data provided by the
Security-module which allows to integrate third-party frameworks (or
custom approaches) to secure pages as well as whole folders. You can
annotate specific parts or a marker-interface.
-<code>CustomAccessDecisionVoter</code> used in the following example can be any
+`CustomAccessDecisionVoter` used in the following example can be any
implementation of
-<code>org.apache.deltaspike.security.api.authorization.AccessDecisionVoter</code>
+`org.apache.deltaspike.security.api.authorization.AccessDecisionVoter`
and needs to be a standard CDI bean which means you can use
dependecy-injection to trigger any kind of security check. All parts
-which inherit from <code>SecuredPages</code> (<code>Pages.Admin</code>, <code>Pages.Admin.Index</code>
-and <code>Pages.Admin.Home</code>) are protected by <code>CustomAccessDecisionVoter</code>.</p>
-</div>
-<div class="paragraph">
-<p>(It is easy to check this hierarchy in a modern Java-IDE. Only for
+which inherit from `SecuredPages` (`Pages.Admin`, `Pages.Admin.Index`
+and `Pages.Admin.Home`) are protected by `CustomAccessDecisionVoter`.
+
+(It is easy to check this hierarchy in a modern Java-IDE. Only for
displaying the final meta-data for every node in the IDE a special
-plug-in would be needed.)</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Secured</span>(CustomAccessDecisionVoter.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SecuredPages</span> {}
+plug-in would be needed.)
-<span class="annotation">@View</span>(navigation = REDIRECT)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
+[source,java]
+-----------------------------------------------
+@Secured(CustomAccessDecisionVoter.class)
+public interface SecuredPages {}
+
+@View(navigation = REDIRECT)
+public interface Pages extends ViewConfig
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Pages { }
+ class Index implements Pages { }
- <span class="type">interface</span> <span class="class">Admin</span> <span class="directive">extends</span> Pages, SecuredPages
+ interface Admin extends Pages, SecuredPages
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Admin { }
+ class Index implements Admin { }
- <span class="annotation">@View</span>(navigation = FORWARD)
- <span class="type">class</span> <span class="class">Home</span> <span class="directive">implements</span> Admin { }
+ @View(navigation = FORWARD)
+ class Home implements Admin { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>For sure it is also possible to use it without a special interface. In
-this case you would need:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@View</span>(navigation = REDIRECT)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
+}
+-----------------------------------------------
+
+For sure it is also possible to use it without a special interface. In
+this case you would need:
+
+[source,java]
+---------------------------------------------
+@View(navigation = REDIRECT)
+public interface Pages extends ViewConfig
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Pages { }
+ class Index implements Pages { }
- <span class="annotation">@Secured</span>(CustomAccessDecisionVoter.class)
- <span class="type">interface</span> <span class="class">Admin</span> <span class="directive">extends</span> Pages
+ @Secured(CustomAccessDecisionVoter.class)
+ interface Admin extends Pages
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Admin { }
+ class Index implements Admin { }
- <span class="annotation">@View</span>(navigation = FORWARD)
- <span class="type">class</span> <span class="class">Home</span> <span class="directive">implements</span> Admin { }
+ @View(navigation = FORWARD)
+ class Home implements Admin { }
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>or:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@View</span>(navigation = REDIRECT)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
+}
+---------------------------------------------
+
+or:
+
+[source,java]
+-------------------------------------------------
+@View(navigation = REDIRECT)
+public interface Pages extends ViewConfig
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Pages { }
+ class Index implements Pages { }
- <span class="type">interface</span> <span class="class">Admin</span> <span class="directive">extends</span> Pages
+ interface Admin extends Pages
{
- <span class="annotation">@Secured</span>(CustomAccessDecisionVoter.class)
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Admin { }
+ @Secured(CustomAccessDecisionVoter.class)
+ class Index implements Admin { }
- <span class="annotation">@Secured</span>(CustomAccessDecisionVoter.class)
- <span class="annotation">@View</span>(navigation = FORWARD)
- <span class="type">class</span> <span class="class">Home</span> <span class="directive">implements</span> Admin { }
+ @Secured(CustomAccessDecisionVoter.class)
+ @View(navigation = FORWARD)
+ class Home implements Admin { }
}
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_view_controller_callbacks_via_viewcontrollerref">View-Controller Callbacks via @ViewControllerRef</h4>
-<div class="paragraph">
-<p>This annotation is a custom view-meta-data provided by the JSF-module
+}
+-------------------------------------------------
+
+
+==== View-Controller Callbacks via @ViewControllerRef
+
+This annotation is a custom view-meta-data provided by the JSF-module
which allows to configure beans which should act as view-controllers.
-That means they can use view-controller callbacks like <code>@InitView</code>,
-<code>@PreViewAction</code>, <code>@PreRenderView</code> and <code>@PostRenderView</code>. The following
-example shows the usage of <code>@PreRenderView</code>.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//@View //optional</span>
-<span class="annotation">@ViewControllerRef</span>(MyPageController.class)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyPage</span> <span class="directive">implements</span> ViewConfig
+That means they can use view-controller callbacks like `@InitView`,
+`@PreViewAction`, `@PreRenderView` and `@PostRenderView`. The following
+example shows the usage of `@PreRenderView`.
+
+[source,java]
+------------------------------------------
+//@View //optional
+@ViewControllerRef(MyPageController.class)
+public class MyPage implements ViewConfig
{
}
-<span class="annotation">@Model</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyPageController</span>
+@Model
+public class MyPageController
{
- <span class="annotation">@PreRenderView</span>
- <span class="directive">protected</span> <span class="type">void</span> load()
+ @PreRenderView
+ protected void load()
{
- <span class="comment">//...</span>
+ //...
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>From DeltaSpike 0.7, it is possible to observe exceptions thrown by a
+}
+------------------------------------------
+
+From DeltaSpike 0.7, it is possible to observe exceptions thrown by a
@PreRenderView callback and use your configured Default-Error-View to
-display the exception.</p>
-</div>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ExceptionHandler</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">ErrorViewAwareExceptionHandler</span> {
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> ViewConfigResolver viewConfigResolver;
+display the exception.
- <span class="directive">public</span> <span class="type">void</span> onIllegalStateException(<span class="annotation">@Handles</span> ExceptionEvent<<span class="exception">IllegalStateException</span>> e)
+.Example
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+@ExceptionHandler
+public class ErrorViewAwareExceptionHandler {
+ @Inject
+ private ViewConfigResolver viewConfigResolver;
+
+ public void onIllegalStateException(@Handles ExceptionEvent<IllegalStateException> e)
{
FacesContext facesContext = FacesContext.getCurrentInstance();
- <span class="predefined-type">String</span> viewId = viewConfigResolver.getDefaultErrorViewConfigDescriptor().getViewId();
+ String viewId = viewConfigResolver.getDefaultErrorViewConfigDescriptor().getViewId();
UIViewRoot viewRoot = facesContext.getApplication().getViewHandler().createView(facesContext, viewId);
facesContext.setViewRoot(viewRoot);
- <span class="comment">//... - e.g.: store the exception in a page-bean for the default-error-view</span>
+ //... - e.g.: store the exception in a page-bean for the default-error-view
}
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_referencing_views_via_viewref">Referencing Views via @ViewRef</h4>
-<div class="paragraph">
-<p>With <code>@ViewControllerRef#value</code> you can annotate a view-config class to
-bind (/reference) a controller to it. <code>@ViewRef#config</code> allows the same
+}
+--------------------------------------------------------------------------------------------------------------
+
+==== Referencing Views via @ViewRef
+
+With `@ViewControllerRef#value` you can annotate a view-config class to
+bind (/reference) a controller to it. `@ViewRef#config` allows the same
in the other direction. Use an existing view-config to reference one or
-many view/s.</p>
-</div>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> <span class="directive">extends</span> ViewConfig
+many view/s.
+
+.Example
+[source,java]
+----------------------------------------------------
+public interface Pages extends ViewConfig
{
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> Pages { }
+ class Index implements Pages { }
}
-<span class="annotation">@ViewRef</span>(Pages.Index.class)
-<span class="comment">//...</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">IndexController</span> <span class="directive">implements</span> <span class="predefined-type">Serializable</span>
+@ViewRef(Pages.Index.class)
+//...
+public class IndexController implements Serializable
{
- <span class="annotation">@PreRenderView</span>
- <span class="directive">protected</span> <span class="type">void</span> preRenderView()
+ @PreRenderView
+ protected void preRenderView()
{
- <span class="comment">//...</span>
+ //...
}
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The above example leads to the invocation of the pre-render-view logic before
+ //...
+}
+----------------------------------------------------
+
+The above example leads to the invocation of the pre-render-view logic before
/pages/page1.xhtml gets rendered (and it will not be called for other
-pages).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_using_the_optional_viewnavigationhandler">Using the (Optional) ViewNavigationHandler</h4>
-<div class="paragraph">
-<p>With JSF you typically navigate with the action-method bound to a
+pages).
+
+==== Using the (Optional) ViewNavigationHandler
+
+With JSF you typically navigate with the action-method bound to a
command-component. However, also JSF supports manual navigation via
-<code>javax.faces.application.NavigationHandler</code>. With
-<code>ViewNavigationHandler</code> DeltaSpike provides an equivalent optimized for
+`javax.faces.application.NavigationHandler`. With
+`ViewNavigationHandler` DeltaSpike provides an equivalent optimized for
type-safe view-configs which is easier to use (and can be used also for
-other (supported) view technology).</p>
-</div>
-<div class="listingblock">
-<div class="title">Simple Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> {
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> ViewConfig { }
+other (supported) view technology).
+
+.Simple Example
+[source,java]
+-----------------------------------------------------------------
+public interface Pages {
+ class Index implements ViewConfig { }
}
-<span class="annotation">@Model</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">AnyController</span>
+@Model
+public class AnyController
{
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> ViewNavigationHandler viewNavigationHandler;
+ @Inject
+ private ViewNavigationHandler viewNavigationHandler;
- <span class="directive">public</span> <span class="type">void</span> anyMethod()
+ public void anyMethod()
{
- <span class="comment">//navigates to /pages/index.xhtml</span>
- <span class="local-variable">this</span>.viewNavigationHandler.navigateTo(Pages.Index.class);
+ //navigates to /pages/index.xhtml
+ this.viewNavigationHandler.navigateTo(Pages.Index.class);
}
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Also in this case (optional) meta-data will be used for the navigation
-process, since <code>ViewNavigationHandler</code> just delegates to the active
-navigation-handler (of JSF).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_configuring_a_default_error_view">Configuring a Default Error-View</h4>
-<div class="paragraph">
-<p>It is possible to mark one view-config class as default error-view. That
+}
+-----------------------------------------------------------------
+
+Also in this case (optional) meta-data will be used for the navigation
+process, since `ViewNavigationHandler` just delegates to the active
+navigation-handler (of JSF).
+
+==== Configuring a Default Error-View
+
+It is possible to mark one view-config class as default error-view. That
means in case of errors it will be used as navigation target
automatically. Furthermore, it is also possible to use it in your code
-instead of hardcoding your error-view across the whole application.</p>
-</div>
-<div class="paragraph">
-<p>In case of</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">Pages</span> {
- <span class="type">class</span> <span class="class">Index</span> <span class="directive">implements</span> ViewConfig { }
+instead of hardcoding your error-view across the whole application.
- <span class="type">class</span> <span class="class">CustomErrorPage</span> <span class="directive">extends</span> DefaultErrorView { }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>it is possible to navigate with <code>DefaultErrorView.class</code> instead of
-hardcoding it to <code>Pages.CustomErrorPage.class</code>.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Model</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">PageController</span>
+In case of
+
+[source,java]
+------------------------------------------------------
+public interface Pages {
+ class Index implements ViewConfig { }
+
+ class CustomErrorPage extends DefaultErrorView { }
+}
+------------------------------------------------------
+
+it is possible to navigate with `DefaultErrorView.class` instead of
+hardcoding it to `Pages.CustomErrorPage.class`.
+
+[source,java]
+-------------------------------------------------------------------------
+@Model
+public class PageController
{
- <span class="directive">public</span> <span class="predefined-type">Class</span><? <span class="directive">extends</span> ViewConfig> actionWithoutError()
+ public Class<? extends ViewConfig> actionWithoutError()
{
- <span class="keyword">return</span> Pages.Index.class;
[... 1779 lines stripped ...]