# New Project Wizard format

The new project wizard has been rewritten for Anjuta 2. It is a generic plugin able to create different kind of projects. The files needed by each project and the associated graphical interface used to get user choices are defined in a text file read by the plugin. This documentation will described the format of this file which is called a template.

## Overview

The template files look like xml documents and have normally the extension `.wiz`. All templates and others related files are installed by default in `$anjuta_install_dir/share/anjuta/templates`. But the project wizard looks for templates in the sub directory `anjuta/templates` of all user data directories as defined by XDG Base Directory Specification too. It is possible to override a Anjuta project template by an user one put, by example, in `~/.local/share/anjuta/templates`.

The template file is divided in four parts: an header block, one or more page blocks, a content block and an optional action block. The file is read several times, one time for each block but before reading it, the whole file go though a transformation pass and only the resulting file must be a valid xml file. The transformation pass use autogen.

Autogen is a quite complete text transformation program, it is able to make string substitutions, conditionally generate text, include files and it can even be extended with the guile language. Autogen takes as input a template file which is the wizard template file and some definitions which are generated at run time according to the user choices. Note that the first line of an autogen template need to have special format not compatible with an xml file, so this line is added at run time when needed. It defines the start and end macros marker of autogen which is fixed and defined as "[+" and "+]" in the wizard template.

All blocks on the project wizard are included in a project-template block. This is needed because a valid XML file should have a single root block. This block was not used in older version of the format, so it is optional to keep backward compatibility.

The header block is the only exception, it is read directly from the template file and do not use autogen. It must be the first block and must be valid a xml block, that's why the first line of the template could not contains the autogen special line. The parsing is stopped when the end of this block is reached, so we do not care for the remaining of the file. This block contains informations about the project kind like a name and a short description.

The page blocks are read one by one after being transformed by autogen, they define some properties of the project which could be changed by the user, things like project name or use of a particular library. The graphical interface is created at run time according to these properties. Each page is generated when the user has completed all previous pages. You can ask the user for something on one page and his answers become available as autogen variables for generating the next page. You can, by example, skip a complete page for configuring a CVS reposit, if the user has decided to not use it. In case you insert or remove a complete page you need to take care to not do it before one already displayed.

When all pages have been displayed. The program will read the content block which defined all files and directories needed by the project. This block goes through autogen so you can use this to adjust file names and paths. Typically, at least creating a project file with the name given by the user. Note that the project files itself are transformed with autogen if needed.

Finally, if it exist the action block is read and the corresponding commands are executed in their order of apparition. Typically, it is useful for loading in Anjuta the newly created project.

## Wizard header

Here is all the xml element used in the header block. As this block is read directly from the file, it can not contains autogen variables.

project-wizard

    <project-wizard>
    	<_name>
    	<_description>
    	<icon>
    	<category>
    </project-wizard>

It represents the header block, and contains all other elements.

name

    <_name>
    	text
    </_name>

text is the name of the project, its name start with a underscore to mark a translatable element.

description

    <_description>
    	text
    </_description>

text gives a short description of the project, it appears when the project is selection. It's a translatable element too which explains the underscore.

icon

    <_icon>
    	filename
    </_icon>

filename is the name of the file containing a icon for the project, it must be in the same directory than the project template file. The picture must be of 48 by 48 pixels in png format.

category

    <_category>
    	text
    </_category>

text is a category name. It is a way to group related project, it is typically the programming language name, like C or C++.

order

    <_order>
    	number
    </_order>

number is used to order project in the project selection view. If this element is not specified order is equal to 0. In this case, the projects are added at the end ordered according to their names.

## Wizard pages

This block defines all properties use by the project and the corresponding graphical interface. These properties are grouped in pages. Each page is read and transform with autogen one by one taking in account the value of all properties already defined in previous pages. This allows you to generate pages according to the user inputs on the previous one.

page

    <page name=name _label=label _description=description >
    	<property>
    	...
    </page>

It represents one page block and contains a set of properties.

name is the name of the page, currently unused.

label is the title of the page, it is a translatable attribute.

description is a translatable sub title for the project page.

property

    <property type=hidden|boolean|integer|string|list|directory|file|icon|package
    	name = name _label=label [_description=description] [default=default]
    	[mandatory=yes|no] [exist=yes|no] [summary=yes|no] >
    	[<item>]
    	...
    </property>

This is one of the most important element. A property correspond to an entry widget to get the user choice and a variable in the autogen definition file used to control the generation of the project.

The type attribute define the kind of property. The following types are defined

hidden

- This is the only property that does not correspond to any widget. This is useful to defined additional autogen variables using only name and default attributes. As this value cannot be changed by the user the default attribute defined the value of the property.

boolean

- This correspond to a boolean variable. It is represented by a toggle button. The value is 1 if the user select Yes, and 0 if the user select No.

integer

- This correspond to a integer number. It is represented by a spin button. The value is the corresponding number.

string

- This is a string value represented by an entry box. The value is the text of this entry box.

list

- This property takes its value in a list of values and is represented by a list box. All the values are defined with child item element defined below. The value of the property is defined by the name attribute of the corresponding item.

directory

- This property get a directory selected by the user. The directory could be inexistent, see the exist attribute for more information. It looks like a string property with a Browse button.

file

- This property get a file selected by the user. It is very similar to the directory property.

icon

- This property is quite similar to the file property and allow you to select an icon. The property value will be the name of the file containing the icon.

package

- This property is similar to the file property and allow you to select a pkg-config package. It displays an entry box, that you can fill directly, with a button allowing to display all installed packages and select one. The property value will be the name of the package.

name is the name of the autogen variable corresponding to this property.

label is a translatable label that appears near the entry widget.

description is a translatable description that appears as a tips of the entry widget.

default is the default value of the property. If none is specified the property is empty.

minimum is the minimum value for an integer property. If none is specified the minimum value is 0.

maximum is the maximum value for an integer property. If none is specified the maximum value is 10000.

step is the increment step when clicking on the arrow buttons or using the cursor key, you can always write another value in the allowed range. If none is specified the value is incremented or decremented by 1.

mandatory allow you to define if an empty value is acceptable, by default it is allowed. If you set it to yes and the user does not enter a value, he will get an error message and cannot go further.

exist allow to check if a file or a directory corresponding to the value of the property exist. If exist is set to no, a warning message is displayed if the file or the directory exist. Moreover the value of the default property is tested and a number is automatically added at the end to avoid the warning message if necessary. By default or if exist is set to yes, no check is made.

summary defined if the property and its value should appears at the end of the wizard. This happens if the attribute is set to yes, by default or if it is set to no the property is not displayed.

item

    <item _name=name [_label=label] />

This element is used to defined item of a list property.

name is the name of the item, the property variable will be set with this value if the item is selected.

label is an optional translatable name for this item. This label will be used translated in the graphical interface, typically a list box. If it does not exist the value of the name attribute is used.

## Wizard content

This block defines all files and directories used by the project.

content

    <content>
    	<directory>
    	...
    </content>

It represents the content block and contains any number of directory elements.

directory

    <directory source=source_name [destination=destination_name] >
    	<directory>
    	...
    	<file>
    	...
    </directory>

This element will define the source and destination directory for included files and directories. By default the source directory is the directory of the wizard template file, the destination directory is the current directory. You can put "." instead of a directory name to stay in the current directory. It is useful if you want to change the destination directory but not the source or the reverse. If you specify only the source directory, the destination will use the same value.

file

    <file source=source_name [destination=destination_name] [executable=yes|no] [autogen=yes|no] />

This element will copy a file name source_name to destination_name using the currently defined source and destination directories. If not specified, the destination name will be the name of the source file.

The executable attribute allows to specify if the execute flag of the destination should be set, by default a file is not executable. The permission of the source file is not used.

The autogen attribute allows to specify if the file must be transform or not by autogen. By the default the first line of the file is tested to recognize an autogen template. If autogen is used, the file will get all definitions those have been used for generating the content block of the wizard template.

## Wizard actions

This block is optional, it defines additional actions to do after creating the project.

action

    <action>
    	<run>
    	...
    	<open>
    	...
    </action>

It represents the action block and contains any number of run and open elements. All these actions are executed in order.

run

    <run command=command />

This element allow to run the command command after creating the new project. The output of the command is redirected to one Anjuta message window.

open

    <open file=file_name />

This element will open the file file_name in Anjuta.

## Internationalization

The newer version of the project wizard format, used by Anjuta 2.31 and greater, supports the standard xml:lang attribute. So the translation can be merged in the .wiz file considering it as an xml file and using standard tools. The attributes having a name starting with '_' are considered as translatable.

The translation tools (intltool-merge) has to recognized the .wiz as an .xml file before being preprocessed by autogen. This adds additional constraints when writing the .wiz file, in particular you have to take care of quoting in attribute values. In addition, you need to have the project-template root node. So your template will not be compatible with older version of Anjuta.

## Distribution

You can write your own project template and distribute them in a gzip compressed tar file. The archive has to included all files needed by your template.

With Anjuta version 2.30 or below, the user has to decompress this archive in a directory named `anjuta/templates` in the data directory defined according to XDG Base Directory Specification. With Anjuta version 2.31 or greater, if you name your archive with the extension `.wiz.tgz` the template will be automatically installed and then executed if used as anjuta argument.