Friday, January 18, 2019

Using Intro.js in Oracle APEX

Using Intro.js to create a step-by-step guide and feature introduction in Oracle APEX.

When new users visit your website or product you should demonstrate your product features using a step-by-step guide. Even when you develop and add a new feature to your product, you should be able to represent them to your users using a user-friendly solution. Intro.js is developed to enable web and mobile developers to create a step-by-step introduction easily. Intro.js is open-source and free to use.
You can visit https://introjs.com to find more information about Intro.js


First of all, we should associate CSS and JavaScript files of Intro.js with our application.
Tip: add introjs-rtl.css just if your language is RTL.
To get above files, download source file of Intro.js via https://github.com/usablica/intro.js/tags and after unzip, you need just above files.
Now do something in Oracle APEX Page:
For this blog post I create below form and I am going to show help message for Intro.js Region, Sal Item, Img Item and Download button via Intro.js.

For region components and buttons we should set Static ID , which in my case I set “about_introjs” for “Intro.js” region and set “btn_download” for Download button and for Page Items we don’t need set Static ID because we use their name.
Set Static ID for Intro.js region:
 


Set Static ID for Download button:

 
For next step add help text in JSON format on page level.


{
   "help":{
      "title":"",
      "description":"",
      "items":[
         {
            "itemId":"about_introjs",
            "itemHelpText":"Intro.js is developed to enable web and mobile developers to create a step-by-step introduction easily."
         },
         {
            "itemId":"P26_SAL",
            "itemHelpText":"Salary must be more than 2500 dollars."
         },
         {
            "itemId":"P26_IMG",
            "itemHelpText":"Your photo must be in the jpeg format."
         },
         {
            "itemId":"btn_download",
            "itemHelpText":"Intro.js is free and open-source. Download it from introjs.com"
         }
      ]
   }
}

Tip: don’t use Enter key in “itemHelpText”.
As I said for region components and buttons we should use their Static ID and for page items we use their name for “itemId” in above code.
For next step, add CSS and JavaScript file URLs on page level.

JavaScripts File Urls:

#APP_IMAGES#intro.js

CSS File Urls:

#APP_IMAGES#introjs.css

Tip: If your language is RTL add #APP_IMAGES#introjs-rtl.css too.



Insted of creating help button in each page, you can create it in global page[0] as bellow steps :

First, create a region of type” PL/SQL Dynamic Content” in breadcrumb position, and place the following PL/SQL code in its source:

DECLARE
    l_help_text   NVARCHAR2 (4000);
BEGIN
    SELECT TO_CHAR (HELP_TEXT)
      INTO l_help_text
      FROM apex_application_pages
     WHERE application_id = :APP_ID AND page_id = :APP_PAGE_ID;

    IF (    LENGTH (l_help_text) > 0
        AND TO_CHAR (l_help_text) <> 'No help is available for this page.')
    THEN
        HTP.p (
            '
                  <button class="btnHelp" onclick="javascript:introJs().setOptions({ ''nextLabel'': ''Next'', ''prevLabel'': ''Back'', ''skipLabel'': ''Skip'', ''doneLabel'': ''Done'' }).start();return false;">
                       <span class="icon t-Icon fa fa-info-circle-o"></span>Help</button>
                  ');
    END IF;
EXCEPTION
    WHEN OTHERS
    THEN
        HTP.p ('');
END;






The next step is creating a region of type” PL/SQL Dynamic Content” in “before footer” position in global page[0] and place the following PL/SQL code in its source :

DECLARE
    v_HelpText       NVARCHAR2 (4000) := '';
    v_output         NVARCHAR2 (4000) := '';
    v_ItemId         NVARCHAR2 (4000) := '';
    v_ItemHelpText   NVARCHAR2 (4000) := '';
    l_count          PLS_INTEGER := 0;
    j                apex_json.t_values;
BEGIN
    SELECT TO_CHAR (HELP_TEXT)
      INTO v_HelpText
      FROM apex_application_pages
     WHERE application_id = :APP_ID AND page_id = :APP_PAGE_ID;

    apex_json.parse (j, v_HelpText);
    l_count := apex_json.get_count (p_path => 'help.items', p_values => j);
    v_output := '<script type="text/javascript">';

    FOR i IN 1 .. l_count
    LOOP
        v_ItemId :=
            APEX_JSON.get_varchar2 (p_path     => 'help.items[%d].itemId',
                                    p_values   => j,
                                    p0         => i);
        v_ItemHelpText :=
            APEX_JSON.get_varchar2 (p_path     => 'help.items[%d].itemHelpText',
                                    p_values   => j,
                                    p0         => i);

        v_output :=
               v_output
            || 'document.querySelector("#'
            || v_ItemId
            || '").setAttribute("data-step","'
            || i
            || '");'
            || CHR (13)
            || 'document.querySelector("#'
            || v_ItemId
            || '").setAttribute("data-intro","'
            || v_ItemHelpText
            || '");'
            || CHR (13);
    END LOOP;

    v_output := v_output || '</script>';

    HTP.p (v_output);
EXCEPTION
    WHEN OTHERS
    THEN
        HTP.p ('');
END;

Above code fetch help section of page that you fill.
Now, run your application.
Demo: https://apex.oracle.com/pls/apex/f?p=15676:5

No comments:

Post a Comment