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.

Reply via email to