Modified: myfaces/site/publish/tobago/faq.html URL: http://svn.apache.org/viewvc/myfaces/site/publish/tobago/faq.html?rev=1807710&r1=1807709&r2=1807710&view=diff ============================================================================== --- myfaces/site/publish/tobago/faq.html (original) +++ myfaces/site/publish/tobago/faq.html Fri Sep 8 11:03:38 2017 @@ -1,432 +1,438 @@ - Tobago – Frequently Asked Questions - - - - + Tobago – Frequently Asked Questions + + + +
-
-
-
-
Tobago
-
- -
-
-
-
-
-
Documentation
-
- -
-
-
-
-
-
Project Documentation
-
- -
-
-
-
-
-
Foundation
-
- -
-
-
-
- - Built by Maven - -
-
- - ApacheCon - -
-
-
-
-
- -
-
Where can I find documentation or HowTos for using Tobago?
-
- -

- Please, see -

- -

- Tobago Demo. -

- -

- There is also a demo for -

- -

- - Tobago 2.0 +

+ +
+
+
Documentation
+
+ +
+
+
+
+
+
Project Documentation
+
+ +
+
+
+
+
+
Foundation
+
+ +
+
+
+
+ + Built by Maven -

- -

[top]

-
-
-
Where can I find a "Hello World" example and a list of required - jars? -
-
- -

- Please look at - - tobago-example-blank or download the myfaces-tobago-example from the - nightly - builds directory. -

- -

[top]

-
-
-
Does Tobago run with the Sun reference implementation (RI)?
-
- -

Tobago runs with Sun RI and with MyFaces. - Please take a look at the Compatibility List.

- -

[top]

-
-
-
Does Tobago supports Facelets?
-
+
+
+ + ApacheCon + +
+
+
+
+
+ +
+
Where can I find documentation or HowTos for using Tobago?
+
+ +

+ Please, see +

+ +

+ Tobago Demo. +

+ +

+ There is also a demo for +

+ +

+ + Tobago 2.0 + +

+ +

[top]

+
+
+
Where can I find a "Hello World" example and a list of required + jars? +
+
+ +

+ Please look at + + tobago-example-blank or download the myfaces-tobago-example from the + nightly + builds directory. +

+ +

[top]

+
+
+
Does Tobago run with the Sun reference implementation (RI)?
+
+ +

Tobago runs with Sun RI and with MyFaces. + Please take a look at the Compatibility List.

+ +

[top]

+
+
+
Does Tobago supports Facelets?
+
-

Tobago 2.0.x:

+

Tobago 2.0.x:

-

Tobago supports the JSF 2.0 Facelets. - Note: Please add following context param in your web.xml

+

Tobago supports the JSF 2.0 Facelets. + Note: Please add following context param in your web.xml

-
+
 <context-param>
   <param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
   <param-value>true</param-value>
 </context-param>
-
+
-

Tobago 1.0.x and 1.5.x:

+

Tobago 1.0.x and 1.5.x:

-

Tobago supports Facelets with the tobago-facelets.jar. - Note: Please add following context param in your web.xml

+

Tobago supports Facelets with the tobago-facelets.jar. + Note: Please add following context param in your web.xml

-
+
 <context-param>
   <param-name>facelets.SKIP_COMMENTS</param-name>
   <param-value>true</param-value>
 </context-param>
-
+
-

[top]

-
-
-
Can I mix Tobago and MyFaces extensions in the same web application? -
-
- -

JSF only supports one renderkit (renderkitId) per page (f:view). - Because Tobago has it's own renderkitId you cannot use any non-Tobago - components that need a renderer. -

- -

[top]

-
-
-
How do I use GridLayout in Tobago?
-
+

[top]

+
+
+
Can I mix Tobago and MyFaces extensions in the same web + application? +
+
+ +

JSF only supports one renderkit (renderkitId) per page (f:view). + Because Tobago has it's own renderkitId you cannot use any non-Tobago + components that need a renderer. +

+ +

[top]

+
+
+
How do I use GridLayout in Tobago?
+
-
+
 <tc:gridLayout rows="fixed;100px;1*;2*" />
-
+
-

- The attribute 'fixed' means a theme dependent height of one row (i.e. in Speyside - a row is typically 20px high.) In a 'fixed' row all one height unit high elements find their place - (like buttons, input fields, one row of text...).

- Using px heights is at your own risk, but it is sometimes needed for elements like box or sheet. -

- -

- Alternatively you can give elements a proportion with the * notation.

- For example rows="1*;2*" gives the first row 1/3 of the available vertical space and the - second row 2/3. This works fine for columns, too. -

- -

- You can group elements with a tc:panel element. Such a panel is interpreted as one - element regarding layout. The panel itself can have its own layout for multiple elements inside - the panel. -

- -

[top]

-
-
-
How do I configure file upload in Tobago?
-
- -

Till Tobago 2.0 and lower, you have two options.

- -

Add a TobagoMultipartFormdataFilter to your web.xml. - JavaDoc - Description -

- -

Add the tobago-fileupload.jar to your project. - The tobago-fileupload.jar contains a FacesContextFactory that wraps the - multipart-formdata request inside the FacesContext. - JavaDoc - Description -

- -

Starting with Tobago 3.0 the Servlet API 3.0 will be used. Some more information about the - usage you will find in Jira - and in the Tobago - Demo 3.0. - There is also a migration - guide available. -

- -

[top]

-
-
-
Do I need a form tag in a normal Tobago page?
-
- -

The page tag already acts like a form tag. You only need a explicit form tag for partial validation of your - data. - Please look at the forms example in the - Tobago - demo -

- -

[top]

-
-
-
Which web browsers are currently supported by Tobago?
-
- -

Please take a look at the Compatibility List.

- -

[top]

-
-
-
How do I create my own theme?
-
- -

- You have to define a new name for the theme in the META-INF/tobago-config.xml. - Choose a fallback theme in the tobago-config.xml. - Put the modified resources under the resource-path + theme-name. - An example for this is the charlotteville theme. (TODO more details resource handling) -

- -

- Example layout of a theme jar: -

+

+ The attribute 'fixed' means a theme dependent height of one row (i.e. in Speyside + a row is typically 20px high.) In a 'fixed' row all one height unit high elements find their + place + (like buttons, input fields, one row of text...).

+ Using px heights is at your own risk, but it is sometimes needed for elements like box or sheet. +

+ +

+ Alternatively you can give elements a proportion with the * notation.

+ For example rows="1*;2*" gives the first row 1/3 of the available vertical space and + the + second row 2/3. This works fine for columns, too. +

+ +

+ You can group elements with a tc:panel element. Such a panel is interpreted as one + element regarding layout. The panel itself can have its own layout for multiple elements inside + the panel. +

+ +

[top]

+
+
+
How do I configure file upload in Tobago?
+
+ +

Till Tobago 2.0 and lower, you have two options.

+ +

Add a TobagoMultipartFormdataFilter to your web.xml. + JavaDoc + Description +

+ +

Add the tobago-fileupload.jar to your project. + The tobago-fileupload.jar contains a FacesContextFactory that wraps the + multipart-formdata request inside the FacesContext. + JavaDoc + Description +

+ +

Starting with Tobago 3.0 the Servlet API 3.0 will be used. Some more information about the + usage you will find in Jira + and in the Tobago + Demo 3.0. + There is also a migration + guide available. +

+ +

[top]

+
+
+
Do I need a form tag in a normal Tobago page?
+
+ +

The page tag already acts like a form tag. You only need a explicit form tag for partial + validation of your data. + Please look at the forms example in the + Tobago + demo +

+ +

[top]

+
+
+
Which web browsers are currently supported by Tobago?
+
+ +

Please take a look at the Compatibility List.

+ +

[top]

+
+
+
How do I create my own theme?
+
+ +

+ You have to define a new name for the theme in the META-INF/tobago-config.xml. + Choose a fallback theme in the tobago-config.xml. + Put the modified resources under the resource-path + theme-name. + An example for this is the charlotteville theme. (TODO more details resource handling) +

+ +

+ Example layout of a theme jar: +

-
+
 /META-INF/tobago-config.xml
 (resource-path/html/theme-name)
@@ -434,95 +440,97 @@
 /org/apache/myfaces/tobago/renderkit/html/xxxxx/standard/style/tobago-menu.css (menu styles)
 /org/apache/myfaces/tobago/renderkit/html/xxxxx/standard/style/tobago-sheet.css (sheet styles)
 /org/apache/myfaces/tobago/renderkit/html/xxxxx/msie/style/tobago.css (different styles for msie)
-
+
- Property and resource loading and renderer loading is done in the following order + Property and resource loading and renderer loading is done in the following order -
+
 resource-path/content-type/theme/client/[tag(for renderer)|property|style|script|image]_locale
     .(class|property|property.xml|css|js|gif|png...]
-
- - for example OutRenderer

+
- org.apache.myfaces.tobago.renderkit.html.scarborough.standard.tag.OutRenderer

+ for example OutRenderer

- OutRenderer is getRendererType() + "Renderer"

+ org.apache.myfaces.tobago.renderkit.html.scarborough.standard.tag.OutRenderer

- The locale handling is handled like the Properties Class.

- - You have not define everything because the ResourceManager is asking the fallback theme for missing - resources

- - The fallback theme of charlotteville is speyside.

- The fallback theme of speyside is scarborough.

- The fallback theme of scarborough is standard

- - The resource manager looks in the case of the charlotteville theme in

- charlotteville -> speyside -> scarborough -> standard - -

- Please look at - - tobago-example-theme - -

+ OutRenderer is getRendererType() + "Renderer"

-

[top]

-
-
-
How do I use and extend the markup attribute?
-
- -

UIBox, UIInput and UIOutput support custom markup with the markup attribute. - The supported markup is defined in the tobago-config.xml. - The standard markup is defined in tobago-config.xml of the tobago-theme-standard. - This can be extended in your own theme. - The markup attribute is rendered as a CSS class tobago-[renderer-name.toLowerCase]-markup-[markup]. - For an example please look at the markup number and the CSS class tobago-in-markup-number for UIIn - in - theme/scarborough/src/main/resources/org/apache/myfaces/tobago/renderkit/html/scarborough/standard/style/tobago.css -

- -

[top]

-
-
-
In which containers was Tobago tested?
-
- -

Please take a look at the Compatibility List. - Feel free to post your own experiences.

- -

[top]

-
-
-
Can Tobago replace Tiles? Can I ignore Tiles and Sitemesh in - favor of Tobago? -
-
- -

Tobago cannot replace it. But sometimes you may not need it, when - you are using Tobago. - If you want to position and size your components automatically, you - can do this with a Tobago LayoutManager. - If you want your header and sidebar rendered without writing duplicate - code, you may use JSP 2.0 tag files, Facelets or Tiles/Sitemesh. -

- -

[top]

-
-
-
How to configure a maven mirror?
-
- -

- If you want to set up a different mirror for some reason, you can use - your ~/.m2/settings.xml and add the following lines: -

+ The locale handling is handled like the Properties Class.

+ + You have not define everything because the ResourceManager is asking the fallback theme for missing + resources

+ + The fallback theme of charlotteville is speyside.

+ The fallback theme of speyside is scarborough.

+ The fallback theme of scarborough is standard

+ + The resource manager looks in the case of the charlotteville theme in

+ charlotteville -> speyside -> scarborough -> standard + +

+ Please look at + + tobago-example-theme + +

+ +

[top]

+
+
+
How do I use and extend the markup attribute?
+
+ +

UIBox, UIInput and UIOutput support custom markup with the markup attribute. + The supported markup is defined in the tobago-config.xml. + The standard markup is defined in tobago-config.xml of the tobago-theme-standard. + This can be extended in your own theme. + The markup attribute is rendered as a CSS class + tobago-[renderer-name.toLowerCase]-markup-[markup]. + For an example please look at the markup number and the CSS class tobago-in-markup-number for + UIIn + in + theme/scarborough/src/main/resources/org/apache/myfaces/tobago/renderkit/html/scarborough/standard/style/tobago.css +

+ +

[top]

+
+
+
In which containers was Tobago tested?
+
+ +

Please take a look at the Compatibility List. + Feel free to post your own experiences.

+ +

[top]

+
+
+
Can Tobago replace Tiles? Can I ignore Tiles and Sitemesh in + favor of Tobago? +
+
+ +

Tobago cannot replace it. But sometimes you may not need it, when + you are using Tobago. + If you want to position and size your components automatically, you + can do this with a Tobago LayoutManager. + If you want your header and sidebar rendered without writing duplicate + code, you may use JSP 2.0 tag files, Facelets or Tiles/Sitemesh. +

+ +

[top]

+
+
+
How to configure a maven mirror?
+
+ +

+ If you want to set up a different mirror for some reason, you can use + your ~/.m2/settings.xml and add the following lines: +

-
+
 <mirrors>
   <mirror>
@@ -533,70 +541,70 @@ resource-path/content-type/theme/client/
         This must not match the mirror ID</mirrorOf>
   </mirror>
 </mirrors>
-
+
-

See: - - Guide to mirror settings - -

- -

Mirrors: - - List of mirrors - -

+

See: + + Guide to mirror settings + +

+ +

Mirrors: + + List of mirrors + +

+ +

[top]

+
+
+
How do I configure an offline build?
+
+ +

+ If you run into problems with fetching jars from the online + repository, you can configure Maven not to fetch them but use + the ones already in your local repository by adding the following to your ~/.m2/settings.xml: +

-

[top]

-
-
-
How do I configure an offline build?
-
- -

- If you run into problems with fetching jars from the online - repository, you can configure Maven not to fetch them but use - the ones already in your local repository by adding the following to your ~/.m2/settings.xml: -

- -
+
 <settings>
   <offline/>
 </settings>
-
+
-

or use the mvn -o switch.

+

or use the mvn -o switch.

-

[top]

-
-
-
How do I perform a local checkstyle check?
-
+

[top]

+
+
+
How do I perform a local checkstyle check?
+
-
+
 mvn compile checkstyle:check
-
+
-

[top]

-
-
-
How do I check the syntax of Facelet-Files (*.xhtml) with respect to the - Taglib?
-
- -

- The problem is, that there is no concept for deprecation in Taglibs. - The tobago-core.jar contains a generated checkstyle configuration to perform - a syntax check via the maven checkstyle plugin. -

- - -

- Configure in the applications pom.xml an entry like this example -

-
+

[top]

+
+
+
How do I check the syntax of Facelet-Files (*.xhtml) with respect to the + Taglib?
+
+ +

+ The problem is, that there is no concept for deprecation in Taglibs. + The tobago-core.jar contains a generated checkstyle configuration to perform + a syntax check via the maven checkstyle plugin. +

+ + +

+ Configure in the applications pom.xml an entry like this example +

+
    <profile>
       <id>checkstyle-for-view-definition-language</id>
       <build>
@@ -622,310 +630,319 @@ mvn compile checkstyle:check
</build> </profile> -
+
-

- To perform a check call -

-
+

+ To perform a check call +

+
 mvn checkstyle:check -Pcheckstyle-for-view-definition-language
-
- You will find the result in target/checkstyle-result.xml +
+ You will find the result in target/checkstyle-result.xml -

[top]

-
- -
Why my Subversion checkout fails on Windows?
-
- One reason is, that the checked out files will have a too long path name. - Under Windows the MAX_PATH is set to 260 characters. When you try to checkout in - a directory like C:\Dokumente und Einstellungen\MyUser\Apache Projects\ - the path will be too long. A workaround will be checking out in an other directory - or register a new drive letter and check it out in X: +

[top]

+
+
+
Why my Subversion checkout fails on Windows?
+
+ One reason is, that the checked out files will have a too long path name. + Under Windows the MAX_PATH is set to 260 characters. When you try to checkout in + a directory like C:\Dokumente und Einstellungen\MyUser\Apache Projects\ + the path will be too long. A workaround will be checking out in an other directory + or register a new drive letter and check it out in X: -
+
 SUBST X: "C:\Dokumente und Einstellungen\MyUser\Apache Projects\"
-
+
-

[top]

-
-
-
How can I run the Selenium tests? (Tobago 1 and 2)
-
- -

- In the tobago-example-test application, the pages can be checked with selenium since Tobago 1.5. - To run the full test automatically call -

-
+

[top]

+
+
+
How can I run the Selenium tests? (Tobago 1 and 2)
+
+ +

+ In the tobago-example-test application, the pages can be checked with selenium since Tobago 1.5. + To run the full test automatically call +

+
 mvn -P integration-test
-
- This will start a jetty server and a selenium server and calls every listed page in the test application. +
+ This will start a jetty server and a selenium server and calls every listed page in the test + application. -

- If you want to run the tests from your IDE, please start the jetty with -

-
+

+ If you want to run the tests from your IDE, please start the jetty with +

+
 mvn jetty:run
-
- or -
-
mvn jetty:run-exploded
-
- and start the selenium server with +
+ or +
+
mvn jetty:run-exploded
+
+ and start the selenium server with -
+
 mvn selenium:start-server
-
- Now you can start the selenium tests in the IDE. +
+ Now you can start the selenium tests in the IDE. -

- Sometimes there is a problem with Firefox. You may try to use a different version, or an installation - without - plugins. -

- -

[top]

-
- -
How can I run the integration tests? (Tobago 3)
-
- -

In the tobago-example-demo application, the pages can be checked with QUnit/Arquillian. - To run the full test automatically call -

-
+

+ Sometimes there is a problem with Firefox. You may try to use a different version, or an + installation without + plugins. +

+ +

[top]

+
+
+
How can I run the integration tests? (Tobago 3)
+
+ +

In the tobago-example-demo application, the pages can be checked with QUnit/Arquillian. + To run the full test automatically call +

+
cd tobago-example/tobago-example-demo
 mvn verify -Pqunit-integration-tests
-
- The default arquillian browser is 'phantomjs'. - You can change it in tobago-example-demo/pom.xml <arquillian.browser>. +
+ The default arquillian browser is 'phantomjs'. + You can change it in tobago-example-demo/pom.xml <arquillian.browser>. -

If you want to run the tests from your IDE, please use the maven profile 'tomee'. - After that, you can start the test from the QUnitTests class.

+

If you want to run the tests from your IDE, please use the maven profile 'tomee'. + After that, you can start the test from the QUnitTests class.

-

[top]

-
- -
How can I run tests in the browser? (Tobago 3)
-
+

[top]

+
+
+
How can I run tests in the browser? (Tobago 3)
+
-
    +
      -
    1. start demo +
    2. start demo -
      +
      cd tobago-example/tobago-example-demo
       mvn clean jetty:run
      -
      -
    3. - -
    4. open 'Test' menu in the header of the Tobago-Demo-Page - -
        - -
      1. 'Run Test' is enabled if a test is available for the current page.
      2. - -
      3. 'Run all tests' is enabled if in development mode. (opens every test in a separate iframe)
      4. - -
      5. 'Access all pages' is enabled if in development mode. (opens every page in a separate iframe)
      6. -
      -
    5. -
    - -

    [top]

    -
    -
-
How can I run the Tobago demo with WebSphere Liberty Profile (WLP) from Maven?
-
+ + -

- Please use at least Tobago 2.0 for this guidance (in this version the pom.xml files are prepared). -

+
  • open 'Test' menu in the header of the Tobago-Demo-Page -

    - You will need to do the following steps for preparation: -

    +
      -
        +
      • 'Run Test' is enabled if a test is available for the current page.
      • -
      • Download the server like: +
      • 'Run all tests' is enabled if in development mode. (opens every test in a separate + iframe) +
      • + +
      • 'Access all pages' is enabled if in development mode. (opens every page in a + separate iframe) +
      • +
    +
  • + + +

    [top]

    +
    +
    +
    How can I run the Tobago demo with WebSphere Liberty Profile (WLP) from Maven? +
    +
    + +

    + Please use at least Tobago 2.0 for this guidance (in this version the pom.xml files are + prepared). +

    + +

    + You will need to do the following steps for preparation: +

    + + - -

    - After these steps you can start/stop the server and deploy an built artifact. - For these steps, you need to be in the Tobago example demo directory. -

    -
    -
    cd tobago-examples/tobago-example-demo
    -
    - This is important for the first start of the server, - because at the first start the server will be initialized. - For the setup the file - -
    -
    test/resources/server.xml
    -
    - will be read. It contains the features, the WLP server will be support, and other configurations. - In our case we have the following features: +
    +
    <wlp.directory>/opt/wlp-developers-runtime-8.5.5.0/wlp</wlp.directory>
    +
    + + + +

    + After these steps you can start/stop the server and deploy an built artifact. + For these steps, you need to be in the Tobago example demo directory. +

    +
    +
    cd tobago-examples/tobago-example-demo
    +
    + This is important for the first start of the server, + because at the first start the server will be initialized. + For the setup the file + +
    +
    test/resources/server.xml
    +
    + will be read. It contains the features, the WLP server will be support, and other configurations. + In our case we have the following features: -
    +
    <feature>cdi-1.0</feature>
     <feature>jsp-2.2</feature>
     <feature>servlet-3.0</feature>
     <feature>jsf-2.0</feature>
    -
    - - -
    -
    -
    http://localhost:9080/tobago-example-demo/
    -
    - -
  • - Redeploy an artifact: The same as deploy. -
  • + +
    +
    mvn -Pliberty liberty:start-server
    +
    + + +
  • + Build an artifact (you need the "provided" property, because JSF and OWB comes + from the server) + +
    +
    mvn clean package -Djsf=provided
    +
    +
  • + +
  • + Deploy an artifact + +
    +
    mvn -Pliberty liberty:deploy
    +
    +
  • + +
  • + You will find the web application under this URL + +
    +
    http://localhost:9080/tobago-example-demo/
    +
    +
  • + +
  • + Redeploy an artifact: The same as deploy. +
  • + +
  • + Stop the server + +
    +
    mvn -Pliberty liberty:stop-server
    +
    +
  • + + +

    + The server starts very fast and is simple to use (very different from the full WebSphere + installation). + The log files you will find here: +

    +
    +
    cd /opt/wlp-developers-8.5.next.beta/wlp/usr/servers/tobago/logs/
    +
    + Sometime you may need to the clean the server, in particular when you are changing JAR dependencies. + For doing that + + + + Please also consider the plugin configuration in the tobago-example/pom.xml -

    - The server starts very fast and is simple to use (very different from the full WebSphere installation). - The log files you will find here: -

    -
    -
    cd /opt/wlp-developers-8.5.next.beta/wlp/usr/servers/tobago/logs/
    -
    - Sometime you may need to the clean the server, in particular when you are changing JAR dependencies. - For doing that - - - - Please also consider the plugin configuration in the tobago-example/pom.xml - -
    +
               <groupId>com.ibm.websphere.wlp.maven.plugins</groupId>
               <artifactId>liberty-maven-plugin</artifactId>
    -
    +
    -

    [top]

    -
    -
    -
    How to setup my project to work with Portlets?
    -
    - -

    - There is a basic example for portlets in the Subversion repository in the sub-folder - tobago-example/tobago-example-portlet - There is no specific configuration to use Tobago in Portlets. -

    - -

    [top]

    - +

    [top]

    +
    + +
    How to setup my project to work with Portlets?
    +
    + +

    + There is a basic example for portlets in the Subversion repository in the sub-folder + tobago-example/tobago-example-portlet + There is no specific configuration to use Tobago in Portlets. +

    + +

    [top]

    + + - -
    +