CSS or Java API for Widget property specification...How to choose?

[John Gunther]

When designing a new GWT Widget, how do you decide which properties
are best specified via CSS/stylenames, and which are better done via
your Widget's published Java API?

The Java API based property specification route has significant
advantages over CSS:

o You can rename the properties so that the names are exactly right
for your widget, rather than using the one-size-fits-all property
names of CSS. For example, CSS gives you only "color" but a Java API
can give you "curveColor".

o You can select a specific subset of CSS properties most likely to be
useful for your widget, and those methods will be available in your
Java IDE's drop-down lists. With CSS, the user has to remember exactly
which properties are appropriate for specification via CSS, and which
must be specified via the Java API. No nice dropdown lists to help
them.

o You can write tests that assure that those specific style
manipulations wrapped by your API actually work as you expect in all
GWT browsers. Because there are so many potential CSS styling options,
it is practically impossible to test them all, and report to the user
an exact subset of the "allowed-works in all browsers" CSS styling
choices.

o You can completely change the implementation so that, perhaps, it
does not even use HTML elements at all, or uses other properties/
different elements. Once you introduce stylenames, however, you are
tacitly committed to using elements and their CSS properties in a
specific way and changing the implementation could well break user-
created CSS that relied on the previous underlying implementation.

o You can have a single, consistently defined, interface to your
Widget in a single syntax (Java). With CSS in the mix, users must
navigate two distinct syntaxes, jumping between two different files,
to specify your widget's properties (and sometimes these two avenues
can even collide with each other...not to mention the cascade of
unintended consequences.).

On the other hand, CSS based property specification lets you:

o Write less code.

o Allows users to leverage their CSS know-how in various ways you may
not have even thought of, creating combinatorially rich possibilities
for users.

o Makes it possible for non-Java-aware users to configure certain
aspects of your widget using CSS alone, sort of as if your Widget were
a natively defined HTML widget. Thus your Widget may play better as a
part of a larger, HTML-defined, page, etc.

o Also, I've heard CSS can be faster.

Personally, I'm quite leery of using CSS, because I find it very hard
to imagine all the possible ways the gazillion CSS properties might
interact with (and possibly break) my Widget. How can I really test
that my Widget "works with CSS" when I don't even really know every
possible CSS specification that is available? And I hate to give up
the advantages of the Java API listed above. So, especially for
complex composite widgets that may not have a simple one-to-one
mapping into a well defined collection of HTML elements, I've come to
believe the Java API is often a better overall choice.

When designing a GWT Widget, how do you decide which properties should
be CSS defined, and which Java API defined? In those cases when you
choose CSS, what makes that choice work better for users than if you
had wrapped the same properties via your Widget's Java API?

Note: This post was motivated by (and may be quite biased by) my
attempts to "deeply" integrate CSS stylenames into this widget:

http://gchart.googlecode.com

For example, should there be a stylename that lets you, say, change
the color of curve 1? What would introducing such a stylename commit
me to, in terms of future implementation options, etc., etc. Right
now, I'm strongly leaning toward not providing such "deep" stylename
support, but I'm somewhat uncomfortable with that decision since CSS/
stylename support is a GWT best practice.

John

[Peter Blazejewicz]

hi John,
only few remarks:
- with .css you don't need to recompile code, so modification are
possible after deployment,
- adding API for CSS could results in many getter/setter needed to be
added just to control some compound CSS property. There are many
shortcuts in CSS, for example for border or background, in .css
specyfing background with image and position will be one-line of code,
while the same feature in code will results in several getters/
setters,

Also I don't see what add-on value would be to provide CSS styling via
API properties:
- If I use GWT Designer from Instantiations then changes I made e.g.
to MyWidget.color property (getColor()/setColor(String color) will be
reflected immadiately in Design view. However people not using GWT
Designer would not see anything changed unless they hit "refresh" in
hosted mode.

In Flex charting many properties can be set both in .CSS and from api:
http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=charts_formatting_110_03.html
You could read on that docs that there are limitations of how CSS
styling can be used due to charts implementation details. Similiar
restriction could apply to your widget library.

regards,
Peter

[walden]

John,

It's a great question, and one I've certainly put a lot of thought
into as well. I think the answer has largely to do with the fact that
there are css facets which if not under strict component control,
allow the widget to be broken. There are other css facts that are
nothing but pure styling. In working on custom grid controls, for
example, one of my designs depends on fixed table layout. To expose
that via css would be treacherous. On the other end, playing around
with cell background gradients, border colors, etc. and incurring a
compile step on each tweak is way too slow.

So I think there is no black and white answer, but we just need to
think in terms of stuff we need not to break, especially if it will be
reused by someone other than the original author. Constrain those
attributes hard in code, and leave the rest open in css. That's my
strategy, roughly.

I will also add that when I am prototyping such a component, I leave
as much exposed via css stylesheets as possible, to aid in the
feedback process, but that's a prototyping habit, not a pattern for
production code. Once I've got the behavior I'm seeking, I will pull
the critical attributes out and encapsulate them.

Walden

[John Gunther]

walden - glad to hear someone else also struggles with how to balance
CSS vs Java API specification.

Peter- the Adobe link and related suggestions were particularly
helpful/relevant.

Though the Adobe approach that carefully blends both CSS and api based
specifications looks quite sophisticated, I don't think it's feasible
to add anything that complex to GChart (maybe in a future version if
other/smarter people got involved).

The justification for my decision not to include "deep" CSS support in
GChart is contained in the following (not yet released) javadoc
excerpt (I've changed my mind many times already on this decision, so
if someone comes up with a compelling argument on the other side, I
would not be surprised if I changed it again).

<gchart-javadoc-excerpt>

CSS Style Rule

.gchart-GChart { the GChart's primary top-level styles }

Why such limited CSS support?

One person asked, to paraphrase, "why doesn't GChart provide, say,
a stylename like gchart-GChart-curve-1 that would allow me to style
the first curve?"

Because stylename support is a GWT best practice, I seriously
considered such an approach. But I ultimately decided (except for the
top-level stylename above) to go with a straight Java API based
specification instead because:

* Despite a lot of effort, I couldn't find a good algorithm
for placing tick labels properly unless I knew the font size in pixels
before the chart was rendered in the browser. It is because GChart's
Java API only allows tick label font sizes to be specified in pixels
(ruling out, for example, the relative units CSS allows) that GChart's
simple tick label placement algorithm can work. In general, having all
the info needed to layout chart elements up front (independent of what
is going on in the page that contains the GChart) makes the task of
laying out the chart a lot easier to handle.

* Since Google may add a browser independent vector graphics
library to a future GWT version, I didn't want to lock GChart into an
HTML element based rendering scheme (any stylesheet based curve color
specs could break if GChart started rendering curves with such a
vector graphics package). In general, I wanted to "keep GChart's
implementation options open" by not tacitly exposing their internal
element structure via "deep" stylenames.

* GChart applications could require fine-grained, dynamic
control over chart features (e.g., letting the user select a curve's
color from a pop-up with hundreds of possible choices). CSS is best
for switching between a few predefined style categories (e.g. selected
vs unselected tree items) rather than for such fine-grained control.
Thus even if CSS support were provided and adequate for some
applications, finer-grained API-based styling control would likely
still be needed for others. But having some styling use a stylesheet,
and other styling the Java API, could create additional confusion for
users.

* GChart's Java API specification approach, though not fully
leveraging CSS, compensates for this limitation by providing these
benefits:

o It results in a much more succinct and centralized
(and easy to test) specification of what a GChart can do. Of the
myriad of potential CSS options you might consider using, the API
provides only those you are likely to need. And, because the the CSS
styling options are restricted, they are more likely to have been
cross-browser tested and thus to actually work.

o Your Java IDE's drop down lists and such work with
every GChart feature--thanks to wrapper API methods around GChart's
CSS-powered features. No need to switch from Java IDE tooling to CSS
tooling (which, if your CSS tools are as primitive as mine, is often
just a text editor and a manual).

o Method names can be GChart-specific in a way that
makes it more obvious what they do, and the full OO syntax of Java
clarifies how each specification changes the GChart in question. With
CSS (except for the stylename itself) you are stuck using the generic,
low-level, element-related names for the actual properties. These may
or may not be appropriate, depending on the exact role those element
attributes play in realizing chart features.

o Although CSS has a vast syntax, in point of fact only
a handful of these choices are applicable for a GChart. Thus I didn't
have to add many CSS wrapper methods, and the "API clutter" issue that
often comes up with the use of such wrapper methods was not a serious
concern.

o You still use standard CSS syntax in the arguments you
pass to these CSS wrapper methods. Thus you can still leverage your
CSS knowledge--just not via a stylesheet, and in a more restricted
way.

Overall, your ability to control a GChart's styling directly from
a CSS stylesheet without using Java is analogous to what you get with
a GIF or PGN image: with the exception of a few top-level features
(like border and background for the entire image or GChart), the
detailed internal styling cannot be changed via a CSS stylesheet. This
very limited level of CSS stylesheet control has never been a serious
problem for better known, server-based, charting tools like jFreeChart
or the Google Chart API. So I think it will work out OK for GChart,
too.

</gchart-javadoc-excerpt>