Making a Context Sensitive Help App in PHPRunner

Posted by pauladmin on June 2, 2015
Posted in: PHPRunner Articles. Leave a Comment

There are lots of ways you could approach this, if your needs are very specific. But I wanted a generic way of displaying some context sensitive user help in my PHPRunner applications. I have several PHPRunner projects that are using the same database, and the same help information.

Here were my requirements:-

  • accessible from a simple “Help” top level menu item at all times so I dont have to edit every single page that needs help
  • No matter which screen’set’ was active, the help menu item should open a new tab/window with the help content relevant to that screen set
  • I wanted to add the very bare minimum of application or PHP code to each app/project that was to use the help feature. Ideally, each screen set would set a help page ‘name’ as a session variable and that would be it
  • All code related to the help activity would be limited to the menu item, and then by the target help application. I did not want to have to write custom help code in every application
  • Ideally the target help ‘application’ would be a PHPRunner project because it would be easy to create and be pretty much ‘bug free’ taking care of all the normal rendering / html housekeeping. i.e., I could have written a custom PHP external page, but I wanted to try a couple of other techniques too
  • I wanted the help page content to be in a database table so that my subject matter experts could edit the page content, and do some basic formatting.  Essentially, enable it so that you didnt have to have PHPRunner editor to change static pages inside an application! Okay… busted… make it so that I didn’t have to edit help pages…

Challenges! And therefore what this tutorial will demonstrate!!

  • How to pass a parameter to an external page? Visual Editor Menu Builder won’t let you do this!!
  • If that external page was a complete PHPRunner application, how to get it to accept parameters? Assuming I could pass them!
  • Starting a screenset with a VIEW page, and not a LIST page
  • Changing the header of the VIEW page so it shows “page name” instead of record id.

After that, its pretty much standard PHPrunner stuff for page layout and so on.

Bypassing the Login page when the ‘help’ PHPRunner Application is launched.

Because the help app is only going to read the help pages from the database, a login was not required. Which is good, as it took this off the list… if you were really paranoid, you could put your help text pages in a completely separate database schema… but I digress. I didn’t want to send user credentials across the URL, but then realized that this app cannot access any other data so making it such that it required no user login at all was the simplest approach.

Here's the basic table I used to trial all this.
 CREATE TABLE IF NOT EXISTS `help_page` (
 `id` int(11) NOT NULL AUTO_INCREMENT,
 `page_name` varchar(255) NOT NULL,
 `page_text` text,
 PRIMARY KEY (`id`),
 UNIQUE KEY `page_name` (`page_name`)
 ) ENGINE=InnoDB DEFAULT CHARSET=latin1 AUTO_INCREMENT=3 ;

and lets put some data in it. In my admin application that maintains this table, I used a text area with a rich text edit control to allow me put HTML codes in the help text should I decide to.

And here’s a couple of entries

INSERT INTO `help_page` (`id`, `page_name`, `page_text`) VALUES
(1, 'page_not_found', 'oops!  request page was not found.'),
(2, 'choose_plans', 'This is the enrollment wizard.
This page lets you choose the plans that you wish to enroll in or waive coverage for. Click SAVE ... etc');

Note that I put my own page not found record in there!

Process Overview

Here’s an overview of all the elements.
first you make the table in your database to hold your help pages.
You need an admin phprunner project to list/add/edit/delete the help records themselves. All trivial stuff so far.

In your Calling Application that needs context help:

  • create a menu item to launch an external page. My calling app was called IFPEE and in a folder in my web server as wamp/www/ifpee. I put my help application (‘IFPHELP’) in a parallel web server folder like any other PHP Application and named it www/ifphelp/
  • You create an external menu item in your application to launch your help application. Make it open a new window/tab
  • In a page in your calling application you set a session variable to hold the target help page name
  • In your calling application you dynamically modify the ‘help’ menu item to give it a URL parameter using the current value of that session variable

In your target help application you need to

  • set it to start with no login required
  • you need to retrieve the URL line parameters
  • then you need to get the record key id of the target help page using the name you were given
  • Then you need to make the default LIST page start with a view page and the ID that you just resolved

That’s it! it sounds like a lot of work, but it’s a lot less than the alternative of building custom ‘help’ content in every application and page set that you build.

Now, that external page could have been a simple static HTML page, after all we’re not doing much with PHPRunner other than displaying a page of text. But using a PHPRunner view page was good, because I could re-use my default project styles, and of course, building a view page is 100 times faster in PHPRunner than any “hand rolled” page. And guaranteed bug free of all the silly HTML/CSS/PHP things.

So here’s each step in more detail.

The database table is conceptually straight forward. Since this version, I’ve been thinking about making pages have next/previous ‘in topic’ pages, but that’s way too much to demonstrate the concepts here! The basic need I had was to have my calling application reference a ‘page name’ that could be looked up and return the ID of the record to show. Using the ID in the page redirection is the simplest way of working the List to View change later. And also it means I’m not baking in database autoincrement ID’s into my code. Never a great idea if you can avoid it!

The Help Application

Let’s start with this as it is the easiest part, and it can be tested independently of the calling application.
it only needs two pages in it. the List page and the View page. As I mentioned before, I set the edit control to be rich text editor/area so I could put formatting into the help body text. You can mess with this as much as you like.
Make your application such that it does NOT require login, on the Security tab of the PHPRunner Editor.
In the LIST page Before Display event:

$target = $_GET["pagename"];
$page_id = dblookup("select id from help_page where page_name = '" . $target . );

header("Location:help_page_view.php?editid1=".$page_id);

as you see, all we have to do to get the URL parameter called “pagename” is do a PHP $_GET.
Then I simply do a fast dblookup on the help table to turn that logical pagename into a record ID.
You could do a bit more around this area to check for success, i.e., if $page_id comes back empty, you could set it to “1” or whatever your “page not found” record ID is.
Once we’ve got a page id, you can now do a page redirect from the List page to show the view page with that specific id. This is a useful technique to know how to do for any PHPRunner developer.

Easy? Sure!!
Now you can test this easily on the URL command line to make sure its all working. in my case my URL would be
http://localhost/ifphelp/help_page_list.php?pagename=”choose_plans”
note: to avoid complications with special characters in URL’s, I … umm… avoid them! use underscores instead of spaces, and don’t use anything funky.

Now that your help application works, lets turn to the Calling Application.

The Calling Application

Challenge #1 – you cannot set parameters in an external link menu item. And even if you could in the Menu Editor, it needs to be dynamic and sensitive to a changing session variable value.
So … just create an external link to the HELP application with a URL similar to …
“../ifphelp/”
Give it a unique Menu item name. For clarity in this example I named my menu item “XHelp”.
that will do for now. Don’t worry about it!

In your Calling Application, in any screen set that needs context related help content, and I tend to put my help per ‘screen set’ (i.e, list, view, edit, add, etc for a given table), at the LIST page event Before Display:

$_SESSION["help_page"] = 'choose_plans';

That’s all you need to do here.

Now in the MenuItem : Modify event ( which is all the way down the bottom of the events editor list.)… you need some code in here to fiddle dynamically with the menu item 🙂

if ($menuItem->title=="XHelp") {
$menuItem->setURL('../ifphelp/help_page_list.php?pagename='.$_SESSION["help_page"]);
}

basically, the menu item modify event fires on each time the menu items are displayed.
So when this event fires, we are going to dynamically change the target URL so that it now has parameters which include the current value of the session variable. Cute?
Yes! Because the event fires for every menu item in your application, and you are only interested in XHelp item, you need to interrogate the ‘current’ menu item to see if its menu title is the one we are interested in. If it is our Xhelp menu item, then we can use the menuItem method setURL to build the new replacement URL with a parameter strung into it. So now an external menu item has a parameter, and … we’ve dynamically built the value of that parameter.

as a final nicety, I wanted the page name to show in the View Help page. In Visual editor just double click on the page title that usually says something like “View Record : ID=”

that lets you change the Page title. and you can include any valid column name from the current row in there. Just change it to say something like “Help Page : ” {%page_name}

Which then made me think I want to enhance the database schema so the help page has a “page title” which would read better to the user. Just make sure that the field you reference as %page_name is the same field in your schema.  Once you’ve got the basics working the possibilities are endless 😉

And that is it. Build your application and watch it launch a context sensitive help tab/window.
Happy PHP Running!
paul

Leave a Reply