This is an automated email from the ASF dual-hosted git repository. dashorst pushed a commit to branch user-guide-accessibility-1839 in repository https://gitbox.apache.org/repos/asf/wicket.git
commit ab1d424c47eac164970693e18702c5b065ce8ca5 Author: Martijn Dashorst <[email protected]> AuthorDate: Sun Nov 8 00:17:41 2026 +0100 Add an accessibility chapter to the user guide The user guide did not tell developers how to build an accessible Wicket application, and its own examples fell short: no <html> in the guide carried a lang attribute, so a page built from "Wicket says Hello world!" or "Wicket as page layout manager" failed WCAG 3.1.1 from the first line. The new chapter 25, Accessibility, sits after the testing chapters and before the best practices, where forms, repeaters, i18n, AJAX and WicketTester have all been introduced. It covers: - what Wicket takes care of and what stays with the application; - a table of all 55 WCAG 2.2 success criteria of level A and AA, with the Wicket mechanism, the application's part and a link to the code; - an accessible base page: a title per page, lang from the session locale, a skip link, landmarks and replacement error pages; - form errors: wicket:for and wicket:label, a message next to the field, and a behavior that adds aria-invalid and aria-describedby; - focus and announcements after AJAX updates: focusComponent, live regions that stay in the page, busy indicators and ModalDialog roles; - keyboard-operable AJAX controls on <button> and <a>, not on <div>; - data tables: caption, row headers, aria-sort and a stable markup id for sort links so that focus survives an AJAX sort; - validating an application: WicketTester/TagTester assertions, axe-core with Playwright, HTML validation and the manual checks. Where Wicket has no support today the chapter shows the workaround with the current API; the gaps are input for the component audit in GitHub issue #1838. The full-page examples elsewhere in the guide get lang="en", and the layout chapter's base page gets a title label, lang, a skip link and landmark elements, so the new chapter can refer to it. The reference to the internals chapter moves from 26 to 27. GitHub issue #1839 Generated-by: Claude Code (Claude Opus 5.5) --- .../src/main/asciidoc/accessibility.adoc | 6 + .../asciidoc/accessibility/accessibility_1.adoc | 29 ++ .../asciidoc/accessibility/accessibility_2.adoc | 341 +++++++++++++++++++++ .../asciidoc/accessibility/accessibility_3.adoc | 119 +++++++ .../asciidoc/accessibility/accessibility_4.adoc | 154 ++++++++++ .../asciidoc/accessibility/accessibility_5.adoc | 150 +++++++++ .../asciidoc/accessibility/accessibility_6.adoc | 53 ++++ .../asciidoc/accessibility/accessibility_7.adoc | 112 +++++++ .../asciidoc/accessibility/accessibility_8.adoc | 162 ++++++++++ .../asciidoc/accessibility/accessibility_9.adoc | 2 + .../asciidoc/bestpractices/bestpractices_1.adoc | 4 +- .../src/main/asciidoc/forms2/forms2_10.adoc | 2 +- .../src/main/asciidoc/forms2/forms2_5.adoc | 2 +- .../src/main/asciidoc/forms2/forms2_8.adoc | 2 +- .../src/main/asciidoc/helloWorld/helloWorld_3.adoc | 2 +- .../main/asciidoc/keepControl/keepControl_5.adoc | 6 +- .../main/asciidoc/keepControl/keepControl_7.adoc | 2 +- .../main/asciidoc/keepControl/keepControl_8.adoc | 4 +- .../src/main/asciidoc/layout/layout_3.adoc | 37 ++- .../src/main/asciidoc/layout/layout_4.adoc | 23 +- .../main/asciidoc/modelsforms/modelsforms_4.adoc | 2 +- wicket-user-guide/src/main/asciidoc/repeaters.adoc | 2 +- .../src/main/asciidoc/resources/resources_8.adoc | 4 +- wicket-user-guide/src/main/asciidoc/single.adoc | 40 +++ .../src/main/asciidoc/testing/testing_3.adoc | 2 +- .../src/main/asciidoc/urls/urls_3.adoc | 4 +- .../versioningCaching/versioningCaching_2.adoc | 2 +- 27 files changed, 1231 insertions(+), 37 deletions(-) diff --git a/wicket-user-guide/src/main/asciidoc/accessibility.adoc b/wicket-user-guide/src/main/asciidoc/accessibility.adoc new file mode 100644 index 0000000000..19925df7b7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility.adoc @@ -0,0 +1,6 @@ + +An accessible web application can be used by people who do not see the screen, who do not use a mouse, who zoom the page to four times its size or who need more time to read and type. The reference for what that takes is the Web Content Accessibility Guidelines (WCAG), published by the W3C. In many countries WCAG level AA is also a legal requirement, for public sector websites and increasingly for commercial ones. + +Wicket does not make an application accessible by itself, and it does not stand in the way either: the HTML of our pages is ours to write, and most of what Wicket adds to it can be adjusted. In this chapter we will see what Wicket contributes to an accessible application, which WCAG 2.2 success criteria of level A and AA depend on what we write, and how to implement the criteria that need code: an accessible base page, form errors, focus and announcements after AJAX updates, keyboard-ope [...] + +The examples build on the base page of <<_wicket_as_page_layout_manager,chapter 5>>, on the forms of chapters <<_wicket_models_and_forms,11>> and <<_wicket_forms_in_detail,12>>, on the AJAX support of <<_working_with_ajax,chapter 19>> and on _WicketTester_ from <<_test_driven_development_with_wicket,chapter 23>>. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc new file mode 100644 index 0000000000..016c0e8777 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc @@ -0,0 +1,29 @@ + +WCAG states its requirements as success criteria, and a success criterion is met or failed by a page, not by a library. No framework can therefore make an application conform to WCAG. What a framework can do is render markup that does not fail a criterion by itself, and give the application the means to meet the criteria that depend on its content. + +=== What Wicket takes care of + +Wicket renders the markup we write in our HTML files and changes only the tags that are bound to a component. For accessibility this is good news: the elements that convey structure, such as headings, lists, landmarks, tables and the labels of form fields, are written by us and reach the browser as we wrote them. In addition, several components and resolvers render markup that helps assistive technology: + +* a _<label>_ tag with attribute _wicket:for_ gets a _for_ attribute that points to the right form component, whatever markup id Wicket generates for it (see <<_accessible_form_errors,paragraph 25.4>>); +* the label of a form component (_setLabel_ or _<wicket:label>_) is used in its validation messages, so an error names the field it is about; +* text fields render the HTML5 attributes _required_ and _pattern_ when the component is required or has a _PatternValidator_; +* _RadioChoice_ and _CheckBoxMultipleChoice_ render a _<label>_ for each option; +* the headers of a _DataTable_ are _<th>_ cells with a _scope_ attribute, and the table renders a _<caption>_ when we give it one (see <<_accessible_data_tables,paragraph 25.7>>); +* after an AJAX update Wicket gives focus back to the element that had it, when the update replaced that element with one with the same markup id (see <<_focus_and_announcements_after_ajax_updates,paragraph 25.5>>); +* _ModalDialog_ can trap the focus inside the dialog and return it to where it was when the dialog closes; +* _AutoCompleteTextField_ renders the ARIA role and states of a combobox. + +=== What stays with the application + +Most success criteria are about content and design, and those are ours: the contrast between text and background, the alternative text of images, the order and wording of headings, the text of labels, links and messages, captions for video, and a layout that still works when the text is enlarged. Wicket has no say in any of these. The same goes for ARIA attributes on our own markup: Wicket leaves them alone, and it adds very few of its own. + +=== Server-side components and AJAX + +Because Wicket renders HTML on the server, a Wicket page without AJAX behaves like any other server-rendered page: each request loads a complete page, browsers and screen readers announce its title, and focus starts at the top. Most accessibility problems of single-page applications do not arise. + +AJAX brings them back. When an AJAX response replaces a part of the page, the browser does not announce anything, and if the element that had the focus disappears, the focus is lost. Wicket replaces a component by replacing its whole element in the DOM, which has two consequences we will meet again in this chapter: an ARIA live region must not be the element of the component we update, and focus can only be restored to an element whose markup id survives the update. + +=== Where Wicket falls short today + +A few things an accessible page needs are not supported by Wicket at the moment: Wicket does not render a _lang_ attribute, form components do not get _aria-invalid_ when they fail validation, and the default error pages use an HTML 4.01 doctype without a _lang_ attribute. For each of them this chapter shows a workaround with the current API. An audit of all components against WCAG 2.2 AA is under way in https://github.com/apache/wicket/issues/1838[GitHub issue #1838], and its results ma [...] diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc new file mode 100644 index 0000000000..4873182d28 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc @@ -0,0 +1,341 @@ + +The following table lists every success criterion of WCAG 2.2 at level A and AA, in the order of the specification. For each criterion it shows what Wicket offers, what is left to the application, and where this chapter has code for it. Criteria Wicket has no bearing on are marked as such: they depend on content, design or media only, and are met or failed the same way in any web application. The criterion 4.1.1 Parsing is not in the table, because WCAG 2.2 has removed it. + +The descriptions of the criteria are shortened; the full text and the techniques that meet each criterion are in https://www.w3.org/TR/WCAG22/[the WCAG 2.2 specification] and https://www.w3.org/WAI/WCAG22/Understanding/[Understanding WCAG 2.2]. + +[cols="3,1,5,5,1",options="header"] +|=== +|Success criterion |Level |Wicket |Application |Code + +|1.1.1 Non-text Content +|A +|_Image_ and _ContextImage_ render the _alt_ attribute we write in the markup. _AjaxIndicatorAppender_ renders its busy indicator with an empty _alt_. +|An _alt_ text for every meaningful image, _alt=""_ for decorative ones, text alternatives for icons, a CAPTCHA alternative if _CaptchaImageResource_ is used. +| + +|1.2.1 Audio-only and Video-only (Prerecorded) +|A +|No bearing. +|A transcript or an audio track for prerecorded media. +| + +|1.2.2 Captions (Prerecorded) +|A +|No bearing. _Video_ and _Track_ render the _<video>_ and _<track>_ tags. +|Captions for prerecorded video. +| + +|1.2.3 Audio Description or Media Alternative (Prerecorded) +|A +|No bearing. +|Audio description or a text alternative for prerecorded video. +| + +|1.2.4 Captions (Live) +|AA +|No bearing. +|Captions for live video. +| + +|1.2.5 Audio Description (Prerecorded) +|AA +|No bearing. +|Audio description for prerecorded video. +| + +|1.3.1 Info and Relationships +|A +|Our markup reaches the browser unchanged. _wicket:for_ connects labels and fields; _RadioChoice_ and _CheckBoxMultipleChoice_ label their options; _DataTable_ renders _<th scope="col">_ and a _<caption>_. Fields do not get _aria-invalid_, and row headers in a _DataTable_ need a workaround. +|Headings, lists, landmarks, _<fieldset>_ and _<legend>_ for groups of fields, a label for every field, table headers. +|<<_an_accessible_base_page,25.3>>, <<_accessible_form_errors,25.4>>, <<_accessible_data_tables,25.7>> + +|1.3.2 Meaningful Sequence +|A +|Components render where their tag is in the markup. +|A source order that matches the reading order; no reordering with CSS that changes the meaning. +| + +|1.3.3 Sensory Characteristics +|A +|No bearing. +|Instructions that do not rely on shape, colour, size or position only ("the button on the right"). +| + +|1.3.4 Orientation +|AA +|No bearing. +|A layout that works in portrait and landscape. +| + +|1.3.5 Identify Input Purpose +|AA +|Wicket keeps the _autocomplete_ attribute we write on a field. +|An _autocomplete_ attribute with the right token on fields that ask for data about the user (_email_, _name_, _street-address_, ...). +|<<_accessible_form_errors,25.4>> + +|1.4.1 Use of Color +|A +|The CSS classes Wicket adds (_error_ and _required_ on labels, _feedbackPanelERROR_ on messages) carry no colour of their own. +|Errors, required fields, links and states that are not shown by colour alone. +|<<_accessible_form_errors,25.4>> + +|1.4.2 Audio Control +|A +|No bearing. +|A way to stop audio that plays automatically. +| + +|1.4.3 Contrast (Minimum) +|AA +|No bearing. +|A contrast ratio of 4.5:1 for text, 3:1 for large text. +| + +|1.4.4 Resize Text +|AA +|No bearing. +|A page that still works when the text is enlarged to 200%. +| + +|1.4.5 Images of Text +|AA +|No bearing. +|Real text instead of images of text. +| + +|1.4.10 Reflow +|AA +|No bearing. The markup of _DataTable_ and other components is styled by us. +|A layout that works at a width of 320 CSS pixels without scrolling in two directions; data tables may scroll horizontally. +| + +|1.4.11 Non-text Contrast +|AA +|No bearing. +|A contrast ratio of 3:1 for the borders of fields and buttons, focus indicators and icons that convey information. +| + +|1.4.12 Text Spacing +|AA +|No bearing. +|A layout that does not break when users increase line, word and letter spacing. +| + +|1.4.13 Content on Hover or Focus +|AA +|No bearing. +|Tooltips and pop-ups that can be dismissed, hovered and stay until dismissed. +| + +|2.1.1 Keyboard +|A +|Links and buttons are keyboard-operable when their component is attached to _<a>_ or _<button>_. An AJAX behavior attached to any other element is not. +|Every function operable from the keyboard; AJAX behaviors on elements that can receive focus. +|<<_keyboard_operable_ajax_controls,25.6>> + +|2.1.2 No Keyboard Trap +|A +|_ModalDialog.trapFocus()_ keeps the focus inside an open dialog on purpose; _closeOnEscape()_ lets the user leave it. +|A way out of every widget with the keyboard; a close button in every dialog. +|<<_keyboard_operable_ajax_controls,25.6>> + +|2.1.4 Character Key Shortcuts +|A +|Wicket defines no keyboard shortcuts. +|Single-key shortcuts that can be turned off or remapped, if the application defines any. +| + +|2.2.1 Timing Adjustable +|A +|A stateful page lives in the HTTP session; when the session times out, the user sees the page expired page and loses the input. Stateless pages and forms (_StatelessForm_) do not expire. +|A session timeout that is long enough, a warning before it expires with a way to extend it, or stateless pages for long forms. +| + +|2.2.2 Pause, Stop, Hide +|A +|_AbstractAjaxTimerBehavior_ and _AjaxSelfUpdatingTimerBehavior_ can be stopped with _stop(target)_. +|A way to pause content that moves or updates by itself for more than five seconds. +| + +|2.3.1 Three Flashes or Below Threshold +|A +|No bearing. +|No content that flashes more than three times per second. +| + +|2.4.1 Bypass Blocks +|A +|No bearing. +|A skip link and landmarks. +|<<_an_accessible_base_page,25.3>> + +|2.4.2 Page Titled +|A +|A _Label_ on the _<title>_ tag gives every page its own title. The default error pages have a fixed English title. +|A title for every page that describes its topic or purpose. +|<<_an_accessible_base_page,25.3>> + +|2.4.3 Focus Order +|A +|After an AJAX update Wicket restores the focus only if the focused element keeps its markup id. Sort links of an AJAX _DataTable_ get new markup ids, so the focus is lost after sorting. +|Focus moved deliberately after AJAX updates and when dialogs open and close. +|<<_focus_and_announcements_after_ajax_updates,25.5>>, <<_accessible_data_tables,25.7>> + +|2.4.4 Link Purpose (In Context) +|A +|_PagingNavigator_ renders "<<", "<", ">" and ">>" as the text of its links and puts the description in a _title_ attribute only. +|Link texts that describe the target, such as a "Delete" button that names what it deletes. +|<<_focus_and_announcements_after_ajax_updates,25.5>>, <<_accessible_data_tables,25.7>> + +|2.4.5 Multiple Ways +|AA +|No bearing. +|More than one way to find a page: navigation, search, a site map. +| + +|2.4.6 Headings and Labels +|AA +|No bearing. +|Headings and labels that describe the topic or purpose. +| + +|2.4.7 Focus Visible +|AA +|Wicket's own stylesheets do not remove the focus outline. +|A visible focus indicator on every element that can receive focus. +| + +|2.4.11 Focus Not Obscured (Minimum) +|AA +|No bearing. +|Sticky headers, footers and banners that do not hide the element with the focus. +| + +|2.5.1 Pointer Gestures +|A +|No bearing. +|A single-pointer alternative for gestures with multiple fingers or a path. +| + +|2.5.2 Pointer Cancellation +|A +|_AjaxLink_, _AjaxButton_ and _AjaxEventBehavior_ on _click_ fire on the up-event. Behaviors on _mousedown_ or _pointerdown_ do not. +|Actions on _click_ rather than on the down-event. +|<<_keyboard_operable_ajax_controls,25.6>> + +|2.5.3 Label in Name +|A +|No bearing. +|An accessible name (_aria-label_, hidden text) that starts with or contains the visible label. +|<<_focus_and_announcements_after_ajax_updates,25.5>> + +|2.5.4 Motion Actuation +|A +|No bearing. +|An alternative for functions triggered by shaking or tilting the device. +| + +|2.5.7 Dragging Movements +|AA +|No bearing. _Palette_ moves items with buttons, not by dragging. +|A single-pointer alternative for drag and drop, such as in sortable lists or file drop zones. +| + +|2.5.8 Target Size (Minimum) +|AA +|No bearing. +|Targets of at least 24 by 24 CSS pixels, or enough space around them. +| + +|3.1.1 Language of Page +|A +|Wicket does not render a _lang_ attribute. A _TransparentWebMarkupContainer_ on the _<html>_ tag can add it from the session locale. The default error pages have no _lang_. +|A _lang_ attribute on _<html>_ that matches the language of the page. +|<<_an_accessible_base_page,25.3>> + +|3.1.2 Language of Parts +|AA +|Wicket keeps a _lang_ attribute we write in the markup, and _AttributeModifier_ can set it from code. +|A _lang_ attribute on passages in another language. +|<<_an_accessible_base_page,25.3>> + +|3.2.1 On Focus +|A +|AJAX behaviors on _focus_ run only when we attach them. +|No change of context, such as navigation or a submit, when an element receives focus. +|<<_keyboard_operable_ajax_controls,25.6>> + +|3.2.2 On Input +|A +|_FormComponentUpdatingBehavior_, _AjaxFormComponentUpdatingBehavior_ and _OnChangeAjaxBehavior_ run code whenever a value changes. +|No navigation or other change of context on changing a value, unless the user has been told in advance; a submit button instead. +|<<_keyboard_operable_ajax_controls,25.6>> + +|3.2.3 Consistent Navigation +|AA +|Markup inheritance gives all pages the same navigation. +|Navigation that appears in the same order on every page. +|<<_an_accessible_base_page,25.3>> + +|3.2.4 Consistent Identification +|AA +|Reusable panels and _wicket:message_ keep names and labels the same across pages. +|Components with the same function labelled the same way. +| + +|3.2.6 Consistent Help +|A +|Markup inheritance puts help links in the same place on every page. +|Help mechanisms in the same relative order on every page. +|<<_an_accessible_base_page,25.3>> + +|3.3.1 Error Identification +|A +|Validation messages name the field through its label. The error state reaches the _<label>_ as the CSS class _error_, but not the field: there is no _aria-invalid_ and no _aria-describedby_. +|A message next to the field, _aria-invalid_ on the field and a reference from the field to its message. +|<<_accessible_form_errors,25.4>> + +|3.3.2 Labels or Instructions +|A +|_wicket:for_ and _<wicket:label>_ connect a visible label to every field. Text fields copy their label into the _placeholder_ attribute. +|A visible label for every field, required fields marked in the label, formats explained before the user types. +|<<_accessible_form_errors,25.4>> + +|3.3.3 Error Suggestion +|AA +|Validation messages come from resource bundles and can be reworded per field and per validator. +|Messages that say how to correct the input. +|<<_accessible_form_errors,25.4>> + +|3.3.4 Error Prevention (Legal, Financial, Data) +|AA +|A multi-step _Wizard_ or a confirmation page can be built from regular pages and panels. +|Review, confirmation or undo for submissions with legal or financial consequences. +| + +|3.3.7 Redundant Entry +|A +|A form keeps its model between requests, so values entered earlier can be shown again. +|No asking for the same information twice in one process, unless needed. +| + +|3.3.8 Accessible Authentication (Minimum) +|AA +|_PasswordTextField_ allows pasting and password managers. _CaptchaImageResource_ is a cognitive function test. +|Login without a cognitive test, or with an alternative; _autocomplete_ on username and password fields. +| + +|4.1.2 Name, Role, Value +|A +|Native elements carry name, role and value. Wicket adds no roles to elements that need them: an AJAX behavior on a _<div>_, _TabbedPanel_ and _ModalDialog_ have no ARIA roles. +|Native elements first; ARIA roles, states and names on custom widgets. +|<<_keyboard_operable_ajax_controls,25.6>>, <<_accessible_data_tables,25.7>> + +|4.1.3 Status Messages +|AA +|_FeedbackPanel_ is not a live region, and messages that arrive by AJAX are not announced. +|A live region that stays in the page, updated by AJAX. +|<<_focus_and_announcements_after_ajax_updates,25.5>> +|=== + +Most rows say "No bearing" or put the work on the application. The rows with a link are the ones where Wicket offers a mechanism, or where its default markup needs help; the next paragraphs deal with them. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc new file mode 100644 index 0000000000..49bf4bf195 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc @@ -0,0 +1,119 @@ + +Several success criteria are met once for the whole application, in the page all other pages extend. In <<_wicket_as_page_layout_manager,chapter 5>> we have built such a base page with markup inheritance; here we complete it with a title for every page, a _lang_ attribute that follows the session locale, a skip link and landmarks. + +*BasePage.html:* + +[source,html] +---- +<!DOCTYPE html> +<html wicket:id="html" xmlns:wicket="http://wicket.apache.org"> +<head> + <meta charset="utf-8"> + <title wicket:id="pageTitle">Page title</title> +</head> +<body> + <a class="skip-link" href="#content"><wicket:message key="skipToContent">Skip to main content</wicket:message></a> + <header> + <p class="site-name">Example</p> + </header> + <nav wicket:message="aria-label:mainNavigation"> + <ul> + <li><a href="#">Home</a></li> + </ul> + </nav> + <main id="content" tabindex="-1"> + <wicket:child/> + </main> + <footer> + <p>Footer</p> + </footer> +</body> +</html> +---- + +*BasePage.java:* + +[source,java] +---- +public abstract class BasePage extends WebPage { + + public BasePage() { + TransparentWebMarkupContainer html = new TransparentWebMarkupContainer("html"); + html.add(AttributeModifier.replace("lang", () -> getLocale().toLanguageTag())); + add(html); + + add(new Label("pageTitle", this::getPageTitle)); + } + + protected abstract String getPageTitle(); +} +---- + +*BasePage.properties:* + +[source,properties] +---- +skipToContent=Skip to main content +mainNavigation=Main +---- + +=== The language of the page + +Screen readers choose their pronunciation from the _lang_ attribute of the _<html>_ element (success criterion 3.1.1). Wicket does not render this attribute, so we bind the _<html>_ tag to a _TransparentWebMarkupContainer_ and add the attribute with an _AttributeModifier_. Since the container is transparent, the components of the page and of its subclasses can stay where they are and need not be added to the container. Method _getLocale()_ returns the locale of the session (see <<_intern [...] + +If an application supports only one language, a _lang_ attribute written in the markup is enough. Passages in another language than the page, such as a quote or the name of a language in a language switcher, get their own _lang_ attribute (success criterion 3.1.2), either in the markup or with an _AttributeModifier_ on the component that renders them. + +=== A title for every page + +Browsers show the title of a page in their tab, and screen readers read it first when a page loads (success criterion 2.4.2). The _<title>_ tag of the base page is bound to a _Label_, and every page provides its own text by implementing _getPageTitle_: + +[source,java] +---- +public class RegistrationPage extends BasePage { + + @Override + protected String getPageTitle() { + return "Register - Example"; + } +} +---- + +A localized application returns _getString("title")_ and keeps the titles in the resource bundle of each page. A title starts with what is specific to the page, so that users who have several tabs open can tell them apart. + +=== Skip link and landmarks + +The skip link is the first link of the page and points to the _<main>_ element, so keyboard users can jump past the header and the navigation (success criterion 2.4.1). The attribute _tabindex="-1"_ on _<main>_ makes sure that browsers move the keyboard focus to it, and not only the scroll position. The skip link may be hidden until it receives focus, but it must become visible then: + +[source,css] +---- +.skip-link { + position: absolute; + left: -10000px; +} + +.skip-link:focus { + left: 1em; + top: 1em; +} +---- + +The elements _<header>_, _<nav>_, _<main>_ and _<footer>_ are exposed as landmarks, which screen reader users can list and jump to. When a page has more than one _<nav>_, each one needs a name; here the main navigation gets an _aria-label_ from the resource bundle with the attribute form of _wicket:message_. + +Because every page extends the base page, the navigation and any help link appear in the same place and the same order on every page, as success criteria 3.2.3 and 3.2.6 ask. + +=== Error pages + +Wicket shows its own pages when a page has expired, when access is denied and when an internal error occurs. These pages use an HTML 4.01 doctype, have no _lang_ attribute and an English title, and they do not share the layout and navigation of the application. We can replace them with pages that extend our base page: + +[source,java] +---- +@Override +protected void init() { + super.init(); + getApplicationSettings().setPageExpiredErrorPage(MyPageExpiredPage.class); + getApplicationSettings().setAccessDeniedPage(MyAccessDeniedPage.class); + getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class); +} +---- + +The page expired page is also what users see when their session has timed out (success criterion 2.2.1), so it deserves a text that explains what happened and what to do next. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc new file mode 100644 index 0000000000..5997da31ef --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc @@ -0,0 +1,154 @@ + +A form is accessible when every field has a label that is connected to it, when an error tells the user which field is wrong and how to correct it, and when the error can be found without seeing it. Wicket does the first part; for the last part we need a small behavior of our own. + +=== Labels with wicket:for + +A _<label>_ is connected to its field by the _for_ attribute, which must contain the _id_ of the field. Since Wicket generates the markup ids of components, we cannot write that _id_ in the markup ourselves. The attribute _wicket:for_ solves this: it contains the component id of the field, and Wicket renders the _for_ attribute with the markup id of that component, which it makes the field output: + +[source,html] +---- +<label wicket:for="email"><wicket:label>Email address</wicket:label></label> +<input type="email" wicket:id="email" autocomplete="email"> +---- + +The tag _<wicket:label>_ inside the label does one more thing: if the field has no label model yet, its text becomes the label of the field. Validation messages use this label, so the message for a required field reads _'Email address' is required._ instead of naming the component id. The same can be done from code with _setLabel(IModel)_, in which case _<wicket:label>_ renders the text of the model. Either way the visible label and the name in the messages are the same text, which is wh [...] + +The attribute _autocomplete_ tells browsers and assistive technology what the field asks for (success criterion 1.3.5). Wicket leaves it alone, so we write it in the markup with the right token, such as _email_, _name_, _tel_ or _street-address_. + +Besides the _for_ attribute, _wicket:for_ adds the CSS class _required_ to the label of a required field, _error_ to the label of a field that failed validation and _disabled_ to the label of a disabled field. The names of these classes can be changed with the resource keys _AutoLabel.CSS.required_, _AutoLabel.CSS.error_ and _AutoLabel.CSS.disabled_. These classes are useful for styling, but they are not enough on their own: a class is not exposed to assistive technology, and a colour mu [...] + +NOTE: Text fields render the label of the component in their _placeholder_ attribute, and replace any placeholder we wrote in the markup. Some screen readers then read the label twice. Text fields also render the HTML5 attribute _required_ when the component is required. When the form is submitted without AJAX, the browser then checks the field first and shows its own message instead of Wicket's; AJAX submits skip this check. The attribute _novalidate_ on the _<form>_ tag turns the brows [...] + +=== Errors next to the field + +A message in a _FeedbackPanel_ at the top of the page tells the user that something went wrong, but a user who works through the form field by field does not see it there. Success criterion 3.3.1 asks that the field in error is identified, and the most robust way is a message next to the field, which the field refers to. A _ComponentFeedbackPanel_ shows the messages of one component only, so we put one after each field: + +[source,html] +---- +<form wicket:id="form" novalidate> + <label wicket:for="email"><wicket:label>Email address</wicket:label></label> + <input type="email" wicket:id="email" autocomplete="email"> + <div wicket:id="emailError" class="field-error"></div> + + <button wicket:id="register">Register</button> +</form> +---- + +Visually the message is now next to the field. For a screen reader it is not yet connected to it: the field must say that it is invalid, with _aria-invalid="true"_, and refer to its message with _aria-describedby_. Wicket does not render either attribute, so we add them with a behavior: + +[source,java] +---- +public class AriaInvalidBehavior extends Behavior { + + private final Component errorMessage; + + public AriaInvalidBehavior() { + this(null); + } + + public AriaInvalidBehavior(Component errorMessage) { + this.errorMessage = errorMessage; + } + + @Override + public void bind(Component component) { + if (!(component instanceof FormComponent)) { + throw new IllegalArgumentException("AriaInvalidBehavior needs a FormComponent"); + } + if (errorMessage != null) { + errorMessage.setOutputMarkupId(true); + } + } + + @Override + public void onComponentTag(Component component, ComponentTag tag) { + if (((FormComponent<?>) component).isValid() == false) { + tag.put("aria-invalid", "true"); + if (errorMessage != null) { + tag.append("aria-describedby", errorMessage.getMarkupId(), " "); + } + } + } +} +---- + +The behavior writes both attributes only while the field has an error message, which is the case in the render that follows a failed submit. _ComponentTag.append_ keeps an _aria-describedby_ that is already in the markup, for instance one that points to a hint about the expected format. The page puts it together: + +[source,java] +---- +public class RegistrationPage extends BasePage { + + public RegistrationPage() { + Form<Void> form = new Form<>("form"); + form.setOutputMarkupId(true); + add(form); + + EmailTextField email = new EmailTextField("email", Model.of("")); + email.setRequired(true); + form.add(email); + + ComponentFeedbackPanel emailError = new ComponentFeedbackPanel("emailError", email); + form.add(emailError); + email.add(new AriaInvalidBehavior(emailError)); + + form.add(new AjaxButton("register") { + @Override + protected void onSubmit(AjaxRequestTarget target) { + // store the registration + } + + @Override + protected void onError(AjaxRequestTarget target) { + target.add(form); + form.visitFormComponents((field, visit) -> { + if (field.isValid() == false) { + target.focusComponent(field); + visit.stop(); + } + }); + } + }); + } + + @Override + protected String getPageTitle() { + return "Register - Example"; + } +} +---- + +After a failed submit the field is rendered like this (the markup ids are generated by Wicket): + +[source,html] +---- +<input type="email" autocomplete="email" value="" required="required" placeholder="Email address" + pattern="..." name="email" id="email3" aria-invalid="true" aria-describedby="emailError4"> +<div class="field-error" id="emailError4"> + <ul class="feedbackPanel"> + <li class="feedbackPanelERROR"><span>'Email address' is required.</span></li> + </ul> +</div> +---- + +When the form is submitted with AJAX, as here, _onError_ moves the focus to the first field in error. A screen reader then reads the label of the field, that it is invalid, and the error message. Without the focus change the user would not notice that anything happened. When the form is submitted without AJAX, the whole page is rendered again and the focus starts at the top; a summary of the errors at the top of the form, with links to the fields, is then the way to lead the user to them. + +The text of the message is ours to write. Success criterion 3.3.3 asks that it suggests how to correct the input, which the generic messages of Wicket's validators do not always do. They can be reworded for a single field in the resource bundle of the page, with a key that combines the component id and the validator, for example _email.Required_ or _email.EmailAddressValidator_ (see <<_wicket_forms_in_detail,chapter 12>>). + +=== aria-invalid for every field + +Instead of adding _AriaInvalidBehavior_ to each field, we can add it to every form component the application creates, with a component instantiation listener in the _init_ method of the application: + +[source,java] +---- +@Override +protected void init() { + super.init(); + getComponentInstantiationListeners().add(component -> { + if (component instanceof FormComponent) { + component.add(new AriaInvalidBehavior()); + } + }); +} +---- + +This gives every invalid field _aria-invalid_, but not the reference to its message, because the listener does not know where the message is. Fields with a message next to them still get an _AriaInvalidBehavior_ with that message, as in the example above. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc new file mode 100644 index 0000000000..ba76c4f688 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc @@ -0,0 +1,150 @@ + +When an AJAX response updates a part of the page, nothing tells the user so: the browser does not reload the page, the screen reader does not announce anything, and the keyboard focus stays where it was, if the element that had it still exists. In this paragraph we will see how to move the focus where the user needs it and how to announce what has changed. + +=== How Wicket replaces components + +Wicket updates a component by replacing its whole element in the DOM with the newly rendered markup. If the replaced element had the focus, Wicket gives the focus back to the new element with the same markup id. This works as long as the component keeps its markup id, which is the case for a component that stays in the component tree and has _setOutputMarkupId(true)_. + +The focus is lost when the focused element does not come back: a button that deletes its own row, a link that hides itself, or the items of a repeater that creates new components at every render, because new components get new markup ids. The focus then falls back to the start of the document, and keyboard and screen reader users have to find their way back from there (success criterion 2.4.3). + +=== Moving the focus with focusComponent + +In those cases we move the focus ourselves with _focusComponent_ of _AjaxRequestTarget_. Its argument must have _setOutputMarkupId(true)_, otherwise the method throws an _IllegalArgumentException_. Wicket sets the focus after the components of the response have been replaced, so the component may be one that is part of the same update. + +The next example is a page with a list of addresses, each with a button to delete it. After a deletion the button is gone, so we move the focus to the heading of the list: + +*AddressesPage.html:* + +[source,html] +---- +<wicket:extend> + <h1 wicket:id="heading" tabindex="-1">Your addresses</h1> + + <div role="status"> + <span wicket:id="status"></span> + </div> + + <ul wicket:id="list"> + <li wicket:id="addresses"> + <span wicket:id="address"></span> + <button wicket:id="delete">Delete<span class="visually-hidden"> <span wicket:id="deleteWhat"></span></span></button> + </li> + </ul> +</wicket:extend> +---- + +*AddressesPage.java:* + +[source,java] +---- +public class AddressesPage extends BasePage { + + private final List<String> addresses = new ArrayList<>(List.of("Main Street 1", "Station Road 2")); + + public AddressesPage() { + IModel<String> statusMessage = Model.of(""); + Label status = new Label("status", statusMessage); + status.setOutputMarkupId(true); + add(status); + + WebMarkupContainer heading = new WebMarkupContainer("heading"); + heading.setOutputMarkupId(true); + add(heading); + + WebMarkupContainer list = new WebMarkupContainer("list"); + list.setOutputMarkupId(true); + add(list); + + list.add(new ListView<>("addresses", () -> addresses) { + @Override + protected void populateItem(ListItem<String> item) { + item.add(new Label("address", item.getModel())); + AjaxLink<String> delete = new AjaxLink<>("delete", item.getModel()) { + @Override + public void onClick(AjaxRequestTarget target) { + addresses.remove(getModelObject()); + statusMessage.setObject("Address " + getModelObject() + " removed."); + + target.add(list, status); + target.focusComponent(heading); + } + }; + delete.add(new Label("deleteWhat", item.getModel())); + item.add(delete); + } + }); + } + + @Override + protected String getPageTitle() { + return "Your addresses - Example"; + } +} +---- + +A heading cannot receive focus by itself, so it gets _tabindex="-1"_: this lets a script focus it without adding it to the tab order. Which element should get the focus depends on the task. After deleting an item, the next item or the heading of the list are good choices; after opening a panel, its first field or its heading; after closing it, the control that opened it. + +Every _Delete_ button has the same visible text, so each button gets the address as hidden text, and a screen reader announces "Delete Main Street 1" (success criterion 2.4.4). The accessible name still starts with the visible text, as success criterion 2.5.3 asks. The hidden text uses a CSS class that hides content visually but not from screen readers: + +[source,css] +---- +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + overflow: hidden; + clip-path: inset(50%); + white-space: nowrap; +} +---- + +=== Announcing changes with a live region + +A message such as "Address removed" or "Your changes have been saved" is a status message: it should be announced without moving the focus (success criterion 4.1.3). This is what ARIA live regions are for. A screen reader announces changes to the content of an element with _role="status"_ (or _aria-live="polite"_), and urgent ones in an element with _role="alert"_. + +A live region only works if it is in the page before its content changes. Since Wicket replaces the whole element of a component it updates, the live region must not be that element: an element that is new in the page is not announced reliably. In the example above, the _<div role="status">_ is plain markup that stays in the page, and the AJAX response replaces only the _Label_ inside it. The label is rendered with an empty text when the page loads, so the region exists, empty, from the start. + +The same applies to a _FeedbackPanel_. It is not a live region, and messages that it shows after an AJAX update are not announced. Wrapping it in a region that stays in the page solves this: + +[source,html] +---- +<div role="status"> + <div wicket:id="feedback"></div> +</div> +---- + +[source,java] +---- +FeedbackPanel feedback = new FeedbackPanel("feedback"); +feedback.setOutputMarkupId(true); +add(feedback); +---- + +and, in the AJAX callback, _success("Your changes have been saved.")_ followed by _target.add(feedback)_. A live region is for short messages; for validation errors the field and its message, as shown in <<_accessible_form_errors,paragraph 25.4>>, work better than an announcement of all errors at once. + +=== Busy indicators + +The indicator of _AjaxIndicatorAppender_ and the indicating AJAX links and buttons is an image with an empty _alt_ attribute, so it is invisible to screen readers. For requests that take long, a "Loading..." text in a live region, set in the request's _before_ handler and cleared in the _complete_ handler (see <<_ajax_request_attributes_and_call_listeners,paragraph 19.6>>), tells all users that the application is working. + +=== Dialogs + +_ModalDialog_ from wicket-extensions can trap the focus inside the dialog with _trapFocus()_, and gives the focus back to the element that had it when the dialog is closed. With _closeOnEscape()_ the dialog can be closed with the Escape key. These are opt-in, and the dialog element has no ARIA role, so we add the role, _aria-modal_ and a reference to the title of the dialog by overriding _newDialog_: + +[source,java] +---- +ModalDialog dialog = new ModalDialog("dialog") { + @Override + protected WebMarkupContainer newDialog(String dialogId) { + WebMarkupContainer dialog = super.newDialog(dialogId); + dialog.add(AttributeModifier.replace("role", "dialog")); + dialog.add(AttributeModifier.replace("aria-modal", "true")); + dialog.add(AttributeModifier.replace("aria-labelledby", "dialog-title")); + return dialog; + } +}; +dialog.trapFocus(); +dialog.closeOnEscape(); +add(dialog); +---- + +The content panel of the dialog then has a heading with _id="dialog-title"_, and a button that closes the dialog. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc new file mode 100644 index 0000000000..0ca983bf72 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc @@ -0,0 +1,53 @@ + +Every function of the application must be operable from the keyboard (success criterion 2.1.1). With Wicket this mostly comes down to the element an AJAX component or behavior is attached to. + +=== Links and buttons, not div and span + +Browsers make two kinds of elements operable from the keyboard: links with an _href_ attribute and form controls such as _<button>_. They can receive focus with the Tab key, the Enter key activates a link, Enter and Space activate a button, and screen readers announce them as link or button. A _<div>_ or _<span>_ has none of this. An _AjaxEventBehavior_ on _click_ attached to a _<div>_ works with the mouse, but a keyboard user cannot reach it, and a screen reader user does not know it is there: + +[source,html] +---- +<!-- only for mouse users --> +<div wicket:id="details">Show details</div> +---- + +[source,java] +---- +add(new WebMarkupContainer("details") + .add(AjaxEventBehavior.onEvent("click", target -> showDetails(target)))); +---- + +The same goes for an _AjaxLink_ attached to a _<div>_ or _<span>_: _AjaxLink_ adapts the tag only when it is an _<a>_ or a _<button>_. The solution is to attach the component to the element that matches what it does. An action on the current page, such as showing details, deleting an item or opening a dialog, is a button: + +[source,html] +---- +<button wicket:id="details">Show details</button> +---- + +[source,java] +---- +add(new AjaxLink<Void>("details") { + @Override + public void onClick(AjaxRequestTarget target) { + showDetails(target); + } +}); +---- + +On a _<button>_, _AjaxLink_ renders _type="button"_, so the button does not submit a form it is in. Navigation to another page or to another state that the user may want to bookmark is a link, and a plain _Link_ or _BookmarkablePageLink_ on an _<a>_ tag does it without AJAX at all. On an _<a>_ tag, _AjaxLink_ renders _href="#"_: the link can receive focus and is operable from the keyboard, but screen readers announce it as a link, which is not what users expect of an action. + +Forms are submitted with _Button_, _AjaxButton_ or _AjaxSubmitLink_ on a _<button>_ or _<input type="submit">_. A form with such a button can also be submitted with the Enter key in a text field. + +If a custom widget cannot be a native element, it needs everything the native element would have given it: a role (_role="button"_), a place in the tab order (_tabindex="0"_), a key handler for Enter and Space, and an accessible name. This is a lot of work to get right, and a _<button>_ styled with CSS is nearly always the better choice. + +=== Events that change the context + +Some AJAX behaviors react to events that the user does not intend as a command. A behavior on _focus_ runs when keyboard users merely tab through the page; it must not navigate, submit or open a dialog (success criterion 3.2.1). A behavior on _change_, such as _AjaxFormComponentUpdatingBehavior_ or _OnChangeAjaxBehavior_, runs every time the value changes: in a _<select>_ that is navigated with the arrow keys, that is for every option the user passes. Updating a part of the page, such as [...] + +Behaviors that react to _mousedown_ or _pointerdown_ run before the user can cancel the action by moving the pointer away (success criterion 2.5.2). The _click_ event, which _AjaxLink_ and _AjaxButton_ use, does not have this problem. + +=== Dialogs and other widgets + +A modal dialog takes the keyboard focus when it opens, keeps it inside while it is open and gives it back when it closes. _ModalDialog_ does this with _trapFocus()_, and _closeOnEscape()_ gives keyboard users a way out without searching for the close button (success criterion 2.1.2). The setup is shown in <<_focus_and_announcements_after_ajax_updates,paragraph 25.5>>. + +For widgets such as tabs, trees and menus, the WAI-ARIA Authoring Practices (https://www.w3.org/WAI/ARIA/apg/[]) describe the roles and the keyboard interaction users expect. _TabbedPanel_ renders its tabs as a list of links, which is operable from the keyboard but does not implement the tabs pattern. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc new file mode 100644 index 0000000000..4360a3a173 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc @@ -0,0 +1,112 @@ + +A data table is accessible when its headers are marked as headers, so that a screen reader can announce the column (and the row) of each cell, when it has a caption that says what the table contains, and when the sort state of its columns is exposed. _DataTable_ from wicket-extensions renders most of this; this paragraph shows how to add the rest. + +=== What DataTable renders + +The headers of a _DataTable_ come from _HeadersToolbar_ or its AJAX variant _AjaxFallbackHeadersToolbar_. Each header is a _<th>_ with _scope="col"_, or _scope="colgroup"_ for a header that spans several columns. The header toolbar is placed in _<thead>_, the rows in _<tbody>_, as success criterion 1.3.1 asks. A _DataTable_ must be attached to a _<table>_ tag. + +=== A caption + +The _<caption>_ of a table is its title: screen readers announce it when the user enters the table, and it appears in their list of tables. _DataTable_ renders a caption when method _getCaptionModel_ returns a model with a text. By default it returns _null_, and the caption is not rendered: + +[source,java] +---- +public class ContactsTable extends DataTable<Contact, String> { + + public ContactsTable(String id, List<IColumn<Contact, String>> columns, + ISortableDataProvider<Contact, String> provider) { + super(id, columns, provider, 20); + setOutputMarkupId(true); + addTopToolbar(new AccessibleHeadersToolbar<>(this, provider)); + } + + @Override + protected IModel<String> getCaptionModel() { + return () -> "Contacts"; + } +} +---- + +_DataTable_ calls _getCaptionModel_ in its constructor, so the method must not use fields of the subclass, which are not initialized yet at that moment. A localized caption is a _ResourceModel_. + +=== Row headers + +In many tables one column identifies the row, like the name of a contact. Marking its cells as row headers lets screen readers announce the name together with the other cells of the row. _DataTable_ renders all cells of the body as _<td>_, and _IColumn_ has no way to render a _<th>_. We can rename the tag of the cells in the first column by overriding _newCellItem_ in the table: + +[source,java] +---- +@Override +protected Item<IColumn<Contact, String>> newCellItem(String id, int index, + IModel<IColumn<Contact, String>> model) { + if (index != 0) { + return super.newCellItem(id, index, model); + } + return new Item<>(id, index, model) { + @Override + protected void onComponentTag(ComponentTag tag) { + super.onComponentTag(tag); + tag.setName("th"); + tag.put("scope", "row"); + } + }; +} +---- + +The argument _index_ is the index of the column, and Wicket also renders the closing tag with the new name. + +=== Sortable headers + +A sortable header contains a link that changes the sort order, and the _<th>_ gets the CSS class _wicket_orderUp_, _wicket_orderDown_ or _wicket_orderNone_. As with the label classes of <<_accessible_form_errors,paragraph 25.4>>, the class is not exposed to assistive technology. The ARIA attribute _aria-sort_ on the header of the sorted column is: screen readers announce it as "sorted ascending" or "sorted descending". We add it in a subclass of the header toolbar: + +[source,java] +---- +public class AccessibleHeadersToolbar<S> extends AjaxFallbackHeadersToolbar<S> { + + public AccessibleHeadersToolbar(DataTable<?, S> table, ISortStateLocator<S> stateLocator) { + super(table, stateLocator); + } + + @Override + protected WebMarkupContainer newSortableHeader(String headerId, S property, + ISortStateLocator<S> locator) { + WebMarkupContainer header = super.newSortableHeader(headerId, property, locator); + header.get("orderByLink").setMarkupId(getTable().getMarkupId() + "-sort-" + property); + header.add(AttributeModifier.replace("aria-sort", () -> { + SortOrder order = locator.getSortState().getPropertySortOrder(property); + return switch (order) { + case ASCENDING -> "ascending"; + case DESCENDING -> "descending"; + case NONE -> null; + }; + })); + return header; + } +} +---- + +The header returned by _newSortableHeader_ is rendered as the _<th>_ itself, so the attribute ends up in the right place. When the model returns _null_, _AttributeModifier_ leaves the attribute out, so only the sorted column gets _aria-sort_. + +The second line of the method fixes a focus problem of AJAX sorting. _AjaxFallbackHeadersToolbar_ re-creates its headers at every render, so after a click on a sort link the table comes back with new sort links, with new markup ids. As we have seen in <<_focus_and_announcements_after_ajax_updates,paragraph 25.5>>, Wicket can only restore the focus to an element with the same markup id, so a keyboard user loses the focus after every sort. Giving the sort link (which the header contains wi [...] + +The resulting header looks like this: + +[source,html] +---- +<th class="wicket_orderUp" aria-sort="ascending" scope="col"> + <a href="..." id="contacts1-sort-name"><span>Name</span></a> +</th> +---- + +=== Paging + +The _NavigationToolbar_ of a _DataTable_ uses a _PagingNavigator_, whose links have the texts "<<", "<", ">" and ">>". A screen reader reads these characters as the name of the links; the descriptions "Go to first page" and so on are only in the _title_ attribute, which is not reliably announced (success criterion 2.4.4). The link of the current page, and the links to the first and previous page on the first page, are rendered without _href_ and with a _disabled_ attribute, which an _<a> [...] + +[source,html] +---- +<wicket:panel> + <a wicket:id="first"><span aria-hidden="true"><<</span><span class="visually-hidden"><wicket:message key="PagingNavigator.first"/></span></a> + ... +</wicket:panel> +---- + +The markup of the subclass must contain the same component ids as the original, _first_, _prev_, _navigation_ (with _pageLink_ and _pageNumber_), _next_ and _last_. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc new file mode 100644 index 0000000000..854ca14950 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc @@ -0,0 +1,162 @@ + +An application is checked against WCAG at three levels: assertions on the rendered markup in unit tests, automated checks with a rule engine in a browser, and checks by hand. The first two can run in every build. They are worth having, but they are not enough: automated tools find only a part of the failures. A tool can verify that an image has an _alt_ attribute, not that the text describes the image; that a field has a label, not that the label makes sense; that focus moves, not that i [...] + +=== Markup assertions with WicketTester + +With _WicketTester_ and _TagTester_ (see <<_test_driven_development_with_wicket,chapter 23>>) we can assert the accessibility properties our own code is responsible for, without a browser and at the speed of a unit test. The following test checks the base page and the registration form of this chapter: the _lang_ attribute, the page title, a label for every field and _aria-invalid_ with a description after a failed submit. + +[source,java] +---- +class AccessibilityTest { + + private WicketTester tester; + + @BeforeEach + void setUp() { + tester = new WicketTester(new MyApplication()); + } + + @AfterEach + void tearDown() { + tester.destroy(); + } + + @Test + void pageLanguageFollowsSessionLocale() { + tester.getSession().setLocale(Locale.forLanguageTag("nl-NL")); + tester.startPage(RegistrationPage.class); + + TagTester html = TagTester.createTagByName(tester.getLastResponseAsString(), "html"); + assertEquals("nl-NL", html.getAttribute("lang")); + } + + @Test + void pageHasTitle() { + tester.startPage(RegistrationPage.class); + + TagTester title = TagTester.createTagByName(tester.getLastResponseAsString(), "title"); + assertEquals("Register - Example", title.getValue()); + } + + @Test + void everyFieldHasLabel() { + tester.startPage(RegistrationPage.class); + String markup = tester.getLastResponseAsString(); + + Set<String> fields = Set.of("input", "select", "textarea"); + Set<String> unlabelledTypes = Set.of("hidden", "submit", "button", "reset", "image"); + List<TagTester> tags = TagTester.createTags(markup, + tag -> fields.contains(tag.getName()), false); + + assertFalse(tags.isEmpty()); + for (TagTester field : tags) { + if (unlabelledTypes.contains(field.getAttribute("type"))) { + continue; + } + String id = field.getAttribute("id"); + assertNotNull(id, "field without id: " + field.getMarkup()); + assertNotNull(TagTester.createTagByAttribute(markup, "for", id), + "no <label for=\"" + id + "\">"); + } + } + + @Test + void invalidFieldIsMarkedAndDescribed() { + tester.startPage(RegistrationPage.class); + + FormTester form = tester.newFormTester("form"); + form.setValue("email", ""); + tester.executeAjaxEvent("form:register", "click"); + + TagTester email = tester.getTagByWicketId("email"); + assertEquals("true", email.getAttribute("aria-invalid")); + + String errorId = email.getAttribute("aria-describedby"); + TagTester error = tester.getTagById(errorId); + assertTrue(error.getValue().contains("is required.")); + } +} +---- + +The method _createTags_ of _TagTester_ takes a function that selects tags by their name and attributes, which makes it easy to write checks that hold for all pages, such as the label check above, and to run them over every page of the application. After an AJAX request, _getTagByWicketId_ and _getTagById_ search the markup of the components in the AJAX response. + +=== Automated checks in the browser + +Many failures only show in the browser: contrast, which depends on the CSS; the names of elements as the browser computes them; duplicate ids; ARIA attributes that do not fit the role of their element. A rule engine such as https://github.com/dequelabs/axe-core[axe-core] checks these in the rendered page. It runs in a browser that a test drives, against the running application, so the test needs the application started in the same way as for other integration tests, and a browser automat [...] + +The following test uses Playwright for Java and Deque's Playwright integration for axe-core: + +[source,xml] +---- +<dependency> + <groupId>com.deque.html.axe-core</groupId> + <artifactId>playwright</artifactId> + <version>4.10.1</version> + <scope>test</scope> +</dependency> +---- + +[source,java] +---- +class AccessibilityBrowserIT { + + private static final String BASE_URL = System.getProperty("app.url", "http://localhost:8080"); + + private static final List<String> WCAG_22_AA = List.of("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", + "wcag22aa"); + + private static Playwright playwright; + + private static Browser browser; + + @BeforeAll + static void launchBrowser() { + playwright = Playwright.create(); + browser = playwright.chromium().launch(); + } + + @AfterAll + static void closeBrowser() { + playwright.close(); + } + + @Test + void registrationPage() { + Page page = browser.newPage(); + page.navigate(BASE_URL + "/register"); + assertNoViolations(page); + + page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Register")).click(); + page.locator("[aria-invalid=true]").first().waitFor(); + assertNoViolations(page); + } + + private static void assertNoViolations(Page page) { + AxeResults results = new AxeBuilder(page).withTags(WCAG_22_AA).analyze(); + List<Rule> violations = results.getViolations(); + assertTrue(violations.isEmpty(), () -> page.url() + "\n" + violations.stream() + .map(rule -> rule.getId() + ": " + rule.getHelp() + " (" + rule.getNodes().size() + "x)") + .collect(Collectors.joining("\n"))); + } +} +---- + +The tags restrict axe-core to the rules for WCAG 2.0, 2.1 and 2.2 at level A and AA. The test checks the page twice: as it loads, and after a failed submit. Many pages have states that only exist after an interaction, such as validation errors, an open dialog, a panel loaded by AJAX or a table sorted by another column, and each of these states needs its own check. Finding the button by its role and accessible name, as Playwright's _getByRole_ does, is a small accessibility check of its o [...] + +=== HTML validation + +WCAG 2.2 no longer has a success criterion for valid markup, but invalid markup still breaks accessibility: a duplicate _id_ makes a _<label for>_ or an _aria-describedby_ point to the wrong element, and a misnested element can change the structure that screen readers present. The https://validator.github.io/validator/[Nu Html Checker] validates HTML5. It can be run from the command line as _vnu.jar_ with the URLs of the running application, or with files written by tests from _getLastRe [...] + +In development mode Wicket leaves its own tags and _wicket:id_ attributes in the markup, which the checker reports as errors. Validate the markup of the application in deployment mode, or call _getMarkupSettings().setStripWicketTags(true)_ in the test configuration. + +=== Checks by hand + +No tool replaces the following checks. They take a few minutes per page, and they are the ones that find the problems users actually run into. + +* *Keyboard.* Put the mouse away and use the page with Tab, Shift+Tab, Enter, Space, the arrow keys and Escape. Every function must be reachable and operable, the focus must always be visible, it must move in a logical order, it must never get stuck, and after every AJAX update it must be somewhere sensible (success criteria 2.1.1, 2.1.2, 2.4.3, 2.4.7 and 2.4.11). +* *Screen reader.* Use the page with NVDA or JAWS on Windows, VoiceOver on macOS and iOS, or TalkBack on Android. Check that the title is read when the page loads, that headings and landmarks give an overview of the page, that every field announces its label and errors, that buttons and links announce what they do, and that status messages are announced (success criteria 1.3.1, 2.4.2, 2.4.6, 3.3.1, 4.1.2 and 4.1.3). +* *Zoom and reflow.* Zoom the browser to 200%: all text must grow and nothing may be cut off or overlap (success criterion 1.4.4). Then make the viewport 320 CSS pixels wide, which is the same as 1280 pixels at 400% zoom: the content must be readable without scrolling in two directions, except for content such as data tables that needs two dimensions (success criterion 1.4.10). Increase the line, paragraph, letter and word spacing as described in success criterion 1.4.12 and check that n [...] +* *Contrast.* Measure the contrast of text, of the borders of fields and buttons, of the focus indicator and of icons with a contrast checker, in every state: hover, focus, disabled and error (success criteria 1.4.3 and 1.4.11). +* *Content.* Read the alternative texts, headings, labels, link texts and error messages, and check that they make sense on their own (success criteria 1.1.1, 2.4.4, 2.4.6 and 3.3.3). + +The table in <<_wcag_2_2_success_criteria_in_wicket,paragraph 25.2>> lists, for each success criterion, what the application has to take care of, and is a checklist for the remaining criteria. diff --git a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc new file mode 100644 index 0000000000..cee4b18bb7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc @@ -0,0 +1,2 @@ + +WCAG conformance is a property of pages, and most of what makes a Wicket page accessible is in the markup and content we write ourselves. Wicket helps with labels connected through _wicket:for_, validation messages that name their field, table headers and captions, and focus restoration after AJAX updates. Where it does not help yet, as with the _lang_ attribute, _aria-invalid_, live regions, the sort state of table headers and the default error pages, a few lines of code with the curren [...] diff --git a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc index 72c82c58ad..a129969380 100644 --- a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc +++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc @@ -40,7 +40,7 @@ public class RegistrationPage extends Page { [source,html] ---- -<html> +<html lang="en"> <body> <form wicket:id="form"> <!-- These are internal structure information from RegistrationForm --> @@ -114,7 +114,7 @@ public class RegistrationPage extends Page { [source,html] ---- -<html> +<html lang="en"> <body> <form wicket:id="form"> <div wicket:id="registration"> diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc index 7c0509cdce..14b748e370 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc @@ -16,7 +16,7 @@ To avoid these kinds of problems we should build a stateless login page which do [source,html] ---- -<html> +<html lang="en"> <head> <meta charset="utf-8" /> </head> diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc index 15e0dddc28..5c9bd778d0 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc @@ -88,7 +88,7 @@ A notable difference between this component and Button is that SubmitLink can be [source,html] ---- -<html xmlns:wicket="http://wicket.apache.org"> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> </head> <body> diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc index df4b6658ff..dda7f2314b 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc @@ -9,7 +9,7 @@ In the next example (project UploadSingleFile) we will see a form which allows u [source,html] ---- -<html> +<html lang="en"> <head> </head> <body> diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc index 7c70e9f460..a7f8961f03 100644 --- a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc +++ b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc @@ -39,7 +39,7 @@ Here is the HTML markup for _HomePage_ (file HomePage.html): [source,html] ---- <!DOCTYPE html> -<html> +<html lang="en"> <head> <meta charset="utf-8" /> <title>Apache Wicket HelloWorld</title> diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc index c4231fca86..e664b0a37e 100644 --- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc +++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc @@ -9,7 +9,7 @@ In the following example we have defined a fragment in a page and we used it as [source,html] ---- -<html> +<html lang="en"> ... <body> ... @@ -33,7 +33,7 @@ When the page is rendered, markup inside the fragment will be inserted *inside d [source,html] ---- -<html> +<html lang="en"> ... <body> ... @@ -52,7 +52,7 @@ Instead of displaying this message with a new component or in a new page, we can [source,html] ---- -<html> +<html lang="en"> <body> <div wicket:id="contentArea"></div> <wicket:fragment wicket:id="formFrag"> diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc index 77ff7941a8..6d6f329bcc 100644 --- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc +++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc @@ -3,7 +3,7 @@ Wicket's _<wicket:remove>_ tag can be very useful when our web designer needs to [source,html] ---- -<html> +<html lang="en"> <head> </head> diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc index 059fab5078..897d27b126 100644 --- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc +++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc @@ -7,7 +7,7 @@ For example given the following markup and code: [source,html] ---- -<html> +<html lang="en"> <head> <title>Hello world page</title> </head> @@ -30,7 +30,7 @@ the output will be: [source,html] ---- -<html> +<html lang="en"> <head> <title>Hello world page</title> </head> diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc index a2f81fa6fd..0813f6fc22 100644 --- a/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc +++ b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc @@ -65,25 +65,34 @@ Now we can build a generic template page using our brand new panels. Its markup [source,html] ---- -<html> +<!DOCTYPE html> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> -<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -... +<meta charset="utf-8"> +<title wicket:id="pageTitle">Jug4Tenda</title> <!--Include CSS--> ... </head> <body> -<div id="header" wicket:id="headerPanel">header</div> +<a class="skip-link" href="#content">Skip to main content</a> +<header id="header" wicket:id="headerPanel">header</header> <div id="body"> - <div id="menu" wicket:id="menuPanel">menu</div> - <div id="content" wicket:id="contentComponent">content</div> + <nav id="menu" wicket:id="menuPanel">menu</nav> + <main id="content" tabindex="-1" wicket:id="contentComponent">content</main> </div> -<div id="footer" wicket:id="footerPanel">footer</div> +<footer id="footer" wicket:id="footerPanel">footer</footer> </body> </html> ---- -The HTML code for this page implements the generic left-menu layout of our site. You can note the 4 _<div>_ tags used as containers for the corresponding areas. +The HTML code for this page implements the generic left-menu layout of our site. Each layout area gets the HTML element that names its role: _<header>_, _<nav>_ for the menu, _<main>_ for the content and _<footer>_. Browsers and screen readers expose these elements as landmarks, so users can jump between the areas. Three more details make the template usable by everyone: + +* the _lang_ attribute on _<html>_ tells browsers and screen readers which language the page is written in; +* the _<title>_ is bound to a _Label_, so that every page can give itself its own title; +* the first link of the page, _Skip to main content_, lets keyboard users jump past the header and the menu straight to the content area. + +All three are discussed in <<_accessibility,chapter 25>>, which also shows how to derive the _lang_ attribute from the session locale instead of writing it in the markup. + The page class contains the code to physically assemble the page and panels: [source,java] @@ -102,17 +111,24 @@ public class JugTemplate extends WebPage { private Component footerPanel; public JugTemplate(){ + add(new Label("pageTitle", this::getPageTitle)); add(headerPanel = new HeaderPanel("headerPanel")); add(menuPanel = new MenuPanel("menuPanel")); add(footerPanel = new FooterPanel("footerPanel")); add(new Label(CONTENT_ID, "Put your content here")); } + protected String getPageTitle() { + return "Jug4Tenda"; + } + //getters for layout areas //... } ---- +The title label reads its text from method _getPageTitle_ each time the page is rendered, so subclasses override this method to give themselves a title of their own. + Done! Our template page is ready to be used. Now all the pages of our site will be subclasses of this parent page and they will inherit the layout and the HTML markup. They will only substitute the _Label_ inserted as content area with their custom content. === Final example @@ -159,6 +175,11 @@ public class SimpleLoginPage extends JugTemplate { replace(new LoginPanel(CONTENT_ID)); getMenuPanel().setVisible(false); } + + @Override + protected String getPageTitle() { + return "Login - Jug4Tenda"; + } } ---- diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc index b3c9402cb5..5c09f050b7 100644 --- a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc @@ -4,7 +4,7 @@ An example of a parent page using the tag _<wicket:child>_ is the following: [source,html] ---- -<html> +<html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head> @@ -35,7 +35,7 @@ Considering the two pages seen above, the final markup generated for child page [source,html] ---- -<html> +<html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> </head> @@ -56,22 +56,27 @@ Applying _<wicket:child>_ tag to our layout example, we obtain the following mar [source,html] ---- -<html> +<!DOCTYPE html> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <meta charset="utf-8"> + <title wicket:id="pageTitle">Jug4Tenda</title> </head> <body> -<div id="header" wicket:id="headerPanel">header</div> +<a class="skip-link" href="#content">Skip to main content</a> +<header id="header" wicket:id="headerPanel">header</header> <div id="body"> - <div id="menu" wicket:id="menuPanel">menu</div> - <wicket:child/> + <nav id="menu" wicket:id="menuPanel">menu</nav> + <main id="content" tabindex="-1"> + <wicket:child/> + </main> </div> -<div id="footer" wicket:id="footerPanel">footer</div> +<footer id="footer" wicket:id="footerPanel">footer</footer> </body> </html> ---- -We have replaced the _<div>_ tag of the content area with the tag _<wicket:child>_. Going forward with our example we can build a login page creating class _SimpleLoginPage_ which extends the _JugTemplate_ page, but with a related markup file like this: +We have replaced the content component inside the _<main>_ element with the tag _<wicket:child>_. The _<main>_ element itself stays in the template: it is plain markup now, and it is still the target of the skip link. Going forward with our example we can build a login page creating class _SimpleLoginPage_ which extends the _JugTemplate_ page, but with a related markup file like this: [source,html] ---- diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc index 10b7482797..2ad3676d8a 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc @@ -103,7 +103,7 @@ Html: [source,html] ---- -<html> +<html lang="en"> <head> <title>Login page</title> </head> diff --git a/wicket-user-guide/src/main/asciidoc/repeaters.adoc b/wicket-user-guide/src/main/asciidoc/repeaters.adoc index c77a5f52c5..6d88a824da 100644 --- a/wicket-user-guide/src/main/asciidoc/repeaters.adoc +++ b/wicket-user-guide/src/main/asciidoc/repeaters.adoc @@ -3,7 +3,7 @@ A common task for web applications is to display a set of items. The most typica [source,html] ---- -<html> +<html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Insert title here</title> diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc index 7e4032d9a6..fd59fb0c01 100644 --- a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc @@ -4,7 +4,7 @@ Some web developers prefer to put their <script> tags at the end of page body an [source,html] ---- -<html> +<html lang="en"> <head> //no <script> tag here... @@ -51,7 +51,7 @@ Please note that _HeaderResponseContainer_'s needs also a name for the correspon [source,html] ---- -<html> +<html lang="en"> <head> <!-- no <script> tag here... --> diff --git a/wicket-user-guide/src/main/asciidoc/single.adoc b/wicket-user-guide/src/main/asciidoc/single.adoc index 11c5056aa6..bc37beef57 100644 --- a/wicket-user-guide/src/main/asciidoc/single.adoc +++ b/wicket-user-guide/src/main/asciidoc/single.adoc @@ -727,6 +727,46 @@ include::testingspring/testingspring_2.adoc[leveloffset=+1] include::testingspring/testingspring_3.adoc[leveloffset=+1] +== Accessibility + +include::accessibility.adoc[] + +=== What Wicket does and what the application does + +include::accessibility/accessibility_1.adoc[leveloffset=+1] + +=== WCAG 2.2 success criteria in Wicket + +include::accessibility/accessibility_2.adoc[leveloffset=+1] + +=== An accessible base page + +include::accessibility/accessibility_3.adoc[leveloffset=+1] + +=== Accessible form errors + +include::accessibility/accessibility_4.adoc[leveloffset=+1] + +=== Focus and announcements after AJAX updates + +include::accessibility/accessibility_5.adoc[leveloffset=+1] + +=== Keyboard-operable AJAX controls + +include::accessibility/accessibility_6.adoc[leveloffset=+1] + +=== Accessible data tables + +include::accessibility/accessibility_7.adoc[leveloffset=+1] + +=== Validating an application + +include::accessibility/accessibility_8.adoc[leveloffset=+1] + +=== Summary + +include::accessibility/accessibility_9.adoc[leveloffset=+1] + == Wicket best practices include::bestpractices.adoc[] diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc index d888c9519c..a5d1470385 100644 --- a/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc +++ b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc @@ -9,7 +9,7 @@ This test class allows to check if the generated markup contains one or more tag [source,html] ---- -<html xmlns:wicket="http://wicket.apache.org"> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> <meta charset="utf-8" /> <title></title> 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 e1d91ff7a8..2ae53745aa 100644 --- a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc @@ -6,7 +6,7 @@ Bookmarkable pages can be linked directly inside markup files without writing an [source,html] ---- <!DOCTYPE html> -<html xmlns:wicket="http://wicket.apache.org"> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> <meta charset="utf-8" /> <title>Apache Wicket Quickstart</title> @@ -34,7 +34,7 @@ If we take a look also at the markup of SubPackagePage we can see that it contai [source,html] ---- <!DOCTYPE html> -<html xmlns:wicket="http://wicket.apache.org"> +<html lang="en" xmlns:wicket="http://wicket.apache.org"> <head> <meta charset="utf-8" /> <title>Apache Wicket Quickstart</title> diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc index eb11460212..8beff1303e 100644 --- a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc @@ -113,7 +113,7 @@ public void init() Class _org.apache.wicket.util.lang.Bytes_ is an utility class provided by Wicket to express size in bytes (for further details refer to the JavaDoc). -NOTE: More insights on internal page storing will be covered in <<internals.adoc#_wicket_internals,chapter 26>> +NOTE: More insights on internal page storing will be covered in <<internals.adoc#_wicket_internals,chapter 27>> === Page expiration
