Skip to main content

Live demo

You can play with the plug-in without installing it using the sample application available online.

The sample application enables you to learn about the plug-in capabilities, Oracle APEX APEX integration, and simple examples of how to use the United Codes Guided Tour Pro plug-in.

The plug-in sample application can be downloaded and installed in your APEX scheme for free using the Trial License.

The plug-in sample application is one way to install the plug-in. Learn more in the section Getting Started \ Installation.

image-20230303135652378

Identifying the End-User

The sample application is a publicly available application which means the end-user visiting the application is logged as APEX_PUBLIC_USER. In order to let all visitors have an individual experience without being affected by changes made by other visitors, the application seeds tours and steps data when the APEX session is created. Because of that, the sample application table UC_GUIDEDTOUR_SAMPLE_TOURS is extended with the SESSION_ID column. The column is used to make tours and tour steps end-user specific and thanks to this, users don’t affect each other's data.

Supporting Packages

UC_GUIDEDTOUR_API

The Guided Tour Pro sample application is delivered with package UC_GUIDEDTOUR_API. The package is used to create new tours and steps in the plug-in structures UC_GUIDEDTOUR_TOURS and UC_GUIDEDTOUR_STEPS. The package is used in the sample application page Tour Builder.

The package contains

  1. Procedure / Function inserting a new tour
  2. Procedure / Function inserting a new tour step
  3. Procedures to remove existing tour and step
create or replace package UC_GUIDEDTOUR_API as

procedure deleteTour(
p_tour_id in UC_GUIDEDTOUR_TOURS.ID%TYPE
);

procedure updateTour(
p_tour_id in UC_GUIDEDTOUR_TOURS.ID%TYPE,
p_app_id in UC_GUIDEDTOUR_TOURS.APPLICATION_ID%TYPE,
p_app_page_id in UC_GUIDEDTOUR_TOURS.PAGE_ID%TYPE,
p_name in UC_GUIDEDTOUR_TOURS.NAME%TYPE,
p_options in UC_GUIDEDTOUR_TOURS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_TOURS.INIT_JS%TYPE default null,
p_fire_on_page_load in UC_GUIDEDTOUR_TOURS.FIRE_ON_PAGE_LOAD%TYPE default 'N'
);

function insertTour(
p_app_id in UC_GUIDEDTOUR_TOURS.APPLICATION_ID%TYPE,
p_app_page_id in UC_GUIDEDTOUR_TOURS.PAGE_ID%TYPE,
p_name in UC_GUIDEDTOUR_TOURS.NAME%TYPE,
p_options in UC_GUIDEDTOUR_TOURS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_TOURS.INIT_JS%TYPE default null,
p_fire_on_page_load in UC_GUIDEDTOUR_TOURS.FIRE_ON_PAGE_LOAD%TYPE default 'N'
) return UC_GUIDEDTOUR_TOURS.ID%TYPE;


procedure insertTour(
p_app_id in UC_GUIDEDTOUR_TOURS.APPLICATION_ID%TYPE,
p_app_page_id in UC_GUIDEDTOUR_TOURS.PAGE_ID%TYPE,
p_name in UC_GUIDEDTOUR_TOURS.NAME%TYPE,
p_options in UC_GUIDEDTOUR_TOURS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_TOURS.INIT_JS%TYPE default null,
p_fire_on_page_load in UC_GUIDEDTOUR_TOURS.FIRE_ON_PAGE_LOAD%TYPE default 'N'
);

function insertStep(
p_tour_id in UC_GUIDEDTOUR_STEPS.TOUR_ID%TYPE,
p_step_static_id in UC_GUIDEDTOUR_STEPS.STEP_STATIC_ID%TYPE,
p_display_sequence in UC_GUIDEDTOUR_STEPS.DISPLAY_SEQUENCE%TYPE,
p_title in UC_GUIDEDTOUR_STEPS.TITLE%TYPE,
p_body in UC_GUIDEDTOUR_STEPS.BODY%TYPE,
p_mask_padding in UC_GUIDEDTOUR_STEPS.MASK_PADDING%TYPE,
p_mask_radius in UC_GUIDEDTOUR_STEPS.MASK_RADIUS%TYPE,
p_placement in UC_GUIDEDTOUR_STEPS.PLACEMENT%TYPE,
p_options in UC_GUIDEDTOUR_STEPS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_STEPS.INIT_JS%TYPE,
p_affected_elements in UC_GUIDEDTOUR_STEPS.AFFECTED_ELEMENTS%TYPE
) return UC_GUIDEDTOUR_STEPS.ID%TYPE;

procedure insertStep(
p_tour_id in UC_GUIDEDTOUR_STEPS.TOUR_ID%TYPE,
p_step_static_id in UC_GUIDEDTOUR_STEPS.STEP_STATIC_ID%TYPE,
p_display_sequence in UC_GUIDEDTOUR_STEPS.DISPLAY_SEQUENCE%TYPE,
p_title in UC_GUIDEDTOUR_STEPS.TITLE%TYPE,
p_body in UC_GUIDEDTOUR_STEPS.BODY%TYPE,
p_mask_padding in UC_GUIDEDTOUR_STEPS.MASK_PADDING%TYPE,
p_mask_radius in UC_GUIDEDTOUR_STEPS.MASK_RADIUS%TYPE,
p_placement in UC_GUIDEDTOUR_STEPS.PLACEMENT%TYPE,
p_options in UC_GUIDEDTOUR_STEPS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_STEPS.INIT_JS%TYPE,
p_affected_elements in UC_GUIDEDTOUR_STEPS.AFFECTED_ELEMENTS%TYPE
);

procedure updateStep(
p_step_id in UC_GUIDEDTOUR_STEPS.ID%TYPE,
p_tour_id in UC_GUIDEDTOUR_STEPS.TOUR_ID%TYPE,
p_step_static_id in UC_GUIDEDTOUR_STEPS.STEP_STATIC_ID%TYPE,
p_display_sequence in UC_GUIDEDTOUR_STEPS.DISPLAY_SEQUENCE%TYPE,
p_title in UC_GUIDEDTOUR_STEPS.TITLE%TYPE,
p_body in UC_GUIDEDTOUR_STEPS.BODY%TYPE,
p_mask_padding in UC_GUIDEDTOUR_STEPS.MASK_PADDING%TYPE,
p_mask_radius in UC_GUIDEDTOUR_STEPS.MASK_RADIUS%TYPE,
p_placement in UC_GUIDEDTOUR_STEPS.PLACEMENT%TYPE,
p_options in UC_GUIDEDTOUR_STEPS.OPTIONS%TYPE,
p_init_js in UC_GUIDEDTOUR_STEPS.INIT_JS%TYPE,
p_affected_elements in UC_GUIDEDTOUR_STEPS.AFFECTED_ELEMENTS%TYPE
);

procedure deleteStep(
p_step_id in UC_GUIDEDTOUR_STEPS.ID%TYPE
);

end UC_GUIDEDTOUR_API;

UC_GUIDEDTOUR_SAMPLE_APP

The Guided Tour Pro sample application is delivered with an example package UC_GUIDEDTOUR_SAMPLE_APP. The package is used to create new tours and steps for every new APEX session. The data insertion is done using the sample application process Insert data for a new instance (application processes).

The package contains 3 procedures used to

  1. seed data on a new APEX session
  2. insert tour data to table UC_GUIDEDTOUR_SAMPLE_TOURS
  3. insert step data to table UC_GUIDEDTOUR_SAMPLE_STEPS
create or replace package UC_GUIDEDTOUR_SAMPLE_APP as

procedure new_session(
p_session_id in varchar2,
p_app_id in number,
p_app_page_id in number
);

procedure insertTour(
p_session_id in number,
p_app_id in number,
p_app_page_id in number,
p_name in varchar2,
p_options in varchar2,
p_init_js in varchar2 default null,
p_fire_on_page_load in varchar2 default 'N'

);

procedure insertStep(
p_tour_id in number,
p_title in varchar2,
p_body in varchar2,
p_step_id in varchar2,
p_mask_padding in number,
p_mask_radius in number,
p_options in varchar2,
p_affected_elements in varchar2,
p_init_js in varchar2 default null,
p_placement in varchar2 default 'bottom'
);

end UC_GUIDEDTOUR_SAMPLE_APP;

Supporting Tables

The plug-in action Initialize Tour (Table) uses hard-coded SQL queries to fetch tour data and steps data from tables UC_GUIDEDTOUR_TOURS and UC_GUIDEDTOUR_STEPS. The plug-in sample application uses custom tables UC_GUIDEDTOUR_SAMPLE_TOURS, UC_GUIDEDTOUR_SAMPLE_STEPS, and UC_GUIDEDTOUR_SAMPLE_DISABLED to present example usage of the action Initialize Tour (Custom Tables).

UC_GUIDEDTOUR_TOURS

The table is used by the plug-in to fetch tours definition when a dynamic action implementing the plug-in uses the plug-in action Initialize Tour (Table).

Column nameTypeDescription
IDNUMBERTour Primary Key
APPLICATION_IDNUMBERApplication Id for which tour is defined
PAGE_IDNUMBERApplication Page Id for which tour is defined
NAMEVARCHAR2(4000)A tour name. A tour name must be unique in context of a Application Id and Application Page Id
OPTIONSVARCHAR2(4000)A tour settings.

Possible values are the following:

ADD_MASK - Add Masking

DISABLE_PAGE_SCROLLING - Disable Page Scrolling
INIT_JSCLOBA tour Initialization JavaScript Code allowing overriding a tour options.

See the section JavaScript Initialization Code.
FIRE_ON_PAGE_LOADVARCHAR2(1)A flag used by the plug-in to display guided tour on page load.

Possible values are the following

Y

N

The sample application is delivered with supporting objects which create the table, sequence, and trigger. The installation script is presented below.

CREATE TABLE "UC_GUIDEDTOUR_TOURS" 
( "ID" NUMBER NOT NULL ENABLE,
"APPLICATION_ID" NUMBER NOT NULL ENABLE,
"PAGE_ID" NUMBER NOT NULL ENABLE,
"NAME" VARCHAR2(4000) NOT NULL ENABLE,
"OPTIONS" VARCHAR2(4000),
"INIT_JS" CLOB,
"FIRE_ON_PAGE_LOAD" VARCHAR2(1) NOT NULL ENABLE,
CONSTRAINT "UC_GUIDEDTOUR_TOURS_PK" PRIMARY KEY ("ID")
USING INDEX ENABLE,
CONSTRAINT "UC_GUIDEDTOUR_TOURS_UK1" UNIQUE ("APPLICATION_ID", "PAGE_ID", "NAME")
USING INDEX ENABLE
) ;

/

CREATE SEQUENCE "UC_GUIDEDTOUR_TOURS_SEQ" MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 41 CACHE 20 NOORDER NOCYCLE NOKEEP GLOBAL ;

/

CREATE OR REPLACE TRIGGER "BI_UC_GUIDEDTOUR_TOURS"
before insert on "UC_GUIDEDTOUR_TOURS"
for each row
begin
if :NEW."ID" is null then
select "UC_GUIDEDTOUR_TOURS_SEQ".nextval into :NEW."ID" from sys.dual;
end if;
end;

/

ALTER TRIGGER "BI_UC_GUIDEDTOUR_TOURS" ENABLE;

UC_GUIDEDTOUR_STEPS

The table is used by the plug-in to fetch tours steps definition when a dynamic action implementing the plug-in uses the plug-in action Initialize Tour (Table).

Column NameData TypeDescription
IDNUMBERStep Primary Key.
TOUR_IDNUMBERForeign Key to a tour that step belongs to.
STEP_STATIC_IDVARCHAR2(4000)Static step id clearly distinguishes steps defined in one tour instance - it must be unique in the scope of a tour instance. Static step id is used by the Shepherd JavaScript API. Learn more from Shepherd documentation for Tour and Step.
DISPLAY_SEQUENCENUMBERThe value used to set the order of steps defined within tour.
TITLEVARCHAR2(4000)Step title displayed to the end-user.
BODYCLOBStep body HTML displayed to the end-user. Although the body is stored in CLOB, the maximum length must be limited to 32767 characters. Values exceeding the limit will cause the plug-in break.
MASK_PADDINGNUMBERStep masking padding in pixels.
MASK_RADIUSNUMBERStep masking radius in pixels.
OPTIONSVARCHAR2(4000)Step options separated with the colon.

Possible values are the following:

DISABLE_STEP_ELEMENT - Disable Step Element

SHOW_CLOSE_BUTTON - Show Button Close (Title)

BTN_STEP_BACK - Show Button Back

BTN_STEP_CANCEL - Show Button Cancel

BTN_STEP_COMPLETE - Show Button Complete

BTN_STEP_NEXT - Show Button Next

* BTN_STEP_HIDE - Show Button Hide
PLACEMENTVARCHAR2(20)Step placement.

Possible values are the following:

top

bottom

left

right
INIT_JSCLOBA step Initialization JavaScript Code allowing overriding a step options. A value should implement anonymous JavaScript function accepting only one parameter pOptions.

See the section JavaScript Initialization Code.
AFFECTED_ELEMENTSVARCHAR2(4000)jQuery Selector referencing step element. If left NULL a step is displayed as a centered step without any reference to the DOM element.

The sample application is delivered with supporting objects which create the table, sequence, and trigger. The installation script is presented below.

CREATE TABLE "UC_GUIDEDTOUR_STEPS" 
( "ID" NUMBER NOT NULL ENABLE,
"TOUR_ID" NUMBER NOT NULL ENABLE,
"STEP_STATIC_ID" VARCHAR2(4000),
"DISPLAY_SEQUENCE" NUMBER NOT NULL ENABLE,
"TITLE" VARCHAR2(4000) NOT NULL ENABLE,
"BODY" CLOB NOT NULL ENABLE,
"MASK_PADDING" NUMBER NOT NULL ENABLE,
"MASK_RADIUS" NUMBER NOT NULL ENABLE,
"PLACEMENT" VARCHAR2(4000) NOT NULL ENABLE,
"OPTIONS" VARCHAR2(4000),
"INIT_JS" CLOB,
"AFFECTED_ELEMENTS" VARCHAR2(4000),
CONSTRAINT "UC_GUIDEDTOUR_STEPS_PK" PRIMARY KEY ("ID")
USING INDEX ENABLE
) ;

ALTER TABLE "UC_GUIDEDTOUR_STEPS" ADD CONSTRAINT "UC_GUIDEDTOUR_STEPS_FK" FOREIGN KEY ("TOUR_ID")
REFERENCES "UC_GUIDEDTOUR_TOURS" ("ID") ON DELETE CASCADE ENABLE;

/

CREATE SEQUENCE "UC_GUIDEDTOUR_STEPS_SEQ" MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 41 CACHE 20 NOORDER NOCYCLE NOKEEP GLOBAL ;

/

CREATE OR REPLACE TRIGGER "BI_UC_GUIDEDTOUR_STEPS"
before insert on "UC_GUIDEDTOUR_STEPS"
for each row
begin
if :NEW."ID" is null then
select "UC_GUIDEDTOUR_STEPS_SEQ".nextval into :NEW."ID" from sys.dual;
end if;
end;

/

ALTER TRIGGER "BI_UC_GUIDEDTOUR_STEPS" ENABLE;

UC_GUIDEDTOUR_SAMPLE_TOURS

The table is designed to store the information required to successfully create a tour instance for the sample application.

The table includes column SESSION_ID in order to represent the end-user by the APEX session and is not required to implement table based tours in the production environment. The column is used by the sample application examples to identify anonymous end-user - every new session creates tour data that can't be modified by other users.

Column nameTypeDescription
IDNUMBERTour Primary Key
APPLICATION_IDNUMBERApplication Id for which tour is defined
PAGE_IDNUMBERApplication Page Id for which tour is defined
NAMEVARCHAR2(4000)A tour name. A tour name must be unique in context of a Application Id and Application Page Id
OPTIONSVARCHAR2(4000)A tour settings.

Possible values are the following:

ADD_MASK - Add Masking

DISABLE_PAGE_SCROLLING - Disable Page Scrolling
INIT_JSCLOBA tour Initialization JavaScript Code allowing overriding a tour options.

See the section JavaScript Initialization Code.
FIRE_ON_PAGE_LOADVARCHAR2(1)A flag used by the plug-in to display guided tour on page load.

Possible values are the following

Y

N
SESSION_IDNUMBERUsed only by the plug-in sample application to identify the end-user that is not authenticated.

The sample application is delivered with supporting objects which create the table, sequence, and trigger. The installation script is presented below.

CREATE TABLE "UC_GUIDEDTOUR_SAMPLE_TOURS" 
( "ID" NUMBER NOT NULL ENABLE,
"APPLICATION_ID" NUMBER,
"PAGE_ID" NUMBER,
"NAME" VARCHAR2(4000),
"OPTIONS" VARCHAR2(4000),
"SESSION_ID" NUMBER,
"INIT_JS" CLOB,
"FIRE_ON_PAGE_LOAD" VARCHAR2(1),
CONSTRAINT "UC_GUIDEDTOURS_TOURS_PK" PRIMARY KEY ("ID")
USING INDEX ENABLE
) ;

/

CREATE SEQUENCE "UC_GUIDEDTOURS_TOURS_SEQ" MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1661 CACHE 20 NOORDER NOCYCLE NOKEEP GLOBAL ;

/

CREATE OR REPLACE TRIGGER "BI_UC_GUIDEDTOURS_TOURS"
before insert on "UC_GUIDEDTOUR_SAMPLE_TOURS"
for each row
begin
if :NEW."ID" is null then
select "UC_GUIDEDTOURS_TOURS_SEQ".nextval into :NEW."ID" from sys.dual;
end if;
end;

/

ALTER TRIGGER "BI_UC_GUIDEDTOURS_TOURS" ENABLE;

UC_GUIDEDTOUR_SAMPLE_STEPS

The table is designed to store the required information to successfully create a tour step for the sample application.

Column NameData TypeDescription
IDNUMBERStep Primary Key.
TOUR_IDNUMBERForeign Key to a tour that step belongs to.
STATIC_IDVARCHAR2(4000)Static step id clearly distinguishes steps defined in one tour instance - it must be unique in the scope of a tour instance. Static step id is used by the Shepherd JavaScript API. Learn more from Shepherd documentation for Tour and Step.
DISPLAY_SEQUENCENUMBERThe value used to set the order of steps defined within tour.
TITLEVARCHAR2(4000)Step title displayed to the end-user.
BODYCLOBStep body HTML displayed to the end-user. Although the body is stored in CLOB, the maximum length must be limited to 32767 characters. Values exceeding the limit will cause the plug-in break.
MASK_PADDINGNUMBERStep masking padding in pixels.
MASK_RADIUSNUMBERStep masking radius in pixels.
OPTIONSVARCHAR2(4000)Step options separated with the colon.

Possible values are the following:

DISABLE_STEP_ELEMENT - Disable Step Element

SHOW_CLOSE_BUTTON - Show Button Close (Title)

BTN_STEP_BACK - Show Button Back

BTN_STEP_CANCEL - Show Button Cancel

BTN_STEP_COMPLETE - Show Button Complete

BTN_STEP_NEXT - Show Button Next

* BTN_STEP_HIDE - Show Button Hide
PLACEMENTVARCHAR2(20)Step placement.

Possible values are the following:

top

bottom

left

right
INIT_JSCLOBA step Initialization JavaScript Code allowing overriding a step options. A value should implement anonymous JavaScript function accepting only one parameter pOptions.

See the section JavaScript Initialization Code.
AFFECTED_ELEMENTSVARCHAR2(4000)jQuery Selector referencing step element. If left NULL a step is displayed as a centered step without any reference to the DOM element.

The sample application is delivered with supporting objects which create the table, sequence, and trigger. The installation script is presented below.

CREATE TABLE "UC_GUIDEDTOUR_SAMPLE_STEPS" 
( "ID" NUMBER NOT NULL ENABLE,
"TOUR_ID" NUMBER,
"TITLE" VARCHAR2(4000) NOT NULL ENABLE,
"BODY" CLOB NOT NULL ENABLE,
"MASK_PADDING" NUMBER NOT NULL ENABLE,
"MASK_RADIUS" NUMBER NOT NULL ENABLE,
"OPTIONS" VARCHAR2(4000),
"INIT_JS" CLOB,
"AFFECTED_ELEMENTS" VARCHAR2(4000),
"STATIC_ID" VARCHAR2(4000),
"PLACEMENT" VARCHAR2(20),
"DISPLAY_SEQUENCE" NUMBER NOT NULL ENABLE,
CONSTRAINT "UC_GUIDEDTOURS_STEPS_PK" PRIMARY KEY ("ID")
USING INDEX ENABLE,
CONSTRAINT "UC_GUIDEDTOURS_STEPS_CON" UNIQUE ("TOUR_ID", "STATIC_ID") DISABLE
) ;

/

CREATE SEQUENCE "UC_GUIDEDTOURS_STEPS_SEQ" MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 5821 CACHE 20 NOORDER NOCYCLE NOKEEP GLOBAL ;

/

CREATE OR REPLACE TRIGGER "BI_UC_GUIDEDTOURS_STEPS"
before insert on "UC_GUIDEDTOUR_SAMPLE_STEPS"
for each row
begin
if :NEW."ID" is null then
select "UC_GUIDEDTOURS_STEPS_SEQ".nextval into :NEW."ID" from sys.dual;
end if;
end;

/


ALTER TRIGGER "BI_UC_GUIDEDTOURS_STEPS" ENABLE;

UC_GUIDEDTOUR_SAMPLE_DISABLED

The table is used by the sample application example One-time tour. The table stores information about guided tours disabled by the end-user. The end-user is represented by the sample application APEX session.

Column NameData TypeDescription
APPLICATION_IDNUMBERApplication Id
PAGE_IDNUMBERApplication Page Id
SESSION_IDNUMBERApplication session id identifying the end-user.
TOUR_NAMEVARCHAR2(4000)A tour name to be disabled

The sample application is delivered with supporting objects which create the table. The installation script computed together is presented below.

CREATE TABLE "UC_GUIDEDTOUR_SAMPLE_DISABLED" 
( "APPLICATION_ID" NUMBER NOT NULL ENABLE,
"PAGE_ID" NUMBER NOT NULL ENABLE,
"SESSION_ID" NUMBER NOT NULL ENABLE,
"TOUR_NAME" VARCHAR2(4000) NOT NULL ENABLE
) ;