Customizing the PeopleSoft Online Library

This chapter provides an overview of documentation integration and discusses how to integrate customized documentation into the library.

Click to jump to parent topicUnderstanding Documentation Integration

Just as you can add new PeopleSoft Enterprise documentation to an existing PeopleSoft Online Library, you can also integrate customized documentation into the site. This documentation may be preexisting internal documentation or new content that you’ve written to supplement PeopleBooks.

We do not encourage you to modify existing PeopleBooks files or to use a copy of an existing PeopleBook to make your changes. Although tempting at first, this approach can lead to substantial overhead for you, because every change you make to delivered content may render the table of contents or keyword index obsolete. Updating a PeopleBook table of contents and keyword index is a time consuming, manual task. Also, consider that:

By keeping customized documentation in a completely separate directory at the documentation type level, you avoid these issues but can still enable context sensitivity and searching. Also, you don’t have to adhere to the PeopleBooks format and layout; instead, you can choose any editor and any layout that you prefer.

You decide if your documentation will be accessible via the PeopleSoft Online Library home page, and you decide whether to establish context sensitivity and search capabilities.

Click to jump to parent topicIntegrating Personalized Documentation into the Library

This section discusses how to integrate:

Click to jump to top of pageClick to jump to parent topicIntegrating Browsing

To allow users to browse through your documentation in the library:

  1. Create a new documentation type folder below the appropriate language directory in the library site.

    For example: <docroot>/eng/my_psbooks or <docroot>/eng/internal policies

  2. Add the new documentation type to <docroot>/eng/js/doctypes.js.

    See Managing Documentation Types.

  3. Locate the documentation files in the new directory.

  4. Create (or rename) a home page called index.htm at the top directory level of the documentation type.

    This step ensures that the automated link to your documentation from the PeopleSoft Online Library home page works. If you already have a home page that you don’t want to rename, you can insert JavaScript into index.htm to automatically redirect users to your home page.

Note. If you add a book to booklist.js, helplist.js and colllist.js, it will appear at the bottom of the categorized book list area, if you want to integrate the book into the hierarchy or categories, you need to add it to the TopTOCStyle.xml file.

Click to jump to top of pageClick to jump to parent topicIntegrating Context Sensitivity

Any custom documentation in the PeopleSoft Online Library can be used as context-sensitive help for PeopleSoft Enterprise applications. If you have documented the features and uses of an application that you have modified or built, you can ensure that your users see that documentation when they call help from the application.

Preparing and enabling your documentation for context sensitivity requires more steps than adding a link to your documentation on the PeopleSoft Online Library home page. You must adhere to certain directory structures and file naming conventions. You might also need to add anchors to your documentation.

Understanding Context Sensitivity

Later we explain how to set up context sensitivity. But before you read that section, you may want to understand what actually happens during a help request. Understanding the reasoning behind the steps involved in enabling online help might aid you in troubleshooting if your context sensitivity doesn't work as expected.

When you request help from your application, the software generates a URL and passes it to your default web browser. This URL is generated by resolving two variables into a string value stored in the system. Here is an example of the syntax of the string, with variables wrapped in percent signs (%):

http://docroot/f1search.htm?ContextID=%CONTEXT_ID%&LangCD=%LANG_CD%

We discuss instructions for setting the value of the system help string as part of the discussion about installing PeopleBooks.

See your installation guide.

You can see that the string is a URL pointing to the f1search.htm page, which is in the <docroot> level of the library site. During the help call, the variables are resolved as follows:

Using the preceding syntax example, if help is called from the PeopleSoft Enterprise Components Options page by a German user, the resulting URL looks like this (resolved values in bold):

http://docroot/f1search.htm?ContextID=PSOPTIONS&LangCD=GER

When the help URL is passed to a browser, the f1search.htm page is opened, and the JavaScript logic inside uses the two passed arguments (Context ID and LangCD) to load the appropriate context ID lookup files. These files map valid application context IDs to locations in the documentation. The lookup file contents are searched and, when a match is found for the ContextID value, f1search.htm redirects the browser to the related location. If multiple matches are found, a pop-up window displays a list of help topic links from which the user can choose.

Because of the depth of the PeopleSoft Online Library directory structure, the process of loading the lookup files is complex. The following JavaScript sequence of events occurs when f1search.htm is opened:

  1. Validate the LangCD value passed to f1search.htm against <docroot>/js/langs.js to see if the preferred language exists in the library.

    If not, substitute ENG (English).

  2. Once the language (<langdir>) is determined, load <langdir>/js/helptypes.js to see which documentation types are enabled as context-sensitive help.

  3. For each path (<typepath>) found in helptypes.js, load <langdir>/<typepath>/js/helplist.js to determine which books within this documentation type are enabled for context sensitivity.

  4. For each book (<bookpath>) found in helplist.js, load <langdir>/<typepath>/<bookpath>/contextids/x.js, where x is the first character of the ContextID value passed.

The following example assumes that you have PeopleTools PeopleBooks installed and that your internal documentation is integrated as a separate documentation type:

  1. A user with the language preference English clicks help on the USER_PREF page.

  2. The following URL is passed to f1search.htm:

    http://docroot/f1search.htm?ContextID=USER_PREF&LangCD=ENG

  3. The language code of the user’s preferred language is validated against <docroot>/js/langs.js to see if that language exists in the library.

    <docroot>/js/langs.js:

		languages = new Array(
			"cfr||fc||Fran&ccedil;ais&nbsp;du&nbsp;Canada",
			"eng||en||English"
		);

    See Managing Language Support.

  4. Once the language (<langdir>) is determined, <langdir>/js/helptypes.js is loaded.

    eng/js/helptypes.js:

		helptypes = new Array(
			"psbooks||PeopleBooks",
			"my_documentation_type||My Documentation"
		);

    See Managing Documentation Types.

  5. For each path (<typepath>) found in helptypes.js, <langdir>/<typepath>/js/helplist.js is loaded. 

    eng/psbooks/js/helplist.js:

		helpnames[helpnames.length]="psbooks/pt||Enterprise PeopleTools 8.50 PeopleBook:⇒
 Security Administration";

		eng/my_documentation_type/js/helplist.js:
			helpnames[helpnames.length]="my_documentation_type/my_pt_book||Internal⇒
 Document - Oroz Security Policies";

    See Context Sensitivity.

  6. For each book (<bookpath>) found in helplist.js, <langdir>/<typepath>/<bookpath>/contextids/x.js is loaded, where x is the first character of the ContextID value passed to f1search.htm. 

    eng/psbooks/pt/contextids/j.js:
		bookmarks[bookmarks.length] = "USER_PREF||psbooks/pt/htm/ptcom001.htm#F1ID_Job_⇒
Data1";
		bookmarks[bookmarks.length] = "USER_PREF||psbooks/pt/htm/ptcom001.htm#F1ID_Job_⇒
Data2";
...

eng/my_documentation_type/my_pt_book/contextids/j.js:
		bookmarks[bookmarks.length] = "USER_PREF||my_documentation_type/my_pt_book/htm⇒
/xxxxx.htm#MYF1ID_USER_PREF";

  7. Once all lookup files are searched and a match is found for the context ID, the browser is redirected to the location specified in the lookup file.

    If multiple matches result, as in this example, a pop-up window displays the choices and the user can decide which help topic to select.

Preparing Your Documentation

In a help lookup file, a context ID (application page or panel name) can be mapped to a particular location in your documentation. That location can be a file name, or a file and anchor name. Whether you want to specify an anchor name depends on the length of your documentation files. If you document only one application page per HTML file, anchors are probably not necessary. If you document many application pages in an HTML file (as we do in PeopleBooks), however, you definitely need anchors. Anchors place users as close to their requested information as possible when they call help.

Another good reason for using anchors to denote help documentation locations is that they enable an automated process to build lookup files for you. In the PeopleBooks HTML files, we name every help anchor as F1ID_ followed by the name of the application page that is being documented. For example, at the beginning of the help topic on the PeopleSoft Enterprise PeopleTools options page (PSOPTIONS), the following anchor tag is inserted: <A NAME=“F1ID_PSOPTIONS”></A>. We then run a PERL script that parses our HTML files for F1ID_ anchors and builds the lookup files automatically.

Setting Up the Utility Files

During a help call, the various JavaScript utility files are found and loaded in a strict order. For the help logic to work properly, all the necessary directories and files must exist.

Populating the Lookup Files

A help lookup file contains lines of JavaScript code that assign strings to an array. Each string contains the context ID for a help topic and the relative path to the help topic, separated by two pipes (“||”). The name of the lookup file reflects the first character of all the context IDs stored inside. Here is an example of the syntax of these files:

bookmarks[bookmarks.length] = "<contextID1>||<path_to_file>#<anchor_name1>";
bookmarks[bookmarks.length] = "<contextID2>||<path_to_file>#<anchor_name2>";
...
bookmarks[bookmarks.length] = "<contextIDN>||<path_to_file>#<anchor_nameN>";

​arraycount[arraycount.length] = bookmarks.length - 1;
​

A context ID corresponds to the name of the application page at which the user clicks help. This context ID is used by f1search.htm to redirect the user to the correct help topic. Therefore, to create a context-sensitive link for a new application page, MY_APPS, you would insert this line into an m.js file:

bookmarks[bookmarks.length] = "MY_APPS||my_doc_type/my_hr_book/htm/intro_to_
hr.htm#my_anchor";

Adhere to these conventions when populating lookup files:

Populating a Chapter List File

Each PeopleBook folder contains an xxxxfiles.js file, this file consists of JavaScript array member assignments. Each line corresponds to a “chapter” file that makes up the PeopleBook. Each line also contains the title of that chapter. This file is used internally for the PeopleBook navigation controls.

See The Book Level.

The chapter list file is also used during the online help call if a context ID is found in more than one lookup file. In this case, the titles of the destination files are pulled from their corresponding chapter list files; they appear in the online help pop-up window as links.

If any possibility exists that the context IDs in your custom documentation will also be found in PeopleBooks, or found in multiple locations in your own documentation, then you must create chapter list files for your documentation. Certain browsers will generate an error if a chapter list file cannot be found for any of the books found to contain a matching help topic.

You can copy an xxxxfiles.js file from any PeopleBook folder and modify it to match your files and file titles.

Tips and Tricks

When you document a new application, you will want to edit the helptypes.js file and create a helplist.js, chapter list, and lookup files, as described previously. But, if you have documented changes to a delivered application, then you have some other choices:

Click to jump to top of pageClick to jump to parent topicIntegrating Searching

When you integrate new content into the PeopleSoft Online Library, you may want to rebuild the PSOL Verity collections so that you can search the new content.

See Managing Full-Text Searching.

Understanding Searching

Before enabling your documentation to be searchable, you should understand how your documentation type will appear in the search drop-down lists and how Verity finds the field values that help limit a search.

First, the scope of the search forms in the PeopleSoft Online Library is context sensitive. That is, a different search scope is permitted, depending on how you navigated to the search form. For example, at the PeopleSoft Online Library home page, a search form appears in the lower left frame. If you use this form, all of the documentation types in the entire library (those specified in <docroot>/<langdir>/js/colltypes.js) are searched. However, searching at the PeopleBooks home page searches only within PeopleBooks (<docroot>/<langdir>/psbooks/js/colllist.js). You can adjust of scope by modifying the JavaScript, which is inside the forms, that interprets the browser’s URL to find out at what level of the library the user is located.

The Advanced Search page (which you can access by way of either home page) is also context sensitive in this way. However, at the advanced search page, you can change which documentation type that you want to search by selecting from a drop-down list.

Note. A documentation type drop-down list appears in the Advanced Search page only if more than one documentation type is listed in colltypes.js.

You can also filter a search by selecting values from other drop-down lists that appear in the Advanced Search page (for example, Book Title or Product Line):

The drop-down list boxes are populated by dynamically loading the searchfields.js file for each doctype listed in colltypes.js. The searchfields.js file resides in each <doctype>/js folder and is created during the collection build process. Its contents consist of search field names and field values found when parsing the HTML documentation. Here is an example of the searchfields.js contents:

fieldnames_psbooks = new Array('BKTITLE', 'prodline');

BKTITLE_psbooks_fld = new Array('PeopleTools 8.50 PeopleBook: Global Technology',
 'PeopleTools 8.50 PeopleBook: Workflow Technology');
prodline_psbooks_fld = new Array('PeopleTools');

The first line in this file defines a fieldnames_<doctype> array that lists the names of the available search fields. The remaining lines define an array for each fieldname listed in the first array. The array members are all the available values for that field. For example, BKTITLE_psbooks_fld contains a list of all the PeopleBooks titles found in colllist.js during the collection build. prodline_psbooks_fld contains the various prodline values found when parsing the HTML content.

You can control the field names and values that appear in this file by adding custom META tags to your HTML documentation. Do not edit searchfields.js manually, as it is overwritten every time you rebuild your collections.

Creating Custom Search Fields

As previously discussed, the fields in searchfields.js are pulled from META tags that appear in the HTML content files that are parsed during a collection build. You can add your own META tags to define custom fields and field values. The META tags must be added in HEAD section of the HTML file. The syntax of the META tags must appear as follows:

<meta name="filter" content="field_name=field_value">

where field_name is the name of the search field and field_value is the value. For example, if you wanted to create a field for searching by job types or the type of audience for your documentation is intended, you might add one of the following META tags to your HTML files:

<meta name="filter" content="audience=First Time Users">
OR
<meta name="filter" content="audience=Implementers">
OR
<meta name="filter" content="audience=DBAs">

Note. The collection build process does not currently support multiple values for a single field in an HTML file. For example, if you put all three of the above META tags into one HTML file, only the last would be picked up and used in searchfields.js as the value for the audience field. In future releases, we hope to allow the use of a delimiting character in the content attribute to let you specify multiple field values in one META tag.

Assuming each of the three example META tags was inserted into your custom documentation files, when the collection is rebuilt, the searchfields.js file for your documentation type will contain this code:

fieldnames_your_doctype = new Array(audience);

audience_your_doctype_fld = new Array('First Time Users',Implementers,'DBAs');

There is no limit to the number of custom fields that you can create, but consider that each of these fields will appear as a drop-down list on the Advanced Search page. Too many fields might make the search form unwieldy to navigate and use.

Note. Certain field names are reserved by Verity and should not be used in your custom META tags. These field names are title, subject, author, from, source, keyword, and keywords. It is wise to create field names with a unique name string as a prefix or suffix (for example: mybooks_author).

When you search across multiple documentation types, the Advanced Search form displays only those search fields that are shared among those documentation types. For example, PeopleBooks are delivered with the BKTITLE (book title) and prodline (product line) fields predefined. If you want to search your custom doc and PeopleBooks simultaneously and to filter those searches by book title and product line, you should add META tags for BKTITLE and prodline to your documentation:

<meta name="filter" content="BKTITLE=My Custom Book">
<meta name="filter" content="prodline=FSCM">

Creating Custom Search Field Labels

The search field names that you define in the META tags are system names. These names are used internally by the PSOL JavaScript and by Verity. For translation purposes, the names that actually appear on the search form are stored in srchlabels.js, a language-specific labels file found in the js directory under each language directory.

See The Language Level.

The JavaScript variables that define the search field labels must have a particular naming structure in order to be found by the search form code. The syntax is:

strfield_name_fld

where field_name is the name of the field as defined in your META tags. For example, the standard PeopleBook search field, prodline, has a label variable defined in srchlabels.js as:

 strprodline_fld

Important! The variable names are case sensitive. The field name included in the variable name must exactly match the capitalization of the field name as defined in the META tags (and searchfields.js).

Setting Up the Utility Files

When the Advanced Search page opens, the colltypes.js file is loaded to find which doctypes are available for searching. To enable your custom documentation type for searching:

  1. Edit <docroot>/<langdir>/js/colltypes.js.

  2. Add a line to make the documentation type searchable.

    Use this syntax:

    "<doctype_dir>||<doctype_name>"[,]

    Do not use a comma after the last array assignment. For example, if you added your own documentation type to colltypes.js, it might look like this (in bold):

    collections = new Array(
 "psbooks||PeopleBooks",
 ​"my_documentation_type||My Documentation"
​);

See Managing Documentation Types.

If you have created a new doctype directory in PSOL for your documentation, you must also define that doctype directory in the PSOL web.xml file.

See Managing Full-Text Searching.

Inside the <web-app> tags in that file, add the following text:

<context-param>
            <param-name>doctype.doctype_name</param-name>
            <param-value>reg_expr</param-value>
   </context-param>

where doctype_name is the name of your doctype directory and reg_expr is a regular expression used to find your searchable content below the docroot directory. Save the file and restart the web server.

Note. The following regular expression can be used to find all .htm files (but not .html files) anywhere below your doctype directory: [/\\]doctype_name[/\\].*\.htm$

If you want to be more restrictive on which files are parsed for the collection, adjust the regex accordingly. For example, in PeopleBooks, all searchable HTML content is in an htm directory. Therefore, the hard-coded regex for finding PeopleBooks content is [/\\]psbooks[/\\].*[/\\]htm[/\\].*\.htm$

Creating Collections

Once you have added your META tags, added the field labels to srchlabels.js, and updated colltypes.js and web.xml, you are ready to create your collections. Use the PSOL Manager utility.

See Managing Full-Text Searching.