tobago-example/tobago-example-demo/src/main/webapp/content/10-intro/70-faq/FAQ.xhtml

<?xml version="1.0" encoding="UTF-8"?>

<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->

<ui:composition template="/main.xhtml"
                xmlns="http://www.w3.org/1999/xhtml"
                xmlns:tc="http://myfaces.apache.org/tobago/component"
                xmlns:ui="http://xmlns.jcp.org/jsf/facelets">

  <tc:section id="howto" label="Where can I find documentation or HowTos for using Tobago?">
    <p>
      The use of Tobago is explained in the
      <a href="http://tobago-vm.apache.org/">Demo</a>.
    </p>
  </tc:section>

  <tc:section id="support" label="Where can I find support?">
    <p>
      You may subscribe to the user <a href="http://myfaces.apache.org/tobago/mail-lists.html">mailing list</a>,
      and post questions there.
    </p>
  </tc:section>

  <tc:section id="hello-world" label="Where can I find a 'Hello World' example and a list of required jars?">
    <p>
      Please look at
      <a href="https://github.com/apache/myfaces-tobago/tobago-example/tobago-example-blank/">
        tobago-example-blank</a> or download the myfaces-tobago-example from the
      <a href="https://repository.apache.org/content/repositories/snapshots/org/apache/myfaces/tobago/">nightly builds directory</a>.
    </p>
  </tc:section>

  <tc:section id="tobago-RI" label="Does Tobago run with the Sun reference implementation (RI)?">
    <p>Tobago runs with Sun RI and with MyFaces.
      Please take a look at the
      <tc:link image="fa-external-link" link="http://tobago-vm.apache.org/compatibility.html" label="Compatibility"/>
      List.</p>
  </tc:section>

  <tc:section id="tobago-facelets" label="Does Tobago supports Facelets?">
    <p>Tobago 2.0.x:</p>
    <p>Tobago supports the JSF 2.0 Facelets.
      Note: Please add following context param in your web.xml</p>
    <demo-highlight language="markup">&lt;context-param>
  &lt;param-name>javax.faces.FACELETS_SKIP_COMMENTS&lt;/param-name>
  &lt;param-value>true&lt;/param-value>
&lt;/context-param></demo-highlight>
    <p>Tobago 1.0.x and 1.5.x:</p>
    <p>Tobago supports Facelets with the tobago-facelets.jar.
      Note: Please add following context param in your web.xml</p>
    <demo-highlight language="markup">&lt;context-param>
  &lt;param-name>facelets.SKIP_COMMENTS&lt;/param-name>
  &lt;param-value>true&lt;/param-value>
&lt;/context-param></demo-highlight>
  </tc:section>

  <tc:section id="tobago-myfaces-extension" label="Can I mix Tobago and MyFaces extensions in the same web application?">
    <p>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.
    </p>
  </tc:section>

  <tc:section id="tobago-layout" label="How do I use GridLayout in Tobago?">
          <demo-highlight language="markup">&lt;tc:gridLayout rows="auto 100px 1fr 2fr" /></demo-highlight>
    <p>
      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...).<br/>
      Using px heights is at your own risk, but it is sometimes needed for elements like box or sheet.
    </p>
    <p>
      Alternatively you can give elements a proportion with the * notation.<br/>
      For example rows="1fr 2fr" gives the first row 1/3 of the available vertical space and the
      second row 2/3. This works fine for columns, too.
    </p>
    <p>
      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.
    </p>
  </tc:section>

  <tc:section id="tobago-fileupload" label="How do I configure file upload in Tobago?">
    <p>Till Tobago 2.0 and lower, you have two options.</p>
    <p>Add a TobagoMultipartFormdataFilter to your web.xml.
      <a href="http://myfaces.apache.org/tobago/apidocs/org/apache/myfaces/tobago/webapp/TobagoMultipartFormdataFilter.html">JavaDoc Description</a>
    </p>
    <p>Add the tobago-fileupload.jar to your project.
      The tobago-fileupload.jar contains a FacesContextFactory that wraps the
      multipart-formdata request inside the FacesContext.
      <a href="http://myfaces.apache.org/tobago/apidocs/org/apache/myfaces/tobago/fileupload/FileUploadFacesContextFactoryImpl.html">JavaDoc Description</a>
    </p>
    <p>Starting with Tobago 3.0 the Servlet API 3.0 will be used. Some more information about the
      usage you will find in <a href="https://issues.apache.org/jira/browse/TOBAGO-1539">Jira</a>
      and in the
      <a href="http://tobago-vm.apache.org/demo-3-release/faces/content/20-component/100-upload/upload.xhtml">Tobago Demo 3.0</a>.
      There is also a
      <a href="http://tobago-vm.apache.org/migration-guide.html">migration guide</a> available.
    </p>
  </tc:section>

  <tc:section id="tobago-form" label="Do I need a form tag in a normal Tobago page?">
    <p>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
      <a href="http://tobago-vm.apache.org/demo-3-release/faces/content/30-concept/08-form/form.xhtml">Tobago demo</a>
    </p>
  </tc:section>

  <tc:section id="tobago-browser" label="Which web browsers are currently supported by Tobago?">
    <p>Please take a look at the
      <tc:link image="fa-external-link" link="http://tobago-vm.apache.org/compatibility.html" label="Compatibility"/>
      List.</p>
  </tc:section>

  <tc:section id="tobago-owntheme" label="How do I create my own theme?">
    <p>
      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)
    </p>
    <p>
      Example layout of a theme jar:
    </p>
    <demo-highlight language="markup">/META-INF/tobago-config.xml (resource-path/html/theme-name)
/org/apache/myfaces/tobago/renderkit/html/xxxxx/standard/style/tobago.css (standard styles)
/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)</demo-highlight>

    Property and resource loading and renderer loading is done in the following order
    <demo-highlight language="markup">resource-path/content-type/theme/client/[tag(for renderer)|property|style|script|image]_locale.(class|property|property.xml|css|js|gif|png...]</demo-highlight>

    for example OutRenderer<br/>

    org.apache.myfaces.tobago.renderkit.html.scarborough.standard.tag.OutRenderer<br/>

    OutRenderer is getRendererType() + "Renderer"<br/>

    The locale handling is handled like the Properties Class.<br/>

    You have not define everything because the ResourceManager is asking the fallback theme for missing resources<br/>

    The fallback theme of charlotteville is speyside.<br/>
    The fallback theme of speyside is scarborough.<br/>
    The fallback theme of scarborough is standard<br/>

    The resource manager looks in the case of the charlotteville theme in<br/>
    charlotteville -> speyside -> scarborough -> standard
    <p>
      Please look at
      <a href="https://github.com/apache/myfaces-tobago/tobago-theme/tobago-theme-example/src/main/resources">
        tobago-example-theme
      </a>
    </p>
  </tc:section>

  <tc:section id="tobago-custommarkup" label="How do I use and extend the markup attribute?">
    <p>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
    </p>
  </tc:section>


  <tc:section id="tobago-container" label="In which containers was Tobago tested?">
    <p>Please take a look at the
      <tc:link image="fa-external-link" link="http://tobago-vm.apache.org/compatibility.html" label="Compatibility"/>
      List.
      Feel free to post your own experiences.</p>
  </tc:section>


  <tc:section id="tiles-sitemesh">Can Tobago replace Tiles? Can I ignore Tiles and Sitemesh in
    favor of Tobago?
    >
    <p>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.
    </p>
  </tc:section>

  <tc:section id="maven-mirror" label="How to configure a maven mirror?">
    <p>
      If you want to set up a different mirror for some reason, you can use
      your ~/.m2/settings.xml and add the following lines:
    </p>
    <demo-highlight language="markup">&lt;mirrors>
  &lt;mirror>
    &lt;id>mirror ID&lt;/id>
    &lt;name>Give it a name&lt;/name>
    &lt;url>The URL of the mirror&lt;/url>
    &lt;mirrorOf>The server ID of the repository being mirrored. This must not match the mirror ID&lt;/mirrorOf>
  &lt;/mirror>
&lt;/mirrors></demo-highlight>
    <p>See:
      <a href="http://maven.apache.org/guides/mini/guide-mirror-settings.html">
        Guide to mirror settings
      </a>
    </p>
    <p>Mirrors:
      <a href="http://docs.codehaus.org/display/MAVENUSER/Mirrors+Repositories">
        List of mirrors
      </a>
    </p>
  </tc:section>

  <tc:section id="offline-build" label="How do I configure an offline build?">
    <p>
      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:
    </p>
    <demo-highlight language="markup">&lt;settings>
  &lt;offline/>
&lt;/settings></demo-highlight>
    <p>or use the mvn -o switch.</p>
  </tc:section>

  <tc:section id="checkstyle" label="How do I perform a local checkstyle check?">
    <demo-highlight language="markup">mvn compile checkstyle:check</demo-highlight>
  </tc:section>

  <tc:section id="checkstyle-vdl"
              label="How do I check the syntax of Facelet-Files (*.xhtml) with respect to the Taglib?">
    <p>
      The problem is, that there is no concept for <em>deprecation</em> in Taglibs.
      The tobago-core.jar contains a generated checkstyle configuration to perform
      a syntax check via the maven checkstyle plugin.
    </p>

    <p>
      Configure in the applications pom.xml an entry like this example
    </p>
    <demo-highlight language="markup">&lt;profile>
  &lt;id>checkstyle-for-view-definition-language&lt;/id>
  &lt;build>
    &lt;plugins>
      &lt;plugin>
        &lt;groupId>org.apache.maven.plugins&lt;/groupId>
        &lt;artifactId>maven-checkstyle-plugin&lt;/artifactId>
        &lt;configuration>
          &lt;configLocation>META-INF/checkstyle-tobago.xml&lt;/configLocation>
          &lt;includes>**/*.xhtml&lt;/includes>
          &lt;excludes>**/*.java&lt;/excludes>
          &lt;sourceDirectory>src/main/webapp&lt;/sourceDirectory>
        &lt;/configuration>
        &lt;dependencies>
          &lt;dependency>
            &lt;groupId>org.apache.myfaces.tobago&lt;/groupId>
            &lt;artifactId>tobago-core&lt;/artifactId>
            &lt;version>\${tobago.version}&lt;/version>
          &lt;/dependency>
        &lt;/dependencies>
      &lt;/plugin>
    &lt;/plugins>
  &lt;/build>
&lt;/profile></demo-highlight>
    <p>
      To perform a check call
    </p>
    <demo-highlight language="markup">mvn checkstyle:check -Pcheckstyle-for-view-definition-language</demo-highlight>
    <p>
      You will find the result in target/checkstyle-result.xml
    </p>
  </tc:section>

  <tc:section id="max-path" label="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:
    <demo-highlight language="markup">SUBST X: "C:\Dokumente und Einstellungen\MyUser\Apache Projects\"</demo-highlight>
  </tc:section>

  <tc:section id="integrationTest" label="How can I run the integration tests?">
    <tc:section id="seleniumTobago12" label="Tobago 1 and 2">
      <p>In the tobago-example-test application, the pages can be checked with selenium since Tobago 1.5.
        To run the full test automatically call</p>
      <demo-highlight language="markup">mvn -P integration-test</demo-highlight>
      <p>This will start a jetty server and a selenium server and calls every listed page in the test application.</p>
      <p>If you want to run the tests from your IDE, please start the jetty with
        <code class="language-markup">mvn jetty:run</code> or
        <code class="language-markup">mvn jetty:run-exploded</code>
        and start the selenium server with</p>
      <demo-highlight language="markup">mvn selenium:start-server</demo-highlight>
      <p>Now you can start the selenium tests in the IDE.</p>
      <p>Sometimes there is a problem with Firefox. You may try to use a different version, or an installation without
        plugins.</p>
    </tc:section>

    <tc:section id="integrationTestTobago3" label="Tobago 3">
      <p>In the tobago-example-demo application, the pages can be checked with QUnit/Arquillian.
        To run the full test automatically call</p>
      <demo-highlight language="markup">cd tobago-example/tobago-example-demo
mvn verify -Pqunit-integration-tests</demo-highlight>
      <p>The default arquillian browser is 'phantomjs'.
        You can change it in tobago-example-demo/pom.xml &lt;arquillian.browser>.</p>
      <p>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.</p>
    </tc:section>

    <tc:section id="integrationTestTobago4" label="Tobago 4">
      <p>Since Tobago 4.3.0 the integration tests are reimplemented with docker.</p>
      <p>To run the integration tests:</p>
      <demo-highlight language="markup">cd tobago-example/tobago-example-demo
mvn -Pdocker-qunit-tests</demo-highlight>
      <p>The docker container can be rebuild with:</p>
      <demo-highlight language="markup">mvn package -Pdocker-qunit-tests docker:build</demo-highlight>
      <p>You can also just start/stop the docker container manually to run the tests from your IDE.</p>
      <demo-highlight language="markup">mvn -Pdocker-qunit-tests docker:start
mvn -Pdocker-qunit-tests docker:stop</demo-highlight>
    </tc:section>

    <tc:section id="integrationTestTobago5" label="Tobago 5">
      <p>Since Tobago  #{apiController.version500} the integration tests are reimplemented with jasmine and
        testcontainers.</p>
      <p>To run the integration tests:</p>
      <demo-highlight language="markup">cd tobago-example/tobago-example-demo
mvn clean install -Pintegration-tests
      </demo-highlight>
      <p>The docker container can be rebuild with:</p>
      <demo-highlight language="markup">mvn package -Pdocker</demo-highlight>
    </tc:section>
  </tc:section>

  <tc:section id="testInBrowser" label="How can I run tests in the browser? (Tobago 3)">
    <ol>
      <li>start demo
        <demo-highlight language="markup">cd tobago-example/tobago-example-demo
mvn clean jetty:run</demo-highlight>
      </li>
      <li>open 'Test' menu in the header of the Tobago-Demo-Page
        <ol>
          <li>'Run Test' is enabled if a test is available for the current page.</li>
          <li>'Run all tests' is enabled if in development mode. (opens every test in a separate iframe)</li>
          <li>'Access all pages' is enabled if in development mode. (opens every page in a separate iframe)</li>
        </ol>
      </li>
    </ol>
  </tc:section>

  <tc:section id="testQUnit" label="How to create QUnit tests? (Tobago 4.2.1)">

    Howto create QUnit tests for Tobago Demo 3.0 or higher

    <ol>
      <li>
        Choose a <code>sample.xhtml</code> file for testing.
      </li>
      <li>
        Create a <code>sample.test.js</code> file (with same name).
      </li>
      <li>
        Add a
        <tc:link label="QUnit Test" link="https://api.qunitjs.com/" image="fa-external-link"/>
        to the <code>sample.test.js</code>.

        <demo-highlight language="js">QUnit.test("Testtitle", function(assert) { 
  ...
});</demo-highlight>

        <ol>
          <li>The test will run in a different frame.
            To get an element in the test frame use <code>jQueryFrameFn()</code> instead of <code>jQuery()</code>.
            Please note that <code>jQueryFrameFn()</code> return a function, so you have to write
            <code>jQueryVar()</code> instead of <code>jQueryVar</code> to get the element.<br/>
            This is very usefull, because elements are outdated after an AJAX request or a full page reload.
          </li>
          <li>Create a TobagoTestTools variable:
            <demo-highlight language="js">var TTT = new TobagoTestTools(assert);</demo-highlight>
          </li>
          <li>
            User actions like a click on a button can be added to an action function:
            <demo-highlight language="js">TTT.action(function () {
  $button().click();
});</demo-highlight>
          </li>
          <li>If the test have to wait for a response or a specific time use the waitForResponse
            or the waitMs function:
            <demo-highlight language="js">TTT.waitForResponse();
TTT.waitMs(2000); // wait 2000 milliseconds</demo-highlight>
          </li>
          <li>
            <tc:link label="QUnit Assertions" link="https://api.qunitjs.com/assert/" image="fa-external-link"/>
            can be added to a asserts function. The first parameter is the number of assertions:
            <demo-highlight language="js">TTT.asserts(2, function () {
  assert.equal($input().val(), "Alice");
  assert.equal($output().text(), "Bob");
});</demo-highlight>
          </li>
          <li>Start the test with:
            <demo-highlight language="js">TTT.startTest();</demo-highlight></li>
        </ol>

        <demo-highlight language="java">@Test
public void testname() throws UnsupportedEncodingException, InterruptedException {
  String page = "content/.../testname.xhtml";
  runStandardTest(page);
}</demo-highlight>

      </li>
      <li>
        Run the tests from QUnitTests or type

        <demo-highlight language="bash">mvn verify -Pqunit-integration-tests</demo-highlight>
      </li>
    </ol>
  </tc:section>

  <tc:section id="liberty" label="How can I run the Tobago demo with WebSphere Liberty Profile (WLP) from Maven?">
    <p>
      <b>Please use at least Tobago 2.0 for this guidance (in this version the pom.xml files are prepared).</b>
    </p>
    <p>
      You will need to do the following steps for preparation:
    </p>
    <ul>
      <li>Download the server like:
        <demo-highlight language="markup">wlp-developers-runtime-8.5.5.0.jar</demo-highlight>
        from
        <a href="https://www.ibm.com/developerworks/mydeveloperworks/blogs/wasdev/entry/download?lang=en">IBM</a>
      </li>
      <li>
        Unpack the server anywhere in you file system, e.g. like this
        <demo-highlight language="markup">mkdir /opt/wlp-developers-runtime-8.5.5.0
cd /opt/wlp-developers-runtime-8.5.5.0
java -jar ~/Downloads/wlp-developers-runtime-8.5.5.0.jar</demo-highlight>
      </li>
      <li>
        Adding your server home to a property in the settings.xml of Maven
        <demo-highlight language="markup">&lt;wlp.directory&gt;/opt/wlp-developers-runtime-8.5.5.0/wlp&lt;/wlp.directory&gt;</demo-highlight>
      </li>
    </ul>
    <p>
      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.
    </p>
    <demo-highlight language="markup">cd tobago-examples/tobago-example-demo</demo-highlight>
    <p>
      This is <b>important</b> for the first start of the server,
      because at the first start the server will be initialized.
      For the setup the file
    </p>
    <demo-highlight language="markup">test/resources/server.xml</demo-highlight>
    <p>
      will be read. It contains the features, the WLP server will be support, and other configurations.
      In our case we have the following features:
    </p>
    <demo-highlight language="markup">&lt;feature>cdi-1.0&lt;/feature>
&lt;feature>jsp-2.2&lt;/feature>
&lt;feature>servlet-3.0&lt;/feature>
&lt;feature>jsf-2.0&lt;/feature></demo-highlight>
    <ul>
      <li>
        Start the server
        <demo-highlight language="markup">mvn -Pliberty liberty:start-server</demo-highlight>
      </li>
      <li>
        Build an artifact (you need the "provided" property, because JSF and OWB comes from the server)
        <demo-highlight language="markup">mvn clean package -Djsf=provided</demo-highlight>
      </li>
      <li>
        Deploy an artifact
        <demo-highlight language="markup">mvn -Pliberty liberty:deploy</demo-highlight>
      </li>
      <li>
        You will find the web application under this URL
        <demo-highlight language="markup">http://localhost:9080/tobago-example-demo/</demo-highlight>
      </li>
      <li>
        Redeploy an artifact: The same as deploy.
      </li>
      <li>
        Stop the server
        <demo-highlight language="markup">mvn -Pliberty liberty:stop-server</demo-highlight>
      </li>
    </ul>
    <p>
      The server starts very fast and is simple to use (very different from the full WebSphere installation).
      The log files you will find here:
    </p>
    <demo-highlight language="markup">cd /opt/wlp-developers-8.5.next.beta/wlp/usr/servers/tobago/logs/</demo-highlight>
    <p>
      Sometime you may need to the clean the server, in particular when you are changing JAR dependencies.
      For doing that
    </p>
    <ul>
      <li>
        Stop the server
      </li>
      <li>
        Remove the whole concrete server installation
        <demo-highlight language="markup">rm -r /opt/wlp-developers-8.5.next.beta/wlp/usr/servers/tobago</demo-highlight>
      </li>
      <li>
        Start the server (don't forget the server.xml)
      </li>
      <li>
        Deploy again
      </li>
    </ul>
    Please also consider the plugin configuration in the tobago-example/pom.xml
    <demo-highlight language="markup">&lt;groupId>com.ibm.websphere.wlp.maven.plugins&lt;/groupId>
&lt;artifactId>liberty-maven-plugin&lt;/artifactId></demo-highlight>
  </tc:section>

  <tc:section id="portlet" label="How to setup my project to work with Portlets?">
    <p>
      There is a basic example for portlets in the GIT repository in the sub-folder
      tobago-example/tobago-example-portlet
      There is no specific configuration to use Tobago in Portlets.
      The portlet stuff is currently not active, so the example is removed in Tobago 4.
    </p>
  </tc:section>


</ui:composition>