Monday, February 26, 2018

An Alternative to APEX_APPLICATION.HELP

If you are not familiar with the HELP function in the APEX_APPLICATION package, I'd recommend you first read about it in the APEX API Reference Documentation. The Example section provides the steps on how to implement this function in your application to display help information.

I tend to use this function in my projects since I like the idea of creating a reusable page to display help across the entire application. Unfortunately, it is limited to Page and Item(s) Help Text and, I find the parameters to customize the HTML output hard to work with.

I recently started working on a new project an decided to try a different approach. Instead of using the APEX_APPLICATION.HELP function, I'm querying the APEX Views to retrieve the metadata and using a Hero Region to display the page information and a Media List to display the items information.

I created a sample form using all the different item types and help text defined in the "Available Item Types" section on the APEX App Builder User's Guide to illustrate how the list looks like for each type of item:


As you can see, I'm using the same Page Designer icons to differentiate the Item Types, which provides additional visual information:


In case you are interested in doing something similar in your applications, below are the steps to accomplish this. Please let me know in the comments if you have any suggestions or feedback. And, as always, you can access my APEX Demo Application (Username/Password = Demo/Demo). Once you are in the Available Item Types page, click on "Help" on the upper right corner on the Navigation Bar List.

Finally, these are the steps (it assumes the Help page will be number 10):

  1. Create the Navigation Bar List entry with the Help link:
    • Go to Shared Components
    • Under Navigation, go to Navigation Bar List
    • Select the existing list, Desktop Navigation Bar
    • Click the Create Entry button
    • List Entry Label: Help
    • Page: 10
    • Set these items: P10_PAGE_ID
    • With these values: &APP_PAGE_ID.
  2. Create the dynamic Help list that queries the APEX view:
    • Go to Shared Components
    • Under Navigation, go to Lists
    • Click the Create button
    • Create List: From Scratch, Next
    • Name: Help List
    • Type: Dynamic, Next
    • SQL Query:
    • Click the Create button
  3. Create the modal Help page:
    • Go to the App Builder section in your application
    • Click on Create Page
    • Select a Page Type: Blank Page, Next
    • Page Number: 10
    • Name: Help
    • Page Mode: Modal Dialog, Next
    • Accept the defaults, then Finish
  4. Adjust the Help page properties:
    • Width: 800 (I found by not specifying a width, the report was overlapping the modal dialog window instead of wrapping the content.)
    • Under the CSS section, specify the File URLs: #IMAGE_PREFIX#apex_ui/css/core/IconFont.css?v=#APP_VERSION# (This IconFont.css is where the item types icons are defined.)
  5. Create the Hero Region that displays the Page Help:
    • Title: &P10_PAGE_NAME.
    • Type: PL/SQL Dynamic Content
    • PL/SQL Code: sys.htp.p(apex_escape.html_whitelist(:P10_PAGE_HELP_TEXT));
    • Template: Hero
    • Icon CSS Classes: fa-question-circle
    • Server-side Condition:
      • Type: Rows returned
      • SQL Query:
  6. Create the following Hidden Items under the Hero Region. Leave the defaults, including Value Protected = YES:
    • P10_PAGE_ID
    • P10_PAGE_NAME
      • Source Type: SQL Query (return single value)
      • SQL Query:
    • P10_PAGE_HELP_TEXT
      • Source Type: SQL Query (return single value)
      • SQL Query:
  7. Create the List Region that displays the Items' Help:
    • Title: Help
    • Type: List
    • List: Help List
    • Under Template Options:
      • Header: Hidden
    • Under Attributes:
      • List Template: Media List
      • Under Template Options, check Show Badges and Apply Theme Colors
And that's it!

2 comments:

  1. Great Help screen. I think I will use it for all my applications. Great job! Thanks for sharing!
    The only changes I made to my page were:
    1. Page Mode: Non-Modal Dialog - so the user can have the form and the help screen side by side.
    2. Add a [< Back] button since I removed the [X] to close the screen on all my dialogs.

    ReplyDelete
  2. Oops. I forgot another change I made:
    3. I added the type of item in attribute2:
    case
    when display_as_code like 'NATIVE%' then replace(Initcap(substr(display_as_code,8)),'_','-')
    else 'Other'
    end ||
    '
    '||
    'Required: ' || is_required || '' attribute2

    ReplyDelete