Reviewers: jlabanca,
Description:
NOTE: At this point, I'm looking for a design review of the code while
I'm in the early stages of implementation. This isn't ready for a code
review.
Adding a new ElementBuilder API to build DOM Elements using the builder
pattern. There are two implementations: one that builds using DOM
manipulation, and another that builds using String concatenation and
innerHtml. The latter can be user in a regular JVM to create an HTML
string, which will hopefully help with server side rendering in the
future. Both can be used on the client, which allow an app to optimize
depending on which is faster. There are a lot of classes here, so I'll
explain what they are.
At the core, we have the ElementBuilderBase interface and its
subclasses, one for each element type (ex. DivElementBuilder,
SelectElementBuilder). These interfaces mirror the Element JSO types,
with short method names to reduce the verbosity of the builder. You can
build an element by doing something like
divBuilder.id("myDiv").title("my title").end(). If you start a sub
element, you get a builder with methods specific to the new element.
For example, selectBuilder.startOption() returns an
OptionElementBuilder, with methods like disabled() and
defaultSelected(). Note that currently, the only builder subclasses are
Div, Select, and Option. There is also a StyleBuilder for building the
style attribute (similar to SafeStylesBuilder, but generic enough to
work for DOM or HTML). I'll add the rest once we've finalized the
design.
Next, we have the two implementations of these interfaces: one for DOM
and one for HTML. For example, DivElementDomBuilder is a concrete class
to build a div using DOM manipulation, while DivElementHtmlBuilder is a
concrete class to build a div using HTML manipulation. The HTML
versions expose asSafeHtml(), which allows users to access the string
(useful for server side rendering).
Then, there are two impl clases: DomBuilderImpl and HtmlBuilderImpl. In
practice, the concrete implementations of the ElementBuilder interfaces
actually just delegate to a shared instead of one of these impl classes.
That has the benefit that we don't create an object for every single
element that is created (just one object for every element type). The
impl classes are responsible for builder the Element/String, and they
maintain state to ensure that they fire IllegalStateExceptions in
similar circumstances. For example, technically DomBuilderImpl can set
an attribute after setting innerHtml, but that wouldn't work in
HtmlBuilderImpl, so both fire an exception in this case.
Finally, there are the ElementFactory classes, which return a new top
level element builder. ElementFactory#get() will return either
DomElementFactory or HtmlElementFactory, depending on which is optimal
for the platform. Alternatively, user can access the DomElementFactory
or HtmlElementFactory directly. The factory has
createXXXElementBuilder() methods to create a builder for each element.
The classes in the safecss package are improvements to SafeStylesUtils
to make it easier to add attributes. I separated those into a separate
change.
http://gwt-code-reviews.appspot.com/1454808/
Please review this at http://gwt-code-reviews.appspot.com/1455802/
Affected files:
A user/src/com/google/gwt/dom/builder/DomBuilder.gwt.xml
A user/src/com/google/gwt/dom/builder/client/DivElementDomBuilder.java
A user/src/com/google/gwt/dom/builder/client/DomBuilderFactory.java
A user/src/com/google/gwt/dom/builder/client/DomBuilderImpl.java
A user/src/com/google/gwt/dom/builder/client/ElementDomBuilder.java
A user/src/com/google/gwt/dom/builder/client/ElementDomBuilderBase.java
A user/src/com/google/gwt/dom/builder/client/OptionElementDomBuilder.java
A user/src/com/google/gwt/dom/builder/client/SelectElementDomBuilder.java
A user/src/com/google/gwt/dom/builder/client/StyleDomBuilder.java
A user/src/com/google/gwt/dom/builder/client/package-info.java
A user/src/com/google/gwt/dom/builder/shared/DivElementBuilder.java
A user/src/com/google/gwt/dom/builder/shared/DivElementHtmlBuilder.java
A user/src/com/google/gwt/dom/builder/shared/ElementBuilder.java
A user/src/com/google/gwt/dom/builder/shared/ElementBuilderBase.java
A user/src/com/google/gwt/dom/builder/shared/ElementBuilderFactory.java
A user/src/com/google/gwt/dom/builder/shared/ElementHtmlBuilder.java
A user/src/com/google/gwt/dom/builder/shared/ElementHtmlBuilderBase.java
A user/src/com/google/gwt/dom/builder/shared/HtmlBuilderFactory.java
A user/src/com/google/gwt/dom/builder/shared/HtmlBuilderImpl.java
A user/src/com/google/gwt/dom/builder/shared/OptionElementBuilder.java
A user/src/com/google/gwt/dom/builder/shared/OptionElementHtmlBuilder.java
A user/src/com/google/gwt/dom/builder/shared/SelectElementBuilder.java
A user/src/com/google/gwt/dom/builder/shared/SelectElementHtmlBuilder.java
A user/src/com/google/gwt/dom/builder/shared/StyleBuilder.java
A user/src/com/google/gwt/dom/builder/shared/StyleHtmlBuilder.java
A user/src/com/google/gwt/dom/builder/shared/package-info.java
M user/src/com/google/gwt/safecss/SafeCss.gwt.xml
M user/src/com/google/gwt/safecss/shared/SafeStylesBuilder.java
M user/src/com/google/gwt/safecss/shared/SafeStylesUtils.java
M user/src/com/google/gwt/user/User.gwt.xml
A user/test/com/google/gwt/dom/builder/DomBuilderSuite.java
A user/test/com/google/gwt/dom/builder/HtmlBuilderSuite.java
A
user/test/com/google/gwt/dom/builder/client/DivElementDomBuilderTest.java
A
user/test/com/google/gwt/dom/builder/client/OptionElementDomBuilderTest.java
A
user/test/com/google/gwt/dom/builder/client/SelectElementDomBuilderTest.java
A
user/test/com/google/gwt/dom/builder/shared/DivElementHtmlBuilderTest.java
A user/test/com/google/gwt/dom/builder/shared/ElementBuilderTestBase.java
A
user/test/com/google/gwt/dom/builder/shared/OptionElementHtmlBuilderTest.java
A
user/test/com/google/gwt/dom/builder/shared/SelectElementHtmlBuilderTest.java
M user/test/com/google/gwt/safecss/SafeCssGwtSuite.java
M user/test/com/google/gwt/safecss/SafeCssJreSuite.java
A user/test/com/google/gwt/safecss/shared/GwtSafeStylesUtilsTest.java
M user/test/com/google/gwt/safecss/shared/SafeStylesStringTest.java
A user/test/com/google/gwt/safecss/shared/SafeStylesUtilsTest.java
--
http://groups.google.com/group/Google-Web-Toolkit-Contributors
