Making your first custom widget

Learning a new skill can be a daunting task, this is especially true if you’ve never done anything remotely similar to what you’re trying to learn. Freshly graduated from a Java traineeship I set foot in the world of low-code development in Mendix. It is truly amazing what you can achieve with a set of generic plug and play modules, but sometimes that isn’t enough and you need some customization, and so the journey begins.

Prerequisites

We assume you have at least:

Basic understanding of Mendix, i.e. you know how to create microflows and make pages.
Basic understanding of Javascript, i.e. you know how functions and callbacks work,
Basic understanding of CSS, i.e. you know how to give text a different color and know the basics of selector specificity.
Basic understanding of HTML.

If not follow the excellent tutorials in the links.

Goal

We will be making customer checkout pages that we will enhance with some custom widgets, while still making use of the excellent platform features Mendix offers. For this tutorial I will be using Windows 10, with Mendix 7.21 download the complete code here.

The widgets are located in your project folder (Project -> Show project directory in explorer), under the /widgets directory. You will see various pre-bundled widgets, all rocking the .mpk extension. However, don’t be fooled as they are just .zip files with a fancy extension. You can prove this by opening it with for instance 7-zip. Inside you find this typical file structure:

SEARCHINPUT
│   package.xml
└───SearchInput
    │   SearchInput.xml
    └───widget
        │   SearchInput.js
        ├───template
        │       SearchInput.html
        └───ui
                SearchInput.css`

Figure 1: The typical filestructure of a custom widget, in this case the Searchinput widget.

This structure will be the same for 99% of custom widgets, so familiarize yourself with the structure, the individual files are explained below:

Package.xml: This file defines the location of the files containing the code and the location of the widgetName.xml file,
WidgetName.xml: This file contains the settings that you can set in the modeler.
WidgetName.js: This is where most of your javascript will be written.
WidgetName.html: This will house your HTML when you are using a templated widget.
WidgetName.css: The styling specific for this widget, you should always use this file to style your widget so that it may be used independently in another Mendix project.

For the first tutorial I will supply this readymade widget. This widget basically just displays a string that you can type in the modeler. Begin by downloading the .mpk file and unpacking it. Open the PersonalGreeter.js file in a text editor, I recommend Visual Studio Code, on line 77 you will find this block of code.

        dojoStyle.set(this.domNode, "display", "block");
        if (this._contextObj !== null) {
            // Future code will come here.
        } else {
            var greeterNode = dojoConstruct.toDom("Hello World");
            dojoConstruct.place(greeterNode, this.domNode);
        }

This just displays hello world on the page. Don’t believe me? Open the /test/TutorialWebshop.mpr project and run it. Log in using the demo_user account, with the password that you find under:

Project ‘TutorialWebshop’ -> Security -> Demo users -> double click demo_user -> copy password to clipboard.

Run the project and you will see the message on the homepage.

However, we would like to make this a bit more personal. So let’s get in the account entity so that we can greet the user with his or her own name!

Open the PersonalGreeter.xml file,
Change the needsentity attribute to true. This will tell the modeler that we need to put the widget in a part of the page that provides a Mendix object (e.g. a data view, or a page parameter).
Go to the homepage, put down a data view with ‘account’ as entity and keep the data source type to ‘context’, press ok and select no when asked to prefill the dataview.
Finally, place the ‘personalgreeter’ widget in this dataview. Mendix wants us to provide the account entity when making the page, so we open up the ACT_OpenHomePage microflow and set the ‘object to pass’ on the ‘open page’ action to ‘AccountForUser’.

Now go back to your unzipped widget and find the update function in PersonalGreeter.js (line 59), and take note of the parameter. The function has a parameter (obj) that we can access inside the update function. This parameter is the Mendix object of the enclosing dataview, in our case the page parameter account. The type is a MxObject, the javascript representation of an instance of a Mendix entity. We can commit it, change it, read it, and do most of the things that you can also do in the modeler from our widget. We would like to just know the name, so we only use the get function. This function accepts the name of the attribute and returns it’s value.

So let’s change the “hello world” example to something more meaningfull. We are going to replace some code in the “_updateRendering” function, this function can be used to update the DOM. Replace the old code in the _updateRendering function with the one below, but keep the debugger line, and the call to execute callback.

        //0
        if (this._contextObj !== null) {
            // 1
            var name = this._contextObj.get("Name");
            // 2
            var greeting = dojoConstruct.toDom("Hello " +  name);
            // 3
            dojoConstruct.place(greeting, this.domNode)
        } else {
            dojoStyle.set(this.domNode, "display", "none");
        }

Since we put our widget in a dataview, the _contextObj will be defined at line 62. First we get the property name from the contextObject, in our example this object is the ‘Account’ entity provided in the dataview. Subsequently we construct a DOMnode using a Dojo library. And finally we place the node inside the domnode of the widget. If this seems a bit confusing, no worry we will be going more in depth about Dojo and Mendix widgets in the next tutorial. So let’s zip the folder, but try and save it as a .mpk file. When completed, copy the new PersonalGreeter.mpk file to the /widgets directory of your project folder. In the modeler press project -> synchronize project directory (F4) to make sure that the widget you just copied actually gets picked up by the modeler. Since we changed the personalgreeter.xml we have to update our widget, go to the homepage, right click the widget and select ‘update widget’. Save the page and rerun the application. If everything went well you will be greeted with your own name (If your name is demo_user ;) )

Gotcha’s

When zipping the file make sure that the folder structure is exactly the same as in figure 1, if not you will get error messages like:

Package 'C:\Users\%username%\%MendixFolder%\%MendixProject%\widgets\PersonalGreeter.mpk': File 'package.xml' not found.

Conclusion

In this step we learned how to edit and include a custom widget in Mendix. Furthermore, we used the Mendix Client API to get an attribute from a MendixObject.

Final code

The final code is available here.

The next step

Advance to the next step to learn how the inner workings of a Mendix widget work and leverage this knowdledge to create a custom currrency widget for our customers.

Learning the widgettemplate »

Niels de Haas