test

i-Planet Administration Guide

HTML Templates

Caution - Caution -

The classification of these templates and URLs is Unstable. For an explanation of this classification, see the manpage attributes(5) in Solaris 2.6. The likelihood that these templates and URLs will change is very high. Make a backup copy of any template file that you are going to edit.

Generally, you modify the appearance of and the information on the i-Planet Desktop through the Administration Console and through the Edit Preferences page of the end user's i-Planet Desktop. Additionally, however, you can edit template files to control the appearance of the pages in the end user's i-Planet Desktop.

In general, you use the Administration Console to change color settings and certain predefined values. You edit the HTML templates to make substantive changes to layout or design of pages or to add extra functionality, beyond the services possible through the Administration Console.

Caution - Caution -

You must have strong HTML skills as well as a thorough understanding of web servers and server-side includes to edit template files. If you corrupt a template file, you may have to restore the original files from your i-Planet CD-ROM to recover and gain access to the system.

How Templates Work

HTML template files control the layout and source of the i-Planet Desktop and of the login, logout, and time-out screens. The templates are located on the i-Planet server in the directory /etc/opt/SUNWstnr/html_templates.

Note -

If you edit these templates, you must stop and restart the web server. To restart the web server, as root type the following commands on the machine on which you have installed the i-Planet server.

To Stop and Restart the Web Server on the i-Planet Server

  1. As root, type the following commands to stop and restart the web server:


    # /opt/SUNWjeev/bin/iplanet_serv stop
# /opt/SUNWjeev/bin/iplanet_serv start

Templates for Customizing the Authentication Pages

These templates allow you to customize the login, logout, and time-out screens. Make sure the pages still contain the sections that the authentication daemon needs to implement the authentication process.

In general any JavaScript or text segment that is of the form <subst data="rows"></subst> must exist somewhere in the HTML page after you have modified it.

The subst segments are important sections of text that the authentication module dynamically replaces during the login process.

Templates for Customizing the i-Planet Desktop

HTML template files control the layout and source of the i-Planet Desktop. The templates are:

You can edit these files to change the appearance, the information presented, and the links. You can add or remove various features according to your corporate policy or your security policy. You can also copy these files to build new templates.

URLs for Displaying i-Planet Desktop Templates, Help, and Starting Applications

Where not shown, the gateway prefix https://gw.sun.com/ is optional, since these pages and applications can be used from within the intranet.

Desktop

The template= parameter to the i-Planet Desktop Servlet can be used to display any of the four predefined template files, or an arbitrary file using http://file-to-display. Tag-swapping is applied to all tags (if any) found in the source file. See below for a description of the tags:

Help

Applications

Generally, application links are targeted to new windows, so that the i-Planet Desktop page from which they are launched remains displayed.

Custom Pages and Applications

For access from the Internet to intranet sites that do not require tag-swapping, use URLs of this form:

https://gw.sun.com/http://internal_machine:internal_port/url

Template File and Tag Swapping

When the i-Planet end user browses the i-Planet Desktop and the pages associated with these templates, an i-Planet application processes the template, substituting specific values (many specified through the Administration Console) for the place holders in the templates and sends the result to the user. This processing is required to allow you to customize the end-user interface easily through the Administration Console.

The processing and substitution are based on custom tags in the HTML template files. These are not HTML, but rather specialized extensions developed expressly for this application. The extension to HTML is provided by bracketed ([]) tags. Tags appear in-line like this: [tagName]. When a tag is found in any of the templates or other files processed by the i-Planet Desktop servlet, it is replaced with content retrieved from one of the following sources:

These extensions function very much like server-side includes. Only when the file is served properly by the server, and in this case is processed through the Desktop servlet application, can you see the content accurately. If you try to view template files directly in your browser, they will appear to be broken, even if they are not.

Content Inserted from i-Planet End User's Preferences

The preferences that the i-Planet end user provides in the Edit Preferences page can be automatically substituted into a file with the tags listed in the following table. Tags marked with a (D) can be provided to new i-Planet end users as a default value through the Administration Console. The new i-Planet end user can change the default value through the Edit Preferences page of the i-Planet Desktop. Table A-1 contains tags for preferences that the i-Planet end user provides and a description of them.

Table A-1 Tag Names for User's Preferences

Tag Name 

Content Inserted 

firstName

User's first name  

lastName

User's last name 

userName

User's UNIX login name 

mailPass

User's IMAP password  

mailServer

User's IMAP server machine name (D) 

SMTPmailServer 

User's SMTP server (D) 

calendarServer

User's Calendar server machine name (D) 

serviceTimeout

Time-out for status check services (D) 

System Information

Table A-2 contains the tag for the information that the system provides and a description of it.

Table A-2 Tag Names for System Information

Tag Name 

Content Inserted 

curDate 

Current date and time of the machine running the i-Planet Application and web servers. 

i-Planet-Provided Services

i-Planet contains services to check the status of the i-Planet end user's IMAP and calendar servers. They provide descriptive text of the machine's status. Table A-3 contains the tags for the services that i-Planet provides and a description of them.

Table A-3 Tag Names for i-Planet-Provided Services

Tag Name 

Content Inserted 

mailStat 

Output of the "check for new mail" internal service 

calendarStat 

Output of the "check calendar server status" internal service 

Administrator-Provided Values

The i-Planet end user cannot control the content inserted for these tags. They are provided to allow easy administrative control of the overall look of the templates. For these tags, a default value is provided by i-Planet; changing this value affects the appearance of all template files that contain the tag. The initial "A" in each tag name indicates that you can change it. Examining the template files shows the current use of these tags. Table A-4 contains the tags for the values that you provide and a description of them. If you examine the original HTML template files, you can see most of these tags in use.

Table A-4 Tag Names for Administrator-Provided Services

Tag Name 

Description 

AbgColor 

Background color 

AbannerImage 

Image file in [installdir]/public_hmtl/content/common to place at the top of page 

AprodName 

Product/site name to place at the top of each page 

AprodFont 

Font to use for the product name 

AprodSize 

Font size of the product name 

Acolor1-n 

By defining values for the various colors. HTML items using those colors can be changed quickly. 

Files

Files can be inserted into the output of a template. The file itself is passed through the tag-swapping mechanism, so files can contain any of the tags listed above. The initial "F" on the tag name indicates that the tag denotes a file. Table A-5 shows the format for tags that are used for files. Replace the xyz with the path and name referencing the file that you want to use.

Table A-5 Format for Tag Names for Files

Tag Name 

Content Inserted 

Fxyz 

Contents of the file named xyz

URLs

The content of the URL is retrieved and inserted into the document after being passed through the swapper. The initial "U" denotes URL. Table A-6 contains the format for the tags that denote URLs and their description.

Table A-6 Format for Tag Names for URLs

Tag Name 

Content Inserted 

Uabc 

contents of the URL named abc 

Note -

The URLs must be accessible by the server.

Other i-Planet Desktop Values Configured From the Administration Console

In addition to the tag values listed above, from the Administration Console you can configure the following i-Planet Desktop values shown in Table A-7 with their description.

Table A-7 Tag Names for i-Planet Desktop

Tag Name 

Description 

SMTP_host 

The mailhost to use when sending the feedback form 

Feedback_Address 

When a user sends the feedback form via SMTP_host, send to this address. 

Stopping and Restarting the Web Server

After you make your changes to the templates, you must restart the web server on the i-Planet server for the changes to take effect. See the procedure "To Stop and Restart the Web Server on the i-Planet Server"" earlier in this Appendix.