Using SASS with Mendix

Since the introduction of the Mendix DX release (available from version 5.18 and above), using SASS with Mendix has become easier than ever. As someone who’s always worked with more “traditional” HTML and CSS, this introduction meant that I needed to investigate the implications this new approach brings for my work. While I had heard of SASS before, I never took the time to really explore what it had to offer. Though I’ve only recently truly started exploring SASS and working with it for my Mendix projects, I believe I already had my share of “ooh’s” and “aah’s” from a beginner’s perspective that I’d like others to benefit from.

Mendix DX - SASS in Mendix

Purpose of this guide

Though there’s a vast amount of documentation already available on the topic of SASS, I felt that the documentation provided from a Mendix point of view was somewhat lacking. Yes, Mendix does help you get started with SASS by pointing you to the tools you need, but beyond that point, I kind of felt lost. This was especially the case because there’s no mention or explanation of the way they structured their SASS theme folders (more on that later).

Purpose

While I intend to cover all important aspects of getting you started using SASS with Mendix, this post is not meant to be a comprehensive guide that covers every aspect to its full extent. I will also not be covering everything that has to do with SASS and its techniques/mechanisms/possibilities as you’ll find that there are plenty other great resources available (here, here, and here to name a few) that explore these aspects.

The main focus of this guide is to extend the aforementioned documentation provided by Mendix past the point of installing the tools you need to really get you started with this new approach to styling. The assumption is made that you already have some (basic) knowledge of CSS, understand the principles of SASS, and have experience with styling of Mendix applications.

💡 Psst.. In case you’re looking for some good resources to get started with CSS, make sure you have a look at the great interactive tutorials offered by Codecademy.

So.. what’s this SASS with Mendix thing?

According to the official SASS website, SASS (Syntactically Awesome StyleSheets) is:

“Sass is an extension of CSS that adds power and elegance to the basic language. It allows you to use variables, nested rules, mixins, inline imports, and more, all with a fully CSS-compatible syntax.”

SASS

I simply view it as a tool/pre-processor that enables you to better manage your CSS stylesheets through its really structured approach, especially when you have to maintain a responsive website/application. I won’t go into all aspects and functions that SASS has to offer, but would highly recommend you to start exploring it with the SASS documentation as starting point.

Getting started

Now that we’ve set the stage, it’s time to get things started. The first thing I’d like to state is that I’ve been using Koala as SASS compiler instead of Scout, for which Mendix provides documentation as well. While I’m sure that Scout can handle SASS compilation just as well as Koala does (I must admit I haven’t tried Scout), this Mendix community discussion triggered me to simply go for Koala.

The need for Koala

Koala SASS compiler

As Mendix mentions in their quick start guide, Koala provides you with an easy way to compile SASS input into CSS output with the help of a GUI inside a self-contained Ruby environment instead of having to use command lines. There isn’t actually that much you need to do to get this part up and running.

In order to start working with SASS files you simply add your Mendix project directory, after which Koala does all the magic. Yes, that’s all there is to it!

Things to keep in mind

  1. Make sure Koala is running whenever you’re editing your SASS files in order for your changes to be processed.
  2. Always make sure your application is running/redeployed to ensure that your local changes are copied over to your development machine’s deployment directory.
Koala compiler example
Koala compiler example

Tip: If for whatever reason you notice that your changes are not being reflected in your application, open up Koala, right-click your project and select Reload to force a re-compilation of your files.

About the Mendix SASS structure

When following the previously mentioned documentation provided by Mendix, you’ll notice that they do go into customization of your theme. The only problem is that it simply directs you to the _custom-variables.scss file. While it is possible to change all the colors and properties being used throughout the theme, this limits you to using the framework and design that was pre-built for you. In most cases this simply won’t suffice as you’ll be trying to implement a custom made design.

But how do we go forward? This is the point where I frowned my eyebrows a couple of items. The point where the Mendix documentation stopped and from which I intend to pick up, to help you bridge the gap of adding more customized elements into your project.

Let’s investigate the structure

Mendix SASS folder structureIf you browse through your Project folder, you’ll notice that your theme folder will now have a structure which resembles the image on the right.

What’s confusing is that there are css and sass folders, and that both contain a custom and lib folder. So far, what I’ve established (unconfirmed) is that:

  • If you want to work  purely with SAAS, there’s no need to pay attention to the css folder.
  • The lib folder contains all the stuff that is pre-generated and configured by Mendix (makes sense, right?).
  • The custom folder contains a duplication of the folders and files present in the lib folder, but without the settings given from the lib folder files (see example).

To better understand the above, here’s an excerpt from one of the files found under the lib folder:

// Mendix button link
.mx-link {
    padding: 0;
    color: $link-color;

    a {
        color: inherit;
    }
}

And here’s one from the same file, but found in the custom folder:

// Mendix button link
.mx-link {
  /* Styles here */
}

While it’s not a 100% duplication, I think you get the idea.

➡ And that’s actually something I’d like to note immediately: you’ll notice that on some occasions duplicates of files are either missing or the contents of the files are not as complete as the original. I don’t know whether this was done intentional or not, but of course it’s never a show stopper as you’ll be able to adjust the files easily.

If you want to work purely with SASS, just pay attention to the sass and custom folder within it.

From using existing folders and files..

Mendix SASS components folder structureNow that we have a better understanding of how the folder and file structures work on a higher level, you can imagine that it’s not that hard to already start customizing standard components.

As you’ll notice from the excerpt to the right, Mendix has done a great job of dissecting their whole framework’s styling components into smaller files that simply make it easier for you to know where you can find and alter stuff.

I won’t go too deep into the editing aspect of the files, but as you should already be a bit familiar with SASS basics, you’ll immediately notice that these are the files you’ll want to be adjusting. Make sure to also explore all the other folders, as the components folder shown above is just a small part of the whole framework.

Things to keep in mind

  • Insert your customizations into the files found under the sass\custom folder.
  • Always leave the files in the sass\lib folder intact, so that you can fallback onto the original framework whenever needed. Besides that, it’s way more neat to work like this.

Due to the fact that everything from the sass\custom folder is imported into the SASS compiler at a later stage (i.e. @import statements for the files are added below/after the ones from the sass\lib folder), you will always be ensured that your changes will overrule the properties as initially set by the Mendix theme you downloaded. More on that below!

.. to adding your own folders and files

Still with me? Great, because this is where the fun starts!  😎 Though I won’t be going too deep into specifics, the question you might still have is: what about my own custom classes? As I see it, there are two ways you could approach the addition of any custom styling component:

  1. Add your custom classes within the existing folder and file structure by inserting them into one of the files.
  2. Create your own SCSS file and import it into the SASS compiler.

Both approaches have their own pros and cons. On the one hand you want to re-use the existing structure of buttons, datagrid, templategrid, etc. as it ensures anyone else working on the project in the future with the ability to easily backtrace the changes you’ve made. On the other hand, you’ll have many situations in which you’re working on specific parts of your application where a multitude of changes across Mendix components need to take place. In such cases it could be more beneficial to simply create a new file where you bundle all styling aspects related to that part. These are just two of many considerations you could have. In the end it’s up to you which method you prefer, but do try to keep the long-term maintainability by you and/or your colleagues in mind.

In case you’re interested in adding files/folders of your own, simply keep the following rules in mind:

  • Your file must comply to a format similar to _filename.scss ; it has to start with an underscore and should have the .scss file extension.
  • Make sure you @import the created files into the custom.scss file found in the sass\custom.

For more details on this, make sure you read the SASS quick guide on imports.

To illustrate the above, here’s an excerpt of a custom.scss file:

@import "custom-variables";

// Base
@import "base/base.scss";

// Components
@import "components/alerts";
@import "components/buttons";
@import "components/datagrids";
@import "components/dataview";
@import "components/grid";
@import "components/groupbox";
@import "components/inputs";
@import "components/listview";
@import "components/modals";
@import "components/navigation";
@import "components/navigationlist";
@import "components/tabcontainer";
@import "components/tables";
@import "components/templategrids";
@import "components/typography";

// Layouts
@import "layouts/base";

In case you want to add a file you simply @import it, which results in:

@import "custom-variables";

// Base
@import "base/base.scss";

// Components
@import "components/alerts";
@import "components/buttons";
@import "components/datagrids";
@import "components/dataview";
@import "components/grid";
@import "components/groupbox";
@import "components/inputs";
@import "components/listview";
@import "components/modals";
@import "components/navigation";
@import "components/navigationlist";
@import "components/tabcontainer";
@import "components/tables";
@import "components/templategrids";
@import "components/typography";

// Layouts
@import "layouts/base";

// Custom FlowFabric stuff
@import "flowfabric/event";

Going beyond the default framework

Mendix SASS custom structureWhat about a third option? Andrew Hagens rightfully pointed me to the fact that you could also create your own folder which resides at the same level as the custom and lib folders. By going for this approach, you’ll be able to develop a package (or: theme) of components which can become a truly independent layer that is implemented on top of the base framework provided by Mendix. I believe that such an approach is especially useful when wanting to extend the base framework with additions. Or when simply developing a standard look for a multitude of applications belonging to the same company, to better align the look and feel with the company’s identity. The beauty of this approach is that once you have the developed package, it then simply becomes a matter of making sure the folder is added to each application. Easy, right?

Some final thoughts

Sure, in hindsight using SASS with Mendix isn’t all that complex, but somehow I felt a bit puzzled when I first attempted to understand the structure. This holds especially true because the Mendix documentation simply only guides you towards the _custom-variables.scss file. At the same time I was also trying to cope with everything that SASS had to offer. The fact that (of course) there simply isn’t one correct structure or approach also made it more confusing for me as I was trying too hard to find a correct structure.

💡 Do try to use the variables defined in the _custom-variables.scss file as much as possible, as it simply prevents a lot of hassle and helps you better maintain the colors and font-sizes used throughout your project.

Hopefully, this guide will have prevented you from getting into the same confused state of mind I had while exploring the new Mendix + SASS world for the first time.

In case you’re interested in more background information on SASS, of course there’s Google that can help you out 🙂 ,  but here are some of the links mentioned throughout this article which I found really useful: SASS-langScotch.io, The SASS way, Webdesigner Depot.

Happy styling! 😀

4 comments Add yours
  1. Is there a way to autodeploy changes without having to rebuild. Sass recompiles whatever it needs to in %PROJECT_DIRECTORY%/theme/styles, but does not deploy to %PROJECT_DIRECTORY%/deployment/web/styles. For that I currently have to resort to a batch script.

    Thankyou

  2. After starting with styling on my own and I have come to the same conclusions. I really like the article and the way things are explained here.

Leave a Reply

Your email address will not be published. Required fields are marked *