You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by hn...@apache.org on 2020/05/07 12:06:51 UTC
[myfaces-tobago] 01/02: change * in layout manager
This is an automated email from the ASF dual-hosted git repository.
hnoeth pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/myfaces-tobago.git
commit f951871eae9e3c731361e0364191d1e48bc524da
Author: Jasmin Kroeger <ja...@irian.eu>
AuthorDate: Wed Apr 15 11:53:33 2020 +0200
change * in layout manager
* change * for example to 1fr
---
src/docbook/tobago-tutorial.xml | 8 +-
src/site/apt/guide.apt | 1320 ++++++++++----------
.../taglib/component/FlexLayoutTagDeclaration.java | 4 +-
.../component/SplitLayoutTagDeclaration.java | 4 +-
.../50-migration/99-migration/1.0_to_1.5.xhtml | 24 +-
5 files changed, 680 insertions(+), 680 deletions(-)
diff --git a/src/docbook/tobago-tutorial.xml b/src/docbook/tobago-tutorial.xml
index d63acf3..9c18577 100644
--- a/src/docbook/tobago-tutorial.xml
+++ b/src/docbook/tobago-tutorial.xml
@@ -599,7 +599,7 @@
...
<tc:panel>
<f:facet name="layout">
- <tc:gridLayout columns="*;fixed;fixed"/>
+ <tc:gridLayout columns="1fr;fixed;fixed"/>
</f:facet>
<tc:panel/>
<tc:button label="OK">
@@ -692,7 +692,7 @@
<programlisting role="XML"><tc:panel>
<f:facet name="layout">
- <tc:gridLayout columns="*" rows="fixed;fixed;fixed;*"/>
+ <tc:gridLayout columns="1fr" rows="fixed;fixed;fixed;*"/>
</f:facet>
<tf:in ... />
<tf:in ... />
@@ -744,8 +744,8 @@
<informaltable frame="none" colsep="0" rowsep="0">
<tgroup cols="2">
- <colspec colname="c1" colwidth="1*"/>
- <colspec colname="c2" colwidth="1*"/>
+ <colspec colname="c1" colwidth="1fr"/>
+ <colspec colname="c2" colwidth="1fr"/>
<tbody>
<row>
<entry><para><figure id="fig-theme-speyside">
diff --git a/src/site/apt/guide.apt b/src/site/apt/guide.apt
index 58a4bc8..fe24493 100644
--- a/src/site/apt/guide.apt
+++ b/src/site/apt/guide.apt
@@ -1,660 +1,660 @@
- ~~ 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.
-
- ------
- Guide to Tobago
- ------
-
-{Guide to Tobago}
-
- <This guide covers primarily Tobago 1 and 2. Most basic ideas are the same in Tobago 3, but
- documented in the demo application.>
-
-====================
-
- Tobago is a JavaServer Faces (JSF) framework and component library. It provides a comfortable way to layout screens
- of desktop-like applications with a consistent look & feel. Tobago emphasizes the separation of structure
- and design of screens. Screens are developed independently of the view technology -- no HTML, CSS, or JavaScript.
- Because of strict separation a screen can be displayed with different themes. These themes can be used to render
- screens according to different corporate design without changing the sources of the screens.
-
- This guide assumes basic knowledge about JSF. For more information about JSF see one of the various books about JSF,
- the {{{http://java.sun.com/javaee/5/docs/tutorial/doc/bnaph.html}Sun Java 5 Tutorial}} or
- the {{{http://java.sun.com/javaee/javaserverfaces/download.html}JSF Specification.}}
-
-{Content}
-
- \
-
-%{toc|fromDepth=0|toDepth=4}
-
-{Environment}
-
-* {Building and Deploying the Tobago Examples}
-
- Tobago uses Maven as a build management system. The provided examples are normally build with Maven, but it would
- be easy to use an alternative build system. The necessary artifacts can be downloaded {{{./download.html}here}} or
- from the Maven repository.
-
- We will use the address book demo as an example in this guide. Since the address book example is currently
- not part of the Tobago distribution, you have to check-out the sources from the Apache Subversion repository.
- We will use the latest release tag for this.
-
-+------------------------------------------+
-svn co https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/addressbook/ tobago-addressbook
-+------------------------------------------+
-
- You will need Java 5 and Maven 2.0.9 or later to build the address book example. Use the following command to
- compile the sources and deploy the web application on an embedded Jetty server:
-
-+------------------------------------------+
-mvn jetty:run-exploded
-+------------------------------------------+
-
- If you point your browser to {{http://localhost:8080/}} and you will be directed to the login dialog of the address
- book example.\
- \
-
-[images/guide-addressbook-login.png] Address Book Login
-
- You can click on the guest/guest or admin/admin links or fill in the authentication information yourself
- and press the 'Login' button. After displaying a splash screen for a while the application will direct you to
- the address list page.\
- \
-
-[images/guide-addressbook-list.png] Address List
-
- A freshly started instance of the address book example will not contain any addresses in the list. But you can
- add addresses by pressing the 'New' button in the tool bar. The addresses will be stored in an embedded Derby
- database.
-
-* {Building Tobago}
-
- To use the latest version of Tobago you can use the snapshot artifacts build by our continuous integration server Continuum,
- which are available in the {{{https://repository.apache.org/content/repositories/snapshots/org/apache/myfaces/tobago/}Apache snapshot repository.}}
-
- Alternatively, you can build Tobago yourself. You will need Java 5 and Maven 2.0.9 or later.
-
- Check-out Tobago from the Apache Subversion repository
-
-+------------------------------------------+
-svn co https://svn.apache.org/repos/asf/myfaces/tobago/trunk/ tobago
-+------------------------------------------+
-
- To build the complete project with all sub-modules you have to enter the following command
-
-+------------------------------------------+
-mvn install
-+------------------------------------------+
-
- For more information on building Tobago -- especially the 1.0.x branch -- see {{{./getting-started.html}Getting Started.}}
-
-* {Building your own Tobago Application}
-
- The Tobago example distribution contains the tobago-example-blank WAR, which can act as starting point for
- your own Tobago application. Since Tobago is based on JSF you need a JSF implementation if the application server
- you are targeting doesn't contain one.
-
- If you cannot use Java 5 or higher you can use retrotranslated JARs from the Tobago distribution to develop and
- run Tobago applications with Java\ 1.4 (only Tobago 1.0.x).
-
- A Tobago application is a web application which is packaged as a WAR. For a JSF application the <<<FacesServlet>>> needs
- to be configured in the <<</WEB-INF/web.xml>>>. To serve the internal resources of Tobago directly from the Tobago
- JARs the Tobago <<<ResourceServlet>>> has to configured, too. The configuration of a Tobago application is controlled
- by the <<<WEB-INF/tobago-config.xml>>> file. This can be used to declare the available themes and the default theme.
- Additionally, it can be used to locally add markup -- see the {{Themes}} section for further information.
-
-* {A Minimal Tobago Page}
-
- You can use JSP or Facelets to write Tobago pages. For Facelets support the extension module tobago-facelets has to
- be added as a dependency. Because the address book example uses JSP as rendering technology we will focus on JSP
- for now.
-
- Tobago provides two tag libraries -- the core library and the extension library. The corresponding TLDs contain
- documentation for the provided tags which is generated from annotations on the underlying tag classes. The core tag
- library contains basic controls and the extension library convenience tags for pre-assembled tag compositions -- for
- example a composition of a label and an input control.
-
- A minimal Tobago JSP page looks like this:
-
-+------------------------------------------+
-<%@ page contentType="text/html;charset=UTF-8" language="java" %>
-<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
-<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
-<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
-<f:view>
- <tc:page>
- <f:facet name="layout">
- <tc:gridLayout/>
- </f:facet>
- <tc:out value="Hello World"/>
- </tc:page>
-</f:view>
-+------------------------------------------+
-
- A similar page is part of the blank WAR: \
- {{https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/blank/src/main/webapp/helloWorld.jsp}}
-
-{Creating a Tobago page}
-
- The address book example needs an address editing page to add new addresses to the address book and to update
- existing ones.
-
- A simple version of an address editor allows to edit the first and last name of a person and basic address data
- like street, house number and city. Such an editor could look like this:\
- \
-
-[images/guide-simple-editor.png] Simple Address Editor
-
- This page is generated by the following code:
-
-+------------------------------------------+
-<%@ page contentType="text/html;charset=UTF-8" language="java" %>
-<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
-<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
-<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
-<f:view>
- <tc:page width="400">
- <f:facet name="layout">
- <tc:gridLayout rows="fixed;*" margin="10"/>
- </f:facet>
- <tc:box label="Address">
- <f:facet name="layout">
- <tc:gridLayout rows="fixed;fixed;fixed;fixed"/>
- </f:facet>
- <tx:in label="First Name"/>
- <tx:in label="Last Name"/>
-
- <tc:panel>
- <f:facet name="layout">
- <tc:gridLayout columns="6*;1*"/>
- </f:facet>
- <tx:in label="Street / No"/>
- <tc:in />
- </tc:panel>
-
- <tx:in label="City"/>
- </tc:box>
-
- <tc:cell />
- </tc:page>
-</f:view>
-+------------------------------------------+
-
- We have a box with the label "Address" containing four rows of input controls for first name, last name, street,
- house number, and city.
-
-* {Basic Controls}
-
- HTML offers a decent set of basic controls. These controls form the basis of the Tobago controls including
- single-line input controls, text areas, check boxes, radio buttons, links, buttons, labels, and others.
-
- The Tobago demo contains an overview page for the basic controls.\
- \
-
-[images/guide-basic-controls.png] Basic Controls
-
- Live demo of the basic controls: {{http://tobago-vm.apache.org/demo-2-release/faces/content/01-basic/basic.xhtml}}
-
- The basic controls page also shows two variants of a normal input control: the date input control and the time input
- control.
-
-* {Text Input}
-
- The single-line text input control comes in two flavors: the <<<\<tc:in\>>>> tag from the core tag library (<<<tc>>>
- is the preferred prefix for the core tag library) and the <<<\<tx:in\>>>> from the extension tag library (<<<tx>>>).
-
- The extension tag library provides convenient shorthands for boilerplate code. For every input control there
- is for example an extended version, which layouts a label next before the input field. The label is connected
- with the field. If the label is clicked the related field is focused.
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tx:in value="#{controller.currentAddress.firstName}"
- label="#{bundle.editorFirstName}" required="true">
- <f:validateLength minimum="2" maximum="20"/>
-</tx:in>
-+------------------------------------------+
-
- The <<<value>>> attribute refers the content of the control. If a value binding is used, this content can be written
- back into a bean property.
-
- The <<<label>>> attribute generates the textual description for the control. The theme decides how the label is
- actually rendered, for example it assigns a default width. This width can be overwritten with the <<<labelWidth>>>
- attribute. If you utilize a value binding to a resource bundle declared by a <<<\<tc:loadBundle\>>>> tag, you
- automatically get localization for the text labels. An underscore in the label transforms the following
- character into an access key. The theme normally underlines the access key to make this circumstance visible to
- the user. The access key can be used to quickly focus the related input control by pressing <<<Alt>>> in combination
- with the access key.
-
- If the control is marked as <<<required>>> the respective validation takes place. Additionally, the theme tries to
- visualize this fact. Speyside renders a small check mark icon inside the field, which vanishes if the field
- contains any data.
-
- For more information about the possible attributes of an input tag see the TLD documentation for
- {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tc/in.html}<<<\<tc:in\>>>>}} and
- {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tx/in.html}<<<\<tx:in\>>>>}}.
-
-* {Sheet}
-
- The sheet control is used to display tabular data.
-
- The address book example uses a sheet to give an overview of all stored addresses.\
- \
-
-[images/guide-sheet.png] Sheet
-
- Live demo of a sheet: {{http://tobago-vm.apache.org/demo-2-release/faces/content/02-sheet/sheet.xhtml}}
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:sheet columns="1*;1*;1*" value="#{controller.currentAddressList}"
- var="address" state="#{controller.selectedAddresses}"
- sortActionListener="#{controller.sheetSorter}" rows="25"
- showRowRange="left" showPageRange="right" showDirectLinks="center">
- <tc:columnEvent event="dblclick" >
- <tc:command action="#{controller.editAddress}"/>
- </tc:columnEvent>
- <tc:column id="firstName" label="#{bundle.listFirstName}" sortable="true"
- rendered="#{controller.renderFirstName}">
- <tc:out value="#{address.firstName}"/>
- </tc:column>
- <tc:column id="lastName" label="#{bundle.listLastName}" sortable="true"
- rendered="#{controller.renderLastName}">
- <tc:out value="#{address.lastName}"/>
- </tc:column>
- <tc:column id="dayOfBirth" label="Birthday" sortable="true"
- rendered="#{controller.renderDayOfBirth}">
- <tc:out value="#{address.dayOfBirth}">
- <f:convertDateTime pattern="#{bundle.editorDatePattern}"/>
- </tc:out>
- </tc:column>
-</tc:sheet>
-+------------------------------------------+
-
-* {Tab Group}
-
- The tab group control displays rectangular content in the same area of the screen with the help of tab panels.
-
- In the address book example the tab group is used to structure the input controls for an address into three groups
- for general, business, and miscellaneous information.\
- \
-
-[images/guide-tab-group.png] Tab Group
-
- Live demo of a tab group: {{http://tobago-vm.apache.org/demo-2-release/faces/content/04-tab/tab.xhtml}}
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:tabGroup switchType="reloadTab" immediate="true">
- <tc:tab label="#{bundle.editorTabPersonal}">
- <jsp:include page="tab/personal.jsp"/>
- </tc:tab>
-
- <tc:tab label="#{bundle.editorTabBusiness}" rendered="#{!controller.simple}">
- <jsp:include page="tab/business.jsp"/>
- </tc:tab>
-
- <tc:tab label="#{bundle.editorTabMisc}" rendered="#{!controller.simple}">
- <jsp:include page="tab/misc.jsp"/>
- </tc:tab>
-</tc:tabGroup>
-+------------------------------------------+
-
-* {Menu}
-
- The menu control can be used to render a menu bar at the top of a screen like it is typically used in desktop
- applications. But the location for menus is not limited to this place.\
- \
-
-[images/guide-menu.png] Menu
-
- Live demo of a menu: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:menuBar>
- <tc:menu label="#{bundle.menuFile}">
- <tc:menuCommand label="#{bundle.menuFileNew}" action="#{controller.createAddress}" immediate="true"
- image="image/org/tango-project/tango-icon-theme/16x16/actions/contact-new.png"/>
- <tc:menuCommand label="Add Dummy Addresses" action="#{controller.addDummyAddresses}" immediate="true"/>
- <tc:menuSeparator/>
- <tc:menuCommand label="#{bundle.admin}" action="#{admin.admin}"
- image="image/org/tango-project/tango-icon-theme/16x16/categories/preferences-system.png"/>
- <tc:menuSeparator/>
- <tc:menuCommand label="Logout" action="#{controller.logout}"
- image="image/org/tango-project/tango-icon-theme/16x16/actions/system-log-out.png"/>
- </tc:menu>
-
- <tc:menu label="#{bundle.menuSettings}">
- ...
- </tc:menu>
-
- <tc:menu label="#{bundle.menuHelp}">
- ...
- </tc:menu>
-</tc:menuBar>
-+------------------------------------------+
-
-* {Tool Bar}
-
- The tool bar control is used to render a special rectangular area of buttons. There are two versions of toolbars:
- a standalone version and version that embeds itself in the border of a box. To embed a tool bar it has to be
- attached to a <<<\<tc:box\>>>> via a toolbar facet.
-
- The address book example uses a tool bar below the menu to provide convenient access to the most common actions
- from the menu.\
- \
-
-[images/guide-toolbar.png] Tool Bar
-
- Live demo of a tool bar: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:toolBar iconSize="big">
- <tc:button label="#{bundle.toolbarAddressList}" action="#{controller.search}" immediate="true"
- image="image/org/tango-project/tango-icon-theme/32x32/mimetypes/x-office-address-book.png"
- disabled="#{facesContext.viewRoot.viewId == '/application/list.jsp'}"/>
- <tc:button label="#{bundle.listNew}" action="#{controller.createAddress}"
- image="image/org/tango-project/tango-icon-theme/32x32/actions/contact-new.png"/>
- <tc:button label="#{bundle.toolbarAbout}"
- image="image/org/tango-project/tango-icon-theme/32x32/apps/help-browser.png">
- <tc:popupReference for=":page:about"/>
- </tc:button>
- <tc:button label="#{bundle.admin}" action="#{admin.admin}"
- image="image/org/tango-project/tango-icon-theme/32x32/categories/preferences-system.png"/>
-</tc:toolBar>
-+------------------------------------------+
-
-* {Popup}
-
- Popups are used to render small modal dialogs inside the current screen. The original screen is disabled until
- the popup is released with one of the popup buttons.\
- \
-
-[images/guide-popup.png] Tool Bar
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:popup id="about" width="300" height="220" left="200" top="200">
- <tc:box label="About">
- <f:facet name="layout">
- <tc:gridLayout rows="150px;*;fixed" columns="150px;*"/>
- </f:facet>
-
- <tc:image width="150" height="150"
- value="image/org/tango-project/tango-icon-theme/address-book-splash-screen.png"/>
- <tc:panel>
- ...
- </tc:panel>
-
- <tc:cell spanX="2"/>
-
- <tc:cell spanX="2">
- <tc:panel>
- <f:facet name="layout">
- <tc:gridLayout columns="*;fixed"/>
- </f:facet>
- <tc:cell/>
- <tc:button label="OK">
- <tc:attribute name="popupClose" value="immediate"/>
- </tc:button>
- </tc:panel>
- </tc:cell>
- </tc:box>
-</tc:popup>
-+------------------------------------------+
-
-* {File Upload}
-
- The file select control can be used to upload files.\
- \
-
-[images/guide-upload.png] File Upload
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:file value="#{controller.uploadedFile}" required="true">
- <tc:validateFileItem contentType="image/*"/>
-</tc:file>
-+------------------------------------------+
-
-{Features and Concepts}
-
-* {Layout}
-
- Tobago organizes the placement of components with the help of layout managers. The main layout manager
- is called grid layout. It divides the available rectangular space into grid cells. The grid is spawned
- by the column and row values of the <<<\<tc:gridLayout\>>>> tag. The syntax of these values is based on
- the {{{http://www.w3.org/TR/html401/types.html#type-multi-length}multi-length notation}} known from HTML.
-
- To add a layout manager to a container like box, panel or page you have to add a layout facet (i.e. a facet
- with the name 'layout') to the respective container tag.
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:panel>
- <f:facet name="layout">
- <tc:gridLayout columns="*" rows="fixed;fixed;*"/>
- </f:facet>
- <tx:in label="First Name"/>
- <tx:in label="Last Name"/>
- <tc:cell />
-</tc:panel>
-+------------------------------------------+
-
- In this example we place to two input controls with labels into two consecutive rows. Below the two input fields
- we add a spacer element. The layout token '<<<fixed>>>' advises the layout manager to give the input control
- the height, which this kind of control normally possesses in the selected theme.
-
- The values of the column and row attributes of the <<<\<tc:gridLayout\>>>> tag can contain a semicolon separated
- list of layout tokens. A layout token can be an exact length in pixels like <<<200px>>>, a percentage length like <<<25%>>>,
- a relative length like <<<2*>>>, or a specific length called <<<fixed>>>, which's exact length is determined by the
- theme and make sure the control is usable -- a single-line input control for example needs to be so high that
- characters from the assigned font can be read inside the control.
-
- Relative lengths are determined last by the layout manager. The available remaining space is distributed among the
- existing relative lengths. Each length receives space proportional to the integer before the '<<<*>>>'. A single
- '<<<*>>>' is a shorthand for '<<<1*>>>'.
-
- The layout manager handles the <<<rendered>>> attribute of controls, too. If the <<<rendered>>> attribute is
- dynamically defined by a value binding, the page can contain fewer controls in some cases than in others.
- The layout manager can then distribute the newly available space between the remaining relative and percentage
- lengths.
-
-* {Themes}
-
- A theme defines how the structured view is actually rendered. It provides the look & feel of the controls inside a
- view. It appoints colors, dimensions, spacing, fonts and other graphical properties.
-
- Tobago includes a small collection of themes called after cities on the island Tobago: Scarborough, Speyside,
- Charlotteville, and Richmond. Scarborough is a basic theme, which tries to focus on features of plain
- HTML, Speyside is the main theme of Tobago, Charlotteville and Richmond are mainly color variations of Speyside.\
- \
-
-[images/guide-theme-scarborough.png] Scarborough
-
- Scarborough\
- \
-
-[images/guide-theme-speyside.png] Speyside
-
- Speyside\
- \
-
-[images/guide-theme-charlotteville.png] Charlotteville
-
- Charlotteville\
- \
-
-[images/guide-theme-richmond.png] Richmond
-
- Richmond
-
-* {Markup}
-
- Since you don't have direct control over design without writing your own theme, Tobago supports the concept of
- markup. You can assign certain logical markup values to a control to fine-tune the rendering. A theme specifies
- the supported markup for every control. The standard theme already provides some helpful markups.\
- \
-
-*-----------------------+-------------------------+
-| <<<\<tc:out\>>>> | strong, deleted, number |
-*-----------------------+-------------------------+
-| <<<\<tc:in\>>>> | number |
-*-----------------------+-------------------------+
-| <<<\<tc:label\>>>> | number |
-*-----------------------+-------------------------+
-| <<<\<tc:treeNode\>>>> | strong |
-*-----------------------+-------------------------+
-
- Also see the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-standard/src/main/resources/META-INF/tobago-config.xml}standard <<<tobago-config.xml>>>}}
-
- The markup <<<strong>>> is normally emphasized, <<<deleted>>> is rendered struck out, and <<<number>>> is
- right aligned. Multiple markups can be combined as a comma separated list:
-
-+------------------------------------------+
-...
-<tc:label value="Normal"/>
-<tc:out value="999.99"/>
-
-<tc:label value="Number"/>
-<tc:out markup="number" value="999.99"/>
-
-<tc:label value="Emphasized"/>
-<tc:out markup="strong" value="999.99"/>
-
-<tc:label value="Emphasized Number"/>
-<tc:out markup="number,strong" value="999.99"/>
-...
-+------------------------------------------+
-
- This code fragment is rendered like this:\
- \
-
-[images/guide-markup.png] Markup example
-
- You can add markup in your own theme or extend the current themes on the fly by adding a <<<\<renderers\>>>> section
- into the <<<tobago-config.xml.>>>
-
- The address book example adds markup values to the <<<\<tc:progress\>>>> control to be able to colorize the control
- depending on the criticallity of the progress value. On the administration page the progress control is used to
- visualize the memory consumption of the VM.
-
-+------------------------------------------+
-<renderers>
- <renderer>
- <name>Progress</name>
- <supported-markup>
- <markup>ok</markup>
- <markup>warn</markup>
- <markup>error</markup>
- </supported-markup>
- </renderer>
-</renderers>
-+------------------------------------------+
-
- See the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-war/src/main/webapp/WEB-INF/tobago-config.xml}address book <<<tobago-config.xml>>>}} for a complete example.
-
- The various progress variants look like this:\
- \
-
-[images/guide-progress.png] Progress markup
-
-
- Markup attributes are rendered into HTML as extra CSS style classes, which can be used to modify the normal
- styling of a control. In the progress example the following CSS is added to the Speyside theme:
-
-+------------------------------------------+
-.tobago-progress-value-markup-ok {
- background: green;
-}
-
-.tobago-progress-value-markup-warn {
- background: yellow;
-}
-
-.tobago-progress-value-markup-error {
- background: red;
-}
-+------------------------------------------+
-
- See the address book example
- {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-web/src/main/webapp/tobago-resource/html/speyside/standard/style/tobago.css}Speyside <<<tobago.css>>>}}.
-
- The <<<tobago.css>>> file is collected by the Tobago resource manager and can be used to overwrite and extend the
- default <<<tobago.css>>> file of the theme.
-
- Tobago 1.0.x and Tobago 1.5.x are using the old name <<<style.css>>>, since Tobago 2.0.0
- <<<tobago.css>>> is used, <<<style.css>>> will also be included for compatibility (in Tobago 2.x).
-
- The {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-example/}example theme}} provides
- an example for styling sheet cells and contains more complex examples of markup, which need addtional JavaScript
- to generate more dynamic behaviours like fade-out effects or client-side change detection.
-
-* {Partial Rendering}
-
- To avoid the reload of complete screens Tobago provides partial rendering, which advises the client to update
- only parts of the screen to optimize the amount of data sent to the client and the time to render necessary updates.
- Some controls like the tab control and the sheet directly support partial rendering. Whereas container
- controls like the generic panel allow to group arbitrary controls to be able to update them exclusively as a group.
-
-* {Virtual Forms}
-
- The page tag establishes an implicit form for all controls on the screen. The form tag allows to divide these
- controls into smaller groups to be able to manage validation only for these grouped controls.
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-<tc:form>
- <tx:selectOneChoice label="#{bundle.footerLanguage}"
- value="#{controller.language}">
- <f:selectItems value="#{controller.languages}"/>
- <f:facet name="change">
- <tc:command action="#{controller.languageChangedList}"/>
- </f:facet>
- </tx:selectOneChoice>
-</tc:form>
-+------------------------------------------+
-
-* {Security}
-
- The extension module tobago-security allows to protect method bindings with the help of annotations. The module
- provides alternative command components with security handling. The available annotations are <<<...@RolesAllowed>>>,
- <<<...@DenyAll>>>, and <<<...@PermitAll>>>.
-
- A code fragment from the address book example:
-
-+------------------------------------------+
-public class AdminController {
-
- @RolesAllowed("admin")
- public String admin() {
- return OUTCOME_ADMIN;
- }
-
- ...
-}
-+------------------------------------------+
+ ~~ 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.
+
+ ------
+ Guide to Tobago
+ ------
+
+{Guide to Tobago}
+
+ <This guide covers primarily Tobago 1 and 2. Most basic ideas are the same in Tobago 3, but
+ documented in the demo application.>
+
+====================
+
+ Tobago is a JavaServer Faces (JSF) framework and component library. It provides a comfortable way to layout screens
+ of desktop-like applications with a consistent look & feel. Tobago emphasizes the separation of structure
+ and design of screens. Screens are developed independently of the view technology -- no HTML, CSS, or JavaScript.
+ Because of strict separation a screen can be displayed with different themes. These themes can be used to render
+ screens according to different corporate design without changing the sources of the screens.
+
+ This guide assumes basic knowledge about JSF. For more information about JSF see one of the various books about JSF,
+ the {{{http://java.sun.com/javaee/5/docs/tutorial/doc/bnaph.html}Sun Java 5 Tutorial}} or
+ the {{{http://java.sun.com/javaee/javaserverfaces/download.html}JSF Specification.}}
+
+{Content}
+
+ \
+
+%{toc|fromDepth=0|toDepth=4}
+
+{Environment}
+
+* {Building and Deploying the Tobago Examples}
+
+ Tobago uses Maven as a build management system. The provided examples are normally build with Maven, but it would
+ be easy to use an alternative build system. The necessary artifacts can be downloaded {{{./download.html}here}} or
+ from the Maven repository.
+
+ We will use the address book demo as an example in this guide. Since the address book example is currently
+ not part of the Tobago distribution, you have to check-out the sources from the Apache Subversion repository.
+ We will use the latest release tag for this.
+
++------------------------------------------+
+svn co https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/addressbook/ tobago-addressbook
++------------------------------------------+
+
+ You will need Java 5 and Maven 2.0.9 or later to build the address book example. Use the following command to
+ compile the sources and deploy the web application on an embedded Jetty server:
+
++------------------------------------------+
+mvn jetty:run-exploded
++------------------------------------------+
+
+ If you point your browser to {{http://localhost:8080/}} and you will be directed to the login dialog of the address
+ book example.\
+ \
+
+[images/guide-addressbook-login.png] Address Book Login
+
+ You can click on the guest/guest or admin/admin links or fill in the authentication information yourself
+ and press the 'Login' button. After displaying a splash screen for a while the application will direct you to
+ the address list page.\
+ \
+
+[images/guide-addressbook-list.png] Address List
+
+ A freshly started instance of the address book example will not contain any addresses in the list. But you can
+ add addresses by pressing the 'New' button in the tool bar. The addresses will be stored in an embedded Derby
+ database.
+
+* {Building Tobago}
+
+ To use the latest version of Tobago you can use the snapshot artifacts build by our continuous integration server Continuum,
+ which are available in the {{{https://repository.apache.org/content/repositories/snapshots/org/apache/myfaces/tobago/}Apache snapshot repository.}}
+
+ Alternatively, you can build Tobago yourself. You will need Java 5 and Maven 2.0.9 or later.
+
+ Check-out Tobago from the Apache Subversion repository
+
++------------------------------------------+
+svn co https://svn.apache.org/repos/asf/myfaces/tobago/trunk/ tobago
++------------------------------------------+
+
+ To build the complete project with all sub-modules you have to enter the following command
+
++------------------------------------------+
+mvn install
++------------------------------------------+
+
+ For more information on building Tobago -- especially the 1.0.x branch -- see {{{./getting-started.html}Getting Started.}}
+
+* {Building your own Tobago Application}
+
+ The Tobago example distribution contains the tobago-example-blank WAR, which can act as starting point for
+ your own Tobago application. Since Tobago is based on JSF you need a JSF implementation if the application server
+ you are targeting doesn't contain one.
+
+ If you cannot use Java 5 or higher you can use retrotranslated JARs from the Tobago distribution to develop and
+ run Tobago applications with Java\ 1.4 (only Tobago 1.0.x).
+
+ A Tobago application is a web application which is packaged as a WAR. For a JSF application the <<<FacesServlet>>> needs
+ to be configured in the <<</WEB-INF/web.xml>>>. To serve the internal resources of Tobago directly from the Tobago
+ JARs the Tobago <<<ResourceServlet>>> has to configured, too. The configuration of a Tobago application is controlled
+ by the <<<WEB-INF/tobago-config.xml>>> file. This can be used to declare the available themes and the default theme.
+ Additionally, it can be used to locally add markup -- see the {{Themes}} section for further information.
+
+* {A Minimal Tobago Page}
+
+ You can use JSP or Facelets to write Tobago pages. For Facelets support the extension module tobago-facelets has to
+ be added as a dependency. Because the address book example uses JSP as rendering technology we will focus on JSP
+ for now.
+
+ Tobago provides two tag libraries -- the core library and the extension library. The corresponding TLDs contain
+ documentation for the provided tags which is generated from annotations on the underlying tag classes. The core tag
+ library contains basic controls and the extension library convenience tags for pre-assembled tag compositions -- for
+ example a composition of a label and an input control.
+
+ A minimal Tobago JSP page looks like this:
+
++------------------------------------------+
+<%@ page contentType="text/html;charset=UTF-8" language="java" %>
+<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
+<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
+<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
+<f:view>
+ <tc:page>
+ <f:facet name="layout">
+ <tc:gridLayout/>
+ </f:facet>
+ <tc:out value="Hello World"/>
+ </tc:page>
+</f:view>
++------------------------------------------+
+
+ A similar page is part of the blank WAR: \
+ {{https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/blank/src/main/webapp/helloWorld.jsp}}
+
+{Creating a Tobago page}
+
+ The address book example needs an address editing page to add new addresses to the address book and to update
+ existing ones.
+
+ A simple version of an address editor allows to edit the first and last name of a person and basic address data
+ like street, house number and city. Such an editor could look like this:\
+ \
+
+[images/guide-simple-editor.png] Simple Address Editor
+
+ This page is generated by the following code:
+
++------------------------------------------+
+<%@ page contentType="text/html;charset=UTF-8" language="java" %>
+<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
+<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
+<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
+<f:view>
+ <tc:page width="400">
+ <f:facet name="layout">
+ <tc:gridLayout rows="fixed;1fr" margin="10"/>
+ </f:facet>
+ <tc:box label="Address">
+ <f:facet name="layout">
+ <tc:gridLayout rows="fixed;fixed;fixed;fixed"/>
+ </f:facet>
+ <tx:in label="First Name"/>
+ <tx:in label="Last Name"/>
+
+ <tc:panel>
+ <f:facet name="layout">
+ <tc:gridLayout columns="6*;1*"/>
+ </f:facet>
+ <tx:in label="Street / No"/>
+ <tc:in />
+ </tc:panel>
+
+ <tx:in label="City"/>
+ </tc:box>
+
+ <tc:cell />
+ </tc:page>
+</f:view>
++------------------------------------------+
+
+ We have a box with the label "Address" containing four rows of input controls for first name, last name, street,
+ house number, and city.
+
+* {Basic Controls}
+
+ HTML offers a decent set of basic controls. These controls form the basis of the Tobago controls including
+ single-line input controls, text areas, check boxes, radio buttons, links, buttons, labels, and others.
+
+ The Tobago demo contains an overview page for the basic controls.\
+ \
+
+[images/guide-basic-controls.png] Basic Controls
+
+ Live demo of the basic controls: {{http://tobago-vm.apache.org/demo-2-release/faces/content/01-basic/basic.xhtml}}
+
+ The basic controls page also shows two variants of a normal input control: the date input control and the time input
+ control.
+
+* {Text Input}
+
+ The single-line text input control comes in two flavors: the <<<\<tc:in\>>>> tag from the core tag library (<<<tc>>>
+ is the preferred prefix for the core tag library) and the <<<\<tx:in\>>>> from the extension tag library (<<<tx>>>).
+
+ The extension tag library provides convenient shorthands for boilerplate code. For every input control there
+ is for example an extended version, which layouts a label next before the input field. The label is connected
+ with the field. If the label is clicked the related field is focused.
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tx:in value="#{controller.currentAddress.firstName}"
+ label="#{bundle.editorFirstName}" required="true">
+ <f:validateLength minimum="2" maximum="20"/>
+</tx:in>
++------------------------------------------+
+
+ The <<<value>>> attribute refers the content of the control. If a value binding is used, this content can be written
+ back into a bean property.
+
+ The <<<label>>> attribute generates the textual description for the control. The theme decides how the label is
+ actually rendered, for example it assigns a default width. This width can be overwritten with the <<<labelWidth>>>
+ attribute. If you utilize a value binding to a resource bundle declared by a <<<\<tc:loadBundle\>>>> tag, you
+ automatically get localization for the text labels. An underscore in the label transforms the following
+ character into an access key. The theme normally underlines the access key to make this circumstance visible to
+ the user. The access key can be used to quickly focus the related input control by pressing <<<Alt>>> in combination
+ with the access key.
+
+ If the control is marked as <<<required>>> the respective validation takes place. Additionally, the theme tries to
+ visualize this fact. Speyside renders a small check mark icon inside the field, which vanishes if the field
+ contains any data.
+
+ For more information about the possible attributes of an input tag see the TLD documentation for
+ {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tc/in.html}<<<\<tc:in\>>>>}} and
+ {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tx/in.html}<<<\<tx:in\>>>>}}.
+
+* {Sheet}
+
+ The sheet control is used to display tabular data.
+
+ The address book example uses a sheet to give an overview of all stored addresses.\
+ \
+
+[images/guide-sheet.png] Sheet
+
+ Live demo of a sheet: {{http://tobago-vm.apache.org/demo-2-release/faces/content/02-sheet/sheet.xhtml}}
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:sheet columns="1fr;1fr;1fr" value="#{controller.currentAddressList}"
+ var="address" state="#{controller.selectedAddresses}"
+ sortActionListener="#{controller.sheetSorter}" rows="25"
+ showRowRange="left" showPageRange="right" showDirectLinks="center">
+ <tc:columnEvent event="dblclick" >
+ <tc:command action="#{controller.editAddress}"/>
+ </tc:columnEvent>
+ <tc:column id="firstName" label="#{bundle.listFirstName}" sortable="true"
+ rendered="#{controller.renderFirstName}">
+ <tc:out value="#{address.firstName}"/>
+ </tc:column>
+ <tc:column id="lastName" label="#{bundle.listLastName}" sortable="true"
+ rendered="#{controller.renderLastName}">
+ <tc:out value="#{address.lastName}"/>
+ </tc:column>
+ <tc:column id="dayOfBirth" label="Birthday" sortable="true"
+ rendered="#{controller.renderDayOfBirth}">
+ <tc:out value="#{address.dayOfBirth}">
+ <f:convertDateTime pattern="#{bundle.editorDatePattern}"/>
+ </tc:out>
+ </tc:column>
+</tc:sheet>
++------------------------------------------+
+
+* {Tab Group}
+
+ The tab group control displays rectangular content in the same area of the screen with the help of tab panels.
+
+ In the address book example the tab group is used to structure the input controls for an address into three groups
+ for general, business, and miscellaneous information.\
+ \
+
+[images/guide-tab-group.png] Tab Group
+
+ Live demo of a tab group: {{http://tobago-vm.apache.org/demo-2-release/faces/content/04-tab/tab.xhtml}}
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:tabGroup switchType="reloadTab" immediate="true">
+ <tc:tab label="#{bundle.editorTabPersonal}">
+ <jsp:include page="tab/personal.jsp"/>
+ </tc:tab>
+
+ <tc:tab label="#{bundle.editorTabBusiness}" rendered="#{!controller.simple}">
+ <jsp:include page="tab/business.jsp"/>
+ </tc:tab>
+
+ <tc:tab label="#{bundle.editorTabMisc}" rendered="#{!controller.simple}">
+ <jsp:include page="tab/misc.jsp"/>
+ </tc:tab>
+</tc:tabGroup>
++------------------------------------------+
+
+* {Menu}
+
+ The menu control can be used to render a menu bar at the top of a screen like it is typically used in desktop
+ applications. But the location for menus is not limited to this place.\
+ \
+
+[images/guide-menu.png] Menu
+
+ Live demo of a menu: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:menuBar>
+ <tc:menu label="#{bundle.menuFile}">
+ <tc:menuCommand label="#{bundle.menuFileNew}" action="#{controller.createAddress}" immediate="true"
+ image="image/org/tango-project/tango-icon-theme/16x16/actions/contact-new.png"/>
+ <tc:menuCommand label="Add Dummy Addresses" action="#{controller.addDummyAddresses}" immediate="true"/>
+ <tc:menuSeparator/>
+ <tc:menuCommand label="#{bundle.admin}" action="#{admin.admin}"
+ image="image/org/tango-project/tango-icon-theme/16x16/categories/preferences-system.png"/>
+ <tc:menuSeparator/>
+ <tc:menuCommand label="Logout" action="#{controller.logout}"
+ image="image/org/tango-project/tango-icon-theme/16x16/actions/system-log-out.png"/>
+ </tc:menu>
+
+ <tc:menu label="#{bundle.menuSettings}">
+ ...
+ </tc:menu>
+
+ <tc:menu label="#{bundle.menuHelp}">
+ ...
+ </tc:menu>
+</tc:menuBar>
++------------------------------------------+
+
+* {Tool Bar}
+
+ The tool bar control is used to render a special rectangular area of buttons. There are two versions of toolbars:
+ a standalone version and version that embeds itself in the border of a box. To embed a tool bar it has to be
+ attached to a <<<\<tc:box\>>>> via a toolbar facet.
+
+ The address book example uses a tool bar below the menu to provide convenient access to the most common actions
+ from the menu.\
+ \
+
+[images/guide-toolbar.png] Tool Bar
+
+ Live demo of a tool bar: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:toolBar iconSize="big">
+ <tc:button label="#{bundle.toolbarAddressList}" action="#{controller.search}" immediate="true"
+ image="image/org/tango-project/tango-icon-theme/32x32/mimetypes/x-office-address-book.png"
+ disabled="#{facesContext.viewRoot.viewId == '/application/list.jsp'}"/>
+ <tc:button label="#{bundle.listNew}" action="#{controller.createAddress}"
+ image="image/org/tango-project/tango-icon-theme/32x32/actions/contact-new.png"/>
+ <tc:button label="#{bundle.toolbarAbout}"
+ image="image/org/tango-project/tango-icon-theme/32x32/apps/help-browser.png">
+ <tc:popupReference for=":page:about"/>
+ </tc:button>
+ <tc:button label="#{bundle.admin}" action="#{admin.admin}"
+ image="image/org/tango-project/tango-icon-theme/32x32/categories/preferences-system.png"/>
+</tc:toolBar>
++------------------------------------------+
+
+* {Popup}
+
+ Popups are used to render small modal dialogs inside the current screen. The original screen is disabled until
+ the popup is released with one of the popup buttons.\
+ \
+
+[images/guide-popup.png] Tool Bar
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:popup id="about" width="300" height="220" left="200" top="200">
+ <tc:box label="About">
+ <f:facet name="layout">
+ <tc:gridLayout rows="150px;1fr;fixed" columns="150px;*"/>
+ </f:facet>
+
+ <tc:image width="150" height="150"
+ value="image/org/tango-project/tango-icon-theme/address-book-splash-screen.png"/>
+ <tc:panel>
+ ...
+ </tc:panel>
+
+ <tc:cell spanX="2"/>
+
+ <tc:cell spanX="2">
+ <tc:panel>
+ <f:facet name="layout">
+ <tc:gridLayout columns="1fr;fixed"/>
+ </f:facet>
+ <tc:cell/>
+ <tc:button label="OK">
+ <tc:attribute name="popupClose" value="immediate"/>
+ </tc:button>
+ </tc:panel>
+ </tc:cell>
+ </tc:box>
+</tc:popup>
++------------------------------------------+
+
+* {File Upload}
+
+ The file select control can be used to upload files.\
+ \
+
+[images/guide-upload.png] File Upload
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:file value="#{controller.uploadedFile}" required="true">
+ <tc:validateFileItem contentType="image/*"/>
+</tc:file>
++------------------------------------------+
+
+{Features and Concepts}
+
+* {Layout}
+
+ Tobago organizes the placement of components with the help of layout managers. The main layout manager
+ is called grid layout. It divides the available rectangular space into grid cells. The grid is spawned
+ by the column and row values of the <<<\<tc:gridLayout\>>>> tag. The syntax of these values is based on
+ the {{{http://www.w3.org/TR/html401/types.html#type-multi-length}multi-length notation}} known from HTML.
+
+ To add a layout manager to a container like box, panel or page you have to add a layout facet (i.e. a facet
+ with the name 'layout') to the respective container tag.
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:panel>
+ <f:facet name="layout">
+ <tc:gridLayout columns="1fr" rows="fixed;fixed;1fr"/>
+ </f:facet>
+ <tx:in label="First Name"/>
+ <tx:in label="Last Name"/>
+ <tc:cell />
+</tc:panel>
++------------------------------------------+
+
+ In this example we place to two input controls with labels into two consecutive rows. Below the two input fields
+ we add a spacer element. The layout token '<<<fixed>>>' advises the layout manager to give the input control
+ the height, which this kind of control normally possesses in the selected theme.
+
+ The values of the column and row attributes of the <<<\<tc:gridLayout\>>>> tag can contain a semicolon separated
+ list of layout tokens. A layout token can be an exact length in pixels like <<<200px>>>, a percentage length like <<<25%>>>,
+ a relative length like <<<2*>>>, or a specific length called <<<fixed>>>, which's exact length is determined by the
+ theme and make sure the control is usable -- a single-line input control for example needs to be so high that
+ characters from the assigned font can be read inside the control.
+
+ Relative lengths are determined last by the layout manager. The available remaining space is distributed among the
+ existing relative lengths. Each length receives space proportional to the integer before the '<<<*>>>'. A single
+ '<<<*>>>' is a shorthand for '<<<1*>>>'.
+
+ The layout manager handles the <<<rendered>>> attribute of controls, too. If the <<<rendered>>> attribute is
+ dynamically defined by a value binding, the page can contain fewer controls in some cases than in others.
+ The layout manager can then distribute the newly available space between the remaining relative and percentage
+ lengths.
+
+* {Themes}
+
+ A theme defines how the structured view is actually rendered. It provides the look & feel of the controls inside a
+ view. It appoints colors, dimensions, spacing, fonts and other graphical properties.
+
+ Tobago includes a small collection of themes called after cities on the island Tobago: Scarborough, Speyside,
+ Charlotteville, and Richmond. Scarborough is a basic theme, which tries to focus on features of plain
+ HTML, Speyside is the main theme of Tobago, Charlotteville and Richmond are mainly color variations of Speyside.\
+ \
+
+[images/guide-theme-scarborough.png] Scarborough
+
+ Scarborough\
+ \
+
+[images/guide-theme-speyside.png] Speyside
+
+ Speyside\
+ \
+
+[images/guide-theme-charlotteville.png] Charlotteville
+
+ Charlotteville\
+ \
+
+[images/guide-theme-richmond.png] Richmond
+
+ Richmond
+
+* {Markup}
+
+ Since you don't have direct control over design without writing your own theme, Tobago supports the concept of
+ markup. You can assign certain logical markup values to a control to fine-tune the rendering. A theme specifies
+ the supported markup for every control. The standard theme already provides some helpful markups.\
+ \
+
+*-----------------------+-------------------------+
+| <<<\<tc:out\>>>> | strong, deleted, number |
+*-----------------------+-------------------------+
+| <<<\<tc:in\>>>> | number |
+*-----------------------+-------------------------+
+| <<<\<tc:label\>>>> | number |
+*-----------------------+-------------------------+
+| <<<\<tc:treeNode\>>>> | strong |
+*-----------------------+-------------------------+
+
+ Also see the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-standard/src/main/resources/META-INF/tobago-config.xml}standard <<<tobago-config.xml>>>}}
+
+ The markup <<<strong>>> is normally emphasized, <<<deleted>>> is rendered struck out, and <<<number>>> is
+ right aligned. Multiple markups can be combined as a comma separated list:
+
++------------------------------------------+
+...
+<tc:label value="Normal"/>
+<tc:out value="999.99"/>
+
+<tc:label value="Number"/>
+<tc:out markup="number" value="999.99"/>
+
+<tc:label value="Emphasized"/>
+<tc:out markup="strong" value="999.99"/>
+
+<tc:label value="Emphasized Number"/>
+<tc:out markup="number,strong" value="999.99"/>
+...
++------------------------------------------+
+
+ This code fragment is rendered like this:\
+ \
+
+[images/guide-markup.png] Markup example
+
+ You can add markup in your own theme or extend the current themes on the fly by adding a <<<\<renderers\>>>> section
+ into the <<<tobago-config.xml.>>>
+
+ The address book example adds markup values to the <<<\<tc:progress\>>>> control to be able to colorize the control
+ depending on the criticallity of the progress value. On the administration page the progress control is used to
+ visualize the memory consumption of the VM.
+
++------------------------------------------+
+<renderers>
+ <renderer>
+ <name>Progress</name>
+ <supported-markup>
+ <markup>ok</markup>
+ <markup>warn</markup>
+ <markup>error</markup>
+ </supported-markup>
+ </renderer>
+</renderers>
++------------------------------------------+
+
+ See the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-war/src/main/webapp/WEB-INF/tobago-config.xml}address book <<<tobago-config.xml>>>}} for a complete example.
+
+ The various progress variants look like this:\
+ \
+
+[images/guide-progress.png] Progress markup
+
+
+ Markup attributes are rendered into HTML as extra CSS style classes, which can be used to modify the normal
+ styling of a control. In the progress example the following CSS is added to the Speyside theme:
+
++------------------------------------------+
+.tobago-progress-value-markup-ok {
+ background: green;
+}
+
+.tobago-progress-value-markup-warn {
+ background: yellow;
+}
+
+.tobago-progress-value-markup-error {
+ background: red;
+}
++------------------------------------------+
+
+ See the address book example
+ {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-web/src/main/webapp/tobago-resource/html/speyside/standard/style/tobago.css}Speyside <<<tobago.css>>>}}.
+
+ The <<<tobago.css>>> file is collected by the Tobago resource manager and can be used to overwrite and extend the
+ default <<<tobago.css>>> file of the theme.
+
+ Tobago 1.0.x and Tobago 1.5.x are using the old name <<<style.css>>>, since Tobago 2.0.0
+ <<<tobago.css>>> is used, <<<style.css>>> will also be included for compatibility (in Tobago 2.x).
+
+ The {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-example/}example theme}} provides
+ an example for styling sheet cells and contains more complex examples of markup, which need addtional JavaScript
+ to generate more dynamic behaviours like fade-out effects or client-side change detection.
+
+* {Partial Rendering}
+
+ To avoid the reload of complete screens Tobago provides partial rendering, which advises the client to update
+ only parts of the screen to optimize the amount of data sent to the client and the time to render necessary updates.
+ Some controls like the tab control and the sheet directly support partial rendering. Whereas container
+ controls like the generic panel allow to group arbitrary controls to be able to update them exclusively as a group.
+
+* {Virtual Forms}
+
+ The page tag establishes an implicit form for all controls on the screen. The form tag allows to divide these
+ controls into smaller groups to be able to manage validation only for these grouped controls.
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+<tc:form>
+ <tx:selectOneChoice label="#{bundle.footerLanguage}"
+ value="#{controller.language}">
+ <f:selectItems value="#{controller.languages}"/>
+ <f:facet name="change">
+ <tc:command action="#{controller.languageChangedList}"/>
+ </f:facet>
+ </tx:selectOneChoice>
+</tc:form>
++------------------------------------------+
+
+* {Security}
+
+ The extension module tobago-security allows to protect method bindings with the help of annotations. The module
+ provides alternative command components with security handling. The available annotations are <<<...@RolesAllowed>>>,
+ <<<...@DenyAll>>>, and <<<...@PermitAll>>>.
+
+ A code fragment from the address book example:
+
++------------------------------------------+
+public class AdminController {
+
+ @RolesAllowed("admin")
+ public String admin() {
+ return OUTCOME_ADMIN;
+ }
+
+ ...
+}
++------------------------------------------+
diff --git a/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/FlexLayoutTagDeclaration.java b/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/FlexLayoutTagDeclaration.java
index 76fa6e9..d1a8806 100644
--- a/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/FlexLayoutTagDeclaration.java
+++ b/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/FlexLayoutTagDeclaration.java
@@ -58,7 +58,7 @@ public interface FlexLayoutTagDeclaration extends HasIdBindingAndRendered, IsVis
* This value defines the layout constraints for column layout.
* It is a semicolon separated list of layout tokens '<n>*', '<measure>' or the keyword 'auto'.
* Where <n> is a positive integer or empty and <measure> is a valid CSS length.
- * Example: '2*;*;100px;3rem;auto'.
+ * Example: '2fr;1fr;100px;3rem;auto'.
*/
@TagAttribute
@UIComponentTagAttribute(type = "org.apache.myfaces.tobago.layout.MeasureList")
@@ -68,7 +68,7 @@ public interface FlexLayoutTagDeclaration extends HasIdBindingAndRendered, IsVis
* This value defines the layout constraints for row layout.
* It is a semicolon separated list of layout tokens '<n>*', '<measure>' or the keyword 'auto'.
* Where <n> is a positive integer or empty and <measure> is a valid CSS length.
- * Example: '2*;*;100px;3rem;auto'.
+ * Example: '2fr;1fr;100px;3rem;auto'.
*/
@TagAttribute
@UIComponentTagAttribute(type = "org.apache.myfaces.tobago.layout.MeasureList")
diff --git a/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/SplitLayoutTagDeclaration.java b/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/SplitLayoutTagDeclaration.java
index f40622f..6abc7af 100644
--- a/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/SplitLayoutTagDeclaration.java
+++ b/tobago-core/src/main/java/org/apache/myfaces/tobago/internal/taglib/component/SplitLayoutTagDeclaration.java
@@ -60,7 +60,7 @@ public interface SplitLayoutTagDeclaration
* This value defines the layout constraints for column layout.
* It is a semicolon separated list of layout tokens '<n>*', '<measure>' or the keyword 'auto'.
* Where <n> is a positive integer or empty and <measure> is a valid CSS length.
- * Example: '2*;*;100px;3rem;auto'.
+ * Example: '2fr;1fr;100px;3rem;auto'.
*/
@TagAttribute
@UIComponentTagAttribute(type = "org.apache.myfaces.tobago.layout.MeasureList")
@@ -70,7 +70,7 @@ public interface SplitLayoutTagDeclaration
* This value defines the layout constraints for row layout.
* It is a semicolon separated list of layout tokens '<n>*', '<measure>' or the keyword 'auto'.
* Where <n> is a positive integer or empty and <measure> is a valid CSS length.
- * Example: '2*;*;100px;3rem;auto'.
+ * Example: '2fr;1fr;100px;3rem;auto'.
*/
@TagAttribute
@UIComponentTagAttribute(type = "org.apache.myfaces.tobago.layout.MeasureList")
diff --git a/tobago-example/tobago-example-demo/src/main/webapp/content/10-intro/50-migration/99-migration/1.0_to_1.5.xhtml b/tobago-example/tobago-example-demo/src/main/webapp/content/10-intro/50-migration/99-migration/1.0_to_1.5.xhtml
index bb15ea8..95553ac 100644
--- a/tobago-example/tobago-example-demo/src/main/webapp/content/10-intro/50-migration/99-migration/1.0_to_1.5.xhtml
+++ b/tobago-example/tobago-example-demo/src/main/webapp/content/10-intro/50-migration/99-migration/1.0_to_1.5.xhtml
@@ -147,62 +147,62 @@
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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="* * *">
+ <tc:flexLayout columns="1fr 1fr 1fr">
<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>