4. Wizards

Some descriptions may be outdated.
All requirement sections are not linked to real issues. They were left here as an example and to complete the issues.

4.1. N4JS Project Wizard

Wizard creates a new N4JS project.

The following information is to be specified by the user:

Project Name

string, name of project

Default Location

boolean, true by default

Location

string, computed default location, if user set location then default location flag must be false

Project Type

enumeration, the type of the new project

The following files are to be created:

Project Folder

with name of project at given location

Manifest

with default project structure and name

Source Folder

default source folder (src)

Output Folder

default source folder (src-gen)

4.2. Empty N4JS File

The following information is to be specified by the user:

Package Name

dot separated name of the package, empty by default (or set to the package/folder selected in the navigator)

Module Name

string, name of the module – must be a valid module name without extension

The following files are to be created:

Package Folder(s)

if folders representing package structure do not exist, they are to be created

Module File

empty file with name of module and extension n4js in the appropriate package folder

4.3. Empty JS File

Similar to Empty N4JS File but with the file extension js.

4.3.1. N4JS Class Wizard

It is recommended to define a single classifier in a file, the name of the classifier should have the same name as the file. Based on that assumption, file wizards are provided for N4JS classes, interfaces and enumerations.

newclasswizard

4.3.2. Field Properties

The New N4JS Class wizard offers following fields:

Project

Specifies the containing project.

Req. GH-1413a: Project constraints (ver. 1)

Constraints
  1. It is a path of a valid project in the current workspace

  2. This field must not be empty

Req. GH-1413b: Project browse button (ver. 1)

Browse Button

Browsing only allows the selection of projects in the current workspace. Project creation is not possible.

Req. GH-1413c: Project initial selection inference (ver. 1)

Initial selection

The project should be derived from the initial selection.

Req. GH-1413d: Project content assist (ver. 1)

Content Assist

Workspace projects

Source folder

Specifies the containing source folder.

Req. GH-1413e: Source folder constraints (ver. 1)

Constraints
  1. The folder is listed as source folder in the project manifest

  2. This field must not be empty.

  3. The name is a valid path that means each segment of the path matches the following expression:

    [a-zA-z_](([\\.][a-zA-z_0-9\\-])|[a-zA-z_0-9\\-])*

Req. GH-1413f: Source folder browse button (ver. 1)

Browse Button

Browsing only allows the selection of source folders in the selected project. The dialog should provide a list of all source folders of the selected project. This includes nested source folders. A list element is a relative path of a source folder in the project.

Initial selection

The source folder field should be derived from the initial selection

Req. GH-1413h: Source folder content assist (ver. 1)

Content Assist

source folders defined by the project manifest

Module specifier

Specifies the module specifier. May only specify a module container (a folder) but could also include module name. May also be an already existing module. Does not include the file extension.

Req. GH-1413i: Module specifier constraints (ver. 1)

The specifier is a valid module specifier that is - Segments are separated by the path separator - No separator at the beginning or end

Req. GH-1413j: Module specifier completion (ver. 1)

Manually inserting a specifier ending with a separator is valid. It is then interpreted as base path for the full module specifier automatically completed by the class name. (cf. grey suffix)

Req. GH-1413k: Module specifier grey suffix (ver. 1)

A grey suffix should suggest the attached class name as module name if the specifier only specifies a base path.

Req. GH-1413l: Module specifier browse button (ver. 1)

Browsing only allows the selection of modules or module containers in the selected source folder. The browse dialog has to offer a module container creation functionality. In contrast to the other parts of the wizard, the creation of module containers in this dialog should be immediate and on file system level. This is important to comply with the conceptual model of eclipse and the operating system.

When inserting a non-existent path in the text input and opening the browse dialog, an additional dialog should ask the user whether he wants to create this structure on the file system. If he denies, the dialog shows the selection to the level it already exists on the file system.

The module specifier should be derived from the initial selection by using the container of the selection as initial module container

Req. GH-1413n: Module specifier content assist (ver. 1)

Modules in the selected source folder

For now the spec doesn’t specify any constraints for module specifiers

Class name

Specifies the class name.

Req. GH-1413o: Class name basic constraints (ver. 1)

Constraints
  1. The name is a valid n4js class identifier Must not be empty

  2. If the target module already exists no other type with the same identifier may exist in this module

Req. GH-1413p: Class name conflict validation (ver. 1)

If the target module already exists no other type with the same identifier may exist in this module

Req. GH-1413q: File type options (ver. 1)

Definition file (.n4jsd)

Specifies whether the class should be declared external. This option changes the file extension to n4jsd

Req. GH-1413r: Access modifier constraints (ver. 1)

Specifies the access modifiers of the class. One of public, project, private. @Internal is an additionally selectable option.

Constraints
  1. One of the provided access modifiers has to be selected

  2. The @Internal option is only selectable in case of public or project

Other modifiers

Specifies other modifiers and annotations of the class. The non-exclusive options are @Final and @N4JS

Req. GH-1413s: Other modifiers constraints (ver. 1)

Constraints
  1. @N4JS annotation is only enabled and selectable if the Definition File box is checked

Super class

Specifies the super class

Req. GH-1413t: Super class constraints (ver. 1)

Constraints
  1. A valid absolute class specifier that is a module specifier and a class name separated by a dot.

Req. GH-1413u: Super class browse button (ver. 1)

Browse Button

Browsing allows the selection of all classes in the current workspace with modifiable source and visible classes with unmodifiable sources.

Req. GH-1413v: Super class content assist (ver. 1)

Content Assist

All classes matching mentioned criteria

Interfaces

Specifies the implemented interfaces of the class

Req. GH-1413w: Interfaces constraints (ver. 1)

  1. A valid absolute interface specifier that is a module specifier and an interface name separated by a dot.

Req. GH-1413x: Interfaces browsing (ver. 1)

Add Button

Browsing allows the selection of all interfaces in the current workspace with modifiable source and visible interfaces with unmodifiable sources.

Remove Button

Removes the selected interface from the list. Disabled if nothing is selected.

Req. GH-1413y: Interfaces content assist (ver. 1)

Text input is available by clicking in empty space at the end of the list. Content Assist provides all interfaces matching mentioned criteria.

Req. GH-1413z1: Create method stubs (ver. 1)

Specifies if the wizard should generate method stubs for all abstract methods of the newly generated class. That are abstract super class methods or methods that need to be implemented by the class to conform to the selected interfaces.

Req. GH-1413z2: Create method stub conflict detection (ver. 1)

If the selected interfaces are impossible to implement (e.g. method name overlap with unrelated parameter types) this option needs to be disabled and a warning needs to be shown.

Shouldn’t this be a constraint of the selected interfaces? (Never generate invalid code)

4.3.3. Visibility issues or @Final super classes

Req. GH-1413z3: Visibility issue conflict solving (ver. 1)

By allowing the user to select invisible interfaces and super classes or unextendable @Final-annotated super classes, accessability issues may come up. The goal is to never generate a file containing invalid code. To accomplish this, conflicts must get solved before the file is generated.

The slight limitation of the selection of interfaces and classes to elements from modifiable sources (cf. super class browse button) allows to solve all possibly occurring visibility issues.

If the modifications by finishing the wizard do imply changes different from insertions and creations, a compare view is to be shown, giving the user an overview of the needed changes before they’re applied.

4.3.4. Generation

Req. GH-1413z4: Wizard generation (ver. 1)

The following changes are to be made by the wizard:

  1. Create a new file containing the new class (optional)

  2. Insert the new class into the specified module

  3. Change the source module of the super class to fix possible visibility issues (optional)

  4. Change the source module of the interfaces to fix possible visibility issues (optional)

  5. Change the project manifest to add a new source folder (optional) or add new project dependencies (optional)

4.3.5. Preview

Req. GH-1413z5: Generation preview (ver. 1)

On the right of the wizard form a preview window should be provided. It should preview the full path of the generated file and all code that is generated with the options of the wizard. Changes should be updated in realtime as the user is choosing different options.

4.4. Interface Wizard

The N4JS interface wizards is strongly similar to the N4JS Class Wizard. The following paragraph is meant to state the differences and will strongly refer to the N4JS Class Wizard as a lot of properties stay the same.

newinterfacewizard

4.4.1. Field Properties

Project

Specifies the containing project. See N4JS Class Wizard Project.

Source Folder

Specifies the containing source folder.
See N4JS Class Wizard Source Folder

Module Specifier

Specifies the containing source folder.
See N4JS Class Wizard Module specifier

Interface name

Specifies the name of the interface

Constraints
  1. The name is a valid n4js interface identifier

  2. Must not be empty

  3. If the target module already exists, no other type with the same identifier may exist in this module

Definition file (.n4jsd)

Specifies whether the interface should be declared external. This option changes the file extension to n4jsd .

Access Modifiers

Specifies the interface’s access modifiers

See N4JS Class Wizard Modifier Field except for the following point:

Other than classes, interfaces must not be declared as @Final, therefore this option is removed.

Interfaces

The interfaces the interface is implementing

See N4JS Class Wizard Interfaces field except for the following point:

Other than classes interfaces must not be declared as @Final, therefore this option is removed.

Create method stubs

Specifies if the wizard should generate method stubs for all abstract methods of the newly generated class. That are abstract super interface methods or methods that need to be implemented by the interface to conform to the given interfaces.

If the selected interfaces are impossible to implement (e.g. method name overlap with unrelated parameter types) this option needs to be disabled and a warning needs to be shown.

Shouldn’t this be a constraint of the selected interfaces? (Never generate invalid code)

4.4.2. Visibility Issues

As the user might select invisible interfaces, the wizard has to solve these visibility issues. See ** for details.

4.4.3. Import naming conflicts

As the user may select identically named interfaces, the wizard has to solve these naming conflicts. See Class Wizard Visibility Issues for details.

4.4.4. Generation

  1. Create a new file at the given module specifier location (optional)

  2. Insert the new interface into the specified module

  3. Change the source module of the super class to fix visibility issues (optional)

  4. Change the source module of the interfaces to fix possible visibility issues (optional)

  5. Change the project manifest to add a possibly new source folder (optional) or add new project dependencies (optional)

4.4.5. Preview

The Interface Wizard should provided a preview. (See Wizard Preview)

4.5. Enum Wizard

The N4JS Enum File wizards provides the user a wizard to create enums. When speaking of enums in this context ordinary enums as specified in the N4JS Specification are meant.

4.5.1. Field Properties

Project

Specifies the containing project.
See N4JS Class Wizard Project

Source Folder

Specifies the containing source folder.
See N4JS Class Wizard Source Folder

Module Specifier

Specifies the containing source folder. See N4JS Class Wizard Module specifier

Enum name

Specifies the name of the interface

Constraints
  1. The name is a valid n4js enum identifier

  2. Must not be empty

  3. If the target module already exists, no other type with the same identifier may exist in this module

Modifiers

Specifies the interface’s access modifiers + Allows the user to select from following modifier options: public,project,private. The wizard automatically adds missing export if needed. + Furthermore the enum can be declared @Internal using a checkbox.

Should the enum wizard also provide functionality to create enum literals?

4.5.2. Generation

The following changes are to be made by the wizard:

  1. Create a new file containing the new enum (optional, only if module doesn’t exists yet )

  2. Insert the new enum into the specified module

4.5.3. Preview

The Enum Wizard should provided a preview. (See Wizard Preview)