Styling Mendix Apps in Eclipse (alternative to the Scout/Sublime methods)

Part 1 of 3: Setting up the project


This is the first in a series of posts that centers around implementing custom and reusable UI for your Mendix applications utilizing the SASS (Syntactically Awesome Style Sheets). In this post we'll do the setup, in the subsequent one we'll improve your workflow when doing styling (let's face it, although it's fun it gets tedious sometimes), and for the last one I'm planning to address real-life User Experience Design issues and how to address them.

The difference between the method described here and the Mendix how-to is the tools used: instead of using Scout and Sublime, we will only be using one tool likely already in your toolbox - Eclipse. The benefits for you is less applications to install, maintain and learn, and you'll be more efficient because you don't have to switch between an array of tools to give your application that crisp and professional look and feel.

I'm using Eclipse for other development projects too and for Mendix Java Actions. Eclipse is also great for navigation, quick searches and code completion (at first it might take some time to get used to it, but once you learn the shortcuts it's awesome).

What I'm not covering here is how to actually write SASS; there are plenty of resources available online that go into great detail. My recommendation is that you first learn CSS and then SASS. The best place to start is arguably W3Schools.

Without further ado, let's get you up and running.

Install SASS

In this section we are going to install SASS which will build your CSS files used in the Mendix project:

  1. Install Ruby from here (click the big red download button and choose the right installer version for your machine). When installing remember to check the box to Add Ruby executables to your PATH.

  2. Install SASS by opening up your terminal (click the Start menu and start typing CMD and click cmd.exe tip: right-click and run as Administrator if you run into issues) first and then type:

    gem install compass

    You will see various ruby packages being fetched and installed, and after a few moments get a message that the gems were installed.

    Note: If you get the error that 'gem' is not recognized as an internal or external command, operable program or batch file, the simplest way to resolve the issue is to reinstall Ruby and check the box to add Ruby to the PATH variable. Remember to also restart the terminal before trying again.

Install Eclipse

Eclipse will be used to edit the SASS files. It might seem like an overkill for just this purpose, but if you're creating your own Mendix Java Actions (or want to do so in the future) you will have to install it anyway; conversely I find it much easier to just use Eclipse and not a bunch of other tools too.

  1. Download Eclipse from here. Choose the Eclipse IDE for Java EE Developers and the right bit version for your machine. Depending on your Internet connection, it might take a couple of minutes to download (it's about 300mb in size).

  2. Extract the contents of the downloaded Zip file to your desired location. My recommendation is to create a folder eclipse in your C: drive and extract it to there.

  3. Double-click eclipse.exe to start the program.

    Note: You must have JRE (Java Runtime Environment) or JDK (Java Development Kit) installed to run Eclipse. If you don't have it, download it from here or head over to Stack Overflow for more help.

Using Mendix, Eclipse and SASS

The first thing we will do is create a sample Mendix project, do the final Compass configuration, and start editing the SASS files.

Mendix steps
  1. Open the Mendix modeler and create a new project based on the blank theme. I called it rikus-dev-SassTutorial1 and saved it under C:/mendix/rikus-dev-SassTutorial1-main and will refer to that location throughout.

    Note: I'm using the latest version available on the App Store which is currently 6.3.1. This method should work with any version of the modeler since 5.18.0
  2. Run the project and view it in the browser to see the blank project with nothing really interesting. What is of interest however is what happened in the background. Whenever the project is run, the modeler updates the file structure of the project. In particular it updates the C:\mendix\rikus-dev-SassTutorial1-main\deployment folder. This is of interest to enhance the development experience later on.

Eclipse steps
  1. Open or go to Eclipse (choose the desired workspace location), and do the following:
Note: The Eclipse workspace and its projects are (and should be) different from your Mendix application folders - you don't want to mix them up. Later on we'll be linking the two in Eclipse, but they should remain different to avoid inadvertent loss of data.

a. Create a new project (File > New >Project) and select the General > Project type. Give the project a name. I called it rikus-dev-SassTutorial1 and just used the default location. Click finish. You should now see the project in the Project Explorer.

  1. Now we are going to link to the Mendix project files from Eclipse:
    • Right-click rikus-dev-SassTutorial1 > New > Folder.
    • Click Advanced>>, select Link to an alternate location (Linked Folder).
    • Click Browse, navigate to your Mendix project location and select the themes folder, and click open.
    • Click Finish to now see the theme folder underneath your project in Eclipse.

SASS steps

If you expand the themes folder in Eclipse you will see there is a styles folder. We'll use this in a second. First I want to draw your attention to a file called config.rb. Right-click on it and click Open With > Text Editor. The important lines are the ones referencing 'styles/css' and 'styles/sass'. The styles/css folder is where Compass will write your compiled CSS files to. The styles/sass is what you will be editing.

  1. In Eclipse right-click the theme folder and click Show In > Terminal. A Terminal panel will open in the bottom of Eclipse.
  2. In this panel, type compass watch and press enter, you should now see this:
C:\mendix\rikus-dev-SassTutorial1\theme>compass watch
>>> Compass is watching for changes. Press Ctrl-C to Stop. 

Congrats! Now you can make changes to the SASS files in the theme/styles/sass/custom folder and they will automatically be compiled into CSS!

A good place to start is the _custom-variables.scss file. This file conveniently contains variables for basic theme settings like text and button colors. Go ahead and change any of the .scss files, and you will see feedback in the terminal that changes were made and the generated css files updated.


This post covered the setup of using Eclipse to do styling for your Mendix apps using SASS.

In the next post we will look at how to improve your workflow while doing styling; to conclude the series we'll address real-life User Experience Design issues and how to solve them in Mendix (for example how to style a default Mendix Widget using SASS).

A good place to start overall is to get familiar with the tools: Mendix, Eclipse and your web browser (I have found that Google Chrome has the best out of the box features to help with styling).

Leave your comments below!


© 2017