Upgrade Path

This section discusses the changes you will need to make when upgrading from
one Click version to the next. Please note while the upmost effort is made to ensure
there is no impact between releases, some architectural changes will require
you to modify existing applications to upgrade to a newer version.

If you experience any unexpected and undocumented impacts when upgrading between
versions please email the Click user group.

Version Upgrades

Stateful pages was introduced to make it easier to store page state across
multiple HTTP requests. However developing a stateful page is very different
from developing a stateless one and this lead to Click applications that are
inconsistent and harder to maintain.

In addition stateful page support has never been implemented consistently
across the framework and some components did not work correctly.

Stateful pages are very coarse grained, making it difficult to control
which objects are stored in the session.

Stateful pages have also introduced unnecessary complexity in the framework
itself, which can now be phased out.

Unfortunately there is no direct upgrade path from a stateful page.
However the majority of use cases are catered for by the new stateful
controls: Table, Form, TabbedPanel, Field and AbstractLink.

The bypass validation feature introduced in 2.2.0 raised security
concerns and was removed in this release.

The main problem was with bypassValidation is that
an attacker can set the bypassValidation hidden field to true, thus bypassing
validation on the server. In addition , Form.isValid returned true
even when validation was bypassed.

If you are currently using bypassValidation for dynamic forms,
you can bypass form validation by setting Form.setValidate(false),
for example:

public void onInit() {
super.onInit();
form.add(nameField);
form.add(checkbox);
// NB: when using form.submit() the submit button cannot be
// called 'submit'. If it is, the browser is likely to throw a JS exception.
checkbox.setAttribute("onclick", "form.submit()");
...
// NB: Bind the submit button. If it wasn't clicked it means the Form was submitted
// using JavaScript and we don't want to validate yet
ClickUtils.bind(submit);
// If submit was not clicked, don't validate
if(form.isFormSubmission() && !submit.isClicked()) {
form.setValidate(false);
}
submit.setActionListener(new ActionListener() {
public boolean onAction(Control source) {
// We can safely call isValid from within the submit action handler
// since validation is always active if the submit button was clicked
if (form.isValid()) {
addModel("msg", "Form is valid after validation");
}
return true;
}
});
}

Control IDs now render underscores instead of periods. If you targeted
Controls through CSS or JavaScript where the ID had a period, you need
to change to underscores.

The DateField control now accepts month and day names spelled in the
locale of the browser or application (see
Context.getLocale()).
In previous version a few locales used localized spelling of month and
week days names and the remaining locales used English names.

Unfortunately this change can lead to runtime behavioral errors for
applications using the string based getHtmlImports approach.

As runtime errors are often more expensive to fix than compile time errors,
we have decided to remove the getHtmlImports method from the
Page and Control classes. In addition we have set getHtmlImports
to final in Page and Control. This ensures existing codebases
don't accidentally override this method in custom controls and pages.
In a future release of Click these final methods will be removed as well.

This means Click 2.2.0 will force you to migrate from getHtmlImports
to getHeadElements.

Here is a typical example of converting a getHtmlImports method
to getHeadElements.

Field disabled behavior has changed slightly. In previous versions,
disabled fields were processed and validated which isn't the desired
behavior since HTML form POSTs do not submit disabled fields values.
In addition Form copied disabled field values to domain objects.

Starting from Click 2.2.0 the disabled behavior has changed as follows:

Disabled fields are not processed or validated

Disabled field values are not copied to domain objects

Disabled fields are automatically enabled if the field has an
incoming request parameter, indicating that the field was enabled
on the client using JavaScript. Please note that this behavior does
not apply to Checkbox or Radio fields. See the
setDisabled()
javadoc for details.

In previous releases, the default autobinding mode (public)
binded only public Page fields. In 2.2.0 the default autobinding mode
has been replaced with a new default mode which binds both
public fields and fields annotated with the @Bindable annotation.

Please note, for backward compatibility the autobinding attribute still
accepts the public value.

Added new method Container.replace
for replacing an existing control with a new control. AbstractContainer
has an implementation of this method which should cater for most use cases.

If however you have custom controls that override the
insert or
add
methods, you need to ensure that
replace
will function correctly for your control.

For example, if a custom insert method adds the control to an
internal list the replace method must be overridden to replace
the control on that list as well.

Click automatically deploy resources from JARs and folders on the
classpath that are located under a predefined directory. In previous
versions of Click that directory was META-INF/web.

The new Servlet 3.0 specification introduced a similar concept where
resources can be packaged in a JAR and served directly without having
to be deployed. The directory defined by Servlet 3.0 is
META-INF/resources.

Click 2.1.0 aligns with Servlet 3.0 in that resources are also deployed
from META-INF/resources.

For backwards compatibility Click will still deploy resources from
META-INF/web, however it is highly recommended to deploy
resources from META-INF/resources instead.

Version 2.0.1 Upgrade

This is our first Apache Incubator release and is based on Click 1.5.1.

Please note that because of licensing issues, certain third-party
libraries were removed and are hosted externally.

Note the following changes when upgrading from 1.5 to 2.0.1:

All net.sf.click.* packages have been renamed to org.apache.click.*.
When upgrading you must replace all references to net.sf.click.* with
org.apache.click.*.

You can use your favorite IDE and do a global search/replace or
alternatively use Ant's replace task.

Make sure you update the files web.xml and click.xml as well.

JSCalendar which is licensed under LGPL is incompatible with Apache license
and had to be removed. DateField was refactored accordingly and does
not contain any Calendar specific code.

The following methods were removed:

public String getCalendarPattern()

public boolean getShowTime() and public void setShowTime(boolean showTime)

public String getStyle() and public void setStyle(String style)

protected int getFirstDayOfWeek()

protected String parseDateFormatPattern(String pattern)

Since the calendar popup is not available to help users pick dates, it
becomes difficult for users to know the format of the Date.
To remedy this situation, Click 2.0.1 introduces a new resource key,
date-title, which is set as the title of DateField. The new
property provides users with visual feedback of the date format
specified on the DateField. For those building i18n applications remember to add this property
to DateField_<lang>.properties.
You can also send us patches for your languages and we will
include it in the distribution.

A new project called Click Calendar
was created as a port of the old DateField functionality. This project
contains a CalendarField which can be used as a replacement for the
old DateField.

The Chart controls which is licensed under LGPL is incompatible with
Apache license and had to be moved.

A new project called Click Charts
was created as a port of the Chart controls. This project consists of
the BarChart, LineChart and PieChart controls and can be used as drop
in replacements. See the project for more details.

Deprecated methods: Control.setListener(Object, String) and
Control.getContext().
These methods have been deprecated on the Control interface as they are not required for ClickServlet -> Control API.
This refactoring is part of making the Control interface as small as possible,
which allows more flexibility in future releases.

Note these methods are still available on AbstractControl,
so this change should have minimal impact on existing code bases.

Upgrade custom Control rendering code to use new
render
method. This method allows improved rendering performance, because all controls can be
rendered from a single buffer that is created when rendering starts.

If your created custom controls override toString(), please adapt it to the following pattern. From this:

This leads us back to step 1. where CustomField.render invokes
super.toString. This creates the infinite loop and leads to the StackOverflowError.

The fix is straight forward. If you override a Control's render
method, but still want to render the Control's default markup, invoke
super.render instead of super.toString.
Here is the correct version:

Certain controls were retrofitted as containers. These include
Form,
FieldSet
and Panel.

Click 1.5 introduces two new properties: file-size-limit-exceeded-error
and post-size-limit-exceeded-error.
For those building i18n applications remember to add these two properties
to your click-control_<lang>.properties.If you send us patches for your preferred language we will include them in the distribution.

It is possible to write your own LogService instance or extend from
an existing implementation. To setup Click to use an alternative instance you have to
specify the LogService implementation in click.xml: