This is an automated email from the ASF dual-hosted git repository.
bitstorm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/wicket.git
The following commit(s) were added to refs/heads/master by this push:
new a6f7d4344e Document TransparentWebMarkupContainer in its Javadoc and
the user guide (#1968)
a6f7d4344e is described below
commit a6f7d4344e9f37946548b08ac1aca3561b5afed0
Author: Guru R Bharadwaj <[email protected]>
AuthorDate: Sun Nov 22 01:00:53 2026 +0530
Document TransparentWebMarkupContainer in its Javadoc and the user guide
(#1968)
The class Javadoc was one line. It now says what the container does, shows
the <body> CSS-class case, and lists how it behaves with child ids, hiding,
Ajax updates, markup inheritance and borders. The guide gets a subsection
under "Creating in-line panels with WebMarkupContainer" with the same
example.
Fixes #1959
---
.../markup/html/TransparentWebMarkupContainer.java | 40 +++++++++++++++++++++-
.../main/asciidoc/keepControl/keepControl_4.adoc | 33 ++++++++++++++++++
2 files changed, 72 insertions(+), 1 deletion(-)
diff --git
a/wicket-core/src/main/java/org/apache/wicket/markup/html/TransparentWebMarkupContainer.java
b/wicket-core/src/main/java/org/apache/wicket/markup/html/TransparentWebMarkupContainer.java
index fcbae865f3..1f9d8b3e09 100644
---
a/wicket-core/src/main/java/org/apache/wicket/markup/html/TransparentWebMarkupContainer.java
+++
b/wicket-core/src/main/java/org/apache/wicket/markup/html/TransparentWebMarkupContainer.java
@@ -30,7 +30,45 @@ import org.apache.wicket.request.cycle.RequestCycle;
import org.apache.wicket.request.http.WebRequest;
/**
- * A simple "transparent" markup container.
+ * A container whose markup can hold components that were added to its parent
instead of to the
+ * container itself. When a tag in the container's markup has a {@code
wicket:id} that is not one of
+ * the container's own children, the component is looked up in the container's
parent.
+ * <p>
+ * Use it when a tag needs to be a component, for example to change its
attributes, while the
+ * components inside the tag stay where they are in the component hierarchy. A
common case is a CSS
+ * class on the {@code <body>} tag of a page:
+ *
+ * <pre>{@code
+ * <body wicket:id="body">
+ * <h1 wicket:id="title"></h1>
+ * </body>
+ * }</pre>
+ *
+ * <pre>{@code
+ * add(new
TransparentWebMarkupContainer("body").add(AttributeModifier.append("class",
"dark")));
+ * add(new Label("title", "Hello"));
+ * }</pre>
+ *
+ * With a {@link WebMarkupContainer} in its place, rendering fails because the
container has no
+ * child {@code "title"}.
+ * <p>
+ * Things to know:
+ * <ul>
+ * <li>A component rendered this way is still a child of the parent. {@code
get("title")} on the
+ * container returns {@code null}, and the component's path does not contain
the container's id.</li>
+ * <li>A child added to the container itself is used before a component of the
parent with the same
+ * id.</li>
+ * <li>Hiding the container hides everything in its markup, including the
parent's components.</li>
+ * <li>In an Ajax request, a component inside the container's markup can be
added to the
+ * {@code AjaxRequestTarget} on its own. Adding the container re-renders the
components in its
+ * markup, with their header contributions.</li>
+ * <li>With markup inheritance, a base page can put the container around
{@code <wicket:child/>}.
+ * Components that a subclass adds to the page, with their markup in {@code
<wicket:extend>},
+ * render inside the container.</li>
+ * <li>The lookup goes to the container's parent only. Inside the body of a
+ * {@link org.apache.wicket.markup.html.border.Border}, the parent is the
border, so the components
+ * must be added to the border, not to the page.</li>
+ * </ul>
*
* @author Juergen Donnerstag
*/
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
index bc95762090..4aa67aa77a 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
@@ -45,3 +45,36 @@ informationBox.setVisible(false);
As you can see in the snippet above we can handle our information box from
Java code as we do with any other Wicket component.
Note also that we may later choose to make information box visible by calling
_setVisible(true)_, upon for example an AJAX request (we will be covering such
an example in <<_working_with_hidden_components, chapter 19.2.8>>).
+
+=== Containers that leave their components to the parent
+
+Sometimes a tag needs to be a component only so that we can change it from
Java code, while the tags inside it belong to components that are already added
somewhere else. The _<body>_ tag of a page is a typical example: to add a CSS
class to it we need a component, but if that component were a
_WebMarkupContainer_ we would have to move every component of the page into it,
changing their paths and our code.
+
+_org.apache.wicket.markup.html.TransparentWebMarkupContainer_ solves this.
When its markup contains a tag whose _wicket:id_ is not one of its own
children, it looks for the component in its parent. With this page markup:
+
+[source,html]
+----
+<body wicket:id="body">
+ <h1 wicket:id="title"></h1>
+</body>
+----
+
+the page adds both components to itself:
+
+[source,java]
+----
+add(new TransparentWebMarkupContainer("body")
+ .add(AttributeModifier.append("class", "dark")));
+add(new Label("title", "Hello"));
+----
+
+The label renders inside _<body class="dark">_, but it is still a child of the
page: its path is _title_, not _body:title_. With a plain _WebMarkupContainer_
the page would fail to render because the container has no child with id
_title_.
+
+The same works with markup inheritance. A base page can add a
_TransparentWebMarkupContainer_ for its _<body>_ tag and put _<wicket:child/>_
inside it; the components that a subclass adds to the page and places in its
_<wicket:extend>_ then render inside the container.
+
+A few things to keep in mind:
+
+* A child added to the container itself is used before a component of the
parent with the same id.
+* Hiding the container hides everything in its markup, including the parent's
components.
+* During an AJAX request we can add a component inside the container's markup
to _AjaxRequestTarget_ on its own. Adding the container re-renders all the
components in its markup, together with their header contributions.
+* The container looks only in its parent. Inside the body of a _Border_ (see
<<_surrounding_existing_markup_with_border,Surrounding existing markup with
Border>>) its parent is the border, so the components must be added to the
border and not to the page.