Customizing Web Templates

You must accept the FirstClass License Agreement before you can use this product. If you do not accept the terms of the License Agreement, do not install the software and return the entire package within 30 days to the place from which you obtained it for a full refund. No refunds will be given for returned products that have missing components.

Information in this document is subject to change without notice. Certain features and products described in this document may not be currently available in all geographic regions. Distribution or reproduction of this document in whole or in part must be in accordance with the terms of the License Agreement.

All rights reserved. FirstClass is a registered trademark of a Centrinity Inc. subsidiary used under license. Centrinity, the Centrinity logo, and the FirstClass logo are trademarks of Centrinity Inc. All other trademarks are property of their respective owners.

This edition applies to Release 7.0 of FirstClass and to all subsequent releases and modifications until otherwise indicated in new editions. This document is bound by international copyright law and the FirstClass Software License Agreement and Limited Warranty included with every FirstClass product.

Technical support

Telephone technical support is available to registered administrators at the following numbers:

Toll free in North America: 1-800-346-9108

Toronto: 905-762-7060

International: +353-61-725-200.

Online support questions may be directed to support@centrinity.com.

What is a template

A template is a document used to create multiple pages that share the same layout. When you create a template, you indicate which elements of a page remain constant in documents based on that template and which elements change. Templates are most useful for situations where you want a set of pages to have an identical layout—where you want to design the complete final layout for a set of pages first, and then add content later. For example, if you publish an online newsletter, the masthead and overall layout probably won't change from one article to the next or from one issue to the next. However, the content of each newsletter will change. You can see how using templates in this situation would save you and other staff members hours of extra work. With established templates, anyone can put together a new issue of the newsletter and concentrate mainly on the content, without having to recreate any of the layout.

FirstClass web templates work on the same principals as those discussed above. Web templates provide the interface for your web Desktop in much the same way FirstClass client forms provide the interface for your client Desktop. Basically, templates are the web equivalents of client forms. Similar to client forms, the web template layout does not change, for example areas like input field names or the location of input fields, but the information users input changes with each operation.

Why you may want to customize your FirstClass web templates

FirstClass Internet Services comes with a standard set of templates. These templates define the interface of your FirstClass environment when you log in through the web. The most common reason to customize web templates is to change the look and feel of your existing FirstClass web interface. In some cases, you may want your client and web environment to look different. If you support multiple web sites on your system, you can create brand new templates to reflect this diversity. For example, if you have two different sites for your Sales and for your Engineering departments, you could create template sets that reflect the different perspectives of these departments. For information on creating multiple web sites, see the FirstClass Internet Services Administrator's Guide.

How FirstClass web templates work

While a FirstClass web template contains the layout of the object being displayed, it also contains special Internet Services tags. These tags, called X-FC tags, act as placeholders for data that is pulled from the data store on the server. For a complete listing of X-FC tags, including function, sytnax, and examples, see Internet Services X-FC tags.

Similar to client forms, web templates retrieve data from the data store on the FirstClass server through field ID numbers.

FirstClass Designer automatically assigns field ID numbers to fields you have created on your form. In the corresponding web template, embedded X-FC tags act as placeholders for fields on the template. These X-FC tags map directly to fields on a client form and pull the same data from the FirstClass server. Each field on the client form corresponds to the same field on the web template.

You can think of this process as similar to a mail merge in a word-processing application. The template is like the letter, and FirstClass tags are like the embedded field markers in the letter that pull specific information from a central database. The FirstClass server is like the central database. When you perform the mail merge, the field markers are replaced in the letter by actual data (for example, name, address, and salutation). Similarly, when you create a new message or a new document in FirstClass, the FirstClass X-FC tags are replaced by actual data from the server (for example, the From field, Subject field or the Cc field). When the mail merge is completed, you have all the relevant information displayed on the letter.

The graphic below shows how some of the field IDs on a New Message client form and the corresponding X-FC tags on a web template map to each other:

(Double-click to enlarge)

Adding FirstClass resources

Although there are some similarities in how the client forms and web forms display information, there are some differences in how they each acquire the necessary FirstClass resources and where these resources reside. FirstClass resources include images, pictures, icons, sound files, and languages that FirstClass supports. For information on FirstClass client resources, see FirstClass Designer. For information on Internet Services resources, see FirstClass Internet Services Administrator's Guide.

The graphic below illustrates how the FirstClass client outputs forms and resources and how Internet Services outputs templates and resources:

(Double-click to enlarge)

How FirstClass web templates are created

When you create a new form in FirstClass Designer and you want this form to be web accessible, you must create a corresponding HTML template set. This HTML template set must consist of a noneditable (read-only) version and an editable version. The name of the noneditable (read-only) template is the formid number. The name of the editable template is either Send.formid or Edit.formid. For example, the name of the noneditable New Personal Address template is 105 and the name of the editable New Personal Address template is Edit.105.

Note

The New Message template is an exception to this rule. The name of the noneditable New Message template is 141 and the name of the editable template is named Send.

When a web user creates a new object (for example a message or a document), the first thing Internet Services does is look for and retrieve the matching template form ID as its corresponding client form. If Internet Services cannot find a template that matches the form ID, it will load template 95 as a default. If Internet Services cannot find an editable template that matches the form ID of the object, it will load the read-only version of that template.

In noneditable templates (read-only) you can only view the document displayed, not edit any information. For example, when you receive an email message and open it, you can only read it. To edit the message, you must either reply to the message or forward it on to another user. When you perform this action, the displayed template becomes editable, since you are actually opening up the editable version of that same template.

You can create web templates in one of two ways:

• using the Save as HTML feature in Designer on a form you have created

If you use this feature, FirstClass Designer automatically creates HTML documents in both a read-only and either Send.formid or Edit.formid format.

• using an HTML editor

If you create a template in an HTML editor and you want the template to be editable, you must create two HTML documents: read-only and either Send.formid or Edit.formid.

Examples of noneditable and editable template sets are:

• a New Message template: Send and 141

When you create a new Message document on the web, you are using the Send (editable) template. When your recipient reads the message, she is opening the 141 (noneditable) template.

• a phone call form: Send.128 and 128

When you create a new Phone Call document on the web to send a Called No message notification, you are using the Send.128 (editable) template. When your recipient reads the phone message, she is opening the 128 (noneditable) template.

• a Personal Address: Edit.105 and 105.

When you create a New Personal Address on the web, you are using the Edit.105 (editable) template. When you read this address at a later date, you are opening the 105 (noneditable) template.

Editable templates are usually larger and more complex than their corresponding read-only counterparts, due to the extra embedded code intended to create specific actions. The graphic below shows a section of the editable and read-only New Message template:

(Double-click to enlarge)

Internet Services script

Along with HTML (or any other HTTP-friendly language) web templates also contain special tags that call data from the FirstClass server. These special tags, called X-FC tags, are part of Internet Services script (Internet Services script). In addition to X-FC tags, Internet Services script also contains different commands, functions, and variables. Where the purpose of X-FC tags is to pull data from the server, the purpose of the other Internet Services script commands is to enhance the overall functionality of the templates. All Internet Services web templates and server-parsed files incorporate the different components of Internet Services script, which is an extension of Apache's Extended Server-Side Include scripting language (XSSI).

A note on server-side include scripting language

Server-side includes are instructions to the server to include a specified file in the current document before sending the document to the user who requested it (similar to a library item that is provided by the server). Placing a server-side include in a document inserts a reference to an external file; it does not insert the contents of the specified file in the current document. Keep in mind, parsing a file for server-side includes takes a little extra time, though, so pages the server parses are served out slower than other pages.

When you open a document that resides on your server, the server processes the include instructions and creates a new document in which the include instructions are replaced by the contents of the included file. The server then sends this new document to your browser. To edit the contents of a server-side include file, you must directly edit the file that you are including. Any changes to the external file are automatically reflected in every document that includes it.

Internet Services script has four components:

• X-FC tags (see Internet Services X-FC tags)

used to pull information from the FirstClass server and display FirstClass content to the web user

• Internet Services script commands (see Internet Services script commands)

used to provide some flow control when data is being processed and displayed to the web

• Internet Services script functions (see Internet Services script functions)

used as string processing functions (can be part of any Internet Services script expression)

• Internet Services script variables (see Internet Services script global constants)

used in any expression, static value, or function argument by prefixing the variable name with a $ sign.

Top

Customizing web templates

Note

The information in this document should be considered only an overview of the web customizing process. Customizing templates is an advanced exercise and requires a good working knowledge of the FirstClass client, FirstClass Internet Services script (Internet Services script), HTML, HTTP protocol, advanced Java script, and Cascading Style Sheets (CSS).

As stated above, you need a good working knowledge of different protocols, markup languages, scripting languages and more to create custom templates from scratch or customize existing ones. You also need to understand the structure and components of web templates at the tag level. In this section, we focus on examples of real X-FC tags in FirstClass objects and how they map to fields on their corresponding client form. We also break down these X-FC tags into their various components to show you how they pull information from the FirstClass server and display this information to the web. There are many X-FC tags that you need to know to work on templates. For a complete list of X-FC tags, see Internet Services X-FC tags.

Note

FirstClass templates work the same on Microsoft Internet Explorer (MSIE) and Netscape with one exception: how attachments are handled. Microsoft Internet Explorer supports multiple attachments, whereas Netscape only supports one attachment per document.

Location of web templates

By default, web templates are located in the Internet Services/WWW/.templates folder on the administrator's Desktop. You can have as many .name templates folders as you require (where you substitute name for your template set name), but each folder must have a unique name. For example, if you have custom and mobile template sets for your site, you could name the folders that contain them .customtemplates and .mobiletemplates respectively.

Web template structure

There is no standard structure for Internet Services web templates, except for an introductory comment that states the template's subject, name, and the date the template was last modified. The remainder of the template is coded according to what FirstClass content it displays, using X-FC tags and other Internet Services script variables. X-FC tags can be categorized as either LANG tags or field tags. LANG tags pull field text language information out of the en.rez file. Field tags pull information the user inputs in editable fields, such as the name in the "To" field on a New Message form or the body text in the body field. Field tags are also used to pull server information, such as the time stamp on a logout template. The examples below compare the client form, web template code, and web template form for a New Message and New Personal Address.

Warning

Randomly pasting any of the following code examples into a template may not work as desired. Do not consider any of the code shown in these examples as complete.

Note

Print out graphics for best results.

Example 1

New Message form, template code, and displayed web form:

(Double-click to enlarge)

Now, let's break down the tags into their components:

(Double-click to enlarge)

Example 2

New Personal Address form, template code, and displayed web form:

(Double-click to enlarge)

Now, let's break down the tags into their components:

(Double-click to enlarge)

Top

About FirstClass objects

All items that reside on the server are considered FirstClass objects, and templates are used to view these FirstClass objects. To customize web templates, you need to understand the different levels of objects and how you build templates to view them. Objects can grouped into three categories:

• Form objects

• Listings objects

• Exceptions.

Form objects

Form objects are forms that reside on the server and contain data. Form objects can be:

• mail forms (read-only and editable versions)

• documents (read-only and editable versions)

• memforms (edit only)

• system forms (read-only and editable versions)

• calendar forms (read-only).

Mail forms (read-only and editable versions)

Mail forms reside on the server and contain data but specifically support the Send operation. Mail forms include:

• messages

• phone call forms

• file transfer forms.

Documents (read-only and editable versions)

Documents are items that are saved to the server but not sent (do not support the Send operation).

Memforms (edit only)

Memforms are virtual forms that do not represent objects on the server but behave as if they do. Memforms mimic documents, as they are saved but not sent. These forms are associated with actions and include the:

• Auto Registration form

• Change Password form.

System forms (read-only and editable versions)

System forms are used by FirstClass and reside on the server, but you cannot create or delete them. System forms include:

• Preferences

• System Profile forms

Calendar forms (read-only)

Calendars are considered forms when they are viewed by month or by week instead of as a list.

Listings objects

Listings objects are displayed as lists (for example message listings in your Mailbox or document listings in a conference). All listings are composed of multiple templates and have IDs less than zero.

Listings objects consist of:

• container listings and leaf objects

• search listings

• Directory listings

• Who's Online listings

• history listings

Container listings and leaf objects

Containers hold and display listings of other subcontainers and leaf objects. Leaf objects are any non-container items that are listed in a separate pane in a FirstClass client split view. Examples of container objects are:

• conferences

• folders

• calendars.

Examples of leaf objects are:

• messages

• documents

• bookmarks

• events

• tasks

• uploaded files.

Filtering container listings

The output of container and leaf objects in a listing can be limited to a specific range (typically used to introduce 'paging' to reduce download time). Both container and leaf objects each maintain separate ranges, which can be controlled at the URL parameter level by using nItems, nFolders, FirstItem, FirstFolder, LastItem and LastFolder, or inside the templates using the various CONFERENCE-LIST and CONFERENCE-FOLDER-LIST X-FC tags. If you wish to see the deleted items in a container listing, use the 'Show deleted' URL parameter (for example, "<X-FC-OBJURL>?Showdeleted = 1").

Note

If you use more than two tags or items the third will be ignored. Internet Services only reads the first two tags or items in either the object URL or the template code.

Sorting and grouping of container listings

Sorting and grouping sorts a list by whatever criteria you specify in the URL parameters. By default, your sorting parameters follow those set in the client. If you want to change the sorting and grouping behavior, you do so using URL parameters. The URL parameter syntax is:

[I|F]table[commit]=SortCol[_GroupCol]

Where SortCol changes the sort of the columns and GroupCol changes the grouping of the columns.

The parameters for both SortCol and GroupCol are ([-] ColID +1). The (ColID + 1) is a numeric expression that is evaluated. If SortCol < 0, this implies Reverse sort. If GroupCol < 0, this implies collapse groups.

Where [commit] saves the new sort or group column to the server (it commits your changes).

Where[I|F] sorts on Item or Folders (make sure that you have a split in your view before using the [I] literal term).

For a list of current valid columns, see the X-FC-LAYOUT tag in Internet Services X-FC tags.

Container default listing mode

A default listing for a container object is a combination of different templates. It is divided into five sections and follows this order:

1 Header templates (-1 and -10)

2 Subcontainer listing templates (-11, -12, -14)

3 Separator template (-15)

4 Leaf listing templates (-16 to -18)

5 Footer template (-2)

If you don't want all of the contents of a container listed, you can abort the process at any point by including the <X-FC-HEADER-ONLY> tag in the last template you want listed.

Container component listing mode

Internet Services provides the functionality to filter listings based on the types of objects it contains (for example subcontainers or listings). You can obtain these listings by adding a parameter to the container URL. Let's take a look at the different URL parameters required:

• to filter for subcontainers only, use the 'Folders' URL parameter.

• to filter for leaf only items, use the 'Items' URL parameter.

• for a combined listing, use both parameters.

All parameters use the -205, -206, and -207 templates.

Here is an example that works for all three cases:

[<X-FC-OBJURL>?Folders = 1-10]

This URL lists the first ten subcontainers in a container.

Note

The filtering argument can also be used as a paging argument using the syntax: filter=first-last. For more information, see the Filtering section in this document.

Search listings

The Search form is a system form that allows you to specify your search filter criteria in FirstClass. The form ID for this system form is 8000. When you do a search (using the 8000 system form) your results are posted using these templates:

• -300 (Search Listing Header)

• -301 (Search Listing Item)

• -302 (Search Listing Progress)

This template renders the changed search folder.

• -303 (Search Listing Footer).

Directory listings

The FirstClass Directory is a list of everything in the system to which you can address mail (for example users, conferences, address books, and aliases). Directory listings consist of:

• Directory filters

• Directory search listings

• name validation

• Who's Online

Directory filters

Directory filter parameters are used to display only a portion of the Directory. This is useful, as there are usually a large number of items contained in the Directory and the user only wants to view a sublist.

When a user performs a search, FirstClass filters either on Type or Name. When the filter is on Type, you can filter the Directory entries for:

• local names (users on local system plus all address book entries)

• remote names (users on gateway systems)

• conferences (all conferences whose Directory listing is visible to users)

• address book (all address book entries)

• Internet alias (all Internet address aliases)

All these filters are integers and use 1 for 'on' and 0 for 'off' in the URL parameter. The default filter is local/remote/conference.

When the filter is on Name, you can search on a full name or part of a name. In either case use the 'srch' parameter. Also, if you are using a browser, it is a good idea to set your 'charset' parameter to the correct character set of your system (ISO character set codes).

Directory search listings

To open a simple Directory listing (for example, send mail to a user, open a user calendar, or open a résumé) use the <X-FC-LOGIN>Directory URL. The templates used for this type of listing are:

• - 100 (Directory form)

• - 104 (Directory form footer)

To do a Directory lookup, use the Directory search listings URL <X-FC-LOGIN>Directory/Lookup. The templates used for this type of listing are:

• -100 (Directory form)

• -101 (Directory list header)

• -102 (multiple results require multiple -102 templates) or -105 (no results)

• -103 (Directory list footer)

Name validation

To validate names in a field, use the <X-FC-OBJURL SLASH>Lookup URL, where <X-FC-OBJURL > is in whatever object you are validating the names into (where the server puts the names once they are validated).

Some objects(for example, resource or location calendars) have limited Directory listings so filters are used. The templates used for this type of listing are:

• -100 (Directory Form)

• -101 (Directory List Header)

• -102 (one for each name request)

• -105 (only if there are name requests)

• -103 - (Directory List Footer)

Name validation sometimes supports and, in some cases, requires these extra parameters:

• Operation

• Insert|Insert Multi

This parameter is used to search for a recipient to insert in a recipient list. The Insert|Insert Multi parameter uses these parameters:

• Field ID = fieldid

This is a mandatory parameter that specifies the field into which you are inserting.

• [Index = index]

This specifies where in the list you are going to insert the recipient name.

• [standard Directory parameters]

These parameters are standard Directory parameters used to filter the Directory (see Directory listings).

If the Insert parameter returns a single match, the recipient name is inserted directly into the object on the server. For example, if you open a message and type in an exact match for a name in the To field, the name is automatically added to the list in the field. There is no need for a Directory listing. The Insert Multi parameter uses the same syntax as the Insert parameter but inserts multiple names into the object on the server.

• Delete

The Delete parameter is used to delete a name from a recipient list and its valid values are:

• Field ID = fieldid

This parameter specifies the field that you are deleting from.

• [Index = index]|[client ID = clientid]

This parameter must have either an index parameter (one at a time) that deletes a name as per its position in the list, or one or more client ID parameters (removes first instance of the client ID).

Example of Index parameter

If your To list has name1, name2, name3, this URL would delete name1:

<X-FC-OBJURL SLASH>Lookup?Operation=Deleted&FieldID=9&Index=0>

• Add

The Add parameter is used to add a name from a recipient list and its valid values are:

• Field ID = fieldid

This parameter specifies what field you are adding to.

• [Index = index]

This parameter specifies where in the list to place the new names.

• Client ID = clientid

This parameter must have one or more client IDs. If you have specified an Index, the client IDs are added in reverse order. If no Index is specified, no order is defined.

Who's Online listings

A Who's Online listing is a list of all users currently logged who you are allowed to see. To open a Who's Online listing use the URL "<X-FC-LOGIN> whosonline" (see Internet Services X-FC tags). Templates used for this listing are:

• -400 (Who's Online Header)

• -401 (Who's Online Item)

• -402 (Who's Online Footer).

History listings

A History listing lists the history of any leaf object, for example a calendar event, message, or document. To open a history listing use the URL "<X-FC-OBJURL SLASH>history".

The templates used are:

• -110 (History Header)

• -111 (History Item)

• -112 (History Listing Footer)

Exceptions

Exceptions are neither objects nor listings. They include stationery, chats, and monitors. In a filtered container list, however, these exceptions are listed with subcontainers. Internet Services does not inherently render these objects to the web. However, a Java applet is supplied with FirstClass to provide chat support over the web. The Java chat applet, by default, resides at the URL level: <X-FC-LOGIN-JAVA/FCHAT/CHAT.SHTML?Name1, Name2...>.

Top