This tutorial series will show you, how you can turn an Xtext project into a web application.

In this part of the series, we will set up an Xtext project with web integration capabilities. We will have a look at the auto generated web server and where you could implement your functionalities, if you want to stay within the Xtext framework.

Just to warn you: This tutorial will probably feel a bit hacky.

Before you begin, take a look at the official documentation on Xtext web integration. Maybe they provide the better solution for your use case.

I've named the language I am going to use "Expressions". This language is heavily inspired by the expressions example in the book Implementing Domain-Specific Languages with Xtext and Xtend. In my case, it has no real purpose and will not be the subject of this series.

What This Series Is and What It's Not

This is a tutorial series about how to turn a domain specific language (DSL) created with Xtext, into a web application. I will show you how to create an Xtext project, which has the necessary web integration capabilities to export artifacts like the code generator and the language server, which are necessary to build the web application. Furthermore, I will show you, how to take the web editor, which was auto generated by Xtext, and turn it into a Vue.js component. To be able to compile the code from the web editor, I will show you how to implement the corresponding backend functionalities, using Node.js. If you want to stay within Eclipse and the Xtext environment, I will show you where you can find the code for the front- and backend. The overall goal is to understand the mechanics, which are necessary to run your DSL in the web browser. The image below visualizes what we will achieve in this series.

The general architecture of a DSL as a web service

This is not  a tutorial on how to build full stack web applications. If you want to learn how to build a full stack web app using Vue.js and Node.js, I highly recommend following this tutorial series from by Code Seibert (that's the way I've learned it, too). Furthermore, this is not a tutorial on Xtext and how to create your own programming language (DSL). If you are interested in that, I recommend the book  "Implementing Domain-Specific Languages with Xtext and Xtend" by Lorenzo Bettini. The application will be built to work, not to be safe. Neither is this a server hardening tutorial, nor is this a server administration manual.

Prerequisites to Follow This Series

To be able to start somewhere, I will assume you know

  • ... what a front- and backend is and how they work together.
  • ... the JSON format and the concept of communication via HTTP-Requests.
  • ... how to run commands on the command line interface of your system.
  • ... how to use the Xtext framework.
  • ... how JavaScript works.

Especially the last point - how JavaScript works - is quite important, because JavaScript will be the language we will compile to. Why JavaScript? Because this is one language, web browsers understand.

For the frontend I will use Vue.Js, because I am already familiar with it and I like how the idea of components is implemented in this framework. Of course, you could use any other JavaScript framework, or create your frontend without any of these frameworks.

Unsurprisingly for this tutorial it is also necessary that you have a working Eclipse with Xtext installation.

The git repository will contain any source code, we will produce.

Contribute to ngreve/xtext_web development by creating an account on GitHub.

Create the Xtext Project

If you have already created a project without web integration, I unfortunately have some bad news for you. I tried to convert a non-web-integration project into one, but failed multiple times. In theory, you could compare the differences between these two project types and modify the configs in your non-web-integration project accordingly, but experience shows, that it's very likely that things will break. The best option in this case is to create a new project with web integration enabled and copy your sources from the old into the new project.

In the pictures below you can see the two steps of the Xtext project wizard, to create a project with web integration capabilities.

After the project wizard created our project, your have to run the MWE2-Workflow and create the Xtext artifacts. When that's done, we are ready to inspect the web project.

The Web-Directory

In this section we will have a look at the web server which was generated for us. We will start the web server, and we will have a look at the functionalities it comes with.

If everything went well, you now should see the *.web/ directory in the Package Explorer. web

In case your *.web project does not contain any source files, make sure you ran the MWE2-Workflow.

What does this directory contain?

  • *.web/src/ contains the source code of the backend.
  • *.web/WebRoot/ contains the source code of the frontend, but also hides many of it at this point. We will come back to this later.

To start the web server, right click on the *.web/ directory and choose Run as-> Java Application, search for the ServerLauncher of your project and confirm with OK. If you can't find the ServerLauncher of your project, it can help to restart Eclipse.

Starting the Xtext web server

Take a look at the console output and wait for the following message:

[main] INFO de.nicogreve.dsl.expressions.web.ServerLauncher - Server started http://localhost:8080/...
[Thread-18] INFO de.nicogreve.dsl.expressions.web.ServerLauncher - Press enter to stop the server...

Open a browser and go to the told URL, which is in this case http://localhost:8080. What you will find is a simple code editor, which provides syntax highlighting and communicates with the language server in the background (more about that later). The editor used here is called Ace. It's an open source online code editor with lots of functionalities. Take a look at their documentation to potentially customize it. I will leave it, as it is.

To stop the web server, click into the Eclipse console and press enter.

The auto generated web project does not have a lot of functionalities, but it did us a huge favor by providing the language server, which is responsible for parsing and checking the editor inputs for errors.

If you want to stay within Eclipse and the Xtext framework you now know where to start, but unfortunately, for you, the tutorial ends here. You now know were the frontend and backend can be edited and extended with the functionalities that you need. Everything you will change in your validators and language rules will be available in the web project, without further ado.

Depending on the goal of your DSL and web application, I would probably recommend using a framework for your frontend. The biggest disadvantage of plain HTML programming is, that you will have trouble to reuse existing code (at least in my opinion). I prefer a component based approach, like it's done in Vue.js. Of course, you could use any other framework, like Angular or React, if you are more familiar with one of them. I will use Vue.js.

Conclusion Part 1

In this part we've created a project with web integration capabilities. Furthermore, we have familiarized ourselves with the Xtext web server implementation and figured out where the Xtext frontend and backend can be edited. In the end we started the web server and took look at the given code editor features.

In part 2 we will turn this Xtext web application into a Vue.js application.

See you in part 2!