1. ABOUT THIS DOCUMENT
+ +This document describes how to create a wizard template for Carbide.c++.
+ +This document describes the wizardTemplate extension, the xml template format and post-wizard processing model. Some familiarity with XML, Eclipse plugins and extensions and, for custom process creation, the Java programming language, is assumed. This document will not cover instruction in these areas.
+2. Introduction
+Wizards collect data from users and automate tasks. They tend to be UI intensive and can be difficult and tedious to create. For this reason, Carbide.c++ supports wizards generated from xml descriptions. Specifically, Carbide.c++ exposes two such wizards, one for creating projects and one for adding class files to an existing project.
+Carbide.c++ exposes the com.nokia.carbide.templatewizard.wizardTemplate extension point for this purpose. Using this extension point allows you to create a plug-in where you can add as many custom templates as necessary to support your development efforts.
+· Wizard Template extension: an Eclipse extension in a plugin extending the com.nokia.carbide.templatewizard.wizardTemplate extension point.
+++NOTE Do not add custom templates to the default Carbide.c++ plug-in as updates will overwrite your changes.
+
· Extension element: a child element in an Eclipse extension. In the current document, the only extension element is the <template> extension element. This is one of the <template> elements declared in the wizard template extension. Each template extension element defines the specific characteristics of one wizard configuration. A plugin may define more than one wizard template extension, and each extension can have more than one template extension element.
+· Template xml file: an xml file referenced by a template extension element, which describes some number of wizard pages and post-wizard processes in xml.
+· Elements in a template xml file: As the template file is also in xml, it is also made up of elements and child elements. Much of the document will be devoted to explaining the significance of these elements.
+3. The Wizard Template Extension Point
+Starting with a new Plug-in Project created to house your templates (using File > New > Project... > Plug-in Project), here is an example of a wizard template extension with a single template element that should be added to the plugin.xml file:
+ ++<extension point="com.nokia.carbide.templatewizard.wizardTemplate"> + <template + templateId="com.nokia.cdt.templates.s60.controlapplication" + location="templates/projecttemplates/S60-ControlApplication/template.xml" + wizardId="com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppProjectWizard" + groupLabel="S60" + filterArguments="S60:1.2;2.0-2.9" + image="icons/icon_S60.png" + /> +</extension> ++ +
The template wizard extension point has the identifier: com.nokia.carbide.templatewizard.wizardTemplate.
+Extensions of the template wizard extension point must specify the following required attributes:
+1. templateId: the unique identifier for this template
+2. location: the plugin-relative path to the template xml file
+3. wizardId: the id of the wizard in which this template is used
+The two template wizards provided by Carbide.c++ are:
+++a. The Symbian OS C++ project wizard with wizard id: com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppProjectWizard
+b. The Symbian OS C++ class wizard with wizard id: com.nokia.carbide.cpp.project.ui.wizards.NewSymbianOSCppClassWizard
+
4. groupLabel: the group label under which this template will appear in the template choice page of the appropriate template wizard
+Groups are created from group labels that are available from the filtered or unfiltered list of templates for a specific wizard. Anyone creating new templates is free to use an existing group label, or create a new one as needed.
+NOTE The groupLabel attribute, as with all attributes in the plugin.xml, can be localized simply by using a % -prefixed key and a standard Java properties file.
+For example, the attribute in the template extension element could use the key “S60.label” prefixed with a % character:
+groupLabel="%S60.label"
+The plugin.properties file in the same directory as the plugin.xml would contain the entry:
+S60.label=S60
+Additionally, extensions can specify the following optional attributes:
+5. filterArguments: the optional wizard-specific data which is available to the filtering mechanism activated by the “filter templates” checkbox, which is optionally shown in some template wizards; no filter arguments signifies to always show this template
+The filter is provided by the wizard and the argument for the filter is specified optionally by each template, in order to work with its intended wizard (see wizardId attribute).
+Both the Symbian OS C++ project and class wizards filter templates against Symbian Sdks. Both wizards require the filter arguments to be of the form: [sdk family][:sdk versions]. Sdk family is either S60, S80, UIQ or TechView. Sdk versions can be lists of versions separated by semicolon and/or ranges separated by hyphens. Here are some examples of valid filter argument attributes:
+++· S60:1.2;2.0-2.9 allows all S60 sdks version 1.2 and 2nd edition.
+· S60:3.0-3.9 allows all S60 3rd edition sdks.
+· S80 allows all Series 80 sdks.
+
6. image: the optional plugin-relative location of a 16x16 pixel image file to be used when showing this template in the choose template wizard selection page
+7. extraPagesProvider: an optional provider of extra wizard pages
+This class must have a 0-argument public constructor and must implement the com.nokia.carbide.templatewizard.ui.IExtraPagesProvider interface (see javadoc). The class is only constructed once per template per Eclipse session. However, it will be initialized and used as many times as the template is chosen by the users.
+4. The Template XML Format
+This is an example template element with a description:
+ ++<template + version="1.0" + label="S60 2.x Control based GUI application"> + <description>A S60 Control is a rectangular area of the screen that \ +may respond to user input and events. You can use this template for all S60 2.x and 1.2 SDKs. +... + </template> ++ +
The template xml file has one required top-level element, the template element.
+The template element has these required attributes:
+The template element has an optional description child element whose text content is used in the description area of the choose template wizard selection page. When a specific template is selected, its description is displayed.
+NOTE The description strings are elements and not attributes, in order to allow return characters to be easily specified for formatting purposes. Descriptions may be broken for readability without specifying a return character in the actual description by terminating a line with a backslash. All description strings in the template xml format use this pattern.
+ADDITIONAL NOTE: All label attributes and description elements in the template xml format are localizable using the %-prefixed key method described above for plugin.xml files. In the case of localization, the label attribute’s value and/or description element’s content consists of a %-prefixed key instead of the actual value, and a properties file for the template xml exists in the same directory as the template xml file containing the localized strings for these keys.
+The template element can have any number of children of type wizardPage elements and process elements.
+This is an example of a wizardPage element:
+ ++<wizardPage + id="basics" + label="Basic Settings" + <description>Basic properties of a project + <textField + id="Author:" + label="myLabel" + persist="true" + <description>Name of the author</description> + </textField> + <textField + id="copyright" + label="Copyright notice:" + multiline="true" + default="Your copyright notice" + persist="true" + <description>Your copyright notice + </textField> + <uidField + id="uid3" + label="Application UID:" + min="0x00000001" + max="0x01ffffff" + mandatory="true" + persist="true" + <description>The Application UID is the project identifier</description> + </uidField> + <filenameField + id="groupDir" + label="Group:" + default="group" + mandatory="true" + persist="true" + <description>The directory for project files</description> + </filenameField> + </wizardPage> ++ +
Each wizardPage element declaratively specifies one page in the wizard. The child ordering of wizardPage elements in the template element is the order that the pages will appear.
+NOTE Ordering is important and is a common theme in the template xml format. This is true of wizard pages, ui elements within a wizard page, as well as processes. The order is preserved in the context in which child elements are defined.
+The wizardPage element has these required attributes:
+The wizardPage element has an optional description child element whose text content is used as the description of the wizard page – just below the title. This element behaves like all description elements in the template xml format (see above).
+The wizardPage element can have any number of children elements of type textField, uidField or filenameField. These represent user input fields in a wizard page, and although any number can be specified, in practice, only a reasonable number should exist on a given wizard page. The fields are laid out one below the other in the child order in which they are declared in the wizardPage element.
+All field elements have these required attributes:
+All field elements have an optional description child element whose text content is used as the tooltip text for the field, which behaves like all description elements in the template xml format (see above).
+Additionally, fields have these optional attributes:
+In addition to these attributes, each field type has its own additional attributes.
+The textField element specifies a text field that can be validated by a regular expression pattern and that can be specified to be single or multiple lines.
+The textField element has these optional attributes:
+The uidField element specifies a text field that must contain a hexadecimal number in the range of a Java long, beginning with the prefix 0x (e.g., 0x0). The uid field has a button to the right labeled “random” that changes the current value of the field to a random value within a specified range. The specified range is also used to validate values input by the user.
+NOTE: Each uid field adds 2 values to the template for use by processes. The one indexed by the id of the uid field is exactly what is shown in the field, and the other indexed by the id with the suffix -WITHOUT_0X, is the value without the 0x prefix.
+The uidField element has these required attributes:
+The filenameField element specifies a text field that is validated to be a valid OS file name composed of only alpha-numeric, hyphen or underscore characters. The additional restrictions exist to avoid path problems with build tools.
+The filenameField element has the optional attribute:
+This is an example of a process element with a single parameter child:
+ ++<process + class="com.nokia.carbide.cpp.project.core.processes.NewProject" + bundle="com.nokia.carbide.cpp.project.core" + <parameter + name="project" + projectName="$(projectName)" +</process> ++ +
The process elements, like those for wizard pages, are declared in the template xml file as children elements of the template element. Each process element declares the execution of the process method of a class implementing the interface com.nokia.carbide.templatewizard.process.IProcess after the user finishes running a template wizard.
+Execution of processes occurs in the order in which the process elements appear in the template xml file, so it is fully acceptable that some processes will be dependent on the successful execution of previous processes. Failure in the execution of any processes is reported to the user and logged to the error log, but remaining processes are executed.
+The process element has these required attributes:
+This class should have a 0-argument public constructor. An instance of this class will be created and its process method will be called for each process element appearing in the template xml file.
+To assist implementation of the process class, an abstract base class is provided. com.nokia.carbide.templatewizard.process.AbstractProcess has members that encapsulate initialization, failure with CoreException and accessing process parameters.
+See javadoc for class details.
+The process element has any number of children elements of type parameter.
+The parameter element has the required attribute:
+In addition, parameter elements can have any additional attributes required by the process. These will be accessible via the com.nokia.carbide.templatewizard.process.IParameter interface list provided to processes (see javadoc).
+Values collected from the user by the wizard are available to processes via the com.nokia.carbide.template.engine.ITemplate interface provided to processes (see attached javadoc). The method getTemplateValues returns a java.util.Map<String, Object> containing the values indexed by the field ids specified in the field element children of wizardPage elements, as well as values from built in pages.
+The template’s map can also be used to communicate state between processes. For example, one process may add a value to the map which is then read by a subsequent process.
+These are the built in page value ids:
+Additionally, values from the template map are substituted into the parameter attributes specified in the template xml, whenever the attributes contain the pattern $(id) in the value.
+There are a number of built in processes, provided by Carbide.c++
+1. New Project:
+++Requires one parameter with name project, attribute projectName.
+Creates a new Carbide.c++ project.
+
2. Create Folders:
+++Requires one parameter with name project, attribute projectName.
+Any number of parameters with name folder, attribute path.
+Creates new folders in a project.
+
3. Create 4 character resource ID:
+++Requires one parameter with name project, attribute projectName.
+Creates a 4 character string based on the project name, which is used in the main resource file in the NAME statement.
+
4. Copy Files:
+Requires one parameter with name project, attribute projectName.
+Any number of parameters with name file, attributes sourcePath and targetPath and optionally, the boolean attribute substitute, which says whether this file is parameterized and needs to be substituted (defaults to “true”).
+Copies files from the sourcePath (relative to the location of the template xml file) to the targetPath (relative to the project) and optionally substitutes variables using the $(id) pattern. Unrecognized variables are left intact.
+Optionally, any of three operators can be used to automatically uppercase, lowercase and titlecase (uppercase only the first character) the value prior to substitution. The syntax for using the operators is $(id$upper), $(id$lower) or $(id$title).
+5. Project Initialization:
+Requires one parameter with name project, attributes projectName, bldInfPath and targetMMPFileName.
+Initializes Symbian OS c++ projects with build configurations and other required project data, and tries to expand the project tree in the Project Explorer view.
+5. Conclusion
+The wizard template extension, along with template xml files and other associated data files provides a rich environment for creating customized project and class wizards declaratively. New project and class wizards for Symbian OS can be created easily and with little or no programming.
+