How to Convert Your UI When Upgrading to DX
How to Convert Your UI When Upgrading to DX by Russell Hite
If you’re upgrading your pre 5.18 application to capitalize on the features of the latest Mendix release, here is a guide to help you navigate the new UI features in the latest releases.
The UI DX features can be split into two categories: modeler features and the UI framework. By default, all UI elements will remain the same. Upgrading the elements is completely voluntary, and should only be done if you answer yes to either of the following questions:
- Are you looking to changes the entire look and feel of your application, by updating the styling?
- Are you looking to make part or all of your application’s layouts transition between desktop and mobile views, aka a responsive application?
DX UI setup
Before you can begin to use any of the new UI features you need to check your project’s index file. To utilize the latest feature you need to ensure that bootstrap.css is being imported. Open up your index.html file in your project folder and check to make sure something like this line is present:
<link rel=”stylesheet” href=”mxclientsystem/mxui/ui/mxui.css>
If it is not there then add it. All the features in both the modeler and framework hinge on that being present.
Updating the Styling
Before I delve into the step-by-step on how to upgrade, here are the tools we recommend using.
The UI framework uses a CSS pre-processor called Sass. You can learn more about leveraging the power of Sass here.
Sass allows us to break apart huge CSS files to be more legible pieces. In order to convert all those pieces back into CSS that your app can use, you also need a compiler. We recommend using Koala, http://koala-app.com/.
And lastly due to the multi-file nature of Sass we recommend you use a text editor like brackets, http://brackets.io/, which allow you to see your folder structure.
By upgrading to the UI framework you can centralize all your styling, making maintenance easier. This should be done on a separate branch line. In order to integrate your current CSS with the framework, take the following steps:
- Copy and move your current CSS file(s) outside of the project folder.
- From the Modeler, go to the App Store and download the “Vanilla theme”.
- Do not run your application, but first go to the theme folder within your project.
- Open up Vanilla.zip and copy its contents into the theme folder.
- Delete the Vanilla.zip and Vanilla folder.
- Open Koala and add your project > theme > style to be watched
- Open project > theme > style in brackets or text editor of your choice.
- From your style folder navigate to Sass > lib > project and create a new Sass partial called _your-project-name.scss.
- Open up and copy the old CSS files you moved in step 1.
- Paste content into the new Sass partial from step 8.
- Open up the file lib.scss in the lib folder.
- Add @import “project/your-project-name”; to the bottom of the file.
- Save all updated files.
- In the Modeler > Settings change the theme to Default.
- Run your application.
UI Features Within the Modeler
With the release of DX there was a fundamental shift in the HTML structure of Mendix apps. Prior to the release, nearly all apps used tables to layout content. This has now been replaced with the new layout grid, and the layout widget enables you to create responsive layouts.
So you may be asking yourself, “If my app is upgraded to the latest release, how should I go about upgrading my page layouts?” Before you undergo the task of converting all your tables to layout grids, you should honestly ask yourself one question.
“Will this app be used on mobile, and does it need to be mobile friendly?”
If your end users are using this app primarily on a desktop, then leave your app the way it is. I’d recommend only updating the pages to use the layout grid that contain functionality for mobile.
So now that you have decided on which pages you need to rebuild with the layout grid, lets understand how it works. The layout grid works with the bootstrap grid system at its foundation. The layout grid has two key concepts: the column and the viewport.
Every layout grid row is made up of a total of 12 columns, which are represented as the number above every column.
There are 4 viewports: xs, sm, md, and lg. Each represent a span of browser widths and corresponding devices. By default they represent 480 pixels or less for mobile devices, 481 – 768 pixels for tablets, 769 -992 pixels for desktops, and 993 pixels and above for very wide desktop monitors. By default the viewport size in the modeler is set to medium.
The viewport is only evident when you run your application. If you set a row to 4 columns of 3 points each, you’ll notice when you resize your browser that there is a point where it will change from 4 columns to 1. In order to control widths of the columns for the different viewports, classes can be added to each of the columns. All the classes to facilitate this can be found here.
For example, if you want to change the 4 column grid to be 2 rows of 2 columns, add
col-xs-6 to every column. Now when you run the application and resize the browser it will switch to two columns instead of one. One thing to remember when adding these extra classes to your columns is that every viewport size need to equal rows of 12.