Customize the Connected Lifecycle Events

Introduction

Oracle JavaScript Extension Toolkit (JET) apps contain a lifecycle event that is triggered each time a page or tab is loaded into the browser. The this.connected() function provides an opportunity to customize the page title to be specific to the newly displayed page or tab. The function also provides an opportunity to write a custom message to the aria-live region, which will cause a screen reader to announce that the page or tab has been loaded.

Objectives

In this tutorial, you will learn how to set an accessible page title and provide the correct load message to the aria-live region for each page and tab displayed in the ACCLearningPath app.

Prerequisites

Task 1: Define the Requirements

According to WCAG Success Criterion 2.4.2 Page Titled, each page of a web app needs to have a descriptive and unique title. The title should include the page, tab, and app name. There is no specific requirement for the format of the title, but the industry standard is to include the page and tab names first, followed by the app name. When the title is organized in this order, the screen reader speaks the most important and restrictive information first.

Even though the title changes when a new page is loaded, screen readers do not always announce that the page has changed. Especially in a single-page app like an Oracle JET app, page and tab loads occur without notification to the screen reader. In an effort to make Oracle JET more accessible, all apps created using the Oracle JET starter templates (release version 8.0.0 or later) contain the function accUtils.announce(). The function writes text into an aria-live region, which is always present in the Document Object Model (DOM). The Oracle JET templates also include a call to the accUtils.announce() method inside the this.connected lifecycle function. The text in this call states that the page or tab has been loaded.

Task 2: Customize the this.connected Lifecycle Function

The this.connected() function in a newly created Oracle JET app is very concise.

this.connected = function() {
      accUtils.announce("Dashboard page loaded.", "assertive");
      document.title = "Dashboard";
      // Implement further logic if needed
};

The first parameter to the accUtils.announce() method is the text to be spoken. The second parameter determines whether the text will be spoken immediately or wait until the screen reader has finished speaking other items in its buffer.

  1. Navigate to the ACCLearningPath/src/js/viewModels folder and open the intro.js file in a code editor.

  2. Find and modify the this.connected() function. Then save and close the file.

    this.connected = function () {
   accUtils.announce("Introduction page loaded.", "assertive");
   document.title = "Introduction -- Accessibility Learning Path";
   // Implement further logic if needed
};

  3. Open resources.js in an editor and modify its this.connected() function. Then save and close the file.

    this.connected = function () {
   accUtils.announce("Resources page loaded.", "assertive");
   document.title = "Resources -- Accessibility Learning Path";
   // Implement further logic if needed
};

  4. Open overview.js in an editor and modify its this.connected() function. Then save and close the file.

    this.connected = function () {
   accUtils.announce("Overview tab loaded.", "polite");
   document.title = "Introduction : Overview -- Accessibility Learning Path";
   // Implement further logic if needed
};

  5. Open organization.js in an editor and modify its this.connected() function. Then save and close the file.

    this.connected = function () {
   accUtils.announce("Organization tab loaded.", "polite");
   document.title = "Introduction : Organization -- Accessibility Learning Path";
   // Implement further logic if needed
};

  6. Open employees.js in an editor and modify its this.connected() function. Then save and close the file.

    this.connected = function () {
      accUtils.announce("Employees tab loaded.", "polite");
      document.title = "Introduction : Employees  --  Accessibility Learning Path";
      // Implement further logic if needed
};

  7. Open departments.js in an editor and modify its this.connected() function. Then save and close the file.

    this.connected = function () {
      accUtils.announce("Departments tab loaded.", "polite");
      document.title = "Introduction : Departments  -- Accessibility Learning Path";
      // Implement further logic if needed
};

  8. Start your screen reader.

  9. Run the app.

    $ ojet serve

    The browser opens to the Introduction page of the app, with the Overview tab loaded.

  10. Verify that the title is “Introduction : Overview – Accessibility Learning Path” and that the screen reader says, “Introduction page loaded” and “Overview tab loaded.”

  11. Click on the Organization tab in the tab bar.

  12. Verify that the title is “Introduction : Organization – Accessibility Learning Path” and that the screen reader says, “Organization tab loaded.”

    Note: If your screen reader does not mention the page title, try tabbing out and back into the page in your browser.

  13. Verify the title and spoken announcement for the remaining tabs and for the Resources page.

  14. Stop your screen reader.

The initial task of making an app accessible is complete. The next tutorial within this learning path is Validate the Accessibility of Master Detail Views.

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.