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.
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
- Procedure / Function inserting a new tour
- Procedure / Function inserting a new tour step
- 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
- seed data on a new APEX session
- insert tour data to table UC_GUIDEDTOUR_SAMPLE_TOURS
- 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 name | Type | Description |
---|---|---|
ID | NUMBER | Tour Primary Key |
APPLICATION_ID | NUMBER | Application Id for which tour is defined |
PAGE_ID | NUMBER | Application Page Id for which tour is defined |
NAME | VARCHAR2(4000) | A tour name. A tour name must be unique in context of a Application Id and Application Page Id |
OPTIONS | VARCHAR2(4000) | A tour settings. Possible values are the following: ADD_MASK - Add MaskingDISABLE_PAGE_SCROLLING - Disable Page Scrolling |
INIT_JS | CLOB | A tour Initialization JavaScript Code allowing overriding a tour options.See the section JavaScript Initialization Code. |
FIRE_ON_PAGE_LOAD | VARCHAR2(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 Name | Data Type | Description |
---|---|---|
ID | NUMBER | Step Primary Key . |
TOUR_ID | NUMBER | Foreign Key to a tour that step belongs to. |
STEP_STATIC_ID | VARCHAR2(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_SEQUENCE | NUMBER | The value used to set the order of steps defined within tour. |
TITLE | VARCHAR2(4000) | Step title displayed to the end-user. |
BODY | CLOB | Step 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_PADDING | NUMBER | Step masking padding in pixels. |
MASK_RADIUS | NUMBER | Step masking radius in pixels. |
OPTIONS | VARCHAR2(4000) | Step options separated with the colon. Possible values are the following: DISABLE_STEP_ELEMENT - Disable Step ElementSHOW_CLOSE_BUTTON - Show Button Close (Title)BTN_STEP_BACK - Show Button BackBTN_STEP_CANCEL - Show Button CancelBTN_STEP_COMPLETE - Show Button CompleteBTN_STEP_NEXT - Show Button Next* BTN_STEP_HIDE - Show Button Hide |
PLACEMENT | VARCHAR2(20) | Step placement. Possible values are the following: top bottom left right |
INIT_JS | CLOB | A 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_ELEMENTS | VARCHAR2(4000) | A 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 name | Type | Description |
---|---|---|
ID | NUMBER | Tour Primary Key |
APPLICATION_ID | NUMBER | Application Id for which tour is defined |
PAGE_ID | NUMBER | Application Page Id for which tour is defined |
NAME | VARCHAR2(4000) | A tour name. A tour name must be unique in context of a Application Id and Application Page Id |
OPTIONS | VARCHAR2(4000) | A tour settings. Possible values are the following: ADD_MASK - Add MaskingDISABLE_PAGE_SCROLLING - Disable Page Scrolling |
INIT_JS | CLOB | A tour Initialization JavaScript Code allowing overriding a tour options.See the section JavaScript Initialization Code. |
FIRE_ON_PAGE_LOAD | VARCHAR2(1) | A flag used by the plug-in to display guided tour on page load. Possible values are the following Y N |
SESSION_ID | NUMBER | Used 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 Name | Data Type | Description |
---|---|---|
ID | NUMBER | Step Primary Key . |
TOUR_ID | NUMBER | Foreign Key to a tour that step belongs to. |
STATIC_ID | VARCHAR2(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_SEQUENCE | NUMBER | The value used to set the order of steps defined within tour. |
TITLE | VARCHAR2(4000) | Step title displayed to the end-user. |
BODY | CLOB | Step 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_PADDING | NUMBER | Step masking padding in pixels. |
MASK_RADIUS | NUMBER | Step masking radius in pixels. |
OPTIONS | VARCHAR2(4000) | Step options separated with the colon. Possible values are the following: DISABLE_STEP_ELEMENT - Disable Step ElementSHOW_CLOSE_BUTTON - Show Button Close (Title)BTN_STEP_BACK - Show Button BackBTN_STEP_CANCEL - Show Button CancelBTN_STEP_COMPLETE - Show Button CompleteBTN_STEP_NEXT - Show Button Next* BTN_STEP_HIDE - Show Button Hide |
PLACEMENT | VARCHAR2(20) | Step placement. Possible values are the following: top bottom left right |
INIT_JS | CLOB | A 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_ELEMENTS | VARCHAR2(4000) | A 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 Name | Data Type | Description |
---|---|---|
APPLICATION_ID | NUMBER | Application Id |
PAGE_ID | NUMBER | Application Page Id |
SESSION_ID | NUMBER | Application session id identifying the end-user. |
TOUR_NAME | VARCHAR2(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
) ;