Design

Customizing Xtext

By Jan Koehnlein and Sebastian Zarnekow, October 25, 2011

The DSL framework is surprisingly customizable, allowing you to tailor the tools to your specific language's needs

This is the third and final installment of the tutorial on Xtext. In Part 1, we demonstrated how to set up a simple DSL. Part 2 focused on writing a code generator in Xtend, Xtext's language for specifying generated output. In this article, we'll explain how to customize the Xtext infrastructure of your language.

We'll use the examples from Part 1. If you have not done so yet, follow the steps to setup the Xtext project and the runtime configuration. You can start with the final grammar right away, but do not forget to run the workflow and to set the memory settings in the runtime configuration as indicated there. You should now be able to open a .dmodel file in a new project inside Eclipse.

Getting and Outline View

The outline view (Window &lgt; Show View > Outline) displays the structure of the underlying semantic model of the currently edited document. The default works fine. Try Link with Editor, Sort and double click, etc.

However, good defaults do not always fit all use cases. There are some things Xtext could not guess, so the outline looks a bit odd: The root node belongs to an element of type Domainmodel, which does not have a name attribute so the label is '<unnamed>'. Furthermore, all elements have the same icon making it hard to distinguish between Imports, PackageImports, Entities and DataTypes. Also, as shown in Figures 1a and b, the panes can acquire a lot of clutter content.

Figure 1a: The outline view would be clearer and look nicer without the nodes for Domainmodel and Import and with different icons for the remaining types as shown in Figure 1b.

Figure 1b: A cleaned-up right panel.

Before we start customizing the outline, here is a bit of background information on the outline framework used in Xtext: The outline tree consists of IOutlineNodes, which usually correspond to model elements. The component responsible for the outline view of our language is the DomainmodelOutlineTreeProvider. Its superclass DefaultOutlineTreeProvider provides a couple of helper methods to control the structure and the appearance of the tree. This approach is a common idiom in the Xtext framework. You will usually find a fully working default implementation that is either generated or (more often) based on generic functionality of the Eclipse Modeling Framework. That is, there is no piece of code in your own code base but in the libraries of the framework that performs the job. However, for common customization scenarios, a stub implementation may be available in your language project.

Polymorphic Dispatch Functions

To calculate the children of a node, the DefaultOutlineTreeProvider looks for a method named _createChildren. Similar to the dynamic dispatch functions of Xtend2, the method that matches the types of the current node and the model element best is chosen at runtime. It employs Java's reflection mechanism internally.

For example, if we want to skip the first visible node belonging to the Domainmodel, we have to implement _createChildren(DocumentRootNode, Domainmodel):

In this example, we avoided the creation of outline nodes for Import elements by adding another dispatch function _createNode(IOutlineNode,Import) with empty contents.

That is all for the structural changes; let's continue with the appearance. Now that you are familiar with Xtext's concepts of polymorphic dispatch, you should not be surprised that you can choose the icons with another dispatch function _image(), which returns an Image for a model element.

Managing images can be a bit tedious in SWT as they consume scarce OS resources. Xtext provides an interface, IImageHelper, that hides all these nifty details from the user. It expects images to be in a folder icons in the root of the project, so you have to create that folder in the project org.example.domainmodel.ui. Make sure this folder is also visible at runtime by checking it in the build.properties of the same project:

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!