The “Many and Primary” Design Pattern

Design patterns are essentially an optimal, “best practice” solution to a common problem. Typically design patterns solve computer code related problems but Mendix is transforming the traditional world of building systems in that the platform promotes a greater than ever focus on business problems. Design patterns within the Mendix world therefore create reusable solutions to common business related scenarios.

One such design pattern is the “Many and Primary” design pattern. In the business world we often find a relationship between business entities whereby one entity will be linked to many other entities but one of those entities will be a selected primary. One example of this is a very South African specific example whereby a user might speak more than one of the countries 11 official language but have a preferable home language (a primary language). From a solutions point of view the Business Engineer needs to find a way to both link to more than one language but also efficiently highlight the users primary or preferred language. The “Many and Primary” design pattern solves this problem in 3 ways:

1. The Entity Model

The first step is describing the solution within the entity model. The essence of the design pattern is described in the two associations linking the two entities. Firstly we have a 1:1 relationship describing the primary language of a person (the primary relationship), secondly we have a 1:many relationship linking any other languages the person might speak.

Example of the entity model for the Many and Primary design pattern

2. The Capture Screens and Supporting Microflows

On the capture screen a user will be required to select a primary language – implementing this feature is most easily done via a drop down list and then the secondary languages via a search data grid.

A screen indicating how the user would interact with the “Many and Primary” design pattern

Languages are then finally added to the person via a Microflow labelled, in the example case above, as “Select Language”. The Microflow is designed to do 3 things:

1. Check that the language hasn’t been added before

2. Check that the language marked to be added hasn’t been added as a primary language thereby avoiding a situation where an entity is selected as both primary and part of the many list

3. Link the selected language to the user via a change activity.

The Microflow used to link languages to the user

3. The Retrieve List Microflow

Now that we’ve constructed a way to save the data in a pattern we need to ensure that the data can be retrieved consistently as well. Since the primary language as well as the other spoken languages of the user should essentially form a single list: All languages spoken by the user. A simple retrieve won’t give that to us because the primary language isn’t saved as part of the other languages. Therefore we implement a retrieve Micrflow which retrieves the list of languages spoken by the user, adds the primary language to that list and then finally returns the list of total languages spoken by the user.

The microflow to retrieve list of attached languages to a person

The design pattern can be used against many business type problems – for example if a user has many cars but has one they drive most often or a family on medical aid but have a primary member etc.

By thinking in design patterns we can both stream line solutions making it easier for other modellers to understand the solution as well as accelerate project implementations by identifying common problems that can be solved in a common way.

UPDATE

After the post Pieter van de Braak made an interesting comment that made me realize a flaw in entity design.  It has now been updated to the following:

The entity model for the mendix primary and many design pattern

Falling victim to a “lab case” in the first entity model it essentially prevented scalability. The update essentially means that the languages in the language entity can be re-used. A big thanks to Pieter for picking that up!

Enumerations as Entities

Enumerations within most normal languages are annoying to maintain and build logic off of. In most cases I have seen String variables or manually mapped integers being used. My experiences within the system analysis, database and business intelligence combination always led me to using database table entries with business logic attributes, although convincing the developers of their benefit was not always an easy battle. But, more on that transition in another post. So in comes Mendix with a more formal, easier-to-combine into business enumeration. But as we all use them on a daily basis (or at least should be) I won’t go into diatribes about their benefits, proper usages and so on. Instead this article will revolve around a Java function entity combination we use to get around the two issues we have had with enumerations.

The first common issue we faced was associating attributes with an enumeration. Creating an entity with the enumeration as a unique attribute solves the issue. However, the problem comes in maintaining this entity when creating new enumeration values particularly across multiple environments.

The second issue we are commonly faced with is mapping web service string results into enumerations (A nightmare for anyone who has ever tried). Creating a microflow to map these manually is a terrible solution but unfortunately the one we tend towards. Not only does it create clunky technical microflows but it also creates maintenance issues.

So what do we do make our lives simpler? Well fortunately the team from Mendix have provided the reflection module a perfect spot to get inspiration from. So using this starting point we construct a Java function to be called during the start-up microflows which using code inspired liberally from the reflection module runs through an enumeration set and populates an entity and voila we have a self-building entity to run our business logic and web service mappings off of.

Now words are great but let’s not recreate work for everyone and get to an example. So here we have a module (I will work on adding it to the store soon) EnumEntityBuilder with a simple entity FruitEnumEntity add it to a play project and link the FruitEnumEntity-Overview form from the navigation. I have provided 3 buttons to play with “Build”, “Clear” and “Find a fruit”. Build runs the Java function which populates the enumeration entity, the grid on the page will provide them. The second function clears the entities so knock yourself out adding new and removing new fruits. “Find a fruit” pops up a text search dialog to emulate a web service mapping to find that elusive enumeration.

Well I hope this can help you in future projects to save time and build more robust logic. And once more here is that example module: EnumEntityBuilder.mpk.

7 Hotkeys of Highly Effective People

Clicking is sometimes a drag, especially when you are on fire. You don’t want to break your momentum by taking your hands off of the keyboard to invoke some action on the screen. You need hotkeys.

I’ve watched releases of the modeler carefully, and now and then a new hotkey sneaks in without huge fanfare. Here are some that my fingers find most handy.

F5, Run Baby Run

I develop on a Mac, and leverage many of its tools, and the command-line is one of them. Sure not all Business Engineers will be power users, but sometimes you’ll find some Business Engineers need a little more umf now and then. For instance, when designing themes for Mendix, I need to make minor adjustments to my theme and apply it real quick back into the zipfile. After making these changes I cmd-tab to my terminal, hit the “up” key to get my last zip bash command, then cmd-tab back to my Mendix modeler, and hit F5. This gets repeated frequently if my design changes with many little iterations. Better yet, let me just show you 1 iteration. Notice the mouse cursor stays in one place.

Shift-F5, Stop

What goes up, must come down. Use Shift-F5 if you need to stop your server. You’ll probably use this infrequently.

F2, Garden-Variety Rename for Windows

This is a bit redundant, since you can start typing away at captions in your microflows or widgets on your forms. The only time this will be useful, is if your properties pallet has focus on another field than the Caption field.

Ctrl-Left & Ctrl-Right, Moving stuff

This one I absolutely love. Entities with lots of attributes generate grids on forms that contain a horde of columns and search fields. If only there was a way to sort them quickly. Talk is cheap. Lets see it in action.

F11, Maximize and Restore

And as you’ve seen in the previous video, F11 is a must if you work on a screen with little real estate. Use this key to maximize your workspace.

Ctrl-G, Goto Artifact

This one is handy if you know what artifact you want to navigate to within your model, without hunting for it in the Project Explorer.

Another handy trick, is using the Mouse’s middle button on the microflow canvas. Its helps you pan your view, and using the mouse wheel, helps you zoom in and out if you don’t use a Magic Trackpad™.

Productivity is like Formula1 racing. Every little improvement helps, even if it contributes a 1 or 2%. Once you try hotkeys, you will find your ergonomics improve, your fingers do the work and helps you move with incredible ease through your modeling routine letting you focus even more.

I’m burning to see more hotkeys in future versions of Mendix.

6 Steps to Mastering the Basics of the Mendix Excel Importer

The ability that Mendix gives modellers to import excel files into their application is fantastic for a number of reasons – my favourite being that it gives the end user so much more flexibility when it comes to uploading data into the application you’re building.

Here’s how to get a simple excel file imported into your Mendix application using the Mendix Excel Importer Module available for free of the Mendix App Store.

Step 1: Getting Started

Before creating the project it’s important to select, as your language format, USA English or Dutch. The reason is that there is no other language standard to the excel importer so you’ll end up with loads of blank fields which you’ll have to populate yourself (you can, of course, implement your own labels based on the language you chose but to save time it’s best to start with either of those two). The excel importer works using the Reflection module. In order to proceed you’ll need to download both the reflection module as well as the excel importer module. If you download the excel importer first you’ll notice a large number of errors due to the missing reflection module which is automatically resolved upon installation of the reflection module.

Step 2: Fire up that Domain Model

The next step will be to, like all good designs, start with the domain and create a domain model that you’re going to upload the contents of the excel file into, in this case we’ll create a very simple person entity as well as the overview and newEdit file after which we will connect our navigation settings up with the required pages that will implement the excel import module as well as the reflection module — which is needed for synchronizing our objects, allowing the excel importer to access them. Here is a pic of both the domain model I used for the post and the excel file we’re going to upload later.

4 Navigation points need to be established:

1. ExcelImporter.Templates_Overview
2. MxModelReflection.MxObjects_Overview
3. ExcelImporter.Import_Overview
4. Person_Overview

Step 3: Sync the Objects

Firstly you’ll need to sync your objects so that the excel importer can get ahold of it so start up the application and navigate to the MxObjects_Overview page and click on the “sync” button. If you run a search your search results should now be populated by your currently instantiated objects.

Step 4: Creating the Upload Template

There are 2 ways to create a template with this module. For this post we’re just going to show how to create one by importing an excel spreadsheet. Now navigate to your Template_Overview page and click on the “New From File”. When using a spreadsheet  the application will not be able to interpret xlsx files so you’ll have to be sure that the excel is an xls file. Upload the file and select the relevant sheet index, header row number and first data row number.

Step 5: Now Configure the Template

After you’d uploaded the template page you’ll need to set uploaded columns against the entity you’re planning on uploading the document into and clicked save the application will navigate you to the template page whereby you will be required to complete the template creation process. If you’re stuck with the default USA label, you will have to set the Mendix Object to the entity are uploading, in this case the person entity .

Next you’ll need to “map columns to attributes”. Assign each Column number to an attribute on our domain and only set the unique key to “Yes” on the email attribute. After all the attributes have been set save the template.

Step 6: Import the Data into the Application

Navigate to the Import Files page and create a new import.

Once the import file has been created simply select the uploaded file and click on the import microflow which will complete the import process. You can now navigate to the person overview page and search for the data which you have imported into the application.

Get Create – A solution to the dilemma of using Entities in quantum states.

A common problem I come across in developing Mendix applications is when I have to manipulate an entity in a microflow which may or may not exist. This quantum  occurance would occur when having to update an entity from a 1-1 relationship, or on a 1-* where the child entity (on the many relationship side of things) is also related to a secondary attribute, such as a day or version.

When dealing with this situation you have to try retrieve the entity using the relationship or Key Attribute(such as date), check if it exists, if it doesn’t  create the entity with the new Key Attributes. This now leaves us with two  entities which have to be manipulated seperately or reretrieve the entity into  a common name.

Going with the first case lets look at what my first pass solution would look like on the following Module:

As can be followed from the above microflow there will be much duplication of logic, and complication of the microflow at quick inspection.

Note: When checking to see whether an entity I retrieved exists I like to create an exclusive split with the caption ‘Exists?’ and the formula ‘not($Entity=empty)’. This keeps the reading of the flow in the positive light rather than negative.

The solution I follow now as my standard practice in these circumstances is to create a microflow called Entity_GetCreate which will handle this retrieve or create logic for me and return the respective entity so that I dont need to concern myself with handling these cases seperately.

This GetCreate microflow for the above entity would look as follows:

Which results in the original microflow being simplified to:

Much easier to read for business and mendix users.

Format String – Widget spotlight

There are a lot of widgets available in the Mendix Apps- & Add-on Store. Basic display widgets are sufficient for building forms, but sometimes you need a little more kick than what you get from the out-of-the-box widgets. For instance dynamic labels. Creating your own widget is an option, but don’t reinvent the wheel when someone already has, which you’ll find out when you visit the store.

I found Format string and it has some nifty applications. Think of it as an “über-label”, giving your Crud applications a little bit more character in terms of dynamic display. Its handy for dynamic label messages or basic reporting, by allowing you to format a string; very much in the same way we do logging-style messages in Mendix apps. You do this by setting a format string and replacement parameters.

Here is an example. I have a customer as an entity on my form. Instead of displaying a read-only Name and Surname Text box, you simply add the label and use the token place-holders:

Under Data source in the property panel, you select your attributes:

You could also have the ability to format dates and the option of rendering this as a div or an input. With a style formatting you’ll have a perfect header for your report or section in your form.

The result:

I’ve look for something like this for a while now, and this is perfect. It does exactly what I want when displaying dynamic labels.