Documentation Clarification Request

4 views
Skip to first unread message

claude

unread,
Aug 28, 2006, 9:52:39 PM8/28/06
to Google Web Toolkit
As I dig through behavioral aspects of the GWT, I am finding a number
of details that are not documented. I was hoping I could encourage the
some formal documentation for some of these.

1) One of the things I'm currious about is the use of gwt:module
declarations with alternate baseURL settings. The gwt.js code is
clearly designed to support multiple modules in the same host page.
When an equal sign is in the content attribute of the gwt:module meta
tag, the framework assumes the first part defines the base URL. This is
pretty handy if you want to rename the base directory for a module, and
I've had some success having two modules co-exist in Firefox. However,
this doesn't work in, or IE for some reason, nor the Shell since
GWTShell wants a reference to the module XML file and the host page
needs to be releate to this path (as far as I can tell). I would very
much like to have more than one module hosted in the same page, but
there is no documentationt to clarify what is permissible or intended
in the framework.

2) Also, the module definition files contain many tags that are not
documented, including:
* the 'generate-with' and 'when-type-assignable' tags
* the 'replace-with', 'when-type-is' and 'any' tags
* the 'define-property' and 'set-property' tags
* the 'super-source' tag

Many of these are self-explanatory, but I suspect there are other
non-documented aspects that would add to our understanding if they were
part of the standard documentation. The 'super-source' tag is a
complete mystery.

Should I avoid trying to get more than one module working in the same
host page? Is this intended for the future but not fully functional at
the moment? Why is there a documented 'extend-property' but no
'define-property' and 'set-property' documentation?

br...@google.com

unread,
Aug 29, 2006, 9:07:12 AM8/29/06
to Google Web Toolkit
claude wrote:
> As I dig through behavioral aspects of the GWT, I am finding a number
> of details that are not documented. I was hoping I could encourage the
> some formal documentation for some of these.

We've prioritized documenting the areas of GWT that are most
immediately relevant and least likely to need to be tweaked. But, your
point is well taken. Hopefully, it's apparent that we are serious about
having good documentation, so it's really just a matter of what to
document when.

> 1) One of the things I'm currious about is the use of gwt:module
> declarations with alternate baseURL settings.

> ...

This topic is definitely ready for more formal documentation. It has
seen a lot more use than we anticipated. And with 1.1.10, its behavior
has been pretty well normalized, so that's something we'll get in there
pretty soon.

> 2) Also, the module definition files contain many tags that are not
> documented, including:
> * the 'generate-with' and 'when-type-assignable' tags
> * the 'replace-with', 'when-type-is' and 'any' tags
> * the 'define-property' and 'set-property' tags
> * the 'super-source' tag

These are still intentionally undocumented, but after another couple of
bugfix releases, we will start explaining a bit more about the
underpinnings that hopefully people will find valuable.

> The 'super-source' tag is a
> complete mystery.

Yeah, it's a weird concept, and you'll probably never need to use it.
That's why we didn't prioritize documenting that one.

> Should I avoid trying to get more than one module working in the same
> host page? Is this intended for the future but not fully functional at
> the moment?

I would avoid it right now. If you already have a GWT compile step in
your build, then there's probably no need to do it. Whenever you would
have added two modules to a host page, you could have simply created a
hybrid module that inherits the other two. It's *far* better to compile
modules together since then you get better optimization and
obfuscation.

Why is there a documented 'extend-property' but no
> 'define-property' and 'set-property' documentation?

<define-property> is only useful with the other deferred binding tags
such as <replace-with>, etc.

<extend-property> is documented specifically because it's needed to
specify locales for i18n.

-- Bruce

claude

unread,
Aug 29, 2006, 11:01:43 AM8/29/06
to Google Web Toolkit
Thanks for the thoughtful feedback.

One of the reasons I'm interested in hosting multiple modules in a
single page is to make it possible for non GWT users to leverage some
of these featues. For example, I could write components (modules) that
are relatively independent - say a slick table editor for example --
that could be dropped into other parts of our site by non-GWT
developers and configured inline.

Before the Dictionary class came along I had written my own RootPanel
variant which didn't axe the content of each element being replaced
before I could take a look (I'm glad this was recently corrected BTW).
It is possible to get configuration elements from the page this way,
local to the Widget being injected into the page. My preference would
be to have tags where custom attributes could be used to pass values
into the component being deployed, but it doesn't matter how the
configuration happens, so long as I can package modules independently
and to have them coexist on the same page.

I realize this approach is not central to the GWT framework, which is
more of an application development platform. But it bothers me that our
shop needs to use a tree widget written directly in JavaScript when I
could package something more effective and maintainable for them, given
the rich GWT functionality at our disposal. I can't justify writing new
entry point classes every time they want to add something to a PHP page
for example. I'd like to give them the power to reuse elements that I
build by just adding them to the module meta tags and using a generic
entry point class that can find relevant substitution points based on
property meta tags.

I hope this makes sense. I think the missing piece for me is the
coexisting modules. If you are very close to having this in a supported
state, let me know and I'll identify any bugs for you along the way.

hlima

unread,
Sep 4, 2006, 7:37:38 PM9/4/06
to Google Web Toolkit
Hi,

I totally agree with Claude, the ability to build independent modules
and host any number of them in a foreign page will give a plug-in like
capability to GWT, like the one
possible with Java and Flash Applets.

The hosting site could be developed using any server tecnology and the
GWT's modules could access the data through JSON services, possibly in
another domain.

I think this can be done using iframes, but that way it wouldnt be
simple to keep a common CSS template for the entire site.

The mortgage calculator done by Dan Moore
(http://www.cohomefinder.com/Colorado-mortgage.html) is an example but
it only includes ONE module.

Reply all
Reply to author
Forward
0 new messages