Creating Your Own Visual InterDev 6.0 Templates

August 1998

Microsoft Corporation

Summary: Shows how to create templates for HTML, ASP, and other text pages. Also shows how to use the Visual InterDev™ Template Wizard. Familiarity with Visual InterDev will help. (7 printed pages)

Introduction

Many developers need to create highly customized files that are used again and again, under a myriad of circumstances. With Microsoft Visual InterDev version 6.0, you can use custom templates and the Template Wizard to automate this process, giving you fine-tuned control over new files and folders.

This article covers the following basic scenarios that utilize templates, starting with a simple scenario and finishing with the highly customizable one.

Creating a Simple Template

The simplest of templates is merely a master file from which new copies are made. It can be an HTML document, ASP page, or any other text-based file. Because it takes time to create a well-designed page, the time you invest in templates pays off many times over.

To create a custom template:

  1. Create an .asp, .htm, or other text file.

  2. Move it to one of the Visual InterDev Templates directories. For example:
  3. Restart Visual InterDev

Now when you display the Add Item or New File dialog box, Visual InterDev will recognize the new template file and automatically display it.

Figure 1. Template appearing in Add Item dialog box

Note   If a theme and layout have been previously applied the Web project, the new .htm and .asp files that are created by a template take on the project's theme and layout.

Prompting Users for Input with the Template Wizard

Sometimes your users need a template that is more efficient—one that prompts them for input. For example, a prompt could ask a user for something as simple as a name or a department.

The Template Wizard supports this feature by utilizing replaceable parameters (RP). A replaceable parameter is a placeholder in the template that the Template Wizard recognizes as something that it needs to replace. As the wizard runs, it identifies each RP and prompts the user with a step for each RP.

An RP is specified in a template by the delimiters <%# and #%>. For example, to prompt your user with a question, place text between the delimiters, as follows:

<H3><B><%#What is the name of your branch?#%></B> Store Inventory</H3>

If the user responds with the input "Museum Hill", then the new file would contain this line:

<H3><B>Museum Hill</B> Store Inventory</H3>

Note   If you use the Visual InterDev editor in Source view when you are creating templates with RPs, the editor will interpret the delimiters as script elements. Therefore, the editor will display the text with color coding. The color coding can be ignored in this case.

To invoke the Template Wizard with replaceable parameters:

  1. Create a subdirectory in the Templates directory. For example, you could create a directory called "Orders":
    C:\Program Files\Microsoft Visual Studio\VintDev98\Templates\Orders
    
  2. Create a template that includes one or more replaceable parameters. Then move the template to the new directory. For example:
    C:\Program Files\Microsoft Visual Studio\VintDev98\Templates\Orders\Orders.asp
    
  3. Create a text file with a .vsz extension. This file invokes the Template Wizard and points it to a specific Templates directory.

    The .vsz file contains lines that use the following syntax:

    Line syntax Description
    VSWizard 6.0
    Identifies the wizard version. Required
    Wizard=VIWizard.CtemplatePageWizard
    Invokes the Template Wizard. Required
    Param=path to Templates subdirectory
    Identifies the new template subdirectory. Required
    Param=Filename
    Specifies the name of the file that Visual InterDev will open after the wizard has finished. Optional

    If you specify a file to open, the target file must contain an RP. If the file does not contain an RP, then the wizard will not open the file.


    Continuing with the "Orders" scenario, you could create the following file and save it as Orders.vsz.

    VSWizard 6.0
    Wizard=VIWizard.CTemplatePageWizard
    Param=c:\Program Files\Microsoft Visual Studio\Vintdev98\Templates\Orders
    Param=Orders1.asp
    

    Tip   Copy an existing .vsz file and modify it to create your custom version.

  4. Move the .vsz file to the Web Project Items or NewFileItems directory. For example:
    C:\Program Files\Microsoft Visual Studio\VintDev98\Templates\Web Project Items\Orders.vsz

  5. Restart Visual InterDev.

When the user selects the Orders icon in the Add Item or New File dialog box, Visual InterDev invokes the Template Wizard, which recognizes the replaceable parameters. The wizard displays a prompt and the user types in an answer.

Figure 2. Template Wizard prompting user for input

Creating Directories and Multiple Files with the Template Wizard

If you are a developer who has created numerous Web sites that use the same basic files and directory structure, the Template Wizard can save you a lot of time propagating that structure.

To replicate a particular directory and file structure, just create and organize all the files and directories within your Templates subdirectory. You can include any file type. For example:

Because the .vsz file identifies the specific directory under Templates, the wizard automatically reproduces a whole new set of files and directories and adds them to the user's project.

When the wizard is run, it gives the user the opportunity to change the names and locations of files, or accept the default.

Figure 3. Template Wizard allowing file name changes

Manipulating the Wizard with a .vsdir File

You can create a .vsdir file to control how .vsz files are accessed. A .vsdir file is a text file that provides information to the Add Item and New Project dialog boxes. The .vsdir defines such things as names, descriptions, and which icon to display.

A .vsdir file contains a single line, or record, for each template. The parameters, or fields, are separated by a pipe ( | ) character. Any nonrequired parameter for which there is no meaningful data should contain a zero ( 0 ) as a placeholder. The following line specifies parameters that can be specified for a given record:

RelPathName|{clsidPackage}|LocalizedName|SortPriority|Description|{clsidPackage}|IconResourceId|Flags|SuggestedBaseName

Parameter Meaning
RelPathName Name of the .vsz file for the wizard.
{clsidPackage} Optional GUID representing a product (for example, Microsoft Visual J++) that has a DLL containing localized resources.
LocalizedName Optional name of the wizard as it will appear in the Add Item dialog—can be a string or a resource identifier of the form "#ResID".
SortPriority An integer representing the relative priority of the wizard, with 1 being highest. Determines the sort order of items.1
Description Description of the template or wizard as it will appear in the Add Item dialog box—can be a string or a resource identifier of the form: "#ResID".
DLLPath or {clsidPackage} Used to load an icon for the wizard from a .dll or .exe file. Specify either the full path to the .dll or .exe, or a GUID of a product that has a .dll file containing resources.
IconResourceId Optional resource identifier within the .dll file that determines the icon to display. If no icon is defined, the shell substitutes the default icon for a file with the same extension as the item.
Flags Specifies whether the Name field in the Add Item dialog box is enabled or disabled. Flags can have the following values:
   Space (" "): enable file name
   8192:         disable file name

If you are using the Template Wizard to create more than one file, it is a good idea to set the value to 8192. The file names will be controlled by wizard, not the Add Item dialog box.

SuggestedBaseName The default name for the wizard—either a string or a resource identifier of the form: "#ResID". If necessary, the shell appends the base value with an integer to make the name unique. For example, the shell might change MyFile.asp to MyFile1.asp.

This default name is shown in the Name field in the dialog box.

SuggestedBaseName is ignored if Flags is set to 8192.


1 The sort order for the standard Visual InterDev icons that appear in the Web Project Items directory are specified in NewWebItems.vsdir as:

File icon

Sort order

New HTML Page.htm

10

New ASP Page.asp

20

New Style Sheet.css

30

New Site diagram.wdm

40


Therefore, to place the icon for your template as the third icon, you could assign it a value of 25.

To call on a .vsdir file:

  1. Create a text file that contains one line for each .vsz file. After the final line, add exactly one additional carriage return.

    Warning   If you do not end the file with exactly one additional carriage return, Visual InterDev will fail when it invokes the Add Item dialog box.

  2. Save the file with a .vsdir extension and move it to the appropriate Templates subdirectory (for example, the Web Project Items directory).

  3. Restart Visual InterDev.

You can have multiple .vsdir files in a single directory; however, it is a good idea to maintain a single .vsdir file that contains a line for each of your custom templates.

To avoid complications, do not alter the standard Visual InterDev .vsdir files: NewWebItems.vsdir, NewFileItems.vsdir, and NewWebProjects.vsdir.

An easy way to create a customized .vsdir file is to copy an existing .vsdir file and modify it. Note that you can use same value for clsidPackage that is used by other Visual InterDev files: 164B10B9-B200-11D0-8C61-00A0C91E29D5. Using that value allows you to then set the value for IconResourceId to 287 in order to display the Template Wizard's icon.

The following picture illustrates how the Add Item dialog box could be controlled when it calls on Orders.vsz.

Orders.vsz|{0}|Customer Orders|25|Create folder and files for the Customer Orders|{164B10B9-B200-11D0-8C61-00A0C91E29D5}|287|8192|Customer Orders

Figure 4. "Customer Orders" template controlled by a .vsdir file

Additional Resources

For additional and related information, see the following topics in the MSDN Library. You can access MSDN from Visual InterDev by clicking Contents on the Help menu.

Under the node,

Visual Studio Documentation / Visual Studio Development Environments / Visual InterDev/Visual J++ Environment / Environment Tasks

see the list of topics, including "Creating Custom Templates."

Under the node,

Visual Studio Documentation / Visual Studio Development Environments / Visual InterDev/Visual J++ Environment / Environment Extensibility

see the list of topics, including "Creating VSDIR files" and "Creating VSZ files."