◆ If no keyword is passed as a parameter to the method, it returns FALSE. ◆ If the keywords have been supplied, it reads the recent search history as a hash in $hash using the getRecentSearchList() method. The getRecentSearchList() is called with TRUE as a $asis parameter so that it returns the search history as an unmodified hash. ◆ If the current keywords already exist in $hash, then the method returns FALSE since there is no need to add duplicate keywords in the history. ◆ If the current history does not exceed the SEARCH_HISTORY_SIZE size specified in the configuration file (help.conf), then the current keywords are inserted into the a new hash called $outHash along with the existing history data. ◆ Finally, the new $outHash is written to the history file using the writeSearchHistory() method, and the method returns TRUE. getKeywordMatch() This method checks to see whether the given keyword ($keyword) exists in the key- word index of the given sections ($sections) and returns the matching section list. It works as follows: ◆ The given keyword is lowercased because the keyword index stores all keywords in lowercase format. ◆ A list called $matchedSections is initialized as an empty array. ◆ For each given section, the given keyword is searched in the keyword index cache stored in the keyword index file. ◆ In the loop, for each given section, a keyword index cache file called $keywordCacheFile is set using the getKeywordFile() method. ◆ A hash object (that is, keyword index cache) called $cache is loaded using the readKeywordCacheFile() method. ◆ If the current keyword is found in the $cache object, the current section is stored in $matchedSections. ◆ Finally, the matched section list is returned. getSectionNumberList() This method returns the section numbers from the current section hash. getSectionHash() This method returns a hash that has section numbers as keys and section names as values. If a section list is given, the method only returns the hash for the given sec- tion list. Otherwise, it returns the entire list of sections for the current help contents. Chapter 12: Online Help System 411 15 549669 ch12.qxd 4/4/03 9:26 AM Page 411 getSectionList() This method returns the list of sections. getKeywordString() This method creates a string out of the list of keywords and returns the string. getKeywordList() This method sets the object variable _KEYWORDS with given keywords. However, it removes duplicates and any instance of the word ‘or’. The ‘or’ operator is implied automatically when multiple keywords exist in the keyword list and, therefore, it is removed. getSections() This method returns the section hash stored in the object variable _SECTIONS. getHelpDir() This method returns the help directory path stored in _HELP_DIR. If _HELP_DIR is empty, it returns null. makeKeywordIndex() This method creates the keyword index cache object for a given section and stores the cache as a serialized hash object in a file. It works as follows: ◆ First, it creates a local variable called $helpFile that is set to the fully qualified pathname of the given section’s ($section) help file returned by the getFQPNofSection() method. ◆ If the help file (that is, the help contents) does not exist for the current section, the method returns FALSE. ◆ If the help file exists, a local variable called $keywordCacheFile is set to the fully qualified pathname of the current section’s keyword index cache file returned by the getKeywordFile() method. ◆ If this keyword index cache exists, the help file’s modification time ($helpFileModifyTimeStamp) is compared with the modification time ($keywordIndexCreateTimeStamp) of the keyword index. If the help file modification time is older than the keyword index file modification time, the keyword index is up to date and therefore not needed to be re-created, unless the object variable _FORCE is set to true. When the keyword index is up to date and the index doesn’t need to be forcefully re-created, the method returns TRUE, indicating that index creation was a success. ◆ On the other hand, if the keyword index doesn’t exist or the modification time of the help file is newer than the existing keyword index file, then the method must continue and create the index cache from the help contents. 412 Part II: Developing Intranet Solutions 15 549669 ch12.qxd 4/4/03 9:26 AM Page 412 ◆ The _getWords() is called with the help file ($helpFile) and the returned word list is stored in the $words variable. ◆ The _removeExcludedWords() method is called with the $words to remove words that need to be excluded. The words are compared to words stored in the EXCLUDED_WORD_FILE file and matching words are removed from the $words list. ◆ The resulting $words list and the $keywordCacheFile file name are passed as a parameter to the writeKeywordCacheFile() method to write the cache file. ◆ If the file is written successfully, the method returns TRUE; otherwise, it returns FALSE. getFQPNSearchHistoryFile() This method returns the fully qualified search history file name. getFQPNofSection() This method returns the fully qualified section file name. getHelpTemplateDir() This method returns the fully qualified help template directory path. getDefaultSectionTemplate() This method returns the default section template path. getTOCTempalte() This method returns the table of contents template path. getSearchResultTempalte() This method returns the search result template path. getSectionTemplate() This method returns the template path for a given section if it exists; otherwise, it returns the default section template path. getBaseURL() This method returns the base URL. loadMap() This method loads the help map file, which defines all the information needed to provide help for an application. It works as follows: ◆ First, it sets $mapFile to the fully qualified pathname of the map file returned by the getMapFile() method. ◆ If the map file does not exist, the method returns FALSE. Chapter 12: Online Help System 413 15 549669 ch12.qxd 4/4/03 9:26 AM Page 413 ◆ The method then uses the built-in require_once() function to load the map file, which is a PHP script. ◆ If the $HELP_DIR variable in the map file has a value that does not start with leading slash character, the $HELP_DIR is a relative path and ROOT_PATH from help.conf is added as a prefix to this path; finally, it is stored in the object’s _HELP_DIR variable. Similarly, _REL_HELP_DIR is constructed using REL_ROOT_PATH (from help.conf) and the current application’s name. On the other hand, if the $HEL_DIR value does start with a leading slash, it is stored as is along with $REL_HELP_DIR in _HELP_DIR and the _REL_HELP_DIR object variables, respectively. ◆ The other variables in the map file — $REL_TEMPLATE_DIR, $DEFAULT_ SECTION_TEMPLATE , $TOC_TEMPLATE, $SEARCH_RESULT_TEMPLATE, $TEMPLATES, and $SECTIONS — are assigned to _REL_TEMPLATE_DIR, _DEFAULT_SECTION_TEMPLATE, _TOC_TEMPLATE, _SEARCH_RESULT_ TEMPLATE , _TEMPLATES, and _SECTIONS, respectively. getMapFile() This method returns the fully qualified pathname of the map file. readKeywordCacheFile() This method returns the named keyword file ($file), unserializes the contents, and returns the hash object. writeKeywordCacheFile() This methods writes the given word list, $words, in the named keyword file, $file. It first creates a hash called $cache using each of the keywords in the $words list and serializes the $cache object before writing to the file. writeSearchHistory() This method writes the keyword history hash ($hash) into the keyword search history file returned by the getFQPNSearchHistoryFile() method. The $hash is serialized before writing to the file. getKeywordFile() This method returns the fully qualified keyword index cache file name for the given section. _removeExcludedWords() This method removes words from the $words list if they are found in the EXCLUDED_WORD_FILE file. _getWords() This method reads the named file ($file), parses out text from HTML tags, creates a list of unique words, and returns the list. 414 Part II: Developing Intranet Solutions 15 549669 ch12.qxd 4/4/03 9:26 AM Page 414 _getUniqueWords() This method removes duplicates from the given word list ($words) and returns the duplicate-free word list. _loadFile() This method loads the given file ($file) if it exists and returns the contents as a string. HTMLtoText() This method removes HTML tags from the given string ($contents) and returns the HTML tag–free contents. Creating Application Configuration Files Like all other applications you’ve developed in this book, the online help applica- tions also use a standard set of configuration, message, and error files. These files are discussed in the following sections. Creating a main configuration file The primary configuration file for the entire system is called help.conf. Table 12-1 discusses each configuration variables. TABLE 12-1 THE help.conf VARIABLES NEED TO BE CHANGED Configuration Variable Purpose $PEAR_DIR Set to the directory containing the PEAR package; specifically the DB module needed for class.DBI.php in our application framework. By default, this is set to the %DocumentRoot%/pear. $PHPLIB_DIR Set to the PHPLIB directory, which contains the PHPLIB packages; specifically the template.inc package needed for template manipulation. By default this is set to the %DocumentRoot%/phplib. $APP_FRAMEWORK_DIR Set to our application framework directory. By default this is set to the %DocumentRoot%/framework. Continued Chapter 12: Online Help System 415 15 549669 ch12.qxd 4/4/03 9:26 AM Page 415 . needed for class.DBI .php in our application framework. By default, this is set to the %DocumentRoot%/pear. $PHPLIB_DIR Set to the PHPLIB directory, which contains the PHPLIB packages; specifically. 413 ◆ The method then uses the built-in require_once() function to load the map file, which is a PHP script. ◆ If the $HELP_DIR variable in the map file has a value that does not start with leading. template.inc package needed for template manipulation. By default this is set to the %DocumentRoot%/phplib. $APP_FRAMEWORK_DIR Set to our application framework directory. By default this is set to