Creating custom widgets

  • 21 February 2024
  • 9 replies

Userlevel 5
Badge +7

Hi community,


With earlier versions of the webUI, I have played around with creating my own custom widgets (e.g. sankey diagrams using D3) for AIMMS. 

If I now go to the documentatation page about custom widgets ( I see that currently this framework is deprecated and should not be used until the new framework is made available.


Is there anything known about when this new framework will be made available and I could give the custom widgets another try?



Best answer by Edo Nijmeijer 22 February 2024, 08:42

View original

9 replies

Userlevel 4
Badge +4

I don’t think I have an easy answer for this. The short answer has to be that the creation of a real, workable and, most of all, shareable public framework has never made it to onto the list of top-priorities for the WebUI team. And that there is no time-frame within which we would be returning to working on it, as I can foresee it now.

Which is a shame, but as you can see from the documentation we wrote for the ‘old’ one, there is quite a bit involved in opening up all aspects of widgets. Even writing it down is a major task. A public framework like this needs to be complete and documented in order to be useful.

You’re probably just as aware as I am that this deprecation has been standing for quite some time. The ‘new’ framework we use for our own development activities still borrows several aspects from the old one, while at the same time using new features that are not directly set up to be accessible from outside these ‘internals’. So yes, we’re using React components and tons of refactored code, but especially this modern code does not expose anything to the ‘globals’ (AWF.*) that the old framework depends on that heavily.

Deprecation of course means that you can still use the documented way of adding custom widgets. However the team is unlikely to work on fixing any of the problems that might arise from it. There should be little to none for widgets with simple options though.

But whatever the complexity, we might need to phase out support altogether if that is needed. In fact, full removal of the old framework is also a current impossibility for us, because we also still need to support some regular widgets and features that at least depend on it for parts of them.

Instead of custom widgets, the team is focusing much more on creating ‘regular’ widgets and features for which we see a lot of value and demand in the market. So this is why over the years we worked on grid layout, new charts (that do no include Sankey diagrams, I know), theming, Widget Named Views and currently the brand new Diagram/Whiteboard widget. All to try and remove the ‘custom’ aspects from customer’s applications. Which are always a risk to support for anyone.

So although I hope this doesn’t fully discourage you to work on custom widgets, using the ‘deprecated way’, I also hope you see how the availability and documentation of a new framework might not exactly be around the corner.

If you have feature requests, make sure to voice them to us, here in the Community, User Support or anywhere else you encounter us :-)

Userlevel 5
Badge +7

Thanks for you answer Edo.


Unfortunately, not really the answer I was hoping for though 😉

I do understand the need for having everything fully documented if you want to provide a way for users/developers to create custom widgets and that is quite a large task.

From the old winui days, I remember that whenever we wanted to achieve something for which there did not  exist a widget, we had to become very ‘creative’ with how we would use widgets that were available. I do remember really ‘abusing’ the network object in the winui in very creative ways to achieve certain goals. It did work, but it was not really the way the network object was intended to be used and always came with certain caveats.

The problem with the winUI though was that it was impossible to have a regular aimms user add new activex components or other stuff. With the webui my hope really was that this flexibility would be available (and it was with the previous framework/documentation that is now deprecated).

With such a supported framework in place, AIMMS could provide a set of well designed, thoroughly tested widgets to be used by people in all projects, while it would still allow the flexibility for developers to create completely custom widgets/visualizations for edge cases that will never make it to the backlog of the aimms widgets.

The examples could be the earlier mentioned sankey diagram, but also the (agree, just a tiny bit more complicated… 😉) chord diagram, which sometimes can be useful in e.g. the telco industry to display the transitions between either providers, or how customers move between the different plans.

Please note that it is not that I am asking now for these two diagrams to be added to the backlog of widgets, they just are examples of visualizations that might be useful for some industries/problems but probably would not end up in the list of widgets created by aimms because they are not generically applicable enough.


Userlevel 5
Badge +7

Hi @Edo Nijmeijer,

Decided to have a quick go at it and in just a couple of hours (with my very limited knowledge about jquery ui / javascript and basic understanding of D3) I was actually able to relatively easily include a D3 based visualization as a plugin in AIMMS (the tutorial that was created was very helpful for this!):


The link is completely dynamic at the moment, meaning that the moment you make a change in the table data on the bottom, it will redraw the sankey diagram on the top right away (at the moment just a full redraw, but in theory this should now also be very easy to adapt to the nice transition style using enter/exit/update pattern of D3).Note that the communication is one way, I am not implementing any feedback from the D3 visualization back to the aimms model.

Since this poc is based on D3, it means I am actually able to implement not only sankey diagrams, but really any visualization possible with D3 inside my AIMMS project (which I think pretty much covers any potential visualization anybody could ever think of 😉)


As you stated, this framework is deprecated, but still present in order to also support some of your existing widgets. You mention that as long as no complex options, probably no problems should arise. What exactly do you mean with the complex options? Are there more details known about the deprecation timelines with regards to when certain features might not be available anymore?


I completely understand that from the point of view of AIMMS you want to ensure good ‘regular’ widgets are provided, but I honestly think having/keeping the option of allowing developers to create custom visualizations whenever a project requires it like this is one very strong feature. I don’t think I should use D3 to create my own bar chart though, since there exists one that is already in AIMMS that is well tested and very well integrated.

Userlevel 4
Badge +4

That’s a brilliant example of how a custom widget can be put to good use, opening up a whole world of possibilities when it comes to visualizations or ‘other’ things you really want to do within the browser context and that cannot even be handled from the model/server. And most of the latter will also be interaction/visuals.

Thanks for sharing, and inspiring 👍

Like you say, the framework is -officially- deprecated. I’m not aware of clear plans to actually remove or disable it. Especially because, like you are very right to mention, it offers a unique way to interact with model data and I could not see us removing it if there was no alternative.

Nonetheless, even if we created an alternative, any existing usages of custom widgets might break in such a case and rewriting or fixing them would be down to you.
I’ll leave it up to you to determine if the advantage of having a Sankey diagram now outweighs that ‘risk’.

The WebUI development roadmap is all about customer and user feedback, trying to balance all stakeholders involved. Short to medium term plans are of course more detailed than the longer term ones, but none are set in stone. From my personal point of view, I’m simply glad you tried this and I also really think you can, without any problems occurring real soon.

The complex features you talk about would probably be about supporting back-and-forth communication for things like slicing, store focus and maybe future developments that require new option editors too, like per-identifier settings and units. Just like some of our own, older widgets don’t support everything that a Table currently supports.

Hope that clears the air for you, and those who consider custom widgets too. Hope your Sankey diagram gets a lot of use. 😎

Userlevel 6
Badge +6

Very nice @gdiepen ,

Would it be code you are willing to post publicly and have others build and extend from? This way the full community can help (also in making adjustments when needed; or adding option the original developer had not envisioned or time for). It also makes it transparent for our developers what is being developed and/or what is popular inspiring everyone.


Userlevel 5
Badge +7

@Gertjan I am willing to publicly post a refactored version of this code. The current version is really not ready for publication as the amounts of duct-tape and strings holding it together would probably scare everybody away from ever trying something like this 🤣


My first goal was to just check if (with my limited knowledge) I was able to get this working, and I was actually very happy to see the widget appear on the UI and also change when I modified the underlying data! When I have some time in the coming weeks, will try to spend some time on refactoring it in such a way it becomes a bit more modular and easier to modify into other diagrams. Need to also see what I would do with pivotting: should I support that or should I just require in this example a two dimensional parameter where the first index always corresponds to the source and the second index always corresponds to the target of the flow in the sankey. In case you do support pivotting, what does it mean if there are multiple indices in the row area for example. 

So as soon as I have a version with a bit more comments / clear setup for sure will share this publicly!

Userlevel 5
Badge +7

Ok, another quick update with regard to this. Instead of rewriting the sankey code, decided to go for the ‘hello world’ example of d3, namely the bar-chart 😉


D3 Barchart

I was able to link this directly into the AIMMS engine, having bi-directional communication between the widget and other widgets:

  • Changes in the data (initiated by clicking the button) show directly (with the nice smooth transitions that D3 is famous for) in the bar chart. 
  • There is a tooltip/hover text from AIMMS when hovering over the bars in the D3 bar chart
  • Clicking on any of the bars will ‘select’ that bar, indicated by a different filling pattern. You will see that the element parameter is also updated.
  • If you update the element parameter, the correspondig bar in the D3 widget will get the ‘selected’ pattern
  • If you change the bar chart values directly in the table on the bottom, you will see that the bar chart also updates right away to reflect these changes
  • The d3 widget is fully responsive, meaning that when the widget area changes size, the widget will also automatically refit to the new size

How does this look like? You can see it in the screencast below



So of course we have the bar chart already in AIMMS, but as mentioned, this is more the ‘hello world’ example when you start working with D3.




D3 GeoJSON data widget

However, there is another type of widget I was missing in AIMMS that sometimes can be useful. I know that we have the map widget now to display certain things on a map, but this only works based on nodes as far as I could see, sometimes I would like to have a selection based on a region or so. There is a lot of information from for example OpenStreetMap available that typically can be converted to GeoJSON format. In my case, I wanted to do show something about the provinces in the netherlands (very simple, population size as well as the capital). This can be displayed in a table, but sometimes using the fact that it is geographical information is quite nice.


So a second example I created is using a GeoJSON dataset and plots this information in a separate widget. And, again, I know it is just gui-candy, but animations do make things look nice, so here also I am able to click on a province and when I do, the chart will zoom in to that province, and clicking it again will zoom it out. 

The color used for each province actually corresponds to the population size (the higher the population, the darker the color in this chart)

This widget also shows the feature of listening to the aimms model, in this case, the selected province which can also be changed via the aimms selection widget.

This example can be shown in the gif screencast below

The sankey-diagram I am still working on, it is showing items, but unfortunately no fancy animations yet (was focusing more on the bar chart and the geo widget). 


@Gertjan The code for this is almost ready to share, just a couple of things I need to double-check with AIMMS in order to share something that is using certain options in the correct/intended way. Spoke with @Edo Nijmeijer  during the user meetup and will contact the AIMMS team about the data/options questions and as soon as those items are clear, will put the code for the aimms project and the d3 widgets on github!





Userlevel 6
Badge +6

Love what you are doing @gdiepen; please keep it going and I hope other community members get inspired by your energy and great examples!


Userlevel 5
Badge +6

Impressive stuff @gdiepen ! I already feel inspired to try doing something myself. Thanks for the effort!


Didn't find what you were looking for? Try searching on our documentation pages:

AIMMS Developer & PRO | AIMMS How-To | AIMMS SC Navigator