<?xml version="1.0"?>

<!--
 * 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.
-->

<!--
  Note: Please use &lt; instead of < in the source tag, when the example is XML.
  Otherwise you will lost the attributes.
-->

<faqs xmlns="http://maven.apache.org/FML/1.0.1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
      title="Frequently Asked Questions">

  <part id="faq">
    <faq id="howto">
      <question>Where can I find documentation or HowTos for using Tobago?</question>
      <answer>
        <p>
          Please, see
        </p>
        <p>
          <a href="http://www.irian.biz/tobago-example-demo/">Demo</a>
        </p>
        <p>
          and especially the section for best practices:
        </p>
        <p>
          <a href="http://www.irian.biz/tobago-example-demo/faces/best-practice/intro.jsp">
            Best Practices
          </a>
        </p>
      </answer>
    </faq>
    <faq id="hello-world">
      <question>Where can I find a "Hello World" example and a list of required
        jars?
      </question>
      <answer>
        <p>
          Please look at
          <a href="http://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-blank/">
            tobago-example-blank</a> or download the myfaces-tobago-example from the
          <a href="http://people.apache.org/builds/myfaces/nightly/" >nightly builds directory</a>.
        </p>
      </answer>
    </faq>
    <faq id="tobago/RI">
      <question>Does Tobago run with the Sun reference implementation (RI)?</question>
      <answer>
        <p>Tobago runs with Sun RI and with MyFaces.
        Please take a look at the <a href="compatibility.html">Compatibility</a> List.</p>
      </answer>
    </faq>
    <faq id="tobago/facelets">
      <question>Does Tobago supports Facelets?</question>
      <answer>
        <p>Tobago supports Facelets with the tobago-facelets.jar.
        Note: Please add following context param in your web.xml</p>
        <source>
&lt;context-param>
  &lt;param-name>facelets.SKIP_COMMENTS&lt;/param-name>
  &lt;param-value>true&lt;/param-value>
&lt;/context-param></source>
      </answer>
    </faq>
    <faq id="tobago/myfaces extension">
      <question>Can I mix Tobago and MyFaces extensions in the same web application?
      </question>
      <answer>
        <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>
      </answer>
    </faq>
    <faq id="tobago/layout">
      <question>How do I use GridLayout in Tobago?</question>
      <answer>
        <source>
&lt;tc:gridLayout rows="fixed;100px;1*;2*" /></source>
        <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="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.
        </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>
      </answer>
    </faq>

    <faq id="tobago/fileupload">
      <question>How do I configure file upload in Tobago?</question>
      <answer>
        <p>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>
      </answer>
    </faq>

    <faq id="tobago/form">
      <question>Do I need a form tag in a normal Tobago page?</question>
      <answer>
        <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://www.irian.biz/tobago-example-demo/faces/overview/form.jsp" >Tobago demo</a>
        </p>
      </answer>
    </faq>

    <faq id="tobago/browser">
      <question>Which web browsers are currently supported by Tobago?</question>
      <answer>
        <p>Please take a look at the <a href="compatibility.html">Compatibility</a> List.</p>
      </answer>
    </faq>

    <faq id="tobago/owntheme">
      <question>How do I create my own theme?</question>
      <answer>
        <p>
          You have to define a new name for the theme in the META-INF/tobago-theme.xml.
          Choose a fallback theme in the tobago-theme.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>
         <source>
/META-INF/tobago-theme.xml
(resource-path/html/theme-name)
/org/apache/myfaces/tobago/renderkit/html/xxxxx/standard/style/style.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/style.css (different styles for msie)</source>

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

           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="http://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-theme-example/src/main/resources">
            tobago-example-theme
          </a>
         </p>
      </answer>
    </faq>

    <faq id="tobago/custommarkup">
      <question>How do I use and extend the markup attribute?</question>
      <answer>
        <p>UIBox, UIInput and UIOutput support custom markup with the markup attribute.
          The supported markup is defined in the tobago-theme.xml.
          The standard markup is defined in tobago-theme.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 UIInput in theme/scarborough/src/main/resources/org/apache/myfaces/tobago/renderkit/html/scarborough/standard/style/style.css
          </p>
      </answer>
    </faq>

    <faq id="tobago/container">
      <question>In which containers was Tobago tested?</question>
      <answer>
        <p>Please take a look at the <a href="compatibility.html">Compatibility</a> List.
        Feel free to post your own experiences.</p>
      </answer>
    </faq>

    <faq id="tiles/sitemesh">
      <question>Can Tobago replace Tiles? Can I ignore Tiles and Sitemesh in
        favor of Tobago?
      </question>
      <answer>
        <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>
      </answer>
    </faq>
    <faq id="maven-mirror">
      <question>How to configure a maven mirror?</question>
      <answer>
        <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>
        <source>
&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></source>
        <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>
      </answer>
    </faq>
    <faq id="offline-build">
      <question>How do I configure an offline build?</question>
      <answer>
        <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>
        <source>
&lt;settings>
  &lt;offline/>
&lt;/settings></source>
        <p>or use the mvn -o switch.</p>
      </answer>
    </faq>
    <faq id="checkstyle">
      <question>How do I perform a local checkstyle check?</question>
      <answer>
        <source>
mvn compile checkstyle:check</source>
      </answer>
    </faq>
    <faq id="max-path">
      <question>Why my Subversion checkout fails on Windows?</question>
      <answer>
        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:
        <source>
SUBST X: "C:\Dokumente und Einstellungen\MyUser\Apache Projects\"</source>
      </answer>
    </faq>
    <faq id="selenium">
      <question>How can I run the Selenium tests?</question>
      <answer>
      <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
        <source>
mvn -P integration-test</source>
        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
        <source>
mvn jetty:run</source> or <source>mvn jetty:run-exploded</source>
        and start the selenium server with
        <source>
mvn selenium:start-server</source>
        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>
      </answer>
    </faq>
  </part>
</faqs>
