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 fb8b1b7362 Fill gaps in the Wicket markup guide (#1972)
fb8b1b7362 is described below

commit fb8b1b73627cb4062969dee358d5372cdd050f66
Author: Jennydou517 <[email protected]>
AuthorDate: Sat Nov 21 13:32:46 2026 -0600

    Fill gaps in the Wicket markup guide (#1972)
    
    Document missing tags and attributes in their existing chapters so readers 
do not need to consult the old Wiki. Clarify Ajax behavior, show header scoping 
and form label fallback, and fix the package resource cross-reference.
    
    GitHub issue #1960
---
 .../src/main/asciidoc/forms2/forms2_2.adoc         | 26 ++++++++++++++
 .../main/asciidoc/keepControl/keepControl_10.adoc  |  2 ++
 .../main/asciidoc/keepControl/keepControl_6.adoc   |  4 ++-
 .../main/asciidoc/keepControl/keepControl_9.adoc   | 41 ++++++++++++++++++++++
 .../src/main/asciidoc/repeaters/repeaters_2.adoc   | 20 +++++++++++
 .../src/main/asciidoc/urls/urls_3.adoc             |  2 +-
 6 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc 
b/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc
index e15974eb03..17d7acfa5f 100644
--- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc
@@ -29,6 +29,32 @@ email.add(EmailAddressValidator.getInstance());
 
 Wicket comes with a set of built-in validators that should suit most of our 
needs. We will see them later in this chapter.
 
+=== Labeling form fields with wicket:for
+
+Use `wicket:for` on an HTML `<label>` to associate it with a Wicket form field.
+Set its value to the field's component ID. In this example, both the label and
+the input refer to the `name` field.
+
+[source,html]
+----
+<label wicket:for="name"><wicket:label>Name</wicket:label>:</label>
+<input wicket:id="name" type="text"/>
+----
+
+Wicket renders an HTML `for` attribute on the label that matches the input's
+HTML `id`. This lets users click the label to focus the input.
+
+The `<wicket:label>` tag displays the field's label text. For example, a label
+model set with `setLabel(Model.of("First Name"))` displays “First Name”. If the
+model provides no text, Wicket looks for a localized label using the field's
+component ID as the resource key. In this example, if neither source provides
+text, Wicket displays “Name” from the body of `<wicket:label>`.
+
+Use a colon-separated component path in `wicket:for` when the field is nested
+in another container. Use `..` to refer to a parent container. Wicket adds
+the CSS classes `required`, `error`, and `disabled` by default when the field
+is required, has failed validation, or is disabled, respectively.
+
 === Feedback messages and localization
 
 Wicket generates a feedback message for each field that doesn't satisfy one of 
its validation rules. For example the message generated when a required field 
is left empty is the following
diff --git 
a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_10.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_10.adoc
index df045ebf6b..b1c01e8427 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_10.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_10.adoc
@@ -37,6 +37,8 @@ Component _org.apache.wicket.markup.html.border.Border_ is a 
special purpose con
 </html>
 ----
 
+The `xmlns:wicket="http://wicket.apache.org"` declaration binds the `wicket` 
prefix to the Wicket namespace. In this example, `<wicket:border>` and 
`<wicket:body/>` use that prefix.
+
 The _<wicket:body/>_ tag used in the example above is used to indicate where 
the body of the tag will be placed inside border markup. Now if we attached 
this border to the following tag
 
 [source,html]
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_6.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_6.adoc
index 21e98dcfc0..e14066aecd 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_6.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_6.adoc
@@ -45,7 +45,9 @@ Wicket will take care of placing the content of 
_<wicket:head>_ inside the _<hea
 
 NOTE: The _<wicket:head>_ tag can also be used with children pages/panels 
which extend parent markup using tag _<wicket:extend>_.
 
-NOTE: The content of the _<wicket:head>_ tag is added to the header section 
once per component class. In other words, if we add multiple instances of the 
same panel to a page, the _<head>_ tag will be populated just once with the 
content of _<wicket:head>_.
+When rendering the page header, Wicket renders a component's `<wicket:head>` 
contribution once for each combination of generated header ID and scope. 
Multiple instances of the same panel using the same markup normally share both 
and therefore contribute that header block once.
+
+Use the `wicket:scope` attribute on `<wicket:head>` to give a header 
contribution a named scope, for example `<wicket:head wicket:scope="preview">`. 
If two contributions share a generated header ID but have different scopes, 
Wicket can render both.
 
 WARNING: The _<wicket:head>_ tag is ideal if we want to define small in-line 
blocks of CSS or JavaScript. However Wicket provides also a more sophisticated 
technique to let components contribute to header section with in-line blocks 
and resource files like CSS or JavaScript files. We will see this technique 
later in 
 <<_resource_management_with_wicket,chapter 16>>.
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_9.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_9.adoc
index b6ccec29c5..5bf2644fe0 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_9.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_9.adoc
@@ -56,3 +56,44 @@ _child_ attribute supports also nested components with a 
colon-separated path:
 WARNING: _<wicket:enclosure>_ is nice and prevents that users have to add 
boilerplate to their application. But it is not without problems. The child 
components are children in the markup, but the auto component generated for the 
enclosure tag will not magically re-parent the child components. Thus the 
markup hierarchy and the component hierarchy will be out of sync. The 
automatically created enclosure container will be created along side its 
"children" with both attached to the very sam [...]
 On top auto components cannot keep any state. A new instance is created during 
each render process and automatically deleted at the end. That implies that we 
cannot prevent _validation()_ from being called, since _validation()_ is called 
before the actual render process has started.
 Where any of these problems apply, you may replace the tag and manually add a 
https://nightlies.apache.org/wicket/apidocs/12.x/org.apache.wicket.core/org/apache/wicket/markup/html/basic/EnclosureContainer.html[EnclosureContainer]
 which basically does the same. But instead of adding the children to the Page, 
Panel, whatever, you must add the children to this container in order to keep 
the component hierarchy in sync. 
+
+NOTE: When using the `<wicket:enclosure>` tag, adding only the controlling
+child to an Ajax request target updates that child alone. To refresh the whole
+enclosure, wrap it in a `WebMarkupContainer`, call `setOutputMarkupId(true)` on
+the container, and add the container to the Ajax request target.
+
+=== Inline enclosures with the wicket:enclosure attribute
+
+Add the `wicket:enclosure` attribute to an HTML element that contains child
+elements, such as a `<div>` or `<tr>`. Wicket shows or hides the entire HTML
+element according to the visibility of a controlling Wicket component inside
+it.
+
+If the element contains a single Wicket component, leave the attribute value
+empty to let Wicket find that component.
+
+[source,html]
+----
+<div wicket:enclosure="">
+    <span>Total amount: </span><span wicket:id="totalAmount"></span>
+</div>
+----
+
+If the element contains several Wicket components, specify the ID of the
+component that should control visibility. In the example below, `totalAmount`
+controls the entire `<div>`.
+
+[source,html]
+----
+<div wicket:enclosure="totalAmount">
+    <span>Total amount: </span><span wicket:id="totalAmount"></span><br/>
+    <span>Expected delivery date: </span><span wicket:id="delivDate"></span>
+</div>
+----
+
+For a nested controlling component, use its relative component path, such as
+`totalAmountContainer:totalAmount`.
+
+An inline enclosure can be refreshed through Ajax. When the controlling
+component is added to the Ajax response, Wicket can refresh the entire
+enclosure, including the surrounding HTML element.
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc 
b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
index ef0c7ee785..726f2386ca 100644
--- a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc
@@ -58,6 +58,26 @@ image::./img/simple-listview-screenshot.png[]
 
 In this example we have displayed the full name of two Person's instances. The 
most interesting part of the code is the implementation of method populateItem 
where parameter item is the current child component created by ListView and its 
model contains the corresponding element of the list. Please note that inside 
populateItem we must add nested components to the _item_ object and not 
directly to the _ListView_.
 
+=== Repeating multiple table rows with wicket:container
+
+Use `<wicket:container>` to bind a single `ListView` to a group of rows. A 
`<tbody>` can contain `<tr>` elements directly, so the template uses a Wicket 
tag to group the rows without introducing an HTML wrapper such as `<span>`.
+
+[source,html]
+----
+<table wicket:id="results">
+    <tbody>
+        <wicket:container wicket:id="entries">
+            <tr><td>Summary</td></tr>
+            <tr><td>Details</td></tr>
+        </wicket:container>
+    </tbody>
+</table>
+----
+
+Bind the `ListView` with ID `entries` inside a `WebMarkupContainer` with ID 
`results`. Wicket renders the two rows for each list item. With the default 
deployment configuration, Wicket strips the `<wicket:container>` tags and 
leaves the rows directly inside `<tbody>`.
+
+Ajax needs a rendered HTML element to replace, so a stripped 
`<wicket:container>` cannot serve as the replacement target. Wicket does not 
support adding a `ListView` directly to the Ajax request target. To refresh the 
rows with Ajax, call `setOutputMarkupId(true)` on the `results` component and 
add it to the `AjaxRequestTarget` to replace the whole table.
+
 === ListView and Form
 
 By default _ListView_ replaces its children components with new instances 
every time is rendered. Unfortunately this behavior is a problem if _ListView_ 
is inside a form and it contains form components. The problem is caused by the 
fact that children components are replaced by new ones before form is rendered, 
hence they can't keep their input value if validation fails and, furthermore, 
their feedback messages can not be displayed.
diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc 
b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
index 4a2df55c4d..be2e8f2526 100644
--- a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
@@ -73,5 +73,5 @@ Please note that any link to the current page (aka self link) 
is disabled. For e
 
 NOTE: In previous versions of Wicket, the markup used to render disabled links 
could be customized using methods `setDefaultBeforeDisabledLink` and 
`setDefaultAfterDisabledLink` on the markup settings. This customization is no 
longer available in Wicket 10.
 
-The purpose of <wicket:link> tag is not limited to just simplifying the usage 
of bookmarkable pages. As we will see in chapter 13, this tag can also be 
adopted to manage web resources like pictures, CSS files, JavaScript files and 
so on.
+The `<wicket:link>` tag can also resolve package resources such as images, CSS 
files, and JavaScript files. See 
<<_using_package_resources_with_tag_wicketlink,Using package resources with 
wicket:link>>.
 

Reply via email to