About Progress Bar Pro
Progress Bar Pro is your weapon of choice in enhancing the user experience while waiting on longer-lasting procedures to complete.
Users get real-time feedback from the database when running your code in the form of a modern, highly customizable progress bar.
Use the complementary Plug-in API calls to notify your users of the current percentage of completion, the number of processed rows, or current step in the process they are running.
Progress Bar Pro has you covered even if you want your users to be able to have insight into multiple jobs running in the background and their statuses.
Features at a Glance
Real-time
Users get real-time feedback about the status of their actions from the server.
API Included
Progress Bar Pro includes API calls ready to be used in your code to update the state of the progress bar.
Highly Customizable
Easily change style, text layout, and content with declarative options and add your own CSS and JS to take it a step further. Optionally, use text messages to enable multilingual support.
DB Scheduler Job Insight
Display the state of multiple DB Scheduler Jobs. Display them in a list view with the the out-of-the-box dialog and push success messages to users when the job is completed.
Custom Events
The plug-in triggers multiple events that enable you to further customize and interact with your processes.
Customizable Text
Use built-in substitution variables and text messages to declaratively define dynamic text content.
Variety of Styles
Inline in a region or even a button, overlay option, or list view. The choice is yours!
Secure
Bind the progress bar status to a user and session.
Optimized performance
All necessary data is obtained with a single AJAX call
Error Handling
Push error messages and stop progress bar execution when the process or job runs into an error.
Translations supported
Text messages are also supported for live status messages and completed process messages. Can be set as substitution strings or global variables if options are repeated.
Installation
Installation Files
dynamic_action_plugin_unitedcodes_progress_bar.sql - the plug-in installation files for Oracle APEX 18.1 or higher
ddl_unitedcodes_progress_bar_pro.sql – needed database objects and package to support plug-in rendering and API
Install Procedure
To successfully install/update the plug-in follow those steps:
Run ddl_unitedcodes_progress_bar_pro.sql in SQL Workshop > SQL Scripts > Upload and Run.
Run one of the following scripts (depending on your access to internet) in SQL Workshop > SQL Commands or Command Line SQL to activate the license:
Option 1: When you have access to the internet
set serveroutput on -- -- You can find the PLUGIN_NAME and YOUR_API_KEY in the your Plug-ins Pro dashboard -- -- when having access to the internet -- create a license automatically begin uc_pluginspro.auto_license( p_plugin => 'PLUGIN_NAME', p_api_key => 'YOUR_API_KEY'); end; /Option 2: When there is no access to the internet
set serveroutput on -- when there's no access to the internet -- create a license manually -- Step 1: Run the following statement. Then, follow the resulting -- instructions before moving on to Step 2. begin uc_pluginspro.manual_license( p_plugin => 'PLUGIN_NAME', p_api_key => 'YOUR_API_KEY'); end; / -- Step 2: The above statement will return your ACTIVATION KEY, which you will need to -- enter in your plug-ins-pro.com portal (Select the plug-in you -- are activating, then click the Generate License button) to -- retrieve your license key. -- When you have your license key, run the statement below. begin uc_pluginspro.manual_license( p_plugin => 'PLUGIN_NAME', p_api_key => 'YOUR_API_KEY', p_license_key => 'YOUR_LICENSE_KEY'); end; /
Import the APEX plug-in dynamic_action_plugin_unitedcodes_progress_bar.sql into your application.
After successfully importing dynamic_action_plugin_unitedcodes_progress_bar.sql you will be redirected to \Shared Components\Component Settings\ UC - Progress Bar Pro [Plug-in].
Here you can setup the Progress Bar Pro global parameters:
Text location: the display location of the text in relation to the bar position (Top, Inline, Bottom)
Top
Inline
Bottom
Text position: the display location of the text in relation to the bar position (Left, Center, Right)
Left
Center
Right
Usage Guide
This section describes an example of implementation Progress bar Pro in an Oracle APEX application.
Example for basic PROCESS implementation
The initial state of a basic PROCESS progress bar in page designer is presented below.
Steps:
Add Process »My Process«
Example of PL/SQL Code:
declare l_processname varchar2(128 char) := 'PROCESS_01'; begin UC_PROGRESSBAR_PKG.start_process(p_process_name => l_processname, p_maxval => 100); for i in 1..20 loop -- Pause for 0.5 second. UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname, p_value => i*5, p_process_text => 'completed'); sys.DBMS_SESSION.sleep(0.5); end loop; UC_PROGRESSBAR_PKG.stop_process(p_process_name => l_processname); end;Add a Button to the region and create the dynamic action (event Click)
Create a True Action of type UC – Progress Bar Pro [Plug-In]
Under Attributes the following must be set:
Process / Job Name: PROCESS_01 (Name must be the same as in Process PL/SQL code and we also recommend that the process and job name is always unique)
l_processname varchar2(128 char) := 'PROCESS_01';
Below is an example of the page after successfully setting up Progress Bar Pro:
Example for basic JOB implementation
The initial state of a basic JOB progress bar in page designer is presented below.
Steps:
Add a Button to the region and create the dynamic action (event Click)
Create a True Action of type Execute server-side Code
Example Code:
if not UC_PROGRESSBAR_PKG.is_running(p_process_name => 'J_UC_PROGRESSBAR_SAMPLEJOB_01') then dbms_scheduler.set_job_argument_value(job_name => 'J_UC_PROGRESSBAR_SAMPLEJOB_01', argument_position => 1, argument_value => 'J_UC_PROGRESSBAR_SAMPLEJOB_01'); DBMS_SCHEDULER.RUN_JOB( JOB_NAME => 'J_UC_PROGRESSBAR_SAMPLEJOB_01', USE_CURRENT_SESSION => FALSE); end if;Create a True Action of type UC – Progress Bar Pro [Plug-In]
Under Attributes the following must be set:
Action : Show progress bar (JOB name)
Process / Job Name : J_UC_PROGRESSBAR_SAMPLEJOB_01 (Name must be the same as in PL/SQL code and we also recommend that the process and job name is always unique)
Below is an example of the page after successfully setting up Progress Bar Pro:
Attributes
Settings
Action
Progress bar listener - Used mainly on the global page to load running processes in the background (JOBs, Events). This action is required in order for the "Show List" action, which displays all running processes, to work. It is also possible to define the progress bar listener in a single modal page in the combination with the “Show List” action, to avoid running the initialization code on each page.
Show progress bar (Process name) - This action is used when the user needs to wait for the completion of the process. This way we provide a better user experience for processes that require the user to stand by until the process is complete.
Show progress bar (JOB name) - This action is used for long-running processes and database jobs which we want to run in the background while the user continues with their work. This action will automatically pick up the running process used in the Progress Bar Pro API. The progress bar can be displayed in the “Show list” dialog and/or in a page component defined in the affected elements. We can also define a success message that is displayed after the process is completed.
Show progress bar (Event data) - This action is used as the listener for event data. If we are able to provide this.data on an event with this action then it is possible to dynamically display the progress bar. The purpose of this action is to trigger events like DB Job completion or failure in the background from the external library such as "APEX Office Print".
Show list (All running JOBs) - This action is used to display a list of jobs and events. Affected elements also has an impact on where to display the list.
Clear list (Event data) - With this action, we clear all events from a list in a current session. All events are put into "archive" mode (not displayed anymore).
Process / Job Name
With this attribute, we link the progress bar with our program logic (API). The progress bar will periodically represent the status of the process or DB Job.
This field is mandatory for the "Process" or "Job" type action.
The name of this process or job must be the same as was used in the "UC_PROGRESSBAR_PKG" API call (argument p_process_name as in the example below).
Style
Some basic settings to define the style of the progress bar. Additional options are possible by defining JavaScript Initialization Code or adding CSS settings.
Available options include:
Striped - The progress bar is displayed with a striped pattern.
Animation - Should the progress bar include an animation – only applicable when the striped option is enabled.
Overlay - Enable or disable full-screen overlay. Only applicable for the "Process" Type action.
Display text - If the text should be displayed inside or among the progress bar at all.
Small (no text inline) - This setting makes the progress bar a bit thinner. This is only applicable if the location of the text is set above or below the progress bar itself.
Color
Option to choose one of the APEX Universal Theme default color classes.
Check interval
Refresh interval defined in seconds.
For job types, we suggest putting more time between check status in order to avoid checking status in case of multiple jobs running at the same time.
In other words, this setting is the time between AJAX calls to the database.
Behavior
The behavior option is used only in "Job" and "Event" types of actions since the "Process" type is straight forward (the user needs to wait until it's finished).
Available options include:
Show inline success/error message - Show a success message after DB Job completion. Only applicable for the "Job" and "Event" type action.
In the case of custom message scripts (SweetAlert, Alertify...) you can turn down this option and use plug-in events to display your custom messages.
Remove after complete - Hide progress bar after completion from the affected elements of the built-in list.
Hide small on complete - Hide progress bar but keep the completion message. Only applicable on small progress bar (no text inline).
Auto open list - Show Job/Event directly on the built-in list. This way we avoid opening Job/Event in the center of the page.
Selection Type
Select how to define the page components to be affected when this action is executed.
Available options include:
Button - The action affects the button you select.
Region - The action affects the region you select.
jQuery Selector - The action affects the page element(s) returned using the jQuery selector syntax you enter.
JavaScript Initialization Code
With this attribute, some settings of the plug-in can be specified on the instance level.
Instead of repeating template settings, you can use "text messages" defined with the option "Used in JavaScript" set to "Yes".
For example, you can add the following text messages to your application :
UCPROCESS.STATUS > "%3"
UCPROCESS.PERCENT > "%1%"
UCPROCESS.PERCENT_OF > "%1% of %2%"
UCPROCESS.PERCENT_NAME > "%0 %1% of %2%"
UCPROCESS.ROWS > "%1 of %2 rows"
UCPROCESS.COMPLETE > "Complete %0!"
Replacement string parameters :
%0 - Name
%1 - Current value
%2 - Max value
%3 - Text status
Dialog lists can be translated with following text messages used with option "Used in JavaScript" set to "Yes".
UC.PROGRESSBAR.DIALOG.TITLEL > "Process list"
UC.PROGRESSBAR.DIALOG.BUTTON.CLOSE_LIST > "Close list"
UC.PROGRESSBAR.DIALOG.BUTTON.CLEAR_LIST > "Clear event list"
Example code
function( pOptions ) {
//style settings
pOptions.style.textLocation = "inline"; // inline, top, bottom
pOptions.style.textPosition = "center"; // center, left, right
pOptions.style.textTemplate = "%1%";
pOptions.style.completeText = "Completed !";
/* or it can be used as text message :
pOptions.style.textTemplate = "UCPROCESS.ROWS";
pOptions.style.completeText = "UCPROCESS.COMPLETE";
*/
// Process/Job name used in a replace string %0
pOptions.progress.displayName = "Custom job name";
return pOptions;
}
Advanced Usage
Event type
Use the Dynamic Event type to load the event action with this.data.
This option can be used as a hook for different tools such as APEX Office Print.
Example Usage for APEX Office Print DA:
Steps:
Create Dynamic Action for APEX Office Print (Event trigger)
Add Action UC-Progress Bar Pro [Plug-In]
In UC-Progress Bar Pro [Plug-In] Action set Attributes:
Settings
Action: Show progress bar (Event data)
Behavior: uncheck Remove after complete and Auto open list
Start Checking At: 80
Idle Time: 10
Two parameters time (Idle Time) and percentage (Start Checking At) are needed to decide idle job 10 seconds in meantime fill up the progress bar to "80% and then start check-in into the database if the job has finished.
History (DBA Friendly)
The plug-in works on the UC_PROGRESSBAR table (collection) this way we can also hold history if needed. Setting how long the history will be saved can be set inside the "OC_PROGRESSBAR_PKG" package with parameter:
g_history_days constant number := 30;
In case we are using "Job" type processes as a long-running job, here is also an option to use "dbms_application_info". Option is enabled by default with following line:
g_use_dbms_application_info constant boolean := true;
You can check execution as a DBA with :
select sid, sql_id, opname, target_desc, sofar, totalwork, start_time, elapsed_seconds, time_remaining, message from v$session_longops where where time_remaining > 0
In case you want to display all jobs in APEX. You can use an Interactive Report.
Steps:
Add Region Interactive Report
Set Source Type to Table / View
Set Table Name Attribute: UC_PROGRESSBAR
Below is an example of the page.
CSS Settings
CSS allows you to customize coloring and display options.
Here are few basic CSS settings for the Progress Bar.
Add these to the Inline CSS of the page:
/* Set height/border radius of progress bar */
.apex-uc-progress .progress {
height:30px;
border-radius: 10px;
background-color:darkred;
}
/* Set color of foreground progress status */
.apex-uc-progress .progress-bar {
background-color:skyblue!important;
}
/* Set text color / weight on progress bar */
.apex-uc-progress .progress-bar-text {
color:red!important;
font-size:16px;
font-weight:120;
}
/* Separate settings for job list */
.ucp-list .progress {
height:20px;
font-size: 1.35rem;
border-radius: 8px;
}
/* To set up link color if HTML used inside text */
.apex-uc-progress a {
color:inherit;
font-weight:700;
/*color: darkblue !important;*/
}
Inline CSS settings:
API
Supported Options
All supported options are inside package UC_PROGRESSBAR_PKG.
/**
* Start process and set initial values.
*
* @p_process_name name of process to follow
* @p_process_type type of process "process" of "job"
* @p_maxval Max val if we have % than put 100 as 100% if you know rowcount put rowcount as maxvalue
* @p_shared This parameter is used mostly for "Job" type to decide if this is global long running process (Database JOB) or displayed only in selected session (p_username, p_session)
* @p_username Username, it's automated this setting is need only in case p_shared = 'N' parameter
* @p_session APEX session, it's automated this setting is need only in case p_shared = 'N' parameter
*/
procedure start_process(p_process_name in uc_progressbar.process_name%type,
p_process_type in uc_progressbar.process_type%type default 'process',
p_process_text in uc_progressbar.process_text%type default null,
p_maxval in uc_progressbar.max_value%type default 100,
p_shared in uc_progressbar.process_shared%type default null,
p_username in uc_progressbar.updated_by%type default null,
p_session in uc_progressbar.updated_session%type default null
);
/**
* Set current status value.
*
* @p_process_name unique name of process
* @p_value current value, if you working with percent put 10 as 10% or some current value
* @p_process_text text message to display on progress bar
* @p_username Username, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
* @p_session APEX session, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
*/
procedure set_status(p_process_name in uc_progressbar.process_name%type,
p_value in uc_progressbar.curr_value%type,
p_process_text in uc_progressbar.process_text%type default null,
/* Rare use case p_user and p_session only for non shared jobs */
p_username in uc_progressbar.updated_by%type default null,
p_session in uc_progressbar.updated_session%type default null);
/**
* Check if process is still running.
*
* @p_process_name unique name of process
*
* @return true/false.
*/
function is_running(p_process_name in uc_progressbar.process_name%type)
return boolean;
/**
* Stop process and set end state.
*
* @p_process_name unique name of process
* @p_process_errorˇerror message to display
* @p_username Username, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
* @p_session APEX session, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
*
*/
procedure error_process(p_process_name in uc_progressbar.process_name%type,
p_process_error in uc_progressbar.error_text%type,
/* Rare use case p_user and p_session only for non shared jobs */
p_username in uc_progressbar.updated_by%type default null,
p_session in uc_progressbar.updated_session%type default null);
/**
* Stop process and set end state.
*
* @p_process_name unique name of process
* @p_process_text text message to display on progress bar
* @p_username Username, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
* @p_session APEX session, it's automated this setting is need only in case p_shared = 'N' parameter on start_process
*/
procedure stop_process(p_process_name in uc_progressbar.process_name%type,
p_process_text in uc_progressbar.process_text%type default null,
/* Rare use case p_user and p_session only for non shared jobs */
p_username in uc_progressbar.updated_by%type default null,
p_session in uc_progressbar.updated_session%type default null);
The plug-in uses the UC_PROGRESSBAR table (collection) this way we can also hold history if needed. Setting how long we history will be saved can be done inside package "OC_PROGRESSBAR_PKG" with parameter
g_history_days constant number := 30;
In case we are using "Job" type processes as a long-running job, here is also an option to use "dbms_application_info". Option is enabled by default with following line:
g_use_dbms_application_info constant boolean := true;
You can check execution as DBA with :
select sid, sql_id, opname, target_desc, sofar, totalwork, start_time, elapsed_seconds, time_remaining, message from v$session_longops where where time_remaining > 0
Examples
Basic Sample
The following is an example of how to use the PL/SQL API inside a page process:
declare
l_processname varchar2(128 char) := 'PROCESS_01';
begin
UC_PROGRESSBAR_PKG.start_process(p_process_name => l_processname,
p_maxval => 100);
for i in 1..20
loop
-- Pause for 0.5 second.
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*5,
p_process_text => 'completed');
sys.DBMS_SESSION.sleep(0.5);
end loop;
UC_PROGRESSBAR_PKG.stop_process(p_process_name => l_processname);
end;
Status Sample
The following is an example of how to use the PL/SQL API inside a page process:
declare
l_processname varchar2(128 char) := 'PROCESS_01';
begin
UC_PROGRESSBAR_PKG.start_process(p_process_name => l_processname,
p_maxval => 100,
p_process_text => 'Starting');
for i in 1..5
loop
if i = 1
then
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*20,
p_process_text => 'Making backup');
elsif i = 2
then
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*20,
p_process_text => 'Getting data');
elsif i = 3
then
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*20,
p_process_text => 'Processing');
elsif i = 4
then
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*20,
p_process_text => 'Finishing');
elsif i = 5
then
UC_PROGRESSBAR_PKG.set_status(p_process_name => l_processname,
p_value => i*20,
p_process_text => 'Clean up');
sys.DBMS_SESSION.sleep(2);
end if;
end loop;
UC_PROGRESSBAR_PKG.stop_process(p_process_name => l_processname);
end;