Package org.zkoss.zul.theme

Class MarbleDensity

java.lang.Object
org.zkoss.zul.theme.MarbleDensity
public final class MarbleDensity extends Object
Switches Marble's data-dense (compact) mode without the caller having to know the underlying DOM detail.

Density in Marble is a declarative knob: a data-density attribute that overrides the semantic-layer size tokens (input height, row height, cell padding, button/toolbar/tab heights, …). Because those are the tokens the components actually read, the attribute takes effect at any scope — the document root for the whole app, or a single component subtree for one region. See doc/spec/data-dense-mode.md.

This helper exposes that knob from Java:

  • apply(Density) — whole app. The attribute is set on the document root (<html>), which is not a ZK component, so this goes through Clients.evalJavaScript(String).
  • apply(Component, Density) — one region. Uses ZK's native Component.setClientDataAttribute(String, String) (no JavaScript string), which re-renders that subtree when the value changes.

When to use this vs. the library property. This API is for runtime switching (a user flipping a density preference). For a fixed whole-app default, prefer the org.zkoss.theme.marble.density library property in zk.xml, which renders data-density on <html> with the page. The property applies only when ZK renders the whole HTML document (a top-level ZUL page); a .zhtml page, a <?page complete="true"?> page or an included page owns its <html> tag, so put data-density there instead. Calling apply(Density) on page load runs after the first paint and can cause a brief comfortable→compact flash (FOUC).

Since:
11.0.0

  • Method Details

    • apply

      public static void apply(MarbleDensity.Density density)
      Applies the density to the whole application by setting data-density on the document root (<html>). Covers body-appended popups (menus, modal windows, notifications) too, since they inherit from the root.

      Must run within an active ZK execution (e.g. inside an event listener or MVVM command) so the client update can be sent.

      Parameters:
      density - the density to apply; never null.

    • apply

      public static void apply(org.zkoss.zk.ui.Component scope, MarbleDensity.Density density)
      Applies the density to a single component subtree by setting data-density on that component's DOM element. Use this to make one region (e.g. a data-dense grid panel) compact while the rest of the app stays comfortable; it nests and can be overridden by a closer descendant.
      Parameters:
      scope - the component whose subtree should adopt the density.
      density - the density to apply; never null.