APPENDIX A |
Customizing i-Planet HTML Template Files |
This chapter describes how to use the HTML templates to customize the authentication pages and the i-Planet Desktop.
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 -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.
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 |
As root, type the following commands to stop and restart the web server:
|
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.
|
login_menu.html--Is sent when more than one authentication module is configured. This gives the i-Planet end user a choice of which module to use for authentication. The text <subst data="rows">No menu?</subst> must be somewhere in the document. It generates a list of URLS to the authentication modules. |
|
|
login_fail_template.html--Is sent when authentication has failed. This page contains no required sections. |
|
|
login_license_fail.html--Is sent when there are no more licenses. This page contains no required sections. |
|
|
login_reauth_menu.html--Is sent when an i-Planet end user's session has been inactive for the time set in the Administration Console. It contains a link for reauthentication. You must not change the JavaScript in this page. You can modify all other HTML. |
|
|
login_trustProxy_warning.html--Is presented to i-Planet end users who log in to the i-Planet Desktop using Netscape and do not have the browser configured to accept all cookies. In this case the end user cannot start the i-Planet Java applets. If you do not want to display this page because you do not allow the end user to run Java applets, replace the contents of this page with an HTML refresh tag that contains zero time-out and is redirected to /login/default. |
|
|
login_template.html--Is sent for individual authentication modules such as RADIUS or UNIX. The six subst text segments must remain after you have modified it. This page is also sent when you log in to the i-Planet Administration Console. |
|
|
logout.html--Is called after the i-Planet end user selects the logout link on the i-Planet Desktop. It contains no required sections. |
|
|
login_timeout_template.html--Is called during an authentication session if the i-Planet end user does not submit the login form within the specified time. It has no required sections. |
|
|
login_reauth_admin.html--Is sent when your administration session has expired. It contains a link for reauthentication. You must not change the JavaScript in this page. You can modify all other HTML. |
|
|
login_timeout_admin.html--Is called during an administration session if you do not enter anything within the specified time. It has no required text. |
|
|
login_fail_admin.html--Is sent when authentication has failed. This page contains no required text. |
|
|
logout_admin.html--Is called after the i-Planet administrator selects the logout link on the i-Planet Administration Console. It contains no required sections. |
|
|
session_terminated.html--Is displayed if the i-Planet Desktop servlet cannot process the i-Planet end user's request. If the i-Planet server is rebooted while i-Planet end users are logged in, for example, their next request will cause this page to be presented. |
HTML template files control the layout and source of the i-Planet Desktop. The templates are:
|
|
advancedTemplate.html--Controls the Advanced page in the end user's i-Planet Desktop. By default, it is set to allow an applet that downloads NetMail and installs it on a local client, but you can add other functionality of your choice. |
|
|
feedbackTemplate.html--Controls the appearance and layout of the feedback form in the end user's i-Planet Desktop. |
|
|
prefTemplate.html--Controls the appearance and layout of the Edit Preferences page in the end user's i-Planet Desktop. |
|
|
userTemplate.html--Controls the Front Page in the end user's i-Planet Desktop. |
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 ApplicationsWhere 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:
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=user Displays /etc/opt/SUNWstnr/html_templates/userTemplate.html |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=user_loginDisplays same template file as above after recording user's login time (visible in admin console under User Preferences) |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=pref Displays /etc/opt/SUNWstnr/html_templates/prefTemplate.html |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=advanced Displays /etc/opt/SUNWstnr/html_templates/advancedTemplate.html. |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=feedback Displays /etc/opt/SUNWstnr/html_templates/feedbackTemplate.html |
|
|
http://apps.sun.com:8080/servlet/SNLogout Ends user's session and displays /etc/opt/SUNWstnr/html_templates/logout.html |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=feedback Displays /etc/opt/SUNWstnr/html_templates/feedbackTemplate.html |
Help
|
|
http://apps.sun.com:8080/docs/usenglish/online_help/user_help_topics.html |
|
|
http://apps.sun.com:8080/docs/usenglish/online_help/user_help_index.html |
Applications
Generally, application links are targeted to new windows, so that the i-Planet Desktop page from which they are launched remains displayed.
|
|
http://apps.sun.com:8080/NetMail/netmail.html: Starts NetMail from a small browser window (400 x 150 in the delivered-userTemplate.html) |
|
|
http://apps.sun.com:8080/servlet/com.sun.webaccess.mail.Mail? realm=SunNet: Starts NetMail Lite application |
|
|
http://apps.sun.com:8080/servlet/com.sun.webaccess.calendar. Calendar?realm=SunNet: Starts Calendar client application |
|
|
http://apps.sun.com:8080/servlet/SNDesktop?template=http://apps.sun.com/apps/main/netsurf/netsurf.html: Starts NetSurf. It is treated as a template file so that tag-swapping can be applied (starting URL to surf to is an administrable tag) |
|
|
https://gw.sun.com/http://apps.sun.com:8080/servlet/SNDesktop?template=http://apps.sun.com:8080/apps/main/netlet/nf0.html Starts Netlet in a small window, and provide link to NetFile. It runs through SNDesktopServlet to apply tag-swapping to the window's display. In the delivered-userTemplate.html, the spawned window is 420 x 220. |
Note - This application must be started with the full i-Planet gateway URL prefix.
|
|
http://apps.sun.com:8080/cgi-bin/netfile/nf_htmlui.cgi Starts the NetFile Lite application |
|
|
http://apps.sun.com:8080/cgi-bin/skey/skeylogin.cgi Creates the Generate S/Keys page |
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
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:
|
|
User preferences |
|
|
System information |
|
|
i-Planet-provided services |
|
|
Configurable data that can be changed with the Administration Console |
|
|
Other configurable data |
|
|
Local files |
|
|
Content referenced by URLs. |
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.
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
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 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
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
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
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.
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.
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.
