Author: [email protected]
Date: Wed May 20 14:49:15 2009
New Revision: 5448
Modified:
wiki/CssResource.wiki
wiki/CssResourceCookbook.wiki
Log:
Update CssResource documentation to trunk, document the proposed @external
directive.
Modified: wiki/CssResource.wiki
==============================================================================
--- wiki/CssResource.wiki (original)
+++ wiki/CssResource.wiki Wed May 20 14:49:15 2009
@@ -38,7 +38,7 @@
1 Write a CSS file, with or without GWT-specific extensions
1 If GWT-specific extensions are used, define a custom subtype of
CssResource
- 1 Declare a method that returns CssResource or a subtype in an
ImmutableResourceBundle
+ 1 Declare a method that returns CssResource or a subtype in an
ClientBundle
1 When the bundle type is generated with `GWT.create()` a Java
expression that evaluates to the contents of the stylesheets will be created
* Except in the simplest case where the Java expression is a string
literal, it is generally not the case that a CSS file could be generated
into the module output
1 At runtime, call `CssResource.getText()` to retrieve the contents of
the stylesheet
@@ -143,14 +143,14 @@
String mySpriteClass();
}
-class MyResources extends ImmutableResourceBundle {
- @Resource("my.css")
+class MyResources extends ClientBundle {
+ @Source("my.css")
MyCssResource css();
- @Resource("some.png")
+ @Source("some.png")
ImageResource imageAccessor();
- @Resource("some.png")
+ @Source("some.png")
@ImageOptions(repeatStyle=RepeatStyle.Horizontal)
ImageResource repeatingImage();
}
@@ -208,7 +208,7 @@
}}}
* `ImageResources` can be automatically flipped in RTL contexts via the
use of the `...@imageoptions` annotation:
{{{
-...@resource("icon128.png")
+...@source("icon128.png")
@ImageOptions(flipRtl = true)
ImageResource logo();
}}}
@@ -238,10 +238,9 @@
* The function just returns the CSS class name, but verifies that the
CSS class exists in the stylesheet.
* _TODO_: Add an @external annotation to allow a "binding" to a
site-wide css file
* No typos.
- * For obfuscation, we'll use a Adler32 checksum of the source css file
expressed in base36 as a prefix (7 chars). The developer can override this
with the `CssResource.globalPrefix` deferred-binding property.
- * `<set-property name="CssResource.globalPrefix" value="empty" />` can
be used for minimal-length selector names, but this is only recommended
when the GWT module has total control over the page.
- * Instead a combination of `<extend-property>` and `<set-property>`
can be used to prove a shorter, but probably unique, prefix.
- * This will transition to `<set-configuration-property>` when moved
into GWT trunk.
+ * For obfuscation, we'll use a Adler32 checksum of the source css file
expressed in base36 as a prefix (7 chars). The developer can override this
with the `CssResource.obfuscationPrefix` deferred-binding property.
+ * `<set-configuration-property name="CssResource.obfuscationPrefix"
value="empty" />` can be used for minimal-length selector names, but this
is only recommended when the GWT module has total control over the page.
+ * The `...@external` at-rule can be used to selectively disable obfuscation
for named selectors; see below for additional detail.
= Unplanned use cases =
@@ -356,8 +355,8 @@
=Levers and Knobs=
- * The deferred-binding property `CssResource.style` may be set to
`pretty` which will disable class-name obfuscation as well as pretty-print
the CSS content. Combine this with a `ResourceBundle.enableInlining` value
of `false` to produce a CSS expression which is amenable to client-side
editing.
- * The deferred-binding property `CssResoure.enableMerge` can be set to
`false` to disable modifications that re-order rules. This should be
considered a temporary measure until the merge logic has been fully vetted.
+ * The configuration property `CssResource.style` may be set to `pretty`
which will disable class-name obfuscation as well as pretty-print the CSS
content. Combine this with a `ClientBundle.enableInlining` value of
`false` to produce a CSS expression which is amenable to client-side
editing.
+ * The configuration property `CssResoure.mergeEnabled` can be set to
`false` to disable modifications that re-order rules. This should be
considered a temporary measure until the merge logic has been fully vetted.
* To allow for client-side tweaking of the effective (i.e.
permutation-specific) style rules, you can store the value of
CssResource.getText() into a TextArea. Wire some UI action to pass the
contents of the TextArea into `StyleInjector.setContents()` to overwrite
the original, injected stylesheet.
= Selector obfuscation details =
@@ -490,12 +489,12 @@
}
interface Resources {
- @Resource("stackPanel.css")
+ @Source("stackPanel.css")
@Strict
StackPanelInner inner();
@Import(StackPanelInner.class)
- @Resource("stackPanel.css", "outer.css")
+ @Source("stackPanel.css", "outer.css")
@Strict
StackPanelOuter outer();
}
@@ -529,7 +528,7 @@
interface Resources {
@Strict
- @Resource("my.css")
+ @Source("my.css")
MyCssResource css();
}
}}}
@@ -543,8 +542,31 @@
The `...@strict` annotation can be applied to a CssResource accessor function
to make it a compile-time error to have any unobfuscated class selectors in
the CSS file. This additional level of restriction is recommended for
library-oriented resource bundles in order to avoid inadvertently polluting
the global CSS namespace.
-Strict scoping can be forced on for all CssResources by adding
`<set-property name="CssResource.forceStrict" value="true" />` to the
module XML file, however this is only recommended for use by applications
or test modules and never in any module that will be redistributed.
+Strict scoping can be forced on for all CssResources by adding
`<set-configuration-property name="CssResource.strictAccessors"
value="true" />` to the module XML file, however this is only recommended
for use by applications or test modules and never in any module that will
be redistributed.
+== External and legacy scopes ==
+
+In many cases, newly-developed CSS will need to be combined with external
or legacy CSS. The `...@external` at-rule can be used to suppress selector
obfuscation while still allowing programmatic access to the selector name.
+
+{{{
+interface MyCssResource extends CssResource {
+ String obfuscated();
+ String legacySelectorA();
+}
+
+interface Resource extends ClientBundle {
+ @Source("my.css")
+ @Strict
+ MyCssResource css();
+}
+}}}
+{{{
+...@external legacySelectorA, legacySelectorB;
+.obfuscated .legacySelectorA { .... }
+.obfuscated .legacySelectorB { .... }
+}}}
+
+In the above example, the `.obfuscated` class selector will be obfuscated,
and the `obfuscated()` method will return the replaced name. Neither of the
legacy selectors will be obfuscated and the `legacySelectorA()` method will
return the unobfuscated value. Furthermore, because the `legacySelectorB`
is explicitly defined in the `...@external` declaration, the `...@strict`
annotation will not trigger an error.
=Important open questions=
* Can we manipulate style rules across browsers?
Modified: wiki/CssResourceCookbook.wiki
==============================================================================
--- wiki/CssResourceCookbook.wiki (original)
+++ wiki/CssResourceCookbook.wiki Wed May 20 14:49:15 2009
@@ -35,8 +35,8 @@
String className();
}
-interface MyResources extends ImmutableResourceBundle {
- @Resource("my.css")
+interface MyResources extends ClientBundle {
+ @Source("my.css")
MyCss css();
}
}}}
@@ -62,11 +62,11 @@
CssResource reuses the ImageResource bundling techniques and applies them
to CSS background images. This is generally known as "spriting" and a
special `...@sprite` rule is used in CssResource.
{{{
-interface MyResources extends ImmutableResourceBundle {
- @Resource("image.png")
+interface MyResources extends ClientBundle {
+ @Source("image.png")
ImageResource image();
- @Resource("my.css");
+ @Source("my.css");
CssResource css();
}
}}}
@@ -85,9 +85,9 @@
If the ImageResource is decorated with an `...@imageoptions` annotation, the
source image can be tiled along the X- or Y-axis. This allows you to use
1-pixel wide (or tall) images to define borders, while still taking
advantage of the image bundling optimizations afforded by ImageResource.
{{{
-interface MyResources extends ImmutableResourceBundle {
+interface MyResources extends ClientBundle {
@ImageOptions(repeatStyle = RepeatStyle.Horizontal)
- @Resource("image.png")
+ @Source("image.png")
ImageResource image();
}
}}}
@@ -101,38 +101,38 @@
TODO: Move this setup into DecoratorPanel or other Widget that just
accepts the following Resources interface.
{{{
- public interface Resources extends ImmutableResourceBundle {
+ public interface Resources extends ClientBundle {
Resources INSTANCE = GWT.create(Resources.class);
- @Resource("bt.png")
+ @Source("bt.png")
@ImageOptions(repeatStyle = RepeatStyle.Horizontal)
ImageResource bottomBorder();
- @Resource("btl.png")
+ @Source("btl.png")
ImageResource bottomLeftBorder();
- @Resource("btr.png")
+ @Source("btr.png")
ImageResource bottomRightBorder();
- @Resource("StyleInjectorDemo.css")
+ @Source("StyleInjectorDemo.css")
CssResource css();
- @Resource("lr.png")
+ @Source("lr.png")
@ImageOptions(repeatStyle = RepeatStyle.Vertical)
ImageResource leftBorder();
- @Resource("rl.png")
+ @Source("rl.png")
@ImageOptions(repeatStyle = RepeatStyle.Vertical)
ImageResource rightBorder();
- @Resource("tb.png")
+ @Source("tb.png")
@ImageOptions(repeatStyle = RepeatStyle.Horizontal)
ImageResource topBorder();
- @Resource("tbl.png")
+ @Source("tbl.png")
ImageResource topLeftBorder();
- @Resource("tbr.png")
+ @Source("tbr.png")
ImageResource topRightBorder();
}
}}}
--~--~---------~--~----~------------~-------~--~----~
http://groups.google.com/group/Google-Web-Toolkit-Contributors
-~----------~----~----~----~------~----~------~--~---
