Channels ▼
RSS

JVM Languages

Customizing Xtext


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):

public class DomainmodelOutlineTreeProvider 
	extends DefaultOutlineTreeProvider {
	
	protected void _createChildren(DocumentRootNode parentNode,
			Domainmodel domainmodel) {
		for(AbstractElement element: domainmodel.getElements()) {
			createNode(parentNode, element);
		}
	}
	
	protected void _createNode(IOutlineNode parentNode, 
			Import modelElement) {
	}
}

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:

source.. = src/,\
          src-gen/
bin.includes = META-INF/,\
               .,\
               plugin.xml,\
               icons/

Now get a grip on some fancy icons and copy them into the icons folder.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

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.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video