Software Development, Xtext, Eclipse, english

New File Wizard – easy to generate with Xtext 2.14

We have already shown on our blog how to generate a new project wizard with Xtext 2.14. Now it's also possible to create a comparable wizard, also based on templates, for creating DSL files in existing projects.

This wizard will appear with Eclipse Photon in June 2018, but here is a quick preview.

Generating the wizard

The wizard for new files is created in much the same way as the wizard for new projects. The following section must be inserted in the mwe2 file, which defines what is generated:

language = StandardLanguage {
   name = "org.xtext.example.mydsl.MyDsl"
   fileExtensions = "mydsl"
   serializer = {
       generateStub = false
   }
   fileWizard = {
       generate = true
   }
}


Invoking Run As -> MWE2 Workflow now generates the wizard and an example template.

A package wizard is generated in the UI project of the language. This contains a file MyDslFileTemplateProvider.xtend, where the actual name of the file depends on the name of the language. This file defines the contents of the wizard: other configurations are usually not necessary.

If only a single template is generated for a language, the wizard will have only one page. All the parameters of the template are specified on this page next to the directory and a name.

Xtext-214-new-file-wizard


If there are several templates, a combo box for selecting a template will be displayed on the first page. The parameters are then configured on the optional second page.

Defining your own templates

To adapt the "Hello World" example to your own language, or to add further templates, you need to adapt the TemplateProvider class, which implements IFileTemplateProvider. This returns a list of all available templates for the language via the getFileTemplates method. By default, the implementation looks like this:

class MyDslFileTemplateProvider implements IFileTemplateProvider {
   override getFileTemplates() {
       #[new HelloWorldFile]
   }
}


Adding another template therefore consists of adding a new instance to this list. The new template must be a subclass of AbstractFileTemplate. The easiest way to do this is by using the active annotatio
n  File Template. This annotation allows you to specify a name, an icon and some descriptive text for the template. These specify the presentation of the template in the list of available templates in the wizard.

So you would start something like this:

@FileTemplate(label="Test", icon="file_template.png",
   description="This creates a new hello world file.")
final class HelloWorldFile {
}


As a minimum you need to implement the generateFile (IFileGenerator) method here. The passed IFileGenerator contains a single method, generate (CharSequence, CharSequence), which you can call any number of times to create files when you close the wizard.

For example, a call to create a simple "Hello World"  file might look like this:

override generateFiles(IFileGenerator generator) {
generator.generate('''«folder»/«name».mydsl''', '''
Hello «helloName»!
    ''')
}


Additional calls to generate generate additional files. The parameters for the templates are defined with the same API as the project templates. The complete "Hello World" example looks like this:

class MyDslFileTemplateProvider implements IFileTemplateProvider {
override getFileTemplates() {
#[new HelloWorldFile]
}
}

@FileTemplate(label="Hello World", icon="file_template.png",
description="Create a hello world for MyDsl.")
final class HelloWorldFile {
val helloName = combo("Hello Name:",
#["Xtext", "World", "Foo", "Bar"],
"The name to say 'Hello' to")

override generateFiles(IFileGenerator generator) {
generator.generate('''«folder»/«name».mydsl''', '''
Hello «helloName»!
''')
}
}


Adding more templates works analogously to the project templates via an extension point, in this case via "org.eclipse.xtext.ui.fileTemplate”.

The release of Eclipse Photon is still a few days away, but here is the link to the nightly update site:

http://download.eclipse.org/modeling/tmf/xtext/updates/composite/latest/

    
About Arne Deutsch

Arne Deutsch works as an IT consultant at itemis AG in Bonn. His focus is on Language Engineering, Xtext and the development of tools for Eclipse.