Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

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.

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:

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:

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:

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: