authorize() This method is used to authorize access to this application. Because we want every- one to access the help file, the method simply returns TRUE. getCommand() This method’s purpose is to determine what the user wants to do with the help application. There are two operations user can request: show help or perform search on an application’s help contents. However, for both operations, the user must supply the application name, because without an application name, the help system does not know what to show or what to search on. The application name is passed as a query parameter (for example, http://server/path/help.php?app=app_name) and, therefore, must be found as an entry called $_REQUEST[‘app’] in the associative array called $_REQUEST provided by PHP. If the application name is not found, the method returns null. If the application name is found, the method checks to see whether the user has provided any keyword in the query string (http://server/path/help. php?app=app_name&keyword=keywords ). If a keyword is found in $_REQUEST [‘keyword’] , then the method returns ‘doSearch’ as the command because the user wants to do a search operation on the named application help contents. If no keyword is found, the method returns ‘showHelp’ as the default command, which makes the help application display help contents. getAppInfo() This method returns a hash object with user-supplied information. showHelp() This method displays help contents. It works as follows: ◆ The user-supplied keyword and application name are stored in $info hash by retrieving them using the getAppInfo() method. ◆ A help object, $helpObj, is created. ◆ If a valid section number is supplied by the user, the method retrieves the section contents using the $helpObj->getSectionContents() method and stores the contents in $contents hash. ◆ If no valid section number is given, the method retrieves the table of contents information using the $helpObj->getTOCContents() method and stores the contents in $contents hash. ◆ It displays the contents in $contents hash using the displayOutput() method. Chapter 12: Online Help System 421 15 549669 ch12.qxd 4/4/03 9:26 AM Page 421 displayOutput() This method displays a page, be it a section contents page, search results, or a table of contents based on the contents[‘output’] field information in the $contents hash. It works as follows: ◆ It creates a template object called $template and loads the $contents [‘template’] template. It then sends the base URL and app parameter. ◆ If the content to be displayed is the search result (that is, the $contents [‘output’] is set to ‘search_result’), the history block of the template is configured. ◆ If the content to be displayed is help section contents (that is, the $contents[‘output’] is set to ‘show_section’), the navigation blocks (prevBlock, nextBlock) of the template are configured. ◆ If there are URL links to sections to be displayed (that is, $contents [‘section_links’] is not empty), then each section to be displayed is inserted and parsed into the template from the data stored in $contents [‘section_links’] . ◆ If the recent search history is to be displayed (that is, $contents [‘recent_search’]) is not empty), then each recent keyword to be displayed is inserted and parsed into the template from the data stored in $contents[‘recent_search’]. Otherwise, the history block is set to null, which is appropriate since only the search result page has the history block data. ◆ If the page to be displayed is search results (that is, match count, $contents[‘match_count’], not empty), then match count data is entered into the template by replacing the MATCH_COUNT tag. ◆ If the body of the contents, $contents[‘body’], is not empty, the body is inserted into the template. Otherwise, an appropriate message is inserted to indicate the body is missing. ◆ The previous and next blocks (prevBlock, nextBlock) are populated with URL links using $contents[‘previous_section’] and $contents [‘next_section’] , respectively. This is needed for the section contents page. If the current page to be displayed is not a section contents page, these blocks are set to null. ◆ The template is parsed and the resulting page is stored in the $documents variable as a string. 422 Part II: Developing Intranet Solutions 15 549669 ch12.qxd 4/4/03 9:26 AM Page 422 ◆ Now if the $documents page has embedded links to other sections using the <a href=”section_number.html”>label</a> HTML tags, they are replaced using appropriate relative URLs built-in using the preg_replace() function. ◆ Finally, the contents of the $documents page are displayed. doSearch() This method performs a keyword search and displays the output. It works as follows: ◆ The user-supplied keyword and application name are stored in $info hash by retrieving them using the getAppInfo() method. ◆ A help object, $helpObj, is created. ◆ The user-supplied keywords are stored in $keyword. The keywords are lowercased and stripped of any slashes, if there are any. ◆ The $helpObj->search() method is called using the keywords, and if the search results in any matches the results are retrieved using the $helpObj->getSearchResults() method into a hash called $contents and displayed using displayOutput(). ◆ On the other hand, if no match is found, an alert window is shown. Installing Help Applications Here we’ll assume that you’re using a Linux system with MySQL and Apache server installed. During the installation process, I refer to this directory as %DocumentRoot%. I also assume that you have installed the PHPLIB and PEAR library. Normally, these get installed during PHP installation. For your convenience, I’ve provided these in the lib/phplib.tar.gz and lib/pear.tar.gz directories on the CD-ROM. In these sample installation steps, we’ll assume that these are installed in the /evoknow/phplib and /evoknow/pear directories. Because your installation loca- tions for these libraries are likely to differ, make sure you replace these paths in the configuration files. Here is how you can get your help applications up and running: ◆ Install the applications framework. If you haven’t yet installed the application framework discussed in Chapter 4, you must do so before proceeding further. ◆ Install help applications. From the ch12 directory on the CD-ROM, extract ch12.tar.gz in %DocumentRoot%. This will create a help directory in your document root. Chapter 12: Online Help System 423 15 549669 ch12.qxd 4/4/03 9:26 AM Page 423 ◆ Set file/directory permissions. Make sure you’ve changed the file and directory permissions such that your intranet Web server can access all the files. The makeindex.php script must write to the help contents directory to store the generated help indexes. Make sure your Web server has write access to the help contents directory you create for your application- specific help files. After you’ve performed the preceding steps, you’re ready to test your online help applications. Testing the Help System If you’ve installed the applications properly, it came with help on itself. Therefore, you can run it immediately without needing to create help contents first. Run http://yourserver/help/apps/help.php?app=self You should see a screen similar to Figure 12-2. Figure 12-2: The table of contents page for the help system itself. Now click on any of the sections and you’ll see the sections page. For example, Figure 12-3 shows the section that introduces the help system to you. 424 Part II: Developing Intranet Solutions 15 549669 ch12.qxd 4/4/03 9:26 AM Page 424 Figure 12-3: A section page. Now you can enter search key words in any of the screens to see if there is any match. For example, I entered the keyword “built-in” in the search keyword entry and clicked on the GO button. The result is shown in Figure 12-4. Figure 12-4: A sample search output. Chapter 12: Online Help System 425 15 549669 ch12.qxd 4/4/03 9:26 AM Page 425 . assume that you have installed the PHPLIB and PEAR library. Normally, these get installed during PHP installation. For your convenience, I’ve provided these in the lib/phplib.tar.gz and lib/pear.tar.gz. (for example, http://server/path/help .php? app=app_name) and, therefore, must be found as an entry called $_REQUEST[‘app’] in the associative array called $_REQUEST provided by PHP. If the application name. to see whether the user has provided any keyword in the query string (http://server/path/help. php? app=app_name&keyword=keywords ). If a keyword is found in $_REQUEST [‘keyword’] , then the