# AJAX Personality Builder Wizard

To start the Personality Builder Wizard, select File > New > Other > AJAX Tooling > AJAX Personality from the workbench menubar. This wizard contains three wizard pages which are described in detail below.

## Technology Runtime Page

The first page is used to collect general information about the AJAX runtime library to be targeted, as well as information about the artifacts that make up the AJAX library. The page is shown below.

The input descriptions for this page are as follows;

- Technology Name - Specifies the name of the target AJAX runtime library or toolkit.
- Generated Plugin Prefix - This is the prefix string that will be used when automatically naming the generated plugins.
- Small Icon - A 16x16 image file that will be used as the icon for any menu items pertaining to this personality.
- Large Icon - A 75x66 image file that will be used as the icon in the wizard pages for any wizard pertaining to this personality.
- Root Directory - The local directory that contains the runtime library artifacts for the targeted AJAX library. The file selector can be used to individually select files and directories that are needed at runtime to develop applications using the target AJAX library. These files and directories will be added to any new project created by the generated project wizard for the new AJAX personality.
- Runtime Artifacts Project - This will be the name of the plugin generated to house the runtime artifacts selected in the Root Directory.
- Project Destination Folder - The directory name within the Runtime Artifacts Project that will be the root of the personality's runtime artifact directory tree.

## Application Wizard Generation Page

The second page is used to collect information pertaining to the personality's application wizard that will be generated. The application wizard is hooked into the "New Wizards" menu by extending the org.eclipse.ui.newWizards extension point. The application wizard is based on Variables, Views and Templates which are all used in constructing the content and behavior of the wizard. Variables are created based on the inputs needed at runtime by the personality's application wizard. Each variable can be displayed, as an input, on a View page. Each View is represented as a wizard page in the resulting applicaton wizard. There are a few predefined Variables that are always displayed as inputs on the first wizard page, but an arbitrary number of Variables and Views can be defined. Templates define the file templates for the files to be created by the application wizard. Any of the previously defined Variables can be used within the content of a Template, in the form ${varname}, so that the template content can be dynamic depending on choices within the application wizard at runtime. Once the Variables, Views, and Templates information is provided, the application wizard's content and behavior can be implemented via extensions within the generated ui plugin (see the org.eclipse.atf.templates.wizardModel extension point documentation for more info on this). The application wizard page is shown below.

The basic inputs are at the top of the page and described below;

- Name - The application wizard name. This will be the string that is displayed in the menu item for the wizard.
- Description - The description that will show up as a description of the application wizard in the New Wizard list.
- Class - The class name of the application wizard implementation class that will be generated.

In addition to the inputs at the top of the page, the inputs relating to the Variables, Views, and Templates are divided into respective tabs within a tabbed folder.

### Creating Variables

To create a new variable to use within the context of the application wizard, select the Variables tab, and click on the New Variable button. A new variable will be created in the table with empty attributes. The different attributes of a variable are described below;

- Name - The unique name of the variable.
- Display Name - The string that will be used within the application wizard when prompting for this variable's value.
- Type - The type of the variable. This attribute is prompted for with a combo box of choices based on the contributions to the org.eclipse.atf.templates.variableFactory extension point. A corresponding variable renderer, contributed via the org.eclipse.atf.templates.variableRendererFactory, will be used to render the variable within the wizard page at runtime.
- Default Value - The variable's default value. Other variable references can be used when specifying this value.
- Options - A comma delimited list of options when the variable's Type requires options to be presented (i.e. StringOptions).

To delete a variable, select the variable and click on the Remove Variable button. Variables that are defined by default cannot be removed.

### Creating Views

Each view that is created translates into a wizard page that will be part of the personality's generated application wizard. By default the first view is pre-created and contains all of the default variables that are defined in the Variables tab. The Views tab is shown below.

From this tab, a new variable reference can be added to an existing view page, or a new view page can be created.

To add a variable reference to an existing view page, select the target view page in the view page table, and click the New Variable Reference button above the variable reference table. Then, select the Name of the variable reference that you would like to add to the page via the combo box in the Name column. A particular variable cannot be referenced more than once per a particular view page.

To create a new view, click on the New Page button. This will create a new view page with default values for the Name, Title, and Description attributes. The Name attribute should be a unique name relative to the other defined view pages. The Title and Description attributes are used as the title and description, respectively, of the wizard page which will be created to represent the view page. Once a new view page is created, at least one variable reference must be added to the page (i.e. it doesn't make sense to have a wizard page without any inputs).

### Creating Templates

Each Template specifies a file template for a file that will be created at runtime by the application wizard. After all inputs have been entered by the user (as defined by the Variables and Views), the wizard will generate files that constitute an AJAX personality application. This file generation is a type of Operation which is provided via the org.eclipse.atf.templates.operationFactory extension. Additional operations may be contributed through this extension point, but currently only the file creation operation is supported. Template definitions are to be entered in the Templates tab as shown below.

To create a new template, click on the New Template button. This will generate a new template without any content. In addition to the content, there are three attributes of a template that are described below.

- Name - This will be the name of the file that is generated. Previously defined variables can be referenced here. For example, to generate an html file with a name based on the user entered name of the application, the value would be ${appName}.html.
- Project Relative Location - This will be the location within the project where the file will be placed. Previously defined variables can be referenced here. For example, one of the default variables provided, ${appRoot}, holds the value of the application's root directory. So, to specify that the file should be placed directly under the application root, the value would be ${appRoot}/.
- Condition - Specifies the condition(s) under which this file should be generated. Previously defined variables can be referenced here. The syntax for the condition can be any legal Java expression that evaluates to a boolean (i.e. ${controllerType}.equals('html')).

The content text area for a particular template should contain the template content for the template. The content shown will correspond to the current template selected in the template table. The template content can contain references to any previously defined variables. In addition, the content can contain any legal JET notation. Each template's content is run through the JET engine at runtime to resolve JET expressions before the file is created.

## Code Snippet Generation Page

The third and final wizard page is used to specify any personality specific code snippets that will be available to the user at application development time. The code snippets will be contributed via the org.eclipse.wst.common.snippets.SnippetContributions extension point, and will be accessible through the workbench's Snippets View.

Code snippets are created much like application wizard pages. They are based off of Variables and Templates. Much like application wizard templates, code snippet templates can refer to previously defined snippet variables and can also contain valid JET notation. For a snippet template that contains variables, a dialog window will pop up to prompt the user for the value of the variable(s) when the snippet is dragged from the Snippet View and dropped into the application file. This allows the content of the snippet to be dynamic based on user input. The code snippet wizard page looks something like this;

To define a new snippet, start by clicking the New Snippet button which will create a new snippet in the snippet table. The Name of the snippet should be unique relative to the rest of the defined snippets, and the Display Name will be the name that is used in the Snippets View to represent the snippet. Once these attributes are specified, new variables can be defined for the snippet to be referenced in the snippet's template. If variables are not required, the code snippet's template content can be specified without variable references. To create a new variable, select the target code snippet in the top table, and then click on the New Variable button above the variables table. This will create a new snippet variable with empty attributes. The descriptions of the snippet variable attributes are as follows;

- Name - The unique name, relative to the other variables defined for the snippet.
- Display Name - The value will represent this variable in the dialog window.
- Type - The variable type. This value will correspond to one of the registered org.eclipse.atf.templates.variableFactory extensions.
- Default Value - The default value of the variable. This value will be shown as the default value in the dialog window.
- Options - A comma delimited list of options when the variable's Type requires options to be presented (i.e. StringOptions).
- Required - Whether or not input is required for the variable.

Creating the code snippet's template is exactly like creating a file template for an application wizard. First, select the target code snippet in the top snippet table. Then, enter the code snippet's template content in the text area at the bottom. The content can reference any previously defined snippet variable for the selected snippet (in the form ${varname}). In addition, the content can contain any valid JET notation such as if or for control statements.

## Plugin Project Creation

When the personality builder wizard's Finish button is selected, it will kick off the generation of three plugin projects. Each plugin, identified by the suffix it will contain in the name, and its contents are defined below;

- core - Contains the AJAX personality facet, nature and builder extensions. Each AJAX personality will have a corresponding facet and nature generated for it which will be added to any new project created for the personality. In addition, a default incremental project builder will be implemented for each AJAX personality using the org.eclipse.core.resources.builders extension point. Initially, the generated IncrementalProjectBuilder class has empty method implementations, but the content of each method can be supplied/modified as necessary.
- ui - Contains all application wizard and snippet extensions.
- runtime - Contains all runtime artifacts specific to the AJAX personality.

Once the plugin projects are generated, they can be further modified or run as is, by either proper Eclipse install procedures or by running the runtime workbench.

Related tasks
Personality Builder Overview
Nature Artifact Handler extension point
Wizard Model extension point
Variable Factory extension point
Variable Renderer Factory extension point
Operation Factory extension point
Snippet Model extension point

(C) Copyright IBM Corporation 2005. All Rights Reserved.
IBM is a registered trademark of IBM. All other trademarks are the property of their respective owners.