The wizard will set the wizardType template variable when it executes,
so template code can check under which wizard type it is running (using <#if>..</#if>), and
execute accordingly. This feature allows the user to create templates that
can be used for multiple wizard types.
There are several types of wizards you can create. Each one has a different goal.
wizardType = project
Project wizards create new projects and let the user create files in them. It is possible to adjust project properties to customize the new project. You can add C++ support to the project, set source and NED folders, etc.
The first two pages of the wizard are standard: they prompt the user for the name of the new project and let the user choose a content template. These pages are followed by pages provided by the selected content template. If the user selected C++ support on the first page, custom pages are followed by the standard CDT New Project pages.
When the user clicks Finish, the wizard creates the project and configures
it according to the selected options (C++ support, source folders, etc.). Then,
template files are copied into the new project, performing template processing
as necessary. Templated pages are responsible for creating the package.ned
file according to the nedPackageName and namespaceName options, as well
as creating source files in the NED and C++ source folders.
NED and C++ files are not automatically placed into the
NED and C++ source folders. Templated pages have to be written
(for example using setoutput) so that they explicitly create the files
in the proper places.
There are a few useful variables that template files use. The
rawProjectName variable contains the project name. This variable cannot be
directly used as C++ or NED package names, type names, etc, because it may
contain spaces or other characters not allowed in identifiers. For convenience,
the wizard provides sanitized versions of the project name that can be used
as identifiers; they are in the variables projectName, PROJECTNAME and
projectname, and differ in capitalization. The targetFolder variable
is set to /<project name>. These variables cannot be edited in custom wizard
pages.
The variables addProjectReference, makemakeOptions, sourceFolders and
nedSourceFolders affect the creation of the project before template files
get processed. It is allowable to provide an initialization value for these
variables in template.properties and to let the user change them in
custom pages.
For conformance with other wizards, the project wizard initializes
the following variables with different case versions of the project name:
targetTypeName, nedPackageName, and namespaceName. The targetMainFile
variable is initialized to projectName+.ned, but there is no requirement
for the template to actually create this file. It can provide a
different initialization value for these variables in template.properties
and can let the user change them in custom pages.
If the new project contains a simulation, it is recommended that targetTypeName
and targetMainFile are used as the network name and NED file name respectively.
The targetFileName variable is not set because the project wizard
is not required to create a file.
See the appendix for the variable names that are supported in project wizard templates.
wizardType = simulation
A new simulation is basically a new folder containing all files required to run a simulation. The simulation folder usually contains NED files, an INI file, and possibly also CC, H and MSG files.
The first two pages of the wizard are standard; they prompt the user for the parent and name of the new folder, and let the user choose a content template. These pages are followed by pages provided by the selected content template. Simulations can only be created in new folders under existing projects or folders.
When the user clicks Finish, the wizard creates the folder. The template files are then copied into the new folder, performing template processing as necessary.
There are a few useful variables that template files can use. The
simulationFolderName contains the name of the new folder (without path).
This variable cannot be directly used as a C++ or NED identifier, because it may
contain spaces or other characters not allowed in identifiers. For convenience,
the wizard provides the simulationName variable which is a sanitized version
of the folder name. The targetFolder variable is set to the workspace path of the new
folder. These variables cannot be edited in custom wizard pages.
For conformance with other wizards, the simulation wizard initializes
the targetTypeName variable with the simulation name. The targetMainFile
variable is initialized to simulationName+.ned, but there is no requirement
that the template actually creates this file. It can provide a
different initialization value for these variables in template.properties
and can let the user change them in custom pages.
The intended purpose of targetTypeName and targetMainFile is to be used
as the network name and NED file name respectively in the new simulation.
The targetFileName variable is not set because the simulation wizard
is not required to create a file.
The nedPackageName and namespaceName variables are set by the wizard to the
NED package name and C++ namespace expected for the given folder. These values
are derived from the folder path, the toplevel package.ned file and the
@namespace property in it, and cannot be overridden.
See the appendix for the variable names that are supported in simulation wizard templates.
wizardType = compoundmodule, network, nedfile, inifile, msgfile
These wizard types generate a single file. The first two pages of the wizard are standard; they prompt the user for the parent folder and name of the new file, and let the user choose a content template. These pages are followed by pages provided by the selected content template.
Currently the wizard does not ensure that the created file will be under a NED/C++ source folder. This may change in the future.
When the user clicks Finish, template files are copied into the selected parent folder, performing template processing as necessary. The template files are expected to create a file with the name chosen by the user.
The wizard passes the file name to the template files in the targetFileName
variable.
The wizard does not prevent the templates from creating other files than
targetFileName. It is the responsibility of the template author to
ensure that only a single file is created.
There are a few useful variables that template files can use. The
targetFolder variable is set to the workspace path of the parent
folder. This variable cannot be edited in custom wizard pages.
For conformance with other wizards, the new wizard initializes the
targetTypeName variable to a sanitized version of the file name (minus
extension). This variable can be used as a NED or message type name
in the generated file. The targetMainFile variable is the same as
targetFileName.
One can provide a different initialization value for the targetTypeName
variable in template.properties and let the user change it in custom pages.
The nedPackageName and namespaceName variables are set by the wizard to the
NED package name and C++ namespace expected for the given folder. These values
are derived from the file path, the toplevel package.ned file and the
@namespace property in it, and cannot be overridden.
See the appendix for the variable names that are supported in new file wizard templates.
wizardType = simplemodule
The simple module wizard creates a simple module, usually consisting of a NED file and C++ implementation files. This wizard works in a similar way as the New NED File or New Compound Module wizard, but it is allowed to create other files (C++ sources) in addition to the NED file.
wizardType = import
An import wizard is not a standalone type, but rather a flag on other wizard types. It makes the wizard appear in the File|Import… dialog in addition to the File|New … dialogs.
To access the import wizards, choose OMNeT++, Networks, simulations and other items as import source on the first page of the Import dialog. The next page will be the content template selection page. After choosing a template, the next page will be the file, folder or project name selection page of the New… wizard, followed by the custom wizard pages.
If an import wizard supports more than one wizard types (e.g. project, simulation,
nedfile, etc.), the File|Import… dialog will use only one of those types. The type
is chosen in the following order of preference: network, nedfile, compoundmodule,
simplemodule, msgfile, inifile, simulation, and project. This may be changed
in the future to explicit wizard type selection.
wizardType = export
Export wizards can be accessed via the File|Export… dialog and export data into one or more files in the workspace or in the file system.
To access the export wizards, choose OMNeT++, Networks, simulations and other items as export destination on the first page of the Export dialog. The next page will be the content template selection page, followed by the custom wizard pages.
Export wizards do not have a standard file/folder selection page, the target file name(s) must be obtained from the user on custom wizard pages.
You can use the SaveAsChooser and ExternalSaveAsChooser custom controls
to prompt for a file name in the workspace and in the file system respectively.
The export wizard does not set targetFileName, targetMainFile, or any similar
variables. It is entirely up to the template author to define a variable for storing the
output file name, letting the user edit it, and saving the content in that file.
Template files are not allowed to produce any output; they are supposed to create the target files programmatically.
Templates can use static methods of the FileUtils class, such as
createFile(workspacepath, content) and createExternalFile(filesystempath, content),
to create the files. Here, content is a string that holds the text to be written
out into the file in the platform’s default encoding.
The content text may be assembled using plain string concatenation
(<#assign content = content + "\nsome text">), or templated content
(<#assign content>some text, ${foo} and ${bar}...</#assign>).
wizardType = wizard
A New Wizard wizard creates a wizard under the templates/ folder of a workspace
project.
The first two pages of the wizard are standard. They prompt the user to select
the project that will hold the wizard, choose the wizard name (name of the new folder under
templates/), and pick a content template. These pages are
followed by pages provided by the selected content template.
When the user clicks Finish, the wizard creates the folder under the
templates/ folder of the chosen project. After that, template files are copied
into the new folder, performing template processing as necessary.
There are a few useful variables that template files can use. The
newWizardName variable contains the name of the new folder (without path),
and newWizardProject contains the name of the project. The project name variables
(rawProjectName, projectName, PROJECTNAME, etc.) and targetFolder
variables are also set. These variables cannot be edited in custom wizard pages.
The wizard does not set the targetFileName and targetMainFile variables.
See the appendix for the variable names that are supported in New Wizard wizard templates.
To create a template.properties file for the new wizard, use a
template.properties.ftl file in the wizard wizard. Similarly, you will
likely have files with the .xswt.ftl and .ftl.ftl extensions in the
wizard wizard. Inside .ftl.ftl files, use the <#noparse>..</#noparse>
directive to protect parts that you want to be copied verbatim into the
created wizards.