Skip to main content

Usage

The plug-in allows defining guided tours directly in the APEX application pages using dynamic actions and storing tours and steps data outside APEX using custom database tables. Both approaches have pros and cons and it's up to the developer to choose the approach that meets thier requirements better.

Keep in mind that dynamic action execution order is defined by the APEX dynamic action Execution Options \ Sequence attribute.

Dynamic Action Based​

This approach requires defining at least one dynamic action to initialize a tour, tour steps, and launch a tour.

Display on Page Load​

The usage guide instructions presented below create a new tour with a single step and automatic launch of a tour on the page load.

  1. Create a new dynamic action

    1. Set Identification \ Name to Guided Tour
    2. Set When \ Event to Page Load

  2. Delete default true action Show

  3. Create a new true action (to initialize a tour)

    1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]
    2. Set Settings \ Action to Initialize Tour (Dynamic Action)
    3. Set Settings \ Tour Name to myFirstTour
    4. (Optional) Set Settings \ Tour Settings accordingly to your requirements

  4. Create a new true action (to add a step)

    1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]
    2. Set Settings \ Action to Add Step
    3. (Optional) Set Settings \ Step Static Id
    4. Set Settings \ Step Title
    5. Set Settings \ Step Body
    6. (Optional) Set Settings \ Masking Padding
    7. (Optional) Set Settings \ Masking Radius
    8. Set Settings \ Step Settings
    9. Set Settings \ Placement
    10. (Optional) Set Advanced \ JavaScript Initialization Code

  5. Create a new true action (to launch guided tour on the page load)

    1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]
    2. Set Settings \ Action to Run Tour (Name)
    3. Set Settings \ Tour Name to myFirstTour

  6. Save and run the page

Display on Button Click​

The usage guide steps below are describing defining a tour and step as in Display on Page Load but tour launch is done using a button and separate dynamic action.

  1. Follow the steps from 1 to 4 from section Display on Page Load

  2. Create a new button

  3. Create a new dynamic action Launch Tour listening to the newly created button (by default on click event)

    1. Delete default true action Show

    2. Create a new true action

      1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]
      2. Set Settings \ Action to Run Tour (Name)
      3. Set Settings \ Tour Name to myFirstTour

  4. Save and run the page

Table Based​

Table based guided tours require storing tours and steps in custom tables. The plug-in exposes 2 actions that differ only by the source from which data is fetched. Initialize Tour (Table) uses a hard-coded SQL Query, while on the other hand, action Initialize Tour (Custom Tables) expects two SQL Queries to be defined. Using action Initialize Tour (Custom Tables) gives more control over fetched tours and steps because a developer can implement custom logic using SQL Query conditions.

Both actions require defining tours and steps data in the database tables and creating at least one dynamic action on the APEX global page.

The Plug-in Action Initialize Tour (Table)​

This action is not shown as an example in the plug-in sample application, however, the implementation is very simple.

  1. Go to the global APEX page

  2. Create a new dynamic action

    1. Set Identification \ Name to Guided Tour from table
    2. Set When \ Event to Page Load
    3. Set Execution Options \ Sequence to 0

  3. Delete default true action Show

  4. Create a new true action (to initialize a tour)

    1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]
    2. Set Settings \ Action to Initialize Tour (Table)

  5. Learn about tables in the section Sample Application \ Supporting Tables

  6. Put tours and steps data into tables UC_GUIDEDTOUR_TOURS and UC_GUIDEDTOUR_STEPS

  7. Save the page and run an application

When the plug-in dynamic action is executed it fetches tours using the SQL Query:

select
  ugt.ID,
  ugt.NAME,
  ugt.OPTIONS,
  ugt.INIT_JS,
  ugt.FIRE_ON_PAGE_LOAD
from
  UC_GUIDEDTOUR_TOURS ugt
where
  APPLICATION_ID = :APP_ID
  and PAGE_ID = :APP_PAGE_ID

and steps using the SQL Query:

select
  ugs.ID,
  ugs.TOUR_ID,
  ugs.STEP_STATIC_ID,
  ugs.TITLE,
  ugs.BODY,
  ugs.MASK_PADDING,
  ugs.MASK_RADIUS,
  ugs.PLACEMENT,
  ugs.OPTIONS,
  ugs.INIT_JS,
  ugs.AFFECTED_ELEMENTS  
from
  UC_GUIDEDTOUR_STEPS ugs
join
  UC_GUIDEDTOUR_TOURS ugt  
on
  ugt.id = ugs.tour_id
where
  APPLICATION_ID = :APP_ID
  and PAGE_ID = :PAGE_ID
order by
  ugs.DISPLAY_SEQUENCE asc
;

The Plug-in Action Initialize Tour (Custom Tables)​

This action is used by the plug-in sample application in examples Table based tour (page 2) and One-time tour \ Table based (page 7). Example Table based tour is handled by a dynamic action defined on the sample application global page, while example One-time tour \ Table based has its own dynamic action defined on page 7. These are two separate implementations because the One-time tour is using an additional table (in SQL Query condition) handling the end-user choice to display or not the example tour.

This usage guide describes the basic implementation without any additional custom logic. To learn more investigate the sample application examples.

  1. Go to the global APEX page

  2. Create a new dynamic action

    1. Set Identification \ Name to Guided Tour from custom tables
    2. Set When \ Event to Page Load
    3. Set Execution Options \ Sequence to 0

  3. Delete default true action Show

  4. Create a new true action (to initialize a tour)

    1. Set Identification \ Action to United Codes Guided Tour Pro [plug-in]

    2. Set Settings \ Action to Initialize Tour (Custom Tables)

    3. Set Settings \ SQL Query Returning Tours to: 

      select
        ID as ID,
        APPLICATION_ID as APPLICATION_ID,
        PAGE_ID as PAGE_ID,
        NAME as NAME,
        OPTIONS as OPTIONS,
        INIT_JS as INIT_JS,
        FIRE_ON_PAGE_LOAD as FIRE_ON_PAGE_LOAD
      from
        UC_GUIDEDTOUR_TOURS
      where
        APPLICATION_ID = :APP_ID
        and PAGE_ID = :APP_PAGE_ID

    4. Set Settings \ SQL Query Returning Tour Steps to: 

      select
        ID as ID,
        TOUR_ID as TOUR_ID,
        TITLE as TITLE,
        BODY as BODY,
        STATIC_ID as STEP_STATIC_ID,
        MASK_PADDING as MASK_PADDING,
        MASK_RADIUS as MASK_RADIUS,
        OPTIONS as OPTIONS,
        INIT_JS as INIT_JS,
        AFFECTED_ELEMENTS as AFFECTED_ELEMENTS,
        PLACEMENT as PLACEMENT,
        DISPLAY_SEQUENCE as DISPLAY_SEQUENCE
      from
        UC_GUIDEDTOUR_STEPS

  5. Learn about tables in the section Sample Application \ Supporting Tables

  6. Put tours and steps data into tables UC_GUIDEDTOUR_TOURS and UC_GUIDEDTOUR_STEPS

  7. Save the page and run an application