<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Ivo Sturm on Medium]]></title>
        <description><![CDATA[Stories by Ivo Sturm on Medium]]></description>
        <link>https://medium.com/@ivo.sturm?source=rss-b43844a7f8d5------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*d0CB-eYfA7COXx0D-svqrA.jpeg</url>
            <title>Stories by Ivo Sturm on Medium</title>
            <link>https://medium.com/@ivo.sturm?source=rss-b43844a7f8d5------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 21:45:11 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@ivo.sturm/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How I Automated Microsoft Word Templating in Mendix Using The Apache POI API]]></title>
            <link>https://medium.com/mendix/how-i-automated-word-templating-in-mendix-with-the-apache-poi-api-4549163b0acc?source=rss-b43844a7f8d5------2</link>
            <guid isPermaLink="false">https://medium.com/p/4549163b0acc</guid>
            <category><![CDATA[microsoft-word]]></category>
            <category><![CDATA[document-generation]]></category>
            <category><![CDATA[apache-poi]]></category>
            <category><![CDATA[tips]]></category>
            <category><![CDATA[mendix]]></category>
            <dc:creator><![CDATA[Ivo Sturm]]></dc:creator>
            <pubDate>Mon, 07 Nov 2022 12:17:44 GMT</pubDate>
            <atom:updated>2023-01-26T14:54:27.788Z</atom:updated>
            <content:encoded><![CDATA[<h4>The world loves Microsoft Office. As a result, most Mendix developers will end up working on a project in which Word documents will need to be generated from your app.</h4><figure><img alt="How I Automated Microsoft Word Templating in Mendix Using The Apache POI API (Banner Image)" src="https://cdn-images-1.medium.com/max/1024/1*mFev4F-qqSa3gegHgbK6vw.png" /><figcaption>How I Automated Microsoft Word Templating in Mendix Using The Apache POI API</figcaption></figure><h3><strong>Mendix Word document generation</strong></h3><p>When it comes to Word documents, Mendix has its own built-in document template design system. Even though it’s a bit clunky to use, you can create great documents from your Mendix apps data. The main concept is that <strong>Mendix</strong> will create the Word document with all its data.</p><h4><strong>Word Templates</strong></h4><p>Over the past eight years, I have seen several use-cases where there is a need to maintain the template in Word itself and let Mendix add/change the Word document. This is specifically interesting if many types of documents need to be generated for different clients within a Mendix app; each client needs its own details in the generated Word document, but the template is mostly generic in structure for all clients. How great would it be if we could maintain the basics of the template in Word and let Mendix automatically populate the Word template to make it client specific? So:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_6ev7V2SWQfxJwRAFbfDuw.png" /><figcaption>Dynamically change words in the template and add rich text, images and lists</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cxEP8yvvdACsoIWufysuBQ.png" /><figcaption>Populate chart template with data from your Mendix app</figcaption></figure><h3><strong>Apache POI</strong></h3><p>The go-to Java library for manipulating MS office documents is the <a href="https://poi.apache.org/">Apache POI library</a>. This Java library has out-of-the-box APIs to create and manipulate the most common Office documents such as Excel and Word. Both Mendix modules related to exporting to and importing from Excel heavily depend on the usage of this library.</p><p>I started to read up on the possibilities of Apache POI and it seemed that accessing word templates wouldn’t be too hard. Indeed that wasn’t the hard part. In some five lines of code, a Word document can be opened and its content manipulated.</p><p>I was in need of a couple of additions Mendix document generation was missing:</p><p><strong>1.</strong> <strong>Word replacements</strong>: replacing a specific word with bookmark value to another (client-specific) value coming from the Mendix app</p><p><strong>2.</strong> <strong>Placing content</strong> (table, (un)ordered lists, image) in an existing word document</p><p><strong>3.</strong> <strong>Rich Text support</strong></p><p><strong>4.</strong> <strong>Manipulating Charts</strong></p><p>Below I will cover all four challenges. I will conclude with a fallback scenario on what to do if the Apache POI library is missing some direct function to get what you need.</p><h4><strong>Word replacements</strong></h4><p>What seemed like a very standard feature, turned out to be fairly complex. This is one of the main reasons why several paid libraries out there have created their own IP on how to access words in a Word document.</p><blockquote>The challenge comes from the fact that any word in a Word document will be divided into so-called ‘<em>runs</em>’. One can’t know upfront how many runs a word will consist of.</blockquote><p>For sure adding a different font or font size will increase the run size. The more complex (both in terms of length and formatting) the word is, the more runs will be created for the word. So, if you want to programmatically search the word document, you have to check all possible runs a word can be part of, combine the texts in these runs and compare with the value the logic is searching for. This is quite challenging as the number of permutations on segments/runs of a word to look into, can grow quickly.</p><p>Happily, there is someone who has a solution for a word consisting of up to threeruns. I implemented <a href="https://github.com/deividasstr/docx-word-replacer">this library</a> by adding the WordReplacer helper class, which has several functions for replacing words in plain text as well as in tables:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*Iud21nv7zlalujNvxFSgiQ.png" /></figure><blockquote><em>As a side note; since only a maximum of three runs are supported for word replacements, stick to simple (no formatting) and short bookmark values without spaces/special characters.</em></blockquote><h4><strong>Placing content</strong></h4><p>If you want to add some (rich) text, table, (un)ordered list, or chart into an existing document, you need a mechanism to manage where the content will be added. Gladly it turns out that tables are very well supported within the Apache POI library and exact positions can be retrieved by using tables as placeholders. The idea is to associate this Mendix content to some Word table cell content name. The code will then open the Word document and search for a 1-by-1 table (so only one cell) with exactly that name as content. It will add the dynamic content there and remove the table altogether.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*KccanZaz63HVnb3sfTJ0wg.png" /><figcaption><em>Code Snippet 1: Moving to the position of the dummy table with the XMLCursor and adding content there with the help of this XMLCursor.</em></figcaption></figure><h4><strong>Rich Text</strong></h4><p>How nice would it be if text formatted as rich text in your Mendix app, could be visualized in the same manner in the Word document? Rich text on a webpage is typically HTML-formatted text. Based on the HTML tags it can be deduced what font formatting to add. I have found a very consistent library, called <a href="https://jsoup.org/">Jsoup</a>, which can properly handle rich text. Jsoup introduces the concept of iterating a stacked HTML structure which is exactly what rich text is.</p><p>Just enter your text as rich text with the CK Editor for Mendix. The module will use the Jsoup library to navigate and iterate the HTML structure and the Apache POI library to enforce specific formatting based on the type of HTML node being iterated over:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*FzckPKdEkJAsrlckhQIZfA.png" /><figcaption><em>Code Snippet 2: Part of the RichTextParser class I created for handling rich text</em></figcaption></figure><h4><strong>Manipulating Charts</strong></h4><p>A feature lacking in Mendix document generation and a real “nice to have feature” is support for charts in a Word document. The idea is that the default chart template is added to the Word template already. Based on Mendix data the chart will be built with possibly multiple different series. The Apache POI library can access the Excel add-in data table that a Word chart uses as a data source:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*AtcXYlOqwfsXxROzW8KdPg.png" /><figcaption>The underlying Excel worksheet of a chart in Word</figcaption></figure><p>And directly manipulate this data set and trigger a refresh of the chart based on this data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*AXEk0sZNgKn16TJrSZkZYg.png" /><figcaption><em>Code Snippet 3: Fill the underlying Excel chart data with series/category data coming from your Mendix app.</em></figcaption></figure><p>If there were more categories in the template than in Mendix, those obsolete series would be removed.</p><blockquote><em>Currently, </em><strong><em>only (stacked) bar and line charts are supported</em></strong></blockquote><h4><strong>What if Apache POI is lacking?</strong></h4><p>The Apache POI library has a feature-rich set of functions for manipulating MS Office products with Java. It can occur, however, that the Apache POI doesn’t support a specific feature yet with a directly available java method for instance changing some specific formatting in a Word graph. Always try to cover it within the template first, but if a real extension to the java code is needed, it is important to understand that <strong>a Word file, just like an Excel file, is nothing more than a zipped folder of XML files</strong>. By unzipping and checking the XML it can be quite easy to find the exact XML tag which is needed to add a specific feature. Just add the feature in Word, save the file and check in the XML it consists of what XML tag is added/changed. See below for the unzipped Word template file which comes with the project:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*EMvqYAdjmnCnZH9eXR-1Kg.png" /><figcaption>A Word document is actually a zipped XML archive</figcaption></figure><p>By locating the specific XML tag there is a fallback scenario in which via the Apache POI library one can access these specific tags and manipulate those. See for instance below a fix on how to set the numbering for item lists by accessing the lower-level XML tags (CTP, PPR, NumPr):</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*oJOzvmI_yd9HfyDhYqZ_9A.png" /><figcaption><em>Code Snippet 4: Accessing lower-level XML tags of Word document</em></figcaption></figure><h3><strong>Demo Project</strong></h3><p>The fully working demo project which demonstrates all the above-mentioned features is <a href="https://marketplace.mendix.com/link/component/111539">available</a> within the Mendix Marketplace. Just download it, run the project and upload the test template that comes with the project to quickly see its capabilities. The test template can be found in the resources folder.</p><blockquote><a href="https://marketplace.mendix.com/link/component/111539/Valcon/Word-Template-Demo-Project"><strong>https://marketplace.mendix.com/link/component/111539/Valcon/Word-Template-Demo-Project</strong></a></blockquote><h3><strong>Known bugs</strong></h3><p>Currently, there are no known bugs. It is good to understand that this module uses the same Java library, Apache POI, which the Mendix modules ‘Excel Importer’ and ‘Excel Exporter’ use. <strong>Be sure to keep those libraries aligned</strong>, so all modules use the same version of the Apache POI library, currently 5.2.2.</p><h3>Demo app</h3><p><a href="https://wordexporter127-sandbox.mxapps.io/index.html">Mendix</a></p><h4>Read more</h4><ul><li><a href="https://poi.apache.org/">Apache POI™ - the Java API for Microsoft Documents</a></li><li><a href="https://poi.apache.org/apidocs/4.1/">POI API Documentation</a></li></ul><p><em>From the Publisher -</em></p><p><em>If you enjoyed this article you can find more like it on our </em><a href="https://medium.com/mendix"><em>Medium page</em></a><em>. For great videos and live sessions, you can go to </em><a href="https://www.mendix.com/live/"><em>MxLive</em></a><em> or our community </em><a href="https://www.youtube.com/c/MendixCommunity/community"><em>Youtube pag</em></a><em>e.</em></p><p><em>For the makers looking to get started, you can sign up for a </em><a href="https://signup.mendix.com/link/signup/?source=direct"><em>free account</em></a><em>, and get instant access to learning with our </em><a href="https://academy.mendix.com/link/home"><em>Academy</em></a><em>.</em></p><p><em>Interested in getting more involved with our community? Join us in our </em><a href="https://join.slack.com/t/mendixcommunity/shared_invite/zt-hwhwkcxu-~59ywyjqHlUHXmrw5heqpQ"><em>Slack community channel</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4549163b0acc" width="1" height="1" alt=""><hr><p><a href="https://medium.com/mendix/how-i-automated-word-templating-in-mendix-with-the-apache-poi-api-4549163b0acc">How I Automated Microsoft Word Templating in Mendix Using The Apache POI API</a> was originally published in <a href="https://medium.com/mendix">Mendix Community</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How I rewrote the Mendix ArcGIS widget in React TypeScript]]></title>
            <link>https://medium.com/mendix/how-i-rewrote-the-mendix-arcgis-widget-in-react-typescript-4cf2158c2267?source=rss-b43844a7f8d5------2</link>
            <guid isPermaLink="false">https://medium.com/p/4cf2158c2267</guid>
            <category><![CDATA[ui]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[mendix]]></category>
            <category><![CDATA[low-code]]></category>
            <category><![CDATA[arcgis]]></category>
            <dc:creator><![CDATA[Ivo Sturm]]></dc:creator>
            <pubDate>Thu, 23 Jun 2022 10:51:06 GMT</pubDate>
            <atom:updated>2022-06-23T10:51:06.144Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="How I rewrote the Mendix ArcGIS widget in React TypeScript (A globe surrounded by the React.js logo against a starry sky)" src="https://cdn-images-1.medium.com/max/1024/1*7-mK-BpSR_Aaw1os74hsWg.png" /><figcaption>How I rewrote the Mendix ArcGIS widget in React TypeScript</figcaption></figure><h3><strong>Geographical visualizations in Mendix</strong></h3><p>At my job at Valcon, I have built many applications over the past 10 years. For a lot of our clients, the geographical aspect of their business is an important part of the day-to-day work. Think for example of infrastructure companies owning assets, construction companies doing projects at a variety of places, and utility companies using resources. Most of the Mendix projects we do therefore have a geographical component. In this type of project, it is important to connect the day-to-day business to geographical visualizations.</p><p>One of the first steps in connecting the day-to-day business to geographical visualizations is to decide which platform to use. Two main players commonly used for these visualizations are Google (Maps) and Esri (ArcGIS). In <a href="https://medium.com/p/cfc6f9a17f66">my previous blog</a>, I shared my learnings on how I built a generic but fully customizable Google Maps widget. Today, I want to share my learnings on building another great — and freely available — ArcGIS widget.</p><h4>Esri ArcGIS vs. Google Maps</h4><p>When it comes to more advanced GIS needs, ArcGIS is a richer platform in terms of out-of-the-box functionality. ArcGIS is built to support business operations in their day-to-day work by extending with various out-of-the-box GIS features. When building a (Mendix) widget one needs an API to integrate both platforms.</p><ul><li>When it comes to API the ArcGIS API is a very complete API, with heaps of functions catering to all kinds of geographical needs.</li><li>Need to group your locations in layers, in need of a legend for your layers? Need the users to toggle visibility in layers? All these things are out of the box available with only a few lines of code needed, whereas in Google Maps these things need to be built yourself.</li><li>Next to that, ArcGIS comes with its geospatial database, hence there is no need to store the locations yourself.</li><li>One downside though, there is no full React-based ArcGIS API available just yet. Google Maps, on the other hand, has multiple. So, I was up for a challenge! a</li></ul><h4><strong>Upgrading ArcGIS widget</strong></h4><p>For some time already Mendix is in the process of moving its complete front end from Dojo to React. Around five years ago, I built an <a href="https://marketplace.mendix.com/link/component/106094">ArcGIS widget</a> using Dojo which has been successfully used by many clients with close to 1000 downloads:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/739/1*_OrSjsz-iRTJVIvcjOGOEg.png" /></figure><p>The widget was built with the old Mendix Client API and the now outdated ArcGIS JavaScript API v3. Upgrading the widget was going to be a major challenge. I had to completely rewrite the ArcGIS widget based on React and TypeScript, the newest ArcGIS API, and the Mendix Pluggable widget API. The challenging process can be summarized with the below six observations:</p><h4><em>1. No full React-based version</em></h4><p>The first challenge was the fact that there is no full React-based version of the ArcGIS API. For Google Maps, there are multiple. I guess the main reason is that the ArcGIS API is very extensive, hence creating and maintaining a React-based version of it is a huge effort. In the end, I wrote the full widget with an on-load event using the <strong>useEffect</strong> hook and some <strong>React Refs</strong> to make sure I could always access the right version of the data throughout each rerender React deems necessary.</p><h4><em>2. The ArcGIS API is huge!</em></h4><p>Since the ArcGIS JavaScript API has such an extensive set of features, all specific features are nicely built into separate JavaScript files. These files need to be loaded with the widget as well. In the current version, <strong>almost 25 MB of JavaScript/CSS files</strong> need to be loaded for the ArcGIS API to properly function. For this to work, the most important part is to add the below code to the file <em>webpack.config.dev.js</em>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gSSdgy9eLG8KwmwG6frdxg.png" /></figure><p>Be sure to also check which (dev) libraries need to be installed with NPM, by checking the <em>package.json</em> file.</p><h4><em>3. Main ArcGIS objects need a Mendix counterpart</em></h4><p>Via the pluggable widgets API, the new ArcGIS widget can now be fed via all data sources like nanoflows. As a result, the Mendix objects will be available in the widget. The Mendix objects (points, layers) need a translation to their ArcGIS counterpart to appear on a map via the ArcGIS API. The widget needs to keep track of two arrays of all objects: one in the Mendix objects (data source) and one in typings of the ArcGIS JS API. For this, I used <strong>React Refs</strong> to make sure I always have the right version of the objects during each rerender React would deem necessary.</p><h4><em>4. Be aware of what to create once and what to update</em></h4><p>I added an isLoaded boolean to the State of the ArcGISContainer component, which is also shared with its parent ReactArcGIS component as a property. In this way, both the ArcGISContainer and ReactArcGIS component always ‘know’ whether the widget was already loaded. Things that are only loaded once are the layers, both the static configured layers and the dynamic layers from the data source:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/908/1*NJsyE4ry9EgO_rvIQT73BQ.png" /></figure><p>Mind the<em> @ts-ignore</em>: not best practice, but needed here, since the get function isn’t recognized in TypeScript but does exist.</p><h4>5. Only rerender if a data source changes</h4><p>React has its mechanism of rerendering concerning the status of data sources in Mendix. Data sources can have multiple statuses and for each status change (i.e. ‘Loading’ &gt; ‘Available’) a rerender is triggered. Sometimes, this results in unnecessary re-rendering which prevents the map from working smoothly. Therefore, I implemented a boolean function that checks the availability of the data sources if the main data sources, layers, and GIS objects have an ‘Available’ status. Only then the widget will rerender itself</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/910/1*TBqSMdwBabWiRQ0jVvFZrQ.png" /></figure><h4><em>6. A Custom Popup: Use both ArcGIS and Mendix ‘owned’ attributes</em></h4><p>One of the great features of the widget is that it can connect Mendix and ArcGIS and access both ArcGIS attributes and Mendix-owned attributes. In this way, an info window pop-up can access and show data from both platforms. For this, I have created my <em>CustomPopup</em> component and <em>PopupUtils</em> TSX file. Because of a shortcoming in the Pluggable widgets API, it was still necessary to load the client API to get access to all attributes of an object not previously loaded via the data source.</p><h3>The result</h3><p>The result is a <a href="https://marketplace.mendix.com/link/component/120041">future-proof ArcGIS widget</a> with even more features like</p><ul><li>dynamically loading layers</li><li>configuring multiple layers of objects also existing in Mendix</li><li>enable marker clustering per layer</li><li>being able to fully configure the info window content with fields owned in both ArcGIS and Mendix</li><li>the option to add three sub widgets (location search, toggle layer visibility, legend) to the map for enhanced user interaction:</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nqygmRQtVDxWAGx6a110wA.png" /></figure><h4>Demo project</h4><p>It can be tricky to sort out the configurations needed for each scenario (listen to the grid, all objects, marker clustering, etc.). Therefore, I have created a <a href="https://marketplace.mendix.com/link/component/119997">fully working demo project</a> that will explain the setup for each scenario on the screen.</p><h3><strong>Conclusion</strong></h3><p>The rewrite of the ArcGIS widget to React TypeScript turned out to be a real challenge, but the result is even better than its predecessor, both in terms of functionality and user interface. In case of questions use the Mendix forum, contact me or dig into the <a href="https://github.com/ivosturm/ArcGIS-React">publicly available code on GitHub</a> yourself.</p><h4>Read more</h4><ul><li><a href="https://medium.com/mendix/build-widgets-in-mendix-with-react-part-1-colour-counter-f1e400c3cdff">Build widgets in Mendix with React — Part 1 — Colour Counter</a></li><li><a href="https://github.com/mendix/widgets-resources/tree/master/packages/pluggableWidgets">widgets-resources/packages/pluggableWidgets at master · mendix/widgets-resources</a></li><li><a href="https://docs.mendix.com/howto/extensibility/create-a-pluggable-widget-one/">Build a Pluggable Web Widget: Part 1</a></li><li><a href="https://docs.mendix.com/howto/extensibility/create-a-pluggable-widget-two/">Build a Pluggable Web Widget: Part 2 (Advanced)</a></li><li><a href="https://doc.arcgis.com/en/">Documentation</a></li></ul><p><em>From the Publisher -</em></p><p><em>If you enjoyed this article you can find more like it on our </em><a href="https://medium.com/mendix"><em>Medium page</em></a><em>. For great videos and live sessions, you can go to </em><a href="https://www.mendix.com/live/"><em>MxLive</em></a><em> or our community </em><a href="https://www.youtube.com/c/MendixCommunity/community"><em>Youtube pag</em></a><em>e.</em></p><p><em>For the makers looking to get started, you can sign up for a </em><a href="https://signup.mendix.com/link/signup/?source=direct"><em>free account</em></a><em>, and get instant access to learning with our </em><a href="https://academy.mendix.com/link/home"><em>Academy</em></a><em>.</em></p><p><em>Interested in getting more involved with our community? Join us in our </em><a href="https://join.slack.com/t/mendixcommunity/shared_invite/zt-hwhwkcxu-~59ywyjqHlUHXmrw5heqpQ"><em>Slack community channel</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4cf2158c2267" width="1" height="1" alt=""><hr><p><a href="https://medium.com/mendix/how-i-rewrote-the-mendix-arcgis-widget-in-react-typescript-4cf2158c2267">How I rewrote the Mendix ArcGIS widget in React TypeScript</a> was originally published in <a href="https://medium.com/mendix">Mendix Community</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Upgrading from Dojo to React]]></title>
            <link>https://medium.com/mendix/upgrading-from-dojo-to-react-cfc6f9a17f66?source=rss-b43844a7f8d5------2</link>
            <guid isPermaLink="false">https://medium.com/p/cfc6f9a17f66</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[how-to]]></category>
            <category><![CDATA[low-code]]></category>
            <category><![CDATA[ui]]></category>
            <category><![CDATA[mendix]]></category>
            <dc:creator><![CDATA[Ivo Sturm]]></dc:creator>
            <pubDate>Mon, 12 Apr 2021 11:00:39 GMT</pubDate>
            <atom:updated>2021-07-09T10:52:24.657Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KdzJtKy3QoPJQNI2iwvoEw.png" /></figure><p>Over the last 7 years I have been building many Mendix applications for just as many clients. One of the expertises I gained is in the field of extending the Mendix platform with GIS functionality using for instance Google Maps or ArcGIS. For both platforms I have published several components in the Mendix Marketplace, like the one I am writing this blog about, <a href="https://marketplace.mendix.com/link/component/117109">Google Maps Polygon</a>.</p><p>These more complex widgets have all been built on top of the Mendix Dojo JavaScript framework. I have been working with the Dojo framework just as long as I have been building Mendix apps, so moving to React was something new for me.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*upjSW1CUGNHMv5jGtfBDaw.png" /></figure><p>Mendix is in the process of moving their main JavaScript front-end framework from Dojo to React, mainly because the React framework is more futureproof. It does mean, however, that all widgets currently built in the Dojo framework will eventually stop working if the usage of the Dojo framework is really phased out. So, eventually all these widgets will need to have a React counterpart.</p><p>In this blog I want to share my takeaways on moving from Dojo to React, hoping it will help other developers on their tasks of upgrading their marketplace content. The main takeaways, handled one by one below, are:</p><ul><li>Choose correct React library!</li><li>Let React do the rendering!</li><li>Take full advantage of Pluggable Widgets API</li><li>Create components for heavily used objects</li><li>Choose carefully what is stored in state of each component</li></ul><h3><strong>1. Choose the correct React library</strong></h3><p>Once the widget is set up via the Mendix widget boilerplate, as explained in other blogs, like <a href="https://medium.com/mendix/building-a-pluggable-widget-url-image-viewer-6fd423858137">this </a>one, the first thing that needs to be done is importing the right React libraries. Next to importing the correct node modules, the typings needed to be loaded as well. It is key to choose the correct library. In my case I wanted to integrate with the Google Maps API. I quickly found out that there are already many React libraries out there. After looking into the three top ones:</p><ul><li>React Google Map</li><li>Google Map React</li><li><strong>Google Maps React</strong></li></ul><p>I chose the last one, and actually even an extension thereof <a href="https://www.npmjs.com/package/@react-google-maps/api">https://www.npmjs.com/package/@react-google-maps/api</a></p><p>There are three reasons for choosing this library:</p><ol><li>The library actually supports Polygons as React components, whereas for instance React Google Map doesn’t</li><li>The library is maintained quite well, see the active status on GitHub</li><li>Mendix also chose this library for the new Map widget</li></ol><figure><img alt="https://bit.ly/MXW21" src="https://cdn-images-1.medium.com/max/1024/1*KEVX4H5BL_VBX3sHpw_smw.png" /><figcaption><a href="https://bit.ly/MXW21">https://bit.ly/MXW21</a></figcaption></figure><h3><strong>2. Let React do the rendering!</strong></h3><p>At first I chose to pick another library, Google Map React, because that is the library the first <a href="https://marketplace.mendix.com/link/component/48911">Mendix Maps</a> widget was built in. After adding the modules and the first components, I found out that the Polygon component was not fully implemented with that React library as I should have known by properly reading the documentation of the React library:</p><blockquote>google-map-react is a component written over a small set of the Google Maps API. It allows you to render any React component on the Google Map.</blockquote><p>Especally the part ‘small set’ turned out to be very important and resulted in quite some waste time from my side. I tried to create the Polygon object as a React component myself which I achieved, but then I also had to add InfoWindow objects. An InfoWindow is an actual pop-up that can be shown when clicking on the map itself or an object on the map. Since for the widget I needed to add a button that can trigger an action (show page/run microflow etc) I needed a bit more complex HTML to be shown in the info window. I tried in several ways to add the HTML (not being a React component itself) to the infowindow via the React library <a href="https://reactjs.org/docs/react-dom-server.html">ReactDOMServer</a>, but all my efforts failed and left me a bit frustrated with how hard it is to add HTML to a component build in React. After reading up on struggles from other developers on ‘Stack Overflow’ and other websites I came to the conclusion that I should not try to use ReactDOMServer unless all other options fail. So, I switched to another library supporting Polygons and InfoWindows as actual React components.</p><h3>3. Take full advantage of Pluggable Widgets API</h3><p>There are four huge benefits I found when working with the new Pluggable Widgets API, so switch if possible! When writing widgets in the older Client API written for the Dojo framework, the first three functionalities would typically take a huge chunk of development time and are not easy to build.</p><ol><li>All types of data source are supported</li><li>All types of action are supported</li><li>Editability/Visibility can be inherited</li><li>Group widget settings together</li></ol><h4>1. All types of data source are supported</h4><p>By in the XML of the widget adding an element of type datasource</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JDpjAPIL40M3zZR_L1Subg.png" /><figcaption>Widget XML: type=”datasource”</figcaption></figure><p>a developer will be able to select all different types of datasource in the widget settings:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*x97ACWX1Fjjdu4ra3qc5-w.png" /><figcaption>New API supports all data sources out-of-the-box</figcaption></figure><p><strong>2. All types of action are supported</strong></p><p>Another standard requirement is being able to trigger actions from inside the widget. In the Google Maps Polygon widget for instance it should be possible to trigger a microflow from clicking on a Polygon or Polyline. With the new Pluggable Widgets API this is very easy now. Just add in the widget XML a type=”action”:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9HmVAK84JYcs9cMQhfcrvA.png" /><figcaption>Widget XML:Type=”action”</figcaption></figure><p>So the developer can select any supported action in the widget settings:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/567/1*YrxbI_Lw4vp3DPlgDa8nSA.png" /><figcaption>New API exposes all actions out-of-the-box</figcaption></figure><p>In the JavaScript only one statement is needed to trigger this action:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/647/1*lVpHi4X_7c1y85kSMxq9fA.png" /></figure><p><strong>3. Editability/Visibility can be inherited</strong></p><p>The new Pluggable Widgets API exposes new system properties also available for other Mendix default widgets:</p><ul><li>Visibility</li><li>Editability</li></ul><p>Add them, again, via a newly available setting in the widget XML:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/625/1*FuVPCmQU_UzCUCzrCNCu9A.png" /><figcaption>Widget XML system properties</figcaption></figure><p><strong>4. Group widget settings together</strong></p><p>It is now possible to add an extra nested propertyGroup in an existing properyGroup within the widget XML. The first propertyGroup will generate a tab in the widget settings, the nested property group will add a groupbox in the specific tab, very usefull for readability:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/517/1*MsG2tTKgD3Ndm49kJ4TkWg.png" /><figcaption>Wdget XML: Nested property groups</figcaption></figure><p>Above setting will result in below widget settings:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/567/1*6rm9LMVGL6OdUQj2BCt9OQ.png" /><figcaption>Studio Pro: nested property groups</figcaption></figure><p><strong>4. Create components for heavily used objects</strong></p><p>Stating the obvious, when building a more complex widget based on React it is best practice to create components out of the most heavily used objects. For the Google Maps Polygon widget I created separate components for the Polygon, Polyline, Marker and Info Window objects.</p><p>In the Dojo framework this was also already a best practice, grouping specific functions in separate JavaScript files, but when using Visual Studio Code and the new React framework with import statements this is so much easier than in the Dojo framework. This was the reason why I sometimes caught myself putting all JS code in one file in the Dojo framework…</p><p><strong>5. Choose carefully what is stored in state of each component</strong></p><p>When needing to support multiple children for your main React component, in my case Polygons, Polylines and InfoWindows, it is key to properly choose what to store in the state of each component. An example: the InfoWindow component should become visible when clicking on a Polygon or Polyline and showing the information of that object. Hence, I was hoping and actually expecting the React library would have a parent - child relation for the components in this order:</p><p><em>Map &gt; Polygon / Polyline &gt; InfoWindow</em></p><p>Sadly, the library had an InfoWindow as a direct child on the Map itself, so:</p><p><em>Map &gt; Polygon / Polyline / InfoWindow</em></p><p>Hence making sure an InfoWindow is shown when clicking on a Polygon or Polyline should be handled via the Map component itself..</p><p>To achieve this I added a couple of things:</p><ul><li>Added a setting to the state of the Map component: showingInfoWindow</li><li>Adding an object to the state of the Map component: infoWindowObj, containing the name, position and corresponding Mendix Object (needed for being able to trigger an action via the InfoWindow)</li><li>Set showingInfoWindow to false on first render of Map Component</li><li>In the render of the Map component, only show the InfoWindow on the position if showingInfoWindow is set to true</li><li>Added a generic handler in the Map component for the on click of child polygon and polyline objects, which sets showingInfoWindow to true and updates the name, position and associated Mendix Object of the infowindow.</li><li>Add a handler on the InfoWindow component to set the showingInfoWindow back to false when closing the InfoWindow.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/977/1*vUlsugGBLWhiSjbuivwzyg.png" /></figure><p>Since we are changing the state of the parent, the render function will be triggered every time an info window is shown by clicking on an object or closed. To make sure not all objects (including kicking off of data source) are reloaded again, you should keep track of whether the objects are already shown as well. This can be done in the Polygon / Polyline shouldComponentUpdate function, to prevent the object from rerendering if all data (props) are still the same.</p><h3><strong>Conclusion</strong></h3><p>Even though my understanding of JavaScript and the Dojo framework was already quite high, it turned out to take quite some time to rewrite this complex widget. I lost some hours on investing in the wrong React library and creating the workaround for the InfoWindow not being a child of the Polygon / Polyline. I am very pleased with the end result, as it is working well and now supports all data sources and actions Mendix provides out-of-the-box. I hope this blog will give other developers some more understanding of the pro’s and con’s of moving from Dojo to React.</p><h3>End result</h3><p>Today I have published the new React based version of the Google Maps Polygon widget to the Mendix Marketplace. You can download it <a href="https://marketplace.mendix.com/link/component/117109">here</a>. Feel free to check out the code on GitHub as well!</p><h4>Read more</h4><ul><li><a href="https://bit.ly/MXW21">Mendix World 2021 | September 7-9, 2021 | Low-Code App Dev Event</a></li><li><a href="https://www.mendix.com/mendix-world/tracks/">Tracks | Mendix World 2021</a></li></ul><p><em>From the Publisher -</em></p><p><em>If you enjoyed this article you can find more like it at our </em><a href="https://medium.com/mendix"><em>Medium page</em></a><em> or at our own </em><a href="https://developers.mendix.com/community-blog/"><em>Community blog site</em></a><em>.</em></p><p><em>For the makers looking to get started, you can sign up for a </em><a href="https://signup.mendix.com/link/signup/?source=direct"><em>free account</em></a><em>, and get instant access to learning with our </em><a href="https://academy.mendix.com/link/home"><em>Academy</em></a><em>.</em></p><p><em>Interested in getting more involved with our community? You can join us in our </em><a href="https://join.slack.com/t/mendixcommunity/shared_invite/zt-hwhwkcxu-~59ywyjqHlUHXmrw5heqpQ"><em>Slack community channel</em></a><em> or for those who want to be more involved, look into joining one of our </em><a href="https://developers.mendix.com/meetups/#meetupsNearYou"><em>Meet ups</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cfc6f9a17f66" width="1" height="1" alt=""><hr><p><a href="https://medium.com/mendix/upgrading-from-dojo-to-react-cfc6f9a17f66">Upgrading from Dojo to React</a> was originally published in <a href="https://medium.com/mendix">Mendix Community</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>