Custom Widgets
Get started with Mendix Pluggable widgets.
Overview
Mendix provides a bunch of widgets in Studio Pro to use on pages. You can download additional ones built by Mendix and the developer community from the Marketplace. You can also modify widgets or build your own. Mendix calls them Pluggable Widgets. They are built with the popular React JavaScript library.
1. Mendix Widgets Overview
Mendix widgets are .mpk files located in the \widgets directory under the Mendix project directory. You can find the project directory on your local drive by going to App > Show App Directory in Explorer in Studio Pro. Underneath that directory will be the \widgets directory.
When you download a widget, it is put in the widgets directory. If you no longer need it, you can delete it from that directory. Be sure it isn't used before you delete it or you will get errors.
An .mpk file is a Mendix app PacKage. It has all the code and assets needed to run a widget. It's just a .zip file. If you use 7-Zip or another archiving utility, you can open the .mpk file and see the directory structure and files inside.
2. Prerequisite Knowledge
HTML, CSS, and SASS
Widgets on a page are rendered with HTML markup and CSS ("Cascading Style Sheets") styles. Mendix uses SASS, "Syntactically Awesome Style Sheets", which is an improvement of CSS that allows additional syntax to simplify writing CSS. You can use plain old CSS in SASS files.
TypeScript and JavaScript
You will need a decent understanding of JavaScript and TypeScript. TypeScript is just JavaScript with object types added. If you know TypeScript, you'll already know JavaScript.
JavaScript is very flexible. You can create variables and use them for different types of primitives. For example, you could use the same variable for a text string ("172") and a number (172). This can cause problems when you process the variable because you might accidentally try to handle it as a number when it should be handled as text. TypeScript adds object types to prevent these errors before you even run the code. Mendix writes their widgets with TypeScript.
Node.js and NPM
Mendix provides tools to build, run, and test pluggable widgets on a local Node.js server. You don't need deep knowledge of Node.js, but a basic understanding of how the Node Package Manager (NPM) works is useful. NPM is used to include libraries of code, including standard Mendix core libraries in your widget project. You need these libraries to interface with Mendix.
React.js Javascript library
Mendix uses React, a Javascript library originally built by Facebook to standardize and simplify building web components. There are other libraries that have emerged that improve on React, like Vue and Svelte, but React has a large developer community and thousands of web components.
DOM and Web Components
It is extremely helpful to understand the Domain Object Model (DOM) that browsers use to render HTML pages and how web components in XML are included in an HTML page. Mendix pluggable widgets are reusable web components written in TypeScript / JavaScript using React libraries that can be dropped onto a page.
3. Build a Mendix Pluggable Widget
The Build Pluggable Web Widgets documentation is (mostly) very helpful. There is also a reference to Build a Pluggable Native Widget.
Note: An essential step was left out in Build a Pluggable Web Widget: Part 1 after generating the widget scaffolding code with yo @mendix/widget {widget name}, answering the questions, and adding the attribute in section 3.3. Before running npm start (or npm run build) in step 3, you must run npm install before that in the widget root directory. For example, if you named the widget TextBox as in the tutorial:
1. If you haven’t done this before, install Yeoman and the Mendix Pluggable Widget Generator to the global Node library (which is what the -g option does). This only needs to be done once for all widget development. If you delete Node then you’ll have to do this again.
2. Generate the widget scaffolding code for the new widget, which creates a directory with the name you entered for the widget (TextBox) under the current directory. By default the first letter is lowercase (textBox).
3. Go to the widget root directory and run npm install or npm install --legacy-peer-deps which will create a node_modules directory under the root.
4. After making changes to the code, build the widget and deploy it to the Mendix project directory you specified (you can change this by editing projectPath under config in package.json).
Or you can use
The latter, npm start, will launch a server that watches for changes to the code and automatically recompiles.
5. In either case you still have to go to the Mendix project and Synchronize App Directory (F4 or go to App > Synchronize App Directory). If there are errors, right-click on the widget and Update Widget or Update All Widgets.
4. Modify a Mendix Pluggable Widget
(under construction)
FAQs
(under construction)