6 Developing the Team Member Pages

Develop the Team Member report generated by the Create Page Wizard into a useful directory of team members, then develop the Team Member form so that your users can edit the Team Member data more easily.

About This Lesson

You used the Create Application Wizard to generate a report and form for the DEMO_TEAM_MEMBERS table.

In this lesson, you use Page Designer to develop a common pair of pages: a report and form. reports are the formatted results of an SQL query; forms are pages paired with reports that enable users to update the table that the report queries. (Typically, a form is a child page to a parent report page.) Both pages query the DEMO_TEAM_MEMBERS table.

The Team Members report serves as a repository for your users’ contact information, whereas the Team Members form is a separate page that users can open to update the information in the Team Members report.

You develop the report page by updating the list of queried columns in the SQL query, updating the Primary report by removing some of the columns that are displayed in the runtime, and moving a button on the page and editing its text.

When the Create Application Wizard creates a report and form, forms appear in the runtime by default as modal dialogs. A modal dialog is an overlay window that displays within the same browser window. It remains active and focused until the user finishes with it and closes it.

For the form page, you update the appearance and function of the fields from the Create Page Wizard defaults, including the addition of a required condition to some fields and configure some Display Only items. You also add a sub region that users can expand if necessary to view information that is used less frequently.

Starting from here:

Basic Projects App Export - Topic 4.sql

If you have not completed the previous lessons, you can use the appendix "Importing an Application into a Workspace" to import the above SQL script into your workspace and continue working from this lesson forward. You can find this script in the /files subdirectory of where you unzipped the .zip file accompanying this tutorial.

6.1 Editing the SQL Query of an Interactive Report

End users can manipulate the data in interactive reports in Oracle Application Express for their own requirements, rather than needing you (the application developer) to define numerous reports. To enable end users to manipulate what data is shown and how it is displayed, you must define the SQL statement to retrieve all of the data from the underlying Oracle Database tables.

Use the Code Editor in Page Designer to edit the interactive report SQL to query columns in the DEMO_TEAM_MEMBERS table. This enables users to do things such as view other users’ tasks and update their own workflow.

To edit the Team Members interactive report in Page Designer:

  1. On the Application home page, click 2 - Team Members to navigate to Page 2.
  2. In the Rendering tree, select the Team Members region.
  3. In the Property Editor under Source: SQL Query, click the Code Editor icon.
    Code Editor icon
  4. In the Code Editor, delete the current contents, then copy and paste the following code: 
    select
"ID",
"USERNAME",
"FULL_NAME",
"EMAIL",
"PROFILE",
"CREATED",
"CREATED_BY",
"UPDATED",
"UPDATED_BY"
 from "DEMO_TEAM_MEMBERS"
  5. Click the Validate icon (checkmark) to confirm that the SQL statement is valid.

    Validate icon
  6. Click OK.
You have updated the SQL query of the interactive report.

6.2 Changing Which Columns Display in an Interactive Report in the Runtime

While the SQL statement of the interactive report must query all the above columns to function, displaying all of them in the interactive report hinders your users. Columns such as ID, CREATED, and CREATED_BY, exist primarily to inform you, not the end user.

Use the Actions menu in the runtime to configure the Primary report of the interactive report to change which columns end users can access.

To change which columns display in the interactive report:

  1. In Page Designer, click the Save and Run Page button.
    1. Click Try Again if prompted with a message about focusing the page.
    The runtime opens or refreshes in a separate browser window.
  2. In the runtime, click the Actions menu button adjacent to the search bar.
  3. Select Columns.
    The Select Columns dialog displays.
  4. In the Display in Report column, hold the Ctrl key and click the following items to select multiple items:

    • Id

    • Username

    • Created

    • Created By

    • Updated

    • Updated By

  5. Click the Remove button ( < ) located between the column panes.
  6. Click Apply.

You can also improve the report’s usability by setting the default order of the table to the alphabetic order of the Full Name column.

To sort the order of the rows by Full Name:

  1. Click the Full Name column heading to open the Column Heading menu and click the Sort Ascending icon.

Finally, you must save the report to preserve these changes to the Primary report of the interactive report (other report types include Private, Alternative, and Public).

All users can save a Private report, but only the developer can save a Primary report. A Primary report is the report that initially displays. A Primary report cannot be renamed or deleted by other users.

To save the current settings as the default:

  1. Click Actions, select Report, and select Save Report.
  2. For Save, select As Default Report Settings.
  3. Verify the Default Report Type is Primary and click Apply.

    Note:

    The Primary report is how all end users see the report when they first access the page. You can save any number of alternative reports, which end users can run by selecting from a drop-down list that is automatically displayed once any additional report layouts are saved.
You have hidden several columns from view and changed the default sort order of the interactive report.

6.3 Moving Buttons to a Different Region

The Create Page Wizard added a CREATE button automatically to the interactive report so that end users can add new members to the table quickly, but it would be more appropriate to relocate the button to a different place.

Use the context menu in Page Designer to move the CREATE button to the Breadcrumbs region.

Tip:

You can also move items in the Layout via drag and drop.

Tip:

Undo button To undo a previous action, click the Undo button.

To move a button to a different region using the context menu:

  1. In the runtime, click Edit Page 2 on the Developer Toolbar.
  2. In the Layout pane, right-click the CREATE button.
  3. Select Move To, select Breadcrumbs, and select Create.

    The CREATE button moves to the CREATE placeholder in the Breadcrumbs region.

    Note:

    In the Rendering tree, the Region Buttons folder (which contains the CREATE button) moves from Content Body to Breadcrumbs automatically.


    Description of GUID-5DCC113C-CD31-4AF8-9EF5-BF023441B323-default.png follows
    Description of the illustration GUID-5DCC113C-CD31-4AF8-9EF5-BF023441B323-default.png
  4. In the Property Editor:
    1. Identification: Label - enter Add Team Member
    2. Appearance: Hot - select Yes
  5. Click Save and Run Page to review the changed button.
    1. If the Focus Page dialog appears, click Try Again.
    The runtime opens or refreshes in a separate browser window.

You have moved the Create button.

The Report portion of the Team Members Report and Form is complete. Next, you develop the Team Members Form.

6.4 Enabling Stretch Form Fields for a Modal Dialog

Next, develop the Maintain Team Member form for the Team Members report page.

The Maintain Team Member form is a modal dialog. Modal dialogs are treated as separate pages in Page Designer because even though they behave like a page within a page, they can be as equally complex.

Begin by navigating to the form in Page Designer, then configuring the field widths in the form’s Template Options so that the form looks cleaner and more consistent.

To stretch the width of all fields in a region:

  1. In the runtime, click the Edit icon (pencil) next to a team member’s name to view the Maintain Team Member modal dialog.
  2. Click Edit Page 3 on the Developer Toolbar to view the page in Page Designer.
  3. Select the Maintain Team Member region.
  4. In the Property Editor, locate Appearance: Template Options and click the Template Options button (Use Template Defaults).
  5. In Template Options:

    • Advanced: Item Width - select Stretch Form Fields

  6. Click OK.
    The Template Options button changes to "Use Template Defaults, Stretch Form Fields."

6.5 Updating Form Fields to and Textarea

The Create App Wizard automatically populated this page with fields based on the columns of the DEMO_TEAM_MEMBERS table. Technically, the fields are all functioning and displaying correctly; however, your users would benefit from the following interface changes:

  • Require users complete certain fields, such as username. This is common and a good practice. The NOT NULL constraint enforces a column to NOT accept NULL values. This enforces a field to always contain a value, which means that you cannot insert a new record, or update a record without adding a value to this field.

  • Increase the size of the Profile field to encourage users to provide information. This field serves as a description of their roles and duties on the team.

  • Change the label of Photo Blob.

  • Hide the unnecessary fields from view to reduce clutter.

To change the Username and Full Name fields to required (so that users cannot leave them blank):

  1. Press and hold the Ctrl key and click P3_USERNAME and P3_FULL_NAME to select both of them.
  2. In the Property Editor:
    1. Appearance: Template - select Required
    2. Validation: Value Required - select Yes
    The Username and Full Name fields are now required.

The Profile field is where users enter biographical information, so it should support the display of multiple lines of text. To convert it to a Textarea:

  1. Select P3_PROFILE.
  2. In the Property Editor:
    1. Identification: Type - select Textarea
    The Profile field now displays as a paragraph instead of a single line.

To change the label of the “Photo Blob” field:

  1. Select P3_PHOTO_BLOB.
  2. In the Property Editor:
    1. Label: Label - enter Photo
    The field now is now labeled "Photo".

Several fields are completely unnecessary for users when they update their profile.

To hide fields from view:

  1. Press and hold the Ctrl key to select only the four following items (do not select P3_PHOTO_BLOB):

    • P3_PHOTO_FILENAME

    • P3_PHOTO_MIMETYPE

    • P3_PHOTO_CHARSET

    • P3_PHOTO_LAST_UPDATED

  2. In the Property Editor:
    1. Identification: Type - select Hidden

    The filename, mimetype, charset, and last updated fields of the photo are hidden from view in the runtime.

    Tip:

    You can also use the Quick Pick button to choose from a short list of the most commonly used types rather than viewing the entire list.
    Description of GUID-2462E263-19A7-4018-AFCD-860434F47477-default.png follows
    Description of the illustration GUID-2462E263-19A7-4018-AFCD-860434F47477-default.png

    Note:

    When you select multiple components, the Property Editor identifies common attributes with a blue triangle adjacent to the attribute name and outlines the attribute field in blue. If all of the selected components have the same Attribute Value, then the name and value display normally; if all the values do not match, the field is blank.

6.6 Creating an Expandable Sub Region

Some details (such as timestamps) can be useful, but most of the time your users do not need to see them. You can group them into an "Audit Details" sub region to preserve them for future use but still save space in the form.

To create a collapsible sub region:

  1. In the Rendering tree, right-click Maintain Team Member region and select Create Sub Region.
    The New sub region appears within the Sub Regions folder.
  2. In the Property Editor:
    1. Identification: Title - enter Audit Details
    2. Appearance: Template - select Collapsible

To move audit columns into the Audit Details sub region with the Property Editor:

  1. Hold the Ctrl key and select the following items:

    • P3_CREATED

    • P3_CREATED_BY

    • P3_UPDATED

    • P3_UPDATED_BY

  2. In the Property Editor:
    1. Layout: Region - select ..Audit Details

      Note:

      The double periods are a shortening device for the names of sub regions in the interface. Think of it as actually reading "Sub Region, Audit Details."

    The items move into the sub region.
  3. Click the Audit Details region.
  4. Locate and click the Appearance: Template Options button (Use Template Defaults, Expanded, Scroll - Default).
  5. In Template Options:
    1. Default State - select Collapsed
    2. Style - select Remove UI Decoration
  6. Click OK.
  7. In the Property Editor, click the Go to Group icon and select Server-side Condition.
    Go to Group icon
  8. In the Property Editor:
    1. Server-side Condition: Type - select Item is NOT NULL
    2. Server-side Condition: Item - enter or select P3_ID

6.7 Restricting User Access with the Display Only Item Type

While it is acceptable for your users to view the information in the audit columns, they should never have permission to alter this system-generated data directly. You can restrict users from editing these items by making them Display Only.

You should also verify this information is restricted in the runtime for security purposes.

To restrict users’ access to the audit columns in the region to Display Only:

  1. Hold the Ctrl key and select the following items in the Audit Details sub region:

    • P3_CREATED

    • P3_CREATED_BY

    • P3_UPDATED

    • P3_UPDATED_BY

  2. In the Property Editor:
    1. Identification: Type - select Display Only

When you are editing a modal dialog in Page Designer, the Save and Run button only saves your changes; it does not navigate to the page in a new browser window. You must open modal dialogs in their parent page in the runtime.

  1. Click Save.

To view the modal dialog in the runtime:

  1. Do one of the following:
    • Refresh the browser window containing the application runtime.
    • In Page Designer, enter 2 in the Page Finder and press Enter to navigate to the modal dialog’s parent page. Click Save and Run. The runtime displays in a new browser window.
  2. Click the Edit icon (pencil) adjacent to a user’s name to view the improved modal dialog.
  3. When you are finished, click Application #### on the Developer Toolbar to return to the Application home page.

You have completed updating the report and the form for the Team Members page.

In this lesson, you learned about interactive reports and how to edit their SQL queries and Primary reports; how to relocate buttons to the Breadcrumbs region; update the fields of a modal dialog from their default settings; and create a sub region with Display Only items.

Proceed to the next lesson.