32.3 Editing the P-Synch GUI files

The M4 files that generate the HTML, CSS, and *.Z pages are located in the DESIGN directory. You customize the P-Synch interface by creating and editing corresponding customization files in the design\custom directory. For example, the file nph-psf.m4, contains a tag sinclude(custom/nph-psf.m4), which applies the code contained in the customization file if it exists. If the customzation file does not exist, then the default code is used. Similarly, the global file header.m4 references customizations contained in custom\header.m4.

P-Synch is shipped with examples of all customization files that also include instructions on how to use them. The example files are located in the design\examples directory. To create and modify the customization files, you copy the corresponding file from the examples directory to the custom directory, so that the customization file can be used during generation of the *.Z files.

The relationship between the M4 files is shown in FIGURE: [DESIGN-DIRECTORIES]

Figure:P-Synch design directory structure

Files in the custom directory will not be overwritten when you upgrade P-Synch. All other M4 files, including those in the examples directory, will be overwritten, and new skins (including HTML pages, *.z files, and CSS files will be automatically generated.

Note:

If you make customizations to the P-Synch GUI, you must include the M4.EXE file in the Windows PATH on the P-Synch server when you make an upgrade or patch.

 

The file MD5SUMS.TXT is included in the P-Synch design directory. This file is used during upgrades to detect changes that you may have made to the m4 files that may conflict with P-Synch changes. Do not delete this file.

Note the following when editing the M4 files:

• Ensure that you enclose macro definitions in single quotes. For example, to define apples as oranges, type define(`apples',`oranges') In language definitions, the quote characters have been redefined as [[ ]], so that apostrophies can be included in the text.
• Do not change any code that begins and ends in percent (%) signs. These codes are replaced by dynamic text when P-Synch builds each page.

The following subsections describe the steps required to customize the P-Synch GUI files.

32.3.1 Applying alternate style sheets

You can pass in an alternate CSS style sheet as a variable to any of the P-Synch cgi modules to apply a different look and feel for different groups within your organization. For example, subsidiaries may require a different corporate style.

An example URL is:

http://psynch.com/psynch/nph-psf.exe?css=http://portal/group1.css

You can use the CUSTOM\STYLE.M4 file as a basis for custom style sheets. The CSS style sheet can be placed in any directory accessible by a web browser. Once specified, the style sheet will be applied to all P-Synch HTML pages during the same session.

32.3.2 Adding multi-language tags

In cases where you define text that users see, you can add custom tags that the CGI program replaces with text in either English, French, or another language that you have added. For example, when you add a pre-defined question set (Section HERE), you add questions that users can select from.

To have locally defined text appear in the language of the user:

1. In the field that requires definition, type a tag beginning with !!! and containing no spaces. For example, when adding a question to a pre-defined question set, type a tag such as:

   !!!NEW_QUESTION

   in the Question field on the Question definition information page.

2. Copy the EXAMPLES\ERRMSG.M4 file to the CUSTOM directory.
3. Open the CUSTOM\ERRMSG.M4 file.
4. Define the tag by adding entries such as:

        EN_US([[NEW_QUESTION]], [[Date of birth]])
        FR_CA([[NEW_QUESTION]], [[Date de naissance]])
   

5. Save and close the CUSTOM\ERRMSG.M4 file.
6. Run make.bat in the design directory, specifying the appropriate (en-us, fr-ca, nl-be) language option to create new *.z files.

   Note:

   The make.bat command requires that you have the M4 interpreter in your path.

   
    

7. Install the new *.z files in the cgi-bin directory by running make.bat with the install option, specifying the appropriate language option.
8. Reload and review the web pages.
   If necessary, modify the M4 files and run make.bat again.

32.3.3 Modifying multi-language text macros

If you have English, French, and Dutch language users, and you want to modify text in forms or GUI screens, ensure that you edit each language version of a macro.

You modify text in multiple languages by editing macro definitions in the CUSTOM\ERRMSG.M4 and CUSTOM\LANGUAGE.M4 files. These files override or expand upon the human readable text, defined in ERRMSG.M4 and LANGUAGE.M4, that the end-user will see.

To modify multi-language text macros:

1. Copy the EXAMPLES\ERRMSG.M4 and EXAMPLES\LANGUAGE.M4 files to the CUSTOM directory.
2. Copy the required macro for each of the required languages from the ERRMSG.M4 and LANGUAGE.M4 files to the CUSTOM\ERRMSG.M4 and CUSTOM\LANGUAGE.M4 files.
3. Modify the macros with appropriate translations. For example, copy:
   EN_US([[__ENTER__]],[[Enter])
FR_CA([[__ENTER__]],[[Entrer]])
   then modify as
   EN_US([[__ENTER__]],[[Go])
FR_CA([[__ENTER__]],[[Marche]])
4. Save and close the M4 files.
5. Run make.bat in the design directory, specifying the appropriate (en-us, fr-ca, nl-be) language option to create new *.z files
6. Install the new *.z files in the cgi-bin directory by running make.bat with the install option, specifying the appropriate language option.
7. Reload and review the web pages.
   If necessary, modify the M4 files and run make.bat again.

32.3.4 Adding a language

You can create screens that use another language besides English, French, and Dutch by editing the CUSTOM\LANGDEFS.M4, CUSTOM\ERRMSG.M4, and CUSTOM\LANGUAGE.M4 files. These files override or expand upon the human readable text, defined in ERRMSG.M4 and LANGUAGE.M4 that the end-user will see.

Each macro is defined in English, French, and Dutch. To add more languages, copy macros from the LANGDEFS.M4, ERRMSG.M4, and LANGUAGE.M4 files to the corresponding customization files and provide definitions and appropriate translations.

For example, to add Spanish language text:

1. Copy the EXAMPLES\LANGDEFS.M4, EXAMPLES\ERRMSG.M4, and EXAMPLES\LANGUAGE.M4 to the CUSTOM directory.
2. Add a new macro definition to the CUSTOM\LANGDEFS.M4 file for ES_ES, similar to the macro definitions for EN_US and FR_CA in the LANGDEFS.M4 file.
3. Copy the macros for one of the existing languages from the ERRMSG.M4 and LANGUAGE.M4 files to the CUSTOM\ERRMSG.M4 and CUSTOM\LANGUAGE.M4 files. For example, copy the English language version of each macro.
4. Modify the definitions to provide appropriate translations. For example, modify:
   EN_US([[__YES__]], [[Yes]]) to read:
   ES_ES([[__YES__]], [[Sí]])
5. Save and close the M4 files.
6. Run make.bat in the design directory, specifying the es-es language option to create new *.z files
7. Install the new *.z files in the cgi-bin directory by running make.bat with the install option, specifying the appropriate language option.
8. Reload and review the web pages.
   If necessary, modify the M4 files and run make.bat again.

32.3.5 Modifying web page design

You can modify the design of any web page, including the placement of fields, buttons and text, by modifying the HTML snippets in the M4 files.

To change the appearance of any page in the application:

1. Login to P-Synch and navigate to a web page that you want to customize.
2. Use the View -> Source (or equivalent) option in your web browser, to see the current HTML code.
3. Open the M4 files in the design directory relating to the web page you want to customize.
4. Find the HTML code snippet that matches the HTML code you saw in the web browser.
5. Create the appropriate customization file by copying the matching example file. For example, copy examples\nph-psf.m4 to custom\nph-psf.m4.
6. Copy the snippet starting from the !!! tag definition up to, but not including, the next !!! tag from the file in the design directory into the customization file.
7. Modify the HTML code to suit your needs.
8. Save the M4 files.
9. Run make.bat in the design directory, specifying the appropriate (en-us, fr-ca, nl-be) language option to create new *.z files
10. Install the new *.z files in the cgi-bin directory by running make.bat with the install option, specifying the appropriate language option.
11. Reload and review the web pages.
    If necessary, modify the M4 files and run make.bat again.

See Section HERE to learn how to add multi-language custom tags for locally defined text.

32.3.6 Moving custom attribute fields

You can add a CGI plug-in to add functionality beyond password management to the help desk or self-service components in P-Synch, as documented in Section HERE.

By default, the input fields and buttons related to new functions appear below the password reset fields in the Help user or Reset my passwords screens.

You can move the new input elements around the page using the same technique (editing M4 files, and compiling *.Z files) described in Section HERE. The key in this case is to move the %EXTERNAL_HTML% element in the appropriate HTML form.