1.0 to 1.5

<?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://java.sun.com/jsf/facelets">
  <ui:param name="title" value="#{demoBundle.migration15}"/>
  <tc:section label="Migration from Tobago 1.0 to 1.5">
    <p>Tobago 1.5 has a lot of changes compared to Tobago 1.0.</p>
    <p>The good news: Most of these changes are made internally in Tobago. If you use Tobago, you don't have to change
      too much.</p>
    <p>The amount of things you have to change in your application depends on how do you use it. On the Tobago Tag
      Library are very few changes made. On the Tobago Java Classes and the Themes are more changes. Here you can see
      which changes has been made.</p>

    <tc:section label="Deprecated">
      <p>There are also <code>@Deprecated</code> annotations in the code and some logging warning when using deprecated
        code via the Deprecation logging category. Before migrating you should check your application about that.</p>
      <p>For the migration phase you may add the tobago-deprecation.jar as dependency to your project. It contains
        classes that has been moved (e. g. to the new <code>internal</code> package) or removed. So you can resolve any
        migration steps step by step. It is not recommended to use the tobago-deprecation.jar for production.</p>
    </tc:section>

    <tc:section label="Internal">
      <p>The new <code>internal</code> package contains classes that should not be used directly in an application. This
        classes may change in minor revisions without announcement. Classes in the <code>renderkit</code> package a
        handled in the same manner.</p>
    </tc:section>

    <tc:section label="Tag Library">
      <p>The main changes in the tag library are</p>
      <tc:segmentLayout extraSmall="6seg 6seg">
        <tc:panel><b>deprecated</b></tc:panel>
        <tc:panel><b>replacement</b></tc:panel>
        <tc:panel><code class="language-markup">&lt;tc:menuCheckbox></code></tc:panel>
        <tc:panel><code class="language-markup">&lt;tx:menuCheckbox></code></tc:panel>
        <tc:panel><code class="language-markup">&lt;tc:menuItem></code></tc:panel>
        <tc:panel><code class="language-markup">&lt;tc:menuCommand></code></tc:panel>
        <tc:panel><code class="language-markup">&lt;tc:message></code></tc:panel>
        <tc:panel><code class="language-markup">&lt;tc:messages></code></tc:panel>
      </tc:segmentLayout>
      <p>In <code class="language-markup">&lt;tc:sheet></code> the default for <code>rows</code> has been changed from
        100 to 0, which means "unlimited".</p>
      <p>For JSP and the <code>tx:</code> library all <code>id</code> attributes have to be renamed to
        <code>fieldId</code>. This is to adjust the JSP library to the Facelet library.</p>
      <p>The tree tag <code class="language-markup">&lt;tc:tree></code> has changed comprehensive. Please check the
        documentation and demo examples.</p>
      <p>The <code>type</code> attribute of commands has been removed. It is no longer needed, when using
        <code>action</code>, <code>onclick</code> or <code>link</code>.</p>
    </tc:section>

    <tc:section label="Layout Manager">
      <p>On of the basic changes in Tobago 1.5 is the reimplementation of the layout manager. The usage if it, has only
        been changed a bit. The most important is that the constraints will be set with the
        <code class="language-markup">&lt;tc:gridLayoutConstraint></code> tag. The
        <code class="language-markup">&lt;tc:cell></code> tag is deprecated now. Spans can be set directly into the
        component with the <code class="language-markup">&lt;tc:gridLayoutConstraint></code> tag.</p>
      <p>The keyword "fixed" has been renamed to "auto".</p>
    </tc:section>

    <tc:section label="UIComponent Classes">
      <p>Some of the UIComponent classes has been renamed or restructured, to get a consistent naming schema. The used
        UIComponents where generated and have super classes with an "Abstract" as prefix. All getters and setters are
        generated in the UIComponent classes. The following code will not work in 1.5
        <code>uiComponent.getAttributes().remove("attributeName")</code>. Please set the value to null.</p>
      <p>old name: <code>org.apache.myfaces.tobago.component.UISelectOne</code><br/>
        new name: <code>org.apache.myfaces.tobago.internal.component.AbstractUISelectOneBase</code></p>
    </tc:section>

    <tc:section label="Naming Container">
      <p>UITab is now a naming container, so you may have to change ids of AJAX calls in your application.</p>
    </tc:section>

    <tc:section label="Other API Classes">
      <p>The class <code>org.apache.myfaces.tobago.OnComponentCreated</code> is moved to
        <code>org.apache.myfaces.tobago.component.OnComponentCreated</code>.<br/>
        The class <code>org.apache.myfaces.tobago.component.ComponentUtil</code> is moved to
        <code>org.apache.myfaces.tobago.util.ComponentUtils</code>.<br/>
        The class <code>org.apache.myfaces.tobago.renderkit.RenderUtil</code> is moved to
        <code>org.apache.myfaces.tobago.renderkit.util.RenderUtils</code>.<br/>
        The class <code>org.apache.myfaces.tobago.renderkit.html.HtmlRendererUtil</code> is renamed to
        <code>org.apache.myfaces.tobago.renderkit.html.util.HtmlRendererUtils</code>.</p>
    </tc:section>

    <tc:section label="Themes and CSS">
      <p>Note: This effects your application only, when you've written your own theme, or using this classes in a
        separate style file.</p>
      <p>The basic changes in CSS are:</p>
      <ul>
        <li>Using CSS 2.1 compliant content box model instead of <i>Quirks mode</i> border box model.</li>
        <li>Changed HTML structure for some components.</li>
      </ul>
      <p>The CSS class name schema has been revised. See the JavaDoc of the <code>Classes</code> class to check the
        naming schema.</p>
      <tc:segmentLayout extraSmall="6seg 6seg">
        <tc:panel><b>old name</b></tc:panel>
        <tc:panel><b>new name</b></tc:panel>
        <tc:panel><code>tobago-[tagName]-default</code></tc:panel>
        <tc:panel><code>tobago-[tagName]</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-error</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-markup-error</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-required</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-markup-required</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-readonly</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-markup-readonly</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-disabled</code></tc:panel>
        <tc:panel><code>tobago-[tagName]-markup-disabled</code></tc:panel>
        <tc:panel><code>tree-junction</code></tc:panel>
        <tc:panel><code>tobago-treeNode-junction</code></tc:panel>
        <tc:panel><code>tree-*</code></tc:panel>
        <tc:panel><code>tobago-treeNode-*</code></tc:panel>
        <tc:panel><code>tobago-input-picker</code></tc:panel>
        <tc:panel><code>tobago-datePicker-icon</code></tc:panel>
        <tc:panel><code>tobago-popup-iframe</code></tc:panel>
        <tc:panel><code>tobago-popup-ie6bugfix</code></tc:panel>
        <tc:panel><code>tobago-textArea-*</code></tc:panel>
        <tc:panel><code>tobago-textarea-*</code></tc:panel>
        <tc:panel><code>tobago-progress-color1-*</code></tc:panel>
        <tc:panel><code>tobago-progress-value-*</code></tc:panel>
      </tc:segmentLayout>
      <p>The class <code>tobago-progress-color2-*</code> is deleted.</p>
    </tc:section>

    <tc:section label="JavaScript">
      <p>The JavaScript API has been refactored. Most application do not use the Tobago JavaScript API directly. But if
        it does, you have to apply some changes.</p>
      <p>The most important things, is the additional first parameter on the submitting functions to compute the
        position of the action element.</p>
      <p>If you are using <code>submitAction()</code> in the old code, you have to add the action element or just
        <code>null</code>. If you are using <code>submitAction2()</code> in the old code, you have to rename it to
        <code>submitAction()</code>.</p>
      <tc:flexLayout rows="auto auto">
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter and put all parameters after the second to an options map</p></tc:panel>
          <tc:panel><p><code>submitAction()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>submitAction2()</code></p></tc:panel>
          <tc:panel><p><code>submitAction()</code></p></tc:panel>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter</p></tc:panel>
          <tc:panel><p><code>openPopupWithAction()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>openPopupWithAction2()</code></p></tc:panel>
          <tc:panel><p><code>openPopupWithAction()</code></p></tc:panel>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter</p></tc:panel>
          <tc:panel><p><code>reloadComponent()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>reloadComponent2()</code></p></tc:panel>
          <tc:panel><p><code>reloadComponent()</code></p></tc:panel>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter</p></tc:panel>
          <tc:panel><p><code>Updater.update()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>Updater.update2()</code></p></tc:panel>
          <tc:panel><p><code>Updater.update()</code></p></tc:panel>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter</p></tc:panel>
          <tc:panel><p><code>Sheet.reloadWithAction()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>Sheet.reloadWithAction2()</code></p></tc:panel>
          <tc:panel><p><code>Sheet.reloadWithAction()</code></p></tc:panel>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1">
          <tc:panel><p>added first parameter</p></tc:panel>
          <tc:panel><p><code>TabGroup.reloadWithAction()</code></p></tc:panel>
          <tc:panel/>
        </tc:flexLayout>
        <tc:flexLayout columns="1 1 1;">
          <tc:panel><p>renamed</p></tc:panel>
          <tc:panel><p><code>TabGroup.reloadWithAction2()</code></p></tc:panel>
          <tc:panel><p><code>TabGroup.reloadWithAction()</code></p></tc:panel>
        </tc:flexLayout>
      </tc:flexLayout>
    </tc:section>

    <tc:section label="Configuration">
      <p>To define an own theme, please use now a file <code>tobago-config.xml</code> instead of
        <code>tobago-theme.xml</code>.
        The content of <code>tobago-theme.xml</code> is a subset of the <code>tobago-config.xml</code>, you have only to
        change the root node.</p>
      <p>Please use the
        <tc:link label="tobago-config-1.5.xsd" link="https://myfaces.apache.org/tobago/tobago-config-1.5.xsd"/> to
        validate the configuration.</p>
    </tc:section>

    <tc:section label="Own Components and Renderers">
      <p>The renderers must now declared inside the <code>faces-config.xml</code>.</p>
      <p>For the Tobago classes, this will be generated at compile time from annotations like in e. g.
        <code>org.apache.myfaces.tobago.internal.taglib.component.BoxTagDeclaration</code>.</p>
    </tc:section>
  </tc:section>
</ui:composition>