Upgrading the TagSelector Widget for Mendix 11.6.6: A Step-by-Step Guide - Mendix Forum

Upgrading the TagSelector Widget for Mendix 11.6.6: A Step-by-Step Guide

0

This article documents the process of upgrading the open-source TagSelector pluggable widget to be fully compatible with Mendix 11.6.6. The original repository, maintained at https://github.com/mendixlabs/TagSelector, was built targeting earlier versions of the Mendix platform and required a series of targeted modifications — including dependency updates, TypeScript compatibility fixes, and build configuration adjustments — before it could be successfully compiled and deployed in a Mendix 11.6.6 environment.


This guide is intended for Mendix developers with basic familiarity with Node.js, npm, and pluggable widget development using Visio Code.


The TagSelector widget allows end users to select and assign multiple tags to a Mendix object through an intuitive input interface. While widely used in Mendix 9 and 10 projects, the widget presents compatibility issues when introduced into a Mendix 11.6.6 application, primarily due to breaking changes in the pluggable widget toolchain and stricter TypeScript enforcement.


This article covers:


Prerequisites

Before proceeding, ensure the following tools are installed on your development machine:


Begin by cloning the official TagSelector repository from GitHub: 

git clone https://github.com/mendixlabs/TagSelector.git


Install the project dependencies using npm: 

npm install


Upon attempting an initial build with npm run build, several errors surface related to Mendix 11 compatibility. The root causes are:


Open package.json and apply the following modifications: 

{
  "name": "TagSelector",
  "widgetName": "mendix.tagselector.TagSelector",
  "version": "1.0.0",
  "description": "Tag Selector widget for Mendix 11",
  "clientModule": {
    "widgetFiles": ["TagSelector.mpk"]
  },
  "scripts": {
    "start": "pluggable-widgets-tools start:web",
    "build": "pluggable-widgets-tools build:web",
    "lint": "pluggable-widgets-tools lint",
    "test": "pluggable-widgets-tools test"
  },
  "devDependencies": {
    "@mendix/pluggable-widgets-tools": "^10.0.0"
  },
  "peerDependencies": {
    "mendix": "^11"
  }
}

Then update the toolchain package: 

npm install @mendix/pluggable-widgets-tools@^10.0.0 --save-de


Fix Import Declarations 

//  Before — old import pattern
import { Component, createElement } from "react";
//  After — functional component with explicit React import
import { createElement, ReactElement } from "react";


Fix ObjectItem and Attribute Value Handling

Mendix 11 enforces stricter null safety on attribute accessors. Add explicit null checks:

//  Before — unsafe access
const label = props.labelAttribute.get(item).value;
// After — safe access with fallback
const label = props.labelAttribute.get(item).value ?? "";


Fix ValueStatus Check Before Rendering

Always verify that the datasource is available before attempting to render:

import { ValueStatus } from "mendix";
// Add status guard at the top of your render function
if (props.tagSource.status !== ValueStatus.Available) {
    return <div className="tag-selector-loading">Loading...</div>;
}


Fix Deprecated EditableValue Action Call

//  Before — deprecated pattern
props.selectedTagsAttribute.setValue(newValue);
//  After — use with validation guard
if (props.selectedTagsAttribute.status === ValueStatus.Available) {
    props.selectedTagsAttribute.setValue(newValue);
}


Fix Function Component Return Type

Ensure the main exported function explicitly declares its return type:

//  Before
export function TagSelector(props: TagSelectorContainerProps) {
// After
export function TagSelector(props: TagSelectorContainerProps): ReactElement {


Building the Widget

Once all changes have been applied, run the build command: 

npm run build


A successful build produces the following output:

dist/TagSelector.mpk← Compiled widget package ready for Mendix


Copy the .mpk file 

# Copy the compiled widget to your Mendix project's widgets folder
cp dist/TagSelector.mpk "C:\path\to\your\MendixProject\widgets\"


Synchronize in Studio Pro

Studio Pro

Press F4 (or Menu → App → Synchronize App Directory)

Studio Pro detects the new .mpk

Widget is registered and available in the toolbox


Clean and Rebuild (If Widget Was Previously Installed)

If a previous version of TagSelector was already present in the project:

Studio Pro

App → Show App Directory in Explorer

Navigate to: deployment/web/widgets/

Delete old TagSelector files

Press F4 to resync

Run Locally (F5)


Verify at Runtime

Run Locally (F5)

Open the browser

Navigate to the page containing the TagSelector widget

Open F12 → Console

Confirm: no errors related to TagSelector


References

TagSelector Repository:

https://github.com/mendixlabs/TagSelector

Mendix Pluggable Widgets Tools:

https://github.com/mendix/pluggable-widgets-tools

Mendix Pluggable Widget How-To:

https://docs.mendix.com/howto/extensibility/create-a-pluggable-widget-one/

Pluggable Widgets API Reference (Mendix 11):

https://docs.mendix.com/apidocs-mxsdk/apidocs/pluggable-widgets/



This guide was produced based on hands-on debugging and migration experience upgrading the TagSelector widget for a Mendix 11.6.6 production environment. Contributions and corrections are welcome via the GitHub repository.


Regards


Posted
0 comments