How to develop templates

Templates form an important part of the drive to support automatic GUI generation of various user interface types as supported in Eclipse frame work. These templates are often referred as project templates, as they are used to support the creation of ready-made projects. For example, you can define a template to create a simple GUI based EXE application for a set of Build Configurations.

The project templates are simple XML files, which follow a structure or schema defined in the TemplateDescriptorSchema.xsd file. These templates define the inputs and processes required to create a project for a particular platform. Inputs define the type of inputs required such as, files, settings etc. The processes define what to do with those inputs to create a particular type of project.

The New Project wizard lists all the templates available based on the matching criteria defined by the templates. Once the user selects a template from the list, the Template Engine plug-in processes the selected template. The plug-in generates the subsequent wizard pages based on whether the template needs user input or not.

This document details the schema for writing project templates. The schema file TemplateDescriptorSchema.xsd, which defines the structure for the project templates, is part of org.eclipse.cdt.core plug-in.

The structure or schema for a project template is as follows:

<template
type="TemplateType"
version="Version"
supplier="Supplier"
revision="Revision"
author="Author"   
id="TemplateId"
label="Template label visible to the user"
description="A brief description of the template"
preview-icon="icon.gif">

<property-group
id="properyGroupId"
label="Property group label"
description="A simple description of the property group"
type=" Type of UIElement group"
branding-icon="icon.gif">
...
</property-group>

<process>
...
</process>

</template>

The root element for a project template is template, which provides the following properties or attributes to describe the template:

• type: Use this attribute to specify the template type. For a project template the type should be ProjTempl.

• version: Use this attribute to specify the major version

• supplier: Use this attribute to specify the name of the supplier who provided the template.

• revision: Use this attribute to specify the minor version number of the template.

• author: Use this attribute to specify the template author's name.

• id: Use this attribute to specify a unique name for the template.

• label: Use this attribute to specify a label for the template, which briefly describes the purpose of the template. For example, if you are defining a template for a Helloworld EXE application, the label can be "HelloWorld EXE Application".

• description: Use this attribute to provide a description for the template, which is displayed to users when they choose the template from the list of available templates.

  preview-icon: Use this attribute to specify a GIF or JPG file name to be used as a icon for the template. There are no constraints on the image, as this attribute is meant for future use.

The template element includes the following child elements:

• property-group: A property-group element represents a wizard page in the New Project wizard. It lists all the fields to be displayed to the user for input using the property element. For example, you could use this element to define all the input fields to be displayed in the Project Directories page of the New Project wizard. The id attribute of the property-group is used as the Eclipse Help system id (see org.eclipse.help.contexts). The containing plug-in of the context id is org.eclipse.cdt.ui.

• process: A process element defines the process of creating the project in the Eclipse workspace, based on the user input values. For example, if the user specifies "include" as the folder name for all the header files, the process of creating a folder by that name and copying all the header files to it is defined here.

property-group

As mentioned earlier, a property-group includes the property elements that specify all the input fields required for a wizard page. A property-group can include any number of property elements. The following attributes can be used to describe a property group:

• id: Use this attribute to specify a unique ID for the property group.

• label: Use this attribute to specify a name for the property group, which is displayed as a title of the wizard page generated by the Template Engine.

• description: Use this attribute to provide a short description of the property group, which is displayed below the wizard page title.

• type: This attribute is for future expansion. Currently, the only valid value is:

  • PAGES-ONLY: If you want all the properties to be listed in a simple page.

• branding-icon: Use this attribute to specify a GIF file name to be used as an icon for the property group.

property

The syntax for the property elements included by the property-group element is as follows:

<property
id="propertyId"
label="User visible label of the property"
description="A brief description of the property"
type="type of the property"
pattern="Regular expression of the expected property"
default="Default value of the property"
size="size"
mandatory="true|false"
hidden="true|false"
persist="true|false">

     <item
     value="value of the item"
     label="User visible label of the item"
     ...
     </item>
</property>

Here is a list of attributes of the property element:

• id: Use this attribute to specify a unique ID for the property.

• label: Use this attribute to specify a name for the property, which is displayed as a label in the wizard page next to the input field.

• description: Use this attribute to provide a short description of the property, which is displayed whenever the mouse hovers over the label.

• type: Use this attribute to specify the property type. The possible values for this attribute are:

  • input: If you want a text input box.

  • multiline: If you want a multiline input box.

  • select: If you want a drop-down combo box.

  • boolean: If you want an option button.

  • stringlist: If you want a list box.

  • speciallist: If you want a list box with buttons to add and delete items to it.

  • browse: If you want a browse button which opens a file (not directory) selection dialog

  • browsedir: If you want a browse button which opens a directory selection dialog

• pattern: Use this attribute to specify the input character pattern for the property using regular expressions. For more information on regular expression patterns, refer to Java API document for java.util.regex.Pattern.

• default: Use this attribute to specify a default value for the property.

• size: Use this attribute to specify the size of the property. Note that this attribute is relevant only if the property type is input or multiline.

• mandatory: Use this attribute to specify whether the property is mandatory or not. The value for this attribute can either be true or false.

• hidden: Use this attribute to specify whether the property is visible to the user or not. The value for this attribute can either be true or false.

• persist: Use this attribute to specify whether the property should persist its value or not. The value for this attribute can either be true or false.

If the property type is select or stringlist, you can include the item element to specify the items to be listed. There is no limitation on the number of items that can be listed. Here is the syntax for the item element:

<item
value="value of the item"
label="User visible label of the item"
</item>

Here is a list of attributes of the item element:

• label: Used to specify a label that is displayed to the user.

• value: Used to specify a unique value for the list item. This will be the value used in macro expansions.

process

The process element within the root element of a project template defines the processes to be followed to create a project, based on the inputs taken. Here is the syntax for this element:

<process type="org.eclipse.cdt.{core|managedbuilder.core}.<process type>">
    <simple name="name" value=""/>

    <complex name="name">
        ...
    </complex>

    <simple-array name="values">
        ...
    </simple-array>

    <complex-array name="name">
        ...
    </complex-array>

</process>

A process element defines a single process. A process is like a procedure with a set of parameters. In similar terms, the process element defines the procedure. You need to specify all the parameters expected by a process. In the project template, you need to specify arguments for the process matching their types and in the order specified.

You can specify the process type using the type attribute. For example, to add files to a project you can use org.eclipse.cdt.core.AddFiles as the process type.

A process element may include the following child elements:

• simple: A simple string parameter. In a project template, you need to specify a name for the parameter using the name attribute along with the corresponding value attribute.

  Here is an example showing the usage of this element:

  <simple name="name" value="value" />

• simple-array: A simple string array parameter. In the project template, you need to specify a name for the parameter using the name attribute along with the corresponding element children. You can have any number of element children per simple-array element with the corresponding value attribute.

  Here is an example showing the usage of this element:

  <simple-array name="values">
        <element value="value1" />
        <element value="value2" />
    </simple-array>

• complex: A complex parameter groups together any number of simple, simple-array and complex parameters. In the project template, you need to specify a name for the parameter using the name attribute along with the corresponding children elements.

  Here is an example showing the usage of this element:

  <complex name="name">
        <element>
            <simple name="name" value="value" />
   <simple-array name="values">
        <element value="value1" />
         <element value="value2" />
    </simple-array>
        </element>
    </complex>

• complex-array: A complex-array parameter. Each element of this parameter is of the type complex. In the project template, you need to specify a name for the parameter using the name attribute along with the corresponding element children. You can have any number of element children per complex-array element with the corresponding complex type arguments.

  Here is an example showing the usage of this element:

  <complex-array name="values">
            <element>
                <simple name="name1" value="value1" />
                <simple name="name2" value="value2" />
                <simple name="name3" value="value3" />
            </element>
            <element>
                <simple name="name4" value="value4" />
                <simple name="name5" value="value5" />
                <simple name="name6" value="value6" />
            </element>
    </complex-array>

Process types

A process type is a prototype of a process procedure. It defines the parameters required to complete a procedure. For example, to copy a file you need its source and destination information, which can be defined as parameters for the copy process.

The Template Engine plug-in provides a set of process types using the extension-point org.eclipse.cdt.core.templateProcessTypes. Using these process types you can describe a process in your template. For example, you can describe the copy process by providing the source and destination folder names.

The following is a list of process types provided by the Template Engine:

org.eclipse.cdt.managedbuilder.core.NewManagedProject: It defines all the parameters required for a new managed project and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• Name: You use this parameter to specify the name of the managed project. It is of type simple.

• projectType: You use this parameter to specify the type of the managed project. It is of type simple.

• location: You use this parameter to specify the location of the managed project. It is of type simple.

• targetType: You use this parameter to specify the type of the target binary. It is of type simple.

• configs: You use this parameter to specify the build configurations for the managed project. It is of type simple.

org.eclipse.cdt.core.Copy: It defines all the parameters required to copy files and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• files: You can use this parameter to list the files to be copied. It is of type complexArrary. Each file to be copied is represented by a baseType element, which contains the following simple types:

  • source: Use this to specify the source file location in the file system.

  • target: Use this to specify the target location for the file.

  • replaceable: Use this flag to specify whether the file should be replaced or not, if it is found in the target location.

org.eclipse.cdt.core.Append: It defines all the parameters required to append files to a project and provides the fully qualified name of the class, which processes these parameters. For more information about the parameters, refer to the Copy process type described above.

org.eclipse.cdt.core.AddFile: It defines all the parameters required to add a file to the project and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project to which the file should be copied. It is of simple type.

• file: Use this parameter to include information related to source, target and replaceable. It is of complex type. For more information about the parameters, refer to the Copy process type described above.

org.eclipse.cdt.core.AddFiles: It defines all the parameters required to add files to a project and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project to which the file should be copied. It is of simple type.

• files: Use this parameter to include information related to source, target and replaceable. It is of complexArray type. For more information about the parameters, refer to the Copy process type described above.

org.eclipse.cdt.core.CreateSourceFolder: It defines all the parameters required to create a folder for the source files in a project and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project to which the file should be copied. It is of simple type.

• path: Use this parameter to specify the path relative to the project folder, where the folder for the source files should be created. It is of simple type.

org.eclipse.cdt.core.AddLink: It defines all the parameters required to create a linked file and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project in which the linked file should be created. It is of simple type.

• filePath: Use this parameter to specify the path of the original file relative to the project folder. It is of simple type.

• targetPath: Use this parameter to specify the target location relative to the project folder, where a linked file to the original file should be created. It is of simple type.

org.eclipse.cdt.managedbuilder.core.CreateIncludeFolder: It defines all the parameters required to create a folder for the header files in a project and provides the fully qualified name of the class, which processes these parameters. For information about the parameters, refer to the CreateSourceFolder process type described above.

org.eclipse.cdt.managedbuilder.core.ExcludeResources: It defines all the parameters required to exclude resources from a CDT project and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project for which resources will be excluded. It is of simple type.

• configIdPattern: Use this parameter to specify a regular expression of java.util.regex.Pattern syntax for matching against project configuration ids. The resources that match any of the regular expressions given in the filePatterns argument will be excluded from all matching project configurations. It is of simple type.

• filePatterns: Use this parameter to specify a simple-array of java.util.regex.Pattern for matching against project resources to be excluded. The paths that will be matched against are workspace relative (include the project folder) and use forward slash as the file separator. That this argument is an array is purely to allow logically separate patterns to be given separately rather than as one big string. If any of the regular expressions matches then the resource in question will be excluded for the matching configuration(s). The resources that match any of the regular expressions given in the filePatterns argument will be excluded for all matching project configurations. It is of simple-array type.

• invertedConfigMatching: If this is set to "true" then the set of configurations for which resources matching any of the specified file patterns will be inverted. This enables you to specify which configurations the files should not be excluded for without having to know what other configurations may exist. It is of simple type.

org.eclipse.cdt.managedbuilder.core.SetMBSStringOptionValue: It defines all the parameters required to create a string option value and provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• projectName: Use this parameter to specify the name of the project for which the string option is created. It is of simple type.

• resourcePaths: Use this parameter to specify the path of the resources. It is of complexArray type. Each resource patth to be created is represented by a baseType element, which contains the following simple types:

  • id: Use this parameter to specify a unique ID for the resource path. It is of simple type.

  • value: Use this parameter to specify a value for the resource path. It is of simple type.

  • path: Use this parameter to specify the path of the resource. It is of simple type.

org.eclipse.cdt.managedbuilder.core.SetMBSStringListOptionValues: It defines all the parameters required to create a string list of option values and provides the fully qualified name of the class, which processes these parameters. The parameters required are similar to that of SetMBSStringOptionValue process type, only difference is that each resource path will have a list of option values. For information about the parameters, refer to the SetMBSStringOptionValue process type described above.

org.eclipse.cdt.managedbuilder.core.SetMBSBooleanOptionValue: It defines all the parameters required to create a boolean option value and provides the fully qualified name of the class, which processes these parameters. The parameters required are similar to that of SetMBSStringOptionValue process type, only difference is that this process type is used to create boolean option value. For information about the parameters, refer to the SetMBSStringOptionValue process type described above.

org.eclipse.cdt.managedbuilder.core.AppendToMBSStringOptionValue: It defines all the parameters required to append a string option value to an existing string option. It also provides the fully qualified name of the class, which processes these parameters. For information about the parameters, refer to the SetMBSStringOptionValue process type described above.

org.eclipse.cdt.managedbuilder.core.AppendToMBSStringListOptionValues: It defines all the parameters required to append a string list of option values to an existing string list of option value. It also provides the fully qualified name of the class, which processes these parameters. For information about the parameters, refer to the SetMBSStringListOptionValues process type described above.

org.eclipse.cdt.core.AppendCreate: It defines all the parameters required to append or create a file in a project. It also provides the fully qualified name of the class, which processes these parameters. For information about the parameters, refer to the AddFiles process type described above.

org.eclipse.cdt.core.CreateResourceIdentifier: It defines all the parameters required to append or create a resource identifier. It also provides the fully qualified name of the class, which processes these parameters.

Here is a list of parameters defined by this process type:

• valueName: Use this attribute to specify a name for the resource identifier. It is of simple type.

• appName: Use this attribute to specify application, which will be using this resource identifier. It is of simple type.

org.eclipse.cdt.managedbuilder.core.GenerateMakefileWithBuildDescription:

• projectName: Use this parameter to specify the name of the project for which a makefile will be generated from the current project build info. It is of simple type.

Once the project template has been written, register it with Eclipse to make it available for use. For more information on this, refer to How to register a template with Eclipse.

• How to register a template with Eclipse

• Example template