Building a Custom Team Folders Template

[Previous] [Next]

Although customizing the built-in templates can be interesting, you might want to create your own template and have the Team Folders Wizard deploy it. There are a number of reasons for doing this. First, the Team Folders Wizard provides an easy way for your users to create applications based on your template. Second, the Team Folders Wizard deploys your application to a folder. This includes copying forms, views, and folder home pages to the application folder. Instead of having to write a deployment and customization application yourself, you can simply leverage the Team Folders Wizard.

Creating a custom template is straightforward. Every custom template must consist of a personal folders file (.pst), a folder home page, and a Template initialization file (.ini). The .pst file contains the folders, items, views, and forms you want to deploy. The folder home page is the Web interface you want to display to the user. The .ini file contains settings that you specify for the wizard when it deploys your application.

Creating the .pst File

To create the .pst file, take your existing application and its folder and simply copy them to a personal folder. If you're creating a new application, you can just create a new .pst file and proceed. You'll need to create a Team Folders root folder to contain your application. The wizard will copy this root folder to the location specified by the user who is deploying your application using the Team Folders Wizard. The .pst file can also contain an Administration folder, which you need if you want your application to have an administration module.

Creating the Folder Home Page

There's no special tasks that you need to perform inside of the folder home page in order to allow the Team Folders Wizard to deploy it. However, you might want to create a separate folder home page for each folder in your application. This arrangement differs from that of the built-in Team Folders templates, which use one folder home page that dynamically changes the HTML when a user clicks on its links.

Creating the Template.ini File

The Template.ini file tells the Team Folders Wizard how to specifically deploy your application. In this file, you tell the wizard how to replace strings in your folder home pages, associate application folders with folder home page files, and localize your application if needed. A sample Template.ini file follows.

'************************************************************** 'Template.ini File * '************************************************************** ' 'The individual files are made up of a list of keys and replacement items. 'The keys are the values that should be searched for in the file. ' 'Notation is as follows: ' ' My String Name=mystring <none - default string> ' 'The global section applies to all HTML files listed in the 'HTMLFiles section. This could provide a convenient mechanism 'for changing elements such as: ' 'Style sheet, corporate logo, and so on ' '************************************************************** '------------------------------------------------------------------ 'GLOBAL SECTION '------------------------------------------------------------------ '[Global] keys added by the search engine at run time: ' '(1) Title ' 'Retrieved from user entry for project name in Team Folders Wizard. 'Replaces <OLTF@Title> tag in HTML files. ' '(2) CodeBaseURL ' 'Specifies location for download of View and Permissions controls. 'It is CtlCodeBase value for the wizard add-in entry under 'HKEY_CURRENT_USER (HKCU), created during installation of Outlook 2000 'Team Folders. Replaces <OLTF@CodeBaseURL> tag in HTML files. ' 'Registry value for CtlCodeBase can be customized with Custom Installation 'Wizard (CIW) or overwritten by running Codebase.bat to install Outlook '2000 Team Folders. Codebase.bat is included with the Team Folders 'Administration Kit. ' '[Global] keys that MUST be defined by template designer: ' '(1) AdminFolder ' 'Used for updating permissions for the project Administration folder '*** Requires full path relative to root folder. *** ' '(2) ShowNavBar ' 'Used to show (value of 1) or hide (value of 0) folder navigation 'buttons 'Replaces <OLTF@ShowNavBar> tag in HTML files ' '------------------------------------------------------------------ [Global] 'AdminFolder=Administration\ ShowNavBar=0 '------------------------------------------------------------------ 'INCLUSIVE HTML FILES LIST SECTION '------------------------------------------------------------------ 'Following section lists the names of all the files that 'need to be edited ' '------------------------------------------------------------------ [HTMLFiles] acctext.htm 'admin.htm '------------------------------------------------------------------ 'INDIVIDUAL HTML FILES SECTION '------------------------------------------------------------------ 'Following sections have search and replace actions 'specific to the file ' '------------------------------------------------------------------ [acctext.htm] 'value=string [Admin.htm] 'value=string '------------------------------------------------------------------ 'FOLDER URL MAPPING '------------------------------------------------------------------ 'This section identifies which HTML file webview each 'project folder is to be associated with ' 'Assumptions: ' '* All target HTML files are in the \Webview directory. '* There is no limit to nesting of the project folders. '* There can be only one root per project. '* The folder names cannot contain the equal sign since this is being ' used as the item delimiter (key=value). '* Folder URL mapping occurs **after** folder name ' localization. ' '[Folders] section pseudo key=value format: (table 'key=idnum,foldername,webview,fullpathrelativetoroot ' 'example: 10=Update Permissions,OLTFaclsTest.htm,\administration\ ' 'path notation ' 'root folder: "root" 'folders nested one level deep: "\" 'folders nested > 1 level must specify path: "\folder1\folder2\" '------------------------------------------------------------------ [Folders] '1=Account Tracking,acctext.htm,root '2=Administration,admin.htm,\ '------------------------------------------------------------------ 'PUBLISH UNIQUE MESSAGE CLASS '------------------------------------------------------------------ 'This section identifies which folders contain forms that need 'unique message class assignment ' '*** Please Note: *** ' 'The ID assigned to each folder in the project from the [Folders] 'section above is also referenced for folder identity in this section ' '(1) The first item in the comma-delimited value string represents the ' ID of the folder containing the form. '(2) The second item in the comma-delimited value string represents the ' existing form MessageClass. '(3) The last item in the comma-delimited value string represents the ' concatenated IDs for folders with associated  html files that need ' to be updated with the new unique MessageClass string. '(4) The folder IDs used in this section must match the assignments in the ' [Folder] section. ' ' [FormClassAssignment] section pseudo key=value format: (table) ' 'ex) idnum=locationfolderid,messageclass,HTMLFolderId1+HTMLFolderId2+… ' '------------------------------------------------------------------ [FormClassAssignment] '1=1,IPM.Post.Account info,1 '2=1,IPM.Contact.Account contact,1 '------------------------------------------------------------------ 'LOCALIZABLE STRINGS '------------------------------------------------------------------ 'This section identifies strings that can be localized. 'At the moment, this consists solely of the folder names. ' '------------------------------------------------------------------ [Strings]

Replacing HTML Strings in Template.ini

By having the Team Folders deploy your application, you can have the wizard replace HTML strings inside your folder home page files. One way to take advantage of this is to change the CodeBase location for ActiveX controls or change constants in your HTML code, depending on the application the user chose to deploy.

The strings in your HTML page must be marked with the format OLTF@searchstring. For example, to replace a string named "username" with the string "Thomriz", you would place OLTF@username in your HTML file. Then, if the name of the HTML file in your Template.ini file was default.htm, you would place a line under the individual HTML files section, as shown in the following example:

[default.htm] username=Thomriz

You can replace the strings either globally or at the individual file level. This example shows how to perform a replacement at an individual file level. The Team Folders Wizard performs a global replacement for names such as OLTF@CodeBaseURL, which specifies the location for the View control and Permissions control, and OLTF@Title, which contains the name of the application provided by the user.

Global Section in Template.ini

In addition to specifying the replacement strings in the global section of Template.ini, you need to specify the path to the Administration folder (if you have one) and whether to display the Internet Explorer navigation bars so that you can move backward and forward between Web pages in your folder home page. The navigation bar setting, ShowNavBar, is helpful only if you use the Team Folders built-in templates or if you implement the functionality that turns on and shuts off the navigation bar (the same functionality that the Team Folders templates implement in your application).

The AdminFolder key takes the full path, relative to your application's root folder, to the Administration folder in your .pst file. For example, if your folder is located directly under the root folder in the .pst file, the value for this key will be "Administration\".

HTMLFiles Section in Template.ini

The HTMLFiles section in Template.ini specifies the HTML files that are included in your application. This section also specifies on which files to perform search and replace actions for your global replacement strings.

Folders Section in Template.ini

The Folders section contains the mappings between your Outlook folders and their corresponding folder home page HTML files. The format for each mapping is keynum=foldername; pagename; path where keynum is any unique integer; foldername, which is the folder name; pagename, which is the HTML file to associate with the folder; and path, which is the path, relative to the root application folder, to the folder. Note that if the folder is the root folder, you need to place root for the path. Also, you should not include the name of the folder when you specify the path. For example, if you wanted to associate the default.htm HTML file to a folder called My Application under your application's root folder, the Folders section of Template.ini would look like this:

[Folders] 1=My application,default.htm,\

FormClassAssignment Section in Template.ini

I recommend that you don't use the FormClassAssignment section of the Template.ini file. This section publishes a unique message class for your form when the form is deployed to a folder. This is important because the Outlook forms cache doesn't work correctly when multiple forms with the same name are published and used from different folders. Instead of using this section of the Template.ini file, give your forms unique names to prevent them from clashing with forms in other applications on your user's system.

Strings Section in Template.ini

The Strings section contains strings that you want to localize throughout the Template.ini file. For example, if you wanted to localize the word Calendar into multiple languages, you could place the following key under this section:

[Strings] CalendarFolder = Calendar

Then, throughout Template.ini, you would use %CalendarFolder%. The Team Folders Wizard will replace all instances of %CalendarFolder% with the literal you specify in the Strings section before processing the Template.ini file.

File Folder Structure for Your Template

When creating the file folder for your template files, including the .pst file and Template.ini file, you need to lay out your folder correctly in order for the Team Folders Wizard to process it. You must place the Template.ini file and the .pst file at the root level of your folder, and you must place the HTML files for your folder home page in a folder named Web view.

Deploying Your Template

Once you've created your .pst file, folder home page files, and Template.ini file, you must deploy your template to the computers of the users who will create applications based on it. In addition to copying the actual files to the users' computers, you'll need to add certain settings to their registries so that the Team Folders Wizard can detect the new template.

To make the template available, you need to create a key under HKEY_CURRENT_USE\Software\Microsoft\Office\Outlook\Addins\Microsoft.OLTeam FolderWizard\1033. The number at the end of this path will vary depending on the language settings for the computer you're deploying to. In this case, 1033 indicates that the language is English. Under this key, you'll need to create a number of other keys:

• AppPath. This key specifies the path of the template in 8.3 format. If your template is located at C:\program files\microsoft office\template\myapp, you'll need to specify C:\progra~1\micros~1\templa~1\myapp.
• Description. This key contains a string value that describes your template to the users of the Team Folders Wizard. The wizard displays this string when a user clicks on the application in the wizard's interface.
• FriendlyName. This key contains a string value that the wizard displays in the list of applications available. The user can select this name in the list box of available templates.
• PSTAppRoot. This key contains a string value that specifies the path, relative to the root of your .pst file, to your template's root folder. If your template's root folder is the root of the .pst, this string is the name of the template's root folder. For example, if your template is named Accounts and is located beneath the root of your .pst, this value would be Accounts.
• PSTName. This key contains the name of the .pst file that contains your application. The Team Folders Wizard will dynamically try to mount this .pst file when users create your applications. This file must be in the folder specified by your AppPath key.
• PSTTitle. This key contains a string that specifies the name of the .pst file in the Outlook interface when the Team Folders Wizard mounts your .pst. Make sure that this name does not conflict with another folder root in your Outlook client.
• UseFinishScreen (optional). This keyword contains a DWORD value that specifies whether to show the final screen of the wizard after it deploys your application. If you do not create an Administration page for your application, set this value to 0 so that the wizard does not display an error when it finishes deploying your application.

You can also customize other keys for the Team Folders Wizard that will affect your application. The main keys for the Team Folders Wizard are located at HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\AddIns\Microsoft.OLTeam FolderWizard. Figure 9-4 in the section "Architecture of the Team Folders Wizard" shows these registry keys.

• DefaultTargetFolder. This key contains a string value that specifies the default Public Folder path to install your application. The user can accept this location in the wizard rather than having to browse for it. An example value for this key is \\Public Folders\All Public Folders\Applications\My Application.
• DefaultTargetURL. This key contains a string value that specifies the default address of a Web location for the folder home pages for your application. The wizard will display this address, and the user can accept it as the location from which to deploy the HTML pages.
• UseWelcomeScreen. This key contains a DWORD value that specifies whether to display the Welcome page to the Team Folders Wizard. If you specify a value of 1, the Welcome page will display; specifying a value of 0 will not display the Welcome page.
• CTLCodeBase. This key contains a string value that indicates the CodeBase location for the ActiveX controls, specifically the View control and the Permissions control, in Team Folders applications.

Example: Account Tracking Template

In order to show you how to build a custom template, I've taken the Account Tracking application and turned it into a Team Folders template. This sample template makes it easier for multiple groups in a corporation to deploy the Account Tracking application with its forms, views, and starter items intact. Figure 9-20 shows how you can add the Account Tracking application to the list of templates in the Team Folders Wizard.

Figure 9-20. The Account Tracking application as one of the Team Folders Wizard templates.

While modifying the Account Tracking application to make it part of the Team Folders Wizard, I added a number of new features to the application's folder home page, shown in Figure 9-21. First, the application detects the custom views contained in the folder so that you don't have to hard-code them into the application. Second, the application shows you how to use the Restriction property of the View control.

Figure 9-21. The new folder home page for the Account Tracking application.

The final and most interesting feature of the new folder home page is that it shows you how to detect whether the application has the default Outlook views enabled. A user or developer can specify that the application should not use the standard Outlook views. You need to detect whether the default Outlooks views are enabled in your applications so that you don't display them in your user interface. The application detects the setting for the default Outlook views by checking a property on one of its folders. The hexadecimal value for this property is &H36E1003. This property will return a value of 1 if the default Outlook views should not be displayed for the folder; if they should be displayed, either the property will return 0 or the field won't exist. The following code checks this property in the folder home page:

'Load the default views for this content type 'Make sure that the default views are enabled first, 'by checking a property on the folder On Error Resume Next If oFolder.Fields(&H36E10003).Value = 1 Then 'Default views should not be displayed! 'Do not attempt to add them Else 'Default views should be displayed 'Note: This sample adds only two of the default 'views for message folders 'You can use the CommandBars method to get the default Outlook 'views if you want If strContainerClass = "IPF.Note" Then AddtoSelect "Messages",oElement AddtoSelect "Messages with AutoPreview",oElement End If End If