Chapter 5: Sacred Components - The blessed building blocks

Label

Label renders text content safely. It is ideal for immutable text, model-backed strings, and runtime status output.

Simple label
add(new Label("status", "The ritual is complete."));

Link handles click behavior in Java. Use it for navigation, command actions, and explicit event handling.

WebMarkupContainer

This container groups components and lets you control visibility and attributes as one unit. It is the practical tool for conditional blocks.

Image

Use classpath resources for packaged assets and predictable deployment. Keep image loading strategy aligned with caching requirements.

Best Practices

Practical Pitfalls

  • Problem
    You set a markup id in Java, but cannot find it in rendered HTML for JS/AJAX targeting.
    Cause
    Setting an id value and enabling id output are separate concerns; output was never enabled.
    Solution
    For any component touched by JS/AJAX, set setOutputMarkupId(true) first, then set fixed id only if needed.
  • Problem
    Open-in-new-tab behavior works inconsistently across browsers.
    Cause
    AJAX-triggered tab opens can be blocked or treated as popup behavior.
    Solution
    Prefer bookmarkable URLs opened via standard links for stable cross-browser behavior.