[Myfaces Wiki] Update of "Drafts/Site/Trinidad" by BartKummel

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.

The "Drafts/Site/Trinidad" page has been changed by BartKummel.
http://wiki.apache.org/myfaces/Drafts/Site/Trinidad?action=diff&rev1=2&rev2=3

--------------------------------------------------

   * It has a dialog framework, making it easy to create pop-up dialogs.
   * “Partial page rendering”, client-side validation and conversion, and other AJAX functionality are embedded in most components and is easy to add where needed. (This is especially important for JSF 1.2 users.)
  
+ == Getting started with Trinidad ==
+ 
+ As with other component libraries, the first thing to do in order to get started with Trinidad is to [[http://myfaces.apache.org/trinidad/download.html|download]] it. Note that Trinidad comes in
+ three versions—a JSF 1.1 version, a JSF 1.2 and a JSF 2.0 version. The JSF version is reflected in the version number of Trinidad. This means that versions 1.0.10 and 1.2.10 are basically the same versions. The only difference is that 1.0.10 is the version for JSF 1.1, whereas 1.2.10 is the version for JSF 1.2. The downloaded archive contains, among other things, two JARs that we’ll have to add to our project—{{{trinidad-api-x.y.z.jar}}} and {{{trinidad-impl-x.y.z.jar}}}. Of course, we don’t have to add the JARs manually if we use Maven.
+ 
+ === Configuring the web.xml file ===
+ Before we can use Trinidad, we’ll have to add some settings to our {{{web.xml}}} file. First, we have to add a filter configuration for Trinidad, which should look like this:
+ {{{
+     <filter>
+         <filter-name>trinidad</filter-name>
+         <filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
+     </filter>
+     <filter-mapping>
+         <filter-name>trinidad</filter-name>
+         <servlet-name>Faces Servlet</servlet-name>
+     </filter-mapping>
+ }}}
+ Note that the filter is mapped to the standard Faces Servlet, which is named {{{Faces Servlet}}} in this example. This name might be different in your own project. 
+ 
+ We also have to set up a resource Servlet for Trinidad:
+ {{{
+     <servlet>
+         <servlet-name>resources</servlet-name>
+         <servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
+     </servlet>
+     <servlet-mapping>
+         <servlet-name>resources</servlet-name>
+         <url-pattern>/adf/*</url-pattern>
+     </servlet-mapping>
+ }}}
+ The resource Servlet is mapped to the {{{/adf/*}}} URL. This is a remainder from the days before Oracle donated its ADF Faces components to the MyFaces project. The URL cannot be changed, as some parts of Trinidad expect to be able to access CSS and JavaScript files via this URL. 
+ 
+ In order to let Trinidad play nice with Facelets, we have to add one extra piece of configuration to our {{{web.xml}}} file:
+ {{{
+     <context-param>
+         <param-name>org.apache.myfaces.trinidad.ALTERNATE_VIEW_HANDLER</param-name>
+         <param-value>com.sun.facelets.FaceletViewHandler</param-value>
+     </context-param>
+ }}}
+ This makes the Trinidad components aware of the fact that Facelets is being used instead of JSP as the view technology. 
+ 
+ === Configuring the faces-config.xml file ===
+ 
+ In the {{{faces-config.xml file}}}, we have to set the default render kit for Trinidad. This can be done with just a single element:
+ {{{
+     <default-render-kit-id>org.apache.myfaces.trinidad.core</default-render-kit-id>
+ }}}
+ We also have to make sure that we do not set the Facelets view handler in the {{{faces-config.xml}}} file. If you ever get a {{{java.lang.IllegalStateException}}} stating "No RenderingContext" from the Trinidad renderer, then it is probably because the Facelets view handler is defined in the {{{faces-config.xml}}} file.
+ 
+ === Configuring the trinidad-config.xml file ===
+ 
+ Trinidad also introduces another configuration file—{{{trinidad-config.xml}}}. As the name implies, this file can be used to adjust several Trinidad-specific settings. This file is optional, which means that we don’t have to create it if Trinidad’s default values are fine for our project. A basic {{{trinidad-config.xml}}} file looks like this:
+ {{{
+ <?xml version="1.0"?>
+ <trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
+     <debug-output>true</debug-output>
+     <skin-family>minimal</skin-family>
+ </trinidad-config>
+ }}}
+ Setting {{{debug-output}}} to {{{true}}} will cause Trinidad to add some helpful comments to the generated pages, and format the XHTML nicely. Of course, this comes at the expense of performance, so you should disable this setting in production environments. The {{{skin-family}}} setting can be used to select an alternative skin for Trinidad. 
+