Interactive Grid Tour App

Last updated on Tuesday, December 24, 2019

At Kscope 19 in Seattle and APEX Connect in Bonn I presented a beginners session on interactive grid where I demonstrated an app that gives a guided tour of the interactive grid features. As promised I’m making the app available. It uses the same data as the Sample Interactive Grids app so make sure that is installed first. Then download the Interactive Grid Tour. If you are new to interactive grid this app is a good introduction to what it can do. It takes a different approach compared to the Sample Interactive Grids app in that it guides you through just about all of the built-in capabilities with a series of popup notes.

Even if you are already an expert on IG the app may still have some value for you. Have you ever wanted to make sure users are aware of some new feature in your app. You have probably seen apps that do this. After an upgrade they will popup a note or notes that point out some new things. There is a reusable widget in this app that does just this.

[Update 24-Dec-19 there is a newer version of the showMe widget that works for 19.2 that you can find here]

Here’s the scenario: You have a popular app that has been in use for years. The users are very familiar with it. You have added two new features that they get to from buttons on the home page but you are concerned that users won’t notice because their navigation patterns are so ingrained. You want a popup to educate them about the new features when they use the app. This is what the showMe widget is for. Making use of this widget will require some JavaScript and CSS skill.

Here are the steps to make use of it in your own apps:

1. Download the tour app and install it. Run the app to get a feeling for what showMe can do.
2. Go to Shared Components > Application Files and extract (download) the IGtour.css and showme.js files.
3. The styles needed for showMe widget are in the IGtour.css file. Copy all the rules after the “Show-me classes” comment into your application’s CSS file. What, your app doesn’t have it’s own CSS file? Hmm. Must be a very straight forward app. No problem. You can add a new CSS file (recommended) or simply copy the rules into the page CSS inline attribute on any pages where showMe is going to be used.
4. Go to your app where you want to add a tour. Or create a new app just to try this out.
1. Go to Shared Components > Static Application Files. Upload the showme.js file and the file where you added the CSS rules. I’ll assume it is called app.css.
2. Now go to Shared Components > User Interface Attributes > Desktop.
   In JavaScript File URLs enter:

       #APP_IMAGES#showme.js

   In Cascading Style Sheets File URLs enter:

       #APP_IMAGES#app.css.

   If you added the CSS rules to an existing file that is already loaded then this last step isn’t needed. Note: If you are only adding a tour to one or a few specific pages then you could load these files just on those pages. The general idea is that these two files need to be loaded on any page where you want to give a tour of your app features.

5. Go to the page where you want to add the tour. I’m going to assume that there are two buttons on this page that represent the new features to call out and their static ids are “feature1” and “feature2”. You can substitute any jQuery selector you like in the tour steps and even add more steps (See step 7).
6. Add an inline popup region to the page. Add a Static Content region to the Inline Dialogs position and set the Template to Inline Popup. Set the title to “Tour”. The title won’t be seen. Set the templates options: Remove page Overlay and Set Dialog Size to None. The showMe widget uses the popup functionality but doesn’t include it so that you can customize the popup to fit your needs. Note: you won’t use the apex.theme.openRegion API with this popup region.
7. The tour is driven by markup added to the popup. Add the following to the popup region Source Text attribute.

   <ul class="show-me">
       <li data-element="#feature1">
         Press this button to make a random person on the Internet a little happier today.
       </li>
       <li data-element="#feature2">
         Press this button to be <em>5% more</em> productive.
       </li>
   </ul>
   

   The show-me class causes this list to be turned into a showMe widget automatically when the page loads. Each list element is a step in the tour. The content of the list element is shown next to the element identified by the jQuery selector in data-element. Other attributes used to control the showMe tour steps include: data-name, data-position, data-zindex, data-width, data-height, data-url. The position attribute controls the popup position relative to the element and can be one of “below” (default), “above”, “left”, “right”, “inside”, and “center”.

8. Add a dynamic action to start the tour when the page loads.
   Name: start tour
   Event: Page Load
   Add one Execute JavaScript Code action and Add this code:

       $(".show-me").first().showMe("nextStep");

9. Add a Next button to the Next button position in the popup region created in step 6. Set the button name to TOUR_NEXT and the label to Next. Add a dynamic action to go to the next step of the tour. This looks a lot like the one in the previous step.
   Name: next step
   Event: Click
   Select Type: Button
   Button: TOUR_NEXT
   Add one Execute JavaScript Code action and Add this code:

       $(".show-me").first().showMe("nextStep");

10. Now run the page and you should see the first tour popup. Click next to see the next tour step.

See the Interactive Grid tour app for more advanced uses. It defines a number of actions and dynamic actions on the global page (page 0) because the tour is used throughout the app. The actions let you use keyboard shortcuts. The showMe step options doBefore and doAfter let you handle advanced situations where the state of the page needs to be set before the step can be shown such as selecting a tab or expanding a region. The logic to open a menu so that a tour step popup can point to a menu item is complicated and not very robust. The code for it is in the IGtour.js file.

It would be easy to add a “don’t show me this again” checkbox to the popup and save that state as a hidden page item backed by a user preference. The page load DA that starts the tour would only start it if the user hasn’t checked the box. There are many other possibilities for starting or continuing the tour.

Read the showme.js source code comments to learn about the options and methods it supports. You will probably want to modify the CSS for the popup for example to change the colors.

Because the showMe widget is driven by simple list markup it would not be unreasonable to create an APEX list template for it. I did not do this because the list is specific to a given page, contains sometimes complex jQuery selectors, and doesn’t leverage app URLs much. So I found it much more convenient to simply author the list markup right on the page.

When I created showMe I wanted to leverage the popup widget as much as possible. One thing that was missing was the callout – that little triangle that points to the element that the popup is related to. So I added the callout functionality as part of showMe. Shakeeb and I liked it so much that we added it to the APEX menu and popup widgets and hopefully this will be in 19.2. So this showMe widget may need to be changed when the popup has its own callout implementation.

If you add showMe to your app I would be happy to hear any feedback you have.