IT Mill Toolkit 5 Packaging PROPOSAL

We need to package Tk5 so that, for a developer on any supported platform, it's

  1. easy to get examples up-and-running
  2. easy to get started on a new application
  3. easy to theme the application
  4. relatively easy to start extending the widget set

All while keeping the packaging process simple.

Definition: theme A theme consists of CSS, images, and customlayouts + their resources. Themes are contained in a directory, placed by convention in a specific location in the project structure. The theme name is the same as the name of the directory in which is is placed. 

Comment (joonas): 
Theme will be placed in (Root of the Webapp)/themes/nameofthetheme/
Layouts will be put into (Root of the Webapp)/themes/nameofthetheme/layouts/layoutstylename.html
 
- Should we have themes or theme; layouts or layout?

Definition: extended widget set New widgets are created using (gwt) java. In order to create a extended widget set one must do two things: 1) create a new widget, by extending Widget and implementing Paintabe 2) extend the DefaultWidgetFactory? and create logic to instantiate the new widget

Proposed strategy

The IT Mill Toolkit 5 package is contained in one zip.

  • The zip contains original gwt distribution packages, with the version used to build tk5 widgets, for all platforms.
    • -> this will produce a large package, but that's ok
  • The contents of the zip is structured as a eclipse project, and can be directly used as such.
  • The eclipse project contains the example applications, ready to run or modify.
  • The eclipse project contains the example theme, ready to be modified.
  • The eclipse project contains the example extended widget set, ready to be modified.
  • The eclipse project contains itmill-toolikit-*.jars, source is in the src directory, but not in the project
    • -> this implies that the eclipse project is not directly used for developing the IT Mill Toolkit itself
  • The eclipse project contains precompiled (javascript) versions of the clientside code, so that no gwt compilation is needed by default, except

GWT is needed only when modifying a extended widget set or creating a new one.

  • An ant script (and task) is provided, capable of extracting gwt for the current platform, and compiling the new or modified widget set. 
Comment (joonas): 
- I would package all architectures and gwt parts (as extracted) inside the main-zip. But have them extracted inside the zip to avoid duplication.

Comment (marc): 
Jani pointed out that for instance Linux users are more used to tar.gz (which for instance retain permissions).
This is a good point, I agree -> tar xvzpf is second nature on linux. 
This implies 3 different toolkit packages, which would also save bandwith and let us know which platforms are most used.

Special devices (e.g iphone) can be supported by creating a specialized theme (e.g "iphonetheme") for that device, and switching themes 'serverside'. In 'extreme' cases, specialized widgets can be used by creating a device-aware widgetfactory. THOUGHT: in the future, we could use generators for device specific resources

"As soon as possible" an itmillProjectCreator java (+ commandline) tool is created. This tool should be designed so that is can be used by a future eclipse plugin.

Extending a widget set

NEW

Due to GWTs lack of reflection, the following is necessary to create an extended widget set:

  1. create the widget, say IFoo
  2. extend DefaultWidgetSet? (previously DefaultWidgetFactory?) or implement WidgetSet?, say FooWidgetSet?
  3. make FooWidgetSet? an entry point by createing a gwt module xml as appropriate
  4. tell the application servlet to use the widget set (entry point) by specifying a widget-set parameter in web.xml

Note: One can create a WidgetSet? which sole purpose is to make the widget set smaller, producing a smaller JS. In the future we could (should) provide a simple UI to create a new WidgetSet?, and allow the user to select which default widgets to include. 

Comment (jani): 
Why one would want to make WidgetSet only smaller? GWT sends only those widgets to client that are actually used, isn't this the case with TK5 also?
Answer (marc):
TK5 uses all components (since it's dynamic, client can't know which will be used). The developer could however decide which components to include.

Directory structure

NEW first draft 
/
/doc
    <documentation by Marko>
/gwt
    <unzipped unmodified platform specific (win, osx, linux) gwt>
/lib (as in "distribution")
    itmill-toolkit-5.0.0-beta.jar
    itmill-toolkit-widgetset-5.0.0-beta.jar
    itmill-toolkit-5.0.0-beta-src.jar
    itmill-toolkit.war
/WebContent
    /META-INF
    /WEB-INF
        itmill-toolkit-license.xml
        web.xml
        /lib (libs required to run TK demos)
            itmill-toolkit-5.0.0-beta.jar
            googlemaps_gwt.jar
            hsqldb.jar
    /ITMILL (place for all tk related stuff not in web-inf)
        /themes
            /example
                styles.css
                    ("@include css/button.css, @include css/...")
                    (/css/button.css)
                    (/img/button-bg.jpg)
                /layouts
                    featurebrowser-mainlayout.html
                    <.. TBD ..>
        /widgetsets (client-side JavaScripts compiled by GWT)
            /com.itmill.toolkit.demo.colorpicker.gwt.WidgetSet
            /com.itmill.toolkit.demo.reservation.gwt.WidgetSet
            /com.itmill.toolkit.terminal.gwt.DefaultWidgetSet
    /src
        <com.itmill.toolkit.demo.*>
/WebServer
    <webserver stuff as in 4.0.3, but additional file(s) are required for HostedMode launch>
/License
    licensing-guidelines.html
    itmill-commercial-license.pdf
.classpath
.project
build.xml
index.html
release-notes.html
start-demo.bat
start-demo.sh
start-demo.txt

14.09.2007 meeting with Marc

Three platform specific packages
 * Win (.zip), Linux (tar.gz) , OSX (zip?)
 * Understand popularity of different platforms
 * Offer more user friendlier attitude towards diff. platforms

Decided that all GWT specific, including gwt-user.jar and service.jar, is stored to /gwt
 * shows that IT Mill has not "tweaked" GWT in any way