Page tree
Skip to end of metadata
Go to start of metadata

With this guide, you will install every tool required to use the JBStrap framework and you will create your first application in JBStrap.

Required Tools

This tutorial will use JDK 1.8, Apache Maven, Eclipse Oxygen 2 (4.7.2) for Java EE Developers, and WildFly 12.0.0 Final. If you already have these installed, feel free to skip to Section 2.

First, you need to install the tools required to use the JBStrap framework. These tools are not part of the framework but they are needed to develop, compile and/or run your application. This document describes the most commonly used tools but you can also use other compatible development and project builder tools.

Java Development Kit 1.8

The Java Development Kit (JDK) is one of Oracle’s tools for developers. The kit includes development tools. For application development with the JBStrap framework, we recommend that you use the 1.8 or later version of the JDK published by Oracle. Another JDK using the Java 1.8 standard can be used, such as OpenJDK.

Download and install the version of Oracle JDK 1.8 that is compatible with your operating system using the following link:

To check if the installation was successful, type the following command into a terminal window (command prompt if using Windows):  java -version

If the installation of the Oracle JDK 1.8 was successful, you should see the following message:

Apache Maven

Maven is a widely used compiler tool for Java development. Maven simplifies the translation of Java applications with automatic dependency management in a unified project structure. Because of this, Maven is one of the most popular compilers used for Java web development. It is supported by most development tools by default so you may not need to install it manually. If you want to create or compile a project using a terminal, this is a must have.

Download the latest version of Maven from the following link:

Apache Maven comes in a compressed file and not as an executable installer (.exe file). You just need to unpack the file into a folder. Assign the bin folder to the PATH environment variable of your operating system so that the Maven tool can be accessed at any location on the computer.

To check that everything is working properly, run the following command in a new terminal window: mvn -v

You should now see the following:


Eclipse is the most popular integrated development environment (IDE) among Java developers. Eclipse is a free, open-source, platform-independent software developed by Eclipse Foundation. It includes all essential tools for development as well as a plugin system that allows the developer environment to be tailored to your needs. Eclipse’s built-in Maven support makes it even more appealing. JBStrap uses Eclipse as a developer tool throughout all of its guides.

Download and install Eclipse from the following link:

Recommended version is Eclipse IDE for Java EE Developers (that is, Eclipse Oxygen 2 (4.7.2) for Java EE Developers).


WildFly (formerly known as JBoss Application Server or JBoss AS) is an open-source, free-to-use implementation of the Java EE specification developed by RedHat. Since it is based on Java, the WildFly application server operates on multiple operating systems that have Java support. JBStrap will use WildFly as an application server in all of its guides.

Download WildFly from the following link:

The recommended version is 12.0.0.Final Java EE7 Full & Web Distribution.

WildFly comes in compressed format and not as an executable installer (.exe file). You just need to unpack the file into a folder. This folder will be the application server’s folder.

Open a new terminal window and navigate to this folder. Open the bin folder and launch the add-user script.

For Windows: add-user.bat

For Linux and MacOS:

This will create a user in the server who will have the right to administer the server and install applications on it.

Follow the on-screen instructions and create a Manager user. Remember the password you entered because you will need it later.

Maven Archetypes

JBStrap provides developers with multiple Maven archetypes to help them to create the project structure and to generate the basic resource files for the application. Various archetypes are available to developers for different applications.

To use archetypes, make the following changes to the Maven compiler.

Locate and open the local repository folder. This folder is located in the user folder named .m2

For Windows:

For Linux and MacOS:

If this folder already contains a file named archetype-catalog.xml, open it. If such a file does not exist, create a file with this name.

Modify the content of the file so that it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog xsi:schemaLocation=“” xmlns=“” xmlns:xsi="">
        <description>JBStrap public application without user authentication</description>

Save the file.

Having done this, you will have access to all of the JBStrap archetypes.

Creating Your First JBStrap Application

This chapter will demonstrate how easily and quickly you can achieve results with JBStrap. By following this guide, you will create your first JBStrap application. It will be a very simple “Hello World” test program, but it will give you a good idea about the use of menus, creating windows and managing events. Creating this application would not take more than 5 minutes.

Creating Your First JBStrap Application

First, you will create an application using a Maven archetype. Since your application will not require either user login or a database connection, you can use the simplest archetype called JBStrapSimpleApp.

Create a folder where the source code of your application will be stored and navigate to this folder. Open a terminal window and enter the following commands:

mkdir JBStrapDemo
cd JBStrapDemo

With this folder, you are now ready to create your first JBStrap application. Regardless of your operating system, this can be done by entering the following command:

mvn archetype:generate -DarchetypeGroupId=com.jbstrap -DarchetypeArtifactId=JBStrapSimpleApp -DarchetypeVersion=1.0 -DartifactId=firstApp -Dversion=1.0.0-SNAPSHOOT

You should now see the screen above. At this point, Maven asks you if the settings of the project to be created are correct. Here, answer yes (type “y” then hit <Enter>).

Your application is ready. It can already be compiled and installed on an application server. However, this is still only the foundation of your application. You have a menu, a home screen and a UI, but there is no real content. Let’s continue developing this application.

Importing Your Project to Eclipse

Open the Eclipse development tool and select the JBStrapDemo folder (which was created in the previous section) as a workspace.

Click the Launch button. Eclipse starts with a welcome screen:

Close the welcome screen and import your application by selecting File → Import...

You will see the following screen:

In this window, click Maven → Existing Maven Projects → Next

A new window will appear:

Click Browse... and select the JBStrapDemo folder. Your application should be listed as one of projects in the middle of the window (starting with /firstApp). Select your application and click on Finish to import your app. Eclipse then checks and builds the project which might take some time.

When importing has finished, you will see the following:

On the left side of the window in the Project Explorer , your first app will appear and you can now continue working on it.

Creating a New Window

On the left side of the Eclipse window, you can see a tree view called Project Explorer. This can be used to navigate between different sources of applications in the workspace. Open the tree structure as below.

firstApp/Java Resources/src/main/java/

Right-click on → New → Class

The following window will pop up:

In this window, type “MyPage” in the Name line and click the Finish button. This is how you create a new source file called This will include your window. The new file is automatically opened by Eclipse.

First, modify the class declaration by extending the BasePage class.

public class MyPage extends BasePage

You will now see a small red X at the beginning of the line in Eclipse. This is how the development tool lets you know that there is something missing from your code in that line. In this instance, the problem is that the BasePage class requires its constructor to specify parameters for the UI and the PageData objects. Since MyPage is an extension of the abstract class BasePage, its constructor does not specify these parameters and Eclipse thinks that there is a mistake in the code.

Click on the red X that appeared and Eclipse will offer you to help to create the required constructor. In the window that pops up, select MyPage (UI, PageDATA). The following method will be created:

public MyPage(UI ui, PageData page) {
    super(ui, page);
    // TODO Auto-generated constructor stub

Now you’ve got the right constructor, but its content is not what you want. Modify the method in the following way.

  1. Create the required components

    1. Create an input field where the user can enter their name

      final TextItem name = new TextItem("name", "Enter your name");

      Here, you create an input field named 
      TextItem . Its name will be “name  and its corresponding entry will be “Enter your name .

    2. Create a button that the user can click on

      final Button welcomeBtn = new Button(Icon.FLASH, "Welcome", ButtonType.PRIMARY);

      Here, you create a 
      PRIMARY  type green button with the text "Welcome" and a lightning icon next to it.

    3. Create a blank label in which the welcome text will appear and set its background color to transparent

      final Label welcomeMessage = new Label("");
      welcomeMessage.setStyle("background-color", "transparent");

      With this line, you create a blank label on the screen. This is not visible, but you will use it later.

  2. Create the event handler that runs when the user presses the button

    welcomeBtn.addClickHandler(event -> {
        welcomeMessage.setText("<h2>Welcome <b>" + name.getValueAsString() + "</b> in my application.</h2>");

    With this code, you have created the click event management method. The event will be triggered when the user clicks the Welcome button. If the event handler runs, it will modify the originally blank label by displaying the greeting sign that already contains the name specified by the user.

  3. Add the components to the page

    final Container pageContainer = new Container();
    pageContainer.addComponents(name, welcomeBtn, welcomeMessage);

    With these lines, you added all the previously created components to your page. You created a 
    Container  component that does not have a visual appearance, but it is necessary for the page to display correctly. The container will have a small space on each side of the page. Components can be added to the side of the page if you do not want to leave margins.

You added the input field, the button and the welcome text to the container. As a result, the three components will be displayed one after the other. Then you added a container to the page.

Your source file should now look like this:


import com.jbstrap.ui.BasePage;
import com.jbstrap.ui.Icon;
import com.jbstrap.ui.UI;
import com.jbstrap.ui.components.Container;
import com.jbstrap.ui.components.Label;
import com.jbstrap.ui.components.button.Button;
import com.jbstrap.ui.components.form.items.TextItem;
import com.jbstrap.ui.template.Bootstrap.ButtonType;

public class MyPage extends BasePage {
public MyPage(UI ui, PageData page) {
  super(ui, page);
  // Create components
  final TextItem name = new TextItem("name", "Enter your name");
  final Button welcomeBtn = new Button(Icon.FLASH, "Welcome", ButtonType.PRIMARY);
  final Label welcomeMessage = new Label("");
  welcomeMessage.setStyle("background-color", "transparent");
  // Handle button click event
  welcomeBtn.addClickHandler(event -> {
  welcomeMessage.setText("<h2>Welcome <b>" + name.getValueAsString() + "</b> in my application.</h2>");
  //Add components to the page
  final Container pageContainer = new Container();
  pageContainer.addComponents(name, welcomeBtn, welcomeMessage); 

Save the code. You have finished creating your first window in JBStrap.

Creating a New Menu Item

Now that you have a window, create a new menu item that allows the user to open this window. To do this, find and open the file using the Project Explorer.

When you open this class, you can see that this is not an empty class but a source generated by the archetype. The ContextInitialized method of this class will run when the system is started (more precisely, when the application server loads your application). It’s a good idea to do some resource-intensive tasks here and upload the caches that will not change when the program is running. As a result of this, the first page will be displayed very quickly when the user opens the application because all the necessary data will be in the server’s memory.

For example, Pages is one such static cache. It keeps a record of the pages that you create and allows you to refer to pages with a unique PageId. This way, you do not need to enter all the parameters of a page each time you open it. Similarly, MenuItems is also a static cache; it contains information about the menu items and their operation.

  1. Create the entry for your new page in the Pages cache

    To do this, look for the section in the class in which the Pages cache is loaded. In the present case, only one mainPage is included in the cache. This is set in line 75. Navigate after this line and enter the following:

    Pages.INSTANCE.addPage("welcomePage", MyPage.class, null);

    This line of code places a simple window’s metadata in the Pages cache. The first parameter specifies the PageId belonging to the window; this can be any text value but it must be unique within the application. We will later refer to the window with this ID.

    The second parameter specifies which class describes the window. In the present case, this will be the MyPage class created in the previous point.

    In the third parameter, you can assign parameters to the window that the PageData will contain. Since you do not use any parameters in this example, you pass a “null” value here.

  2. Change the MenuItems cache to include only two menu items

    The code generated by the archetype contains an example menu structure. There are two menu items in this structure – group1 and group2 – each containing three submenus. There is also a third menu item called menu3 which does not include submenus. In your application, this is not necessary, so delete this part of the source code from line 80 up to line 90. In the now empty line 80, right below the comment, make the following changes:

    1. Set the Home menu

      Create a menu item that allows the user to navigate back to the main page. To do this, enter the following:

      MenuItems.INSTANCE.addMenuItem(new MenuData("home", Icon.HOME, "Home", MenuOperation.OPEN_PAGE, "mainPage"));

      This line places a menu item in the MenuItems cache. The navigation menu will be built from this cache. As the first parameter, enter the name of the menu item; this can be any text value but it must be unique within the application.

      In the second parameter, you add an icon to the menu item. In this case, it is the icon called HOME which will display a small house. If you do not want to use the icon, enter a “null” value.

      In the third parameter, you enter the text appearing on the interface that the user will see. In this case, it will also be “Home”.

      As a fourth parameter, you specify what will happen when the user clicks on the menu item. In this example, a user click should open a window, so you will use OPEN_PAGE.

      The last parameter specifies which window to open. It is the PageId that was previously used in Pages cache. Use mainPage since this is our main page’s identifier.

    2. Prepare the new menu item for your page

      You need another menu item on which the user click can click. When the users clicks on this, the window you created in the previous section should open. The code that creates this menu item only differs from the code creating the previous menu item in its parameters. Enter the following code:

      MenuItems.INSTANCE.addMenuItem(new MenuData("welcome", Icon.SNOWFLAKE_O, "Welcome", MenuOperation.OPEN_PAGE, "welcomePage"));

      In this line, the “welcome” text is the menu’s name, the icon of the menu item is a snowflake, and “Welcome” is its label.

Save the changes. Your application is ready to be compiled and deployed to a suitable application server.

Compiling the Application

The application is built by the Maven compiler. This can be done from the terminal or from Eclipse.

If you want to do this from a terminal, navigate to the JBStrapDemo\firstApp folder and enter the following: mvn clean install

The application is now compiled. A folder named target has been created which contains the file named firstApp.war. This file is ready to be installed on the application server.

It is also possible to use Eclipse for the compilation:

Right-click on your firstApp project in the left side of the Project Explorer → Run as... → Maven build...

In the window that appears, Maven asks you with which Goals it should compile the project. This only has to be set once. Your answer is saved by Eclipse and will be used by default for future compilations.

Type “clean install” in the Goals line and click the Run button to initiate the build.

In the lower part of the Eclipse screen, a tab labelled Console opens that shows you the result of the compilation process.

When the build is completed, you should see the following:

The only thing left to do is to install your application on the application server.

Installing the Application on the WildFly Server

Open a terminal and navigate to the folder of the application server. In this example, this is the folder where the WildFly server was unpacked. Enter the bin folder and start the server with the following command:

For Windows: standalone.bat

For Linux and MacOS:  ./

Once the server has started, open your favorite browser and navigate to http://localhost:8080.

The WildFly server screen should appear:

Click on Administration Console and login with the username and password of the previously created Manager user. The server manager screen will appear:

Open the Deployments tab from the top menu bar:

Click on the blue Add button at the top left to add your newly created application to the server. The following window will appear:

Leave the Upload a new deployment button selected and click Next. A new window will appear in which you can upload the application.

Click the Choose File button and browse for the file containing your application.


After selecting the file, click Next. A new screen will appear:

You do not have to change anything on this screen. Click on the Finish button to start uploading your application. This can take a few seconds.

If everything goes well, you should return to the Deployments screen. On the top of this screen, a green box should appear informing you that the server has successfully installed the application. On the left-hand pane, your application will be listed as shown below:

You are now done with the installation. Let’s run your app!

Running the Application

To run your application, navigate to the following URL in your browser:  http://localhost:8080/firstApp/

You will be greeted with your app’s welcome screen:

On the left side of the screen, you can see the two menu items that you have created: Home and Welcome. The opening screen is in the middle of the page.

Click on the Welcome menu item to try it out.

In the Welcome page, you should see an input field and a button. Type your name in the input field and click on the Welcome button. You should now see a greeting message in the middle of the page.

You can return to the opening page by clicking Home.

Congratulations! You have created your first working application using the JBStrap framework.

We are in the process of developing many more sample applications and tutorials with which you can learn to master the JBStrap system in no time.

The full source code of the application described above can be downloaded as a compressed archive from here.