» How to extend the user interface using templates » How to develop templates

# 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.

## See also:

- How to register a template with Eclipse

- Example template