Mendix

This document should be used by developers to keep their work consistent. Developers reviewing others’ work, should check that any development complies with these standards. Most of this comes from the Best Practices for Mendix Development page (https://docs.mendix.com/howtogeneral/bestpractices/dev-best-practices).

Changes to standard practice must be reflected in this document.

• Pages
  • Naming of pages
  • Application of styles
• Modules and Domain models
• Microflows
  • Microflow readability
  • Naming of microflows
• Appendices
  • Appendix 1 – Styling of specific UX components

Pages

Naming of pages

Home pages

A home page is one that is displayed to the user first (not including the login page). These can be general, or specific to device and/or role. Names should be structured “Home_Device_Role” (or “Home_Device_Default” if it applies to all or all remaining roles). The device part can be omitted if it applies to all devices.

Page name	Device	Role
Home	All	All
Home_Desktop_Default	Desktop	All
Home_Mobile_Default	Mobile	All
Home_Tablet_Default	Tablet	All
Home_UserRole	All	UserRole
Home_Desktop_UserRole	Desktop	UserRole
Home_Mobile_UserRole	Mobile	UserRole
Home_Tablet_UserRole	Tablet	UserRole

Overview (list) pages

An overview page provides an overview of a single entity. It could also be thought of as a list page.

• The page template should be the standard full page template.

• The page name should be in the form EntityName_Overview.

• The page title should be the plural form of the entity name.

• The page URL should be in the form /EntityName/.

New, Edit, and View pages

These pages are used to add, edit and view an instance of an entity respectively.

• The page template should be the standard popup template.

• The page name should be in the form EntityName_New, EntityName_Edit or EntityName_View respectively. “New” and “Edit” functions can often be served by the same page, in which case the page name should be in the form EntityName_NewEdit.

• The page title should be in the form Edit Entity Name. The title should be overridden by New Entity Name where it is called as a “New” page.

• The page URL should be empty.

Summary pages

A Summary page is similar to a View page (which is more a read-only version of the New or Edit pages) but is probably more tailored.

• The page template should be the standard full page template.

• The page name should be in the form EntityName_Summary.

• The page title should be the same as the entity name.

• The page URL should be in the form /EntityName/{Id}.

Select pages

A page used make a selection should have a suffix of “_Select”. These pages are usually displayed on a popup template.

Application of styles

General principals

1. Styling should be generalised wherever possible. This means:

   1. No inline styles (use classes or context instead); and

   2. No HTML widget style blocks (all styling should be contained in custom.scss or a linked file).

   3. Colours in sass stylesheets (*.scss) should use variables whenever possible. These are usually set in “_custom_variables.scss”.

Modules and Domain models

• A module should contain a single main entity, which should be named similarly to the module name, but in the plural form (e.g. the module “Countries” contains a main entity “Country”).

• Second, third and nth level entities can be included in the module to support the main entity.

• A supporting entity should never be associated more closely to a main entity in another module than it is to the main entity in its own module.

• Domain models should be laid out in such a way that they can be easily understood:

  • Entities should not overlap;

  • Association labels should not be obscured; and

  • Cross-module associations should not be obscured by crossing entities.

• Entity names should be named for a single row (e.g. an entity containing countries should be named “Country”).

• Association names should indicate both the referencing and the referenced entities (the tail and tip of the arrow respectively) as well as the purpose of the association if it is unclear or if there are multiple associations between the same entities.

• When changing the name of an entity any associations affected should also be renamed.

• Documents in a module that predominantly use entities in another module should be moved to that module to reduce cross-module dependencies.

• Documents should be filed into folders in modules containing more than 10 documents.

• Folders should reflect a particular function or entity¹.

Microflows

Microflow readability

• A microflow should contain no more than 25 elements where possible (Elements are actions, loops and splits). Sections of longer microflows should be broken down into sub-microflows unless this will reduce readability.

• Decisions and other logic should be represented by multiple splits where possible, so that the logic is clearly visible.

• Elements should be labelled sufficiently to hint at their purpose without the need to view the properties.

• Microflows should read predominantly from left to right.

• True and non-empty flows from a split should generally go right, while false and empty should flow from the bottom of the split (or exceptionally, the top).

• Error flows should come from the bottom of an action and usually flow downward.

• Flow lines should not cross.

Naming of microflows

Microflow names should have a prefix if they are called from anywhere other than another microflow. These prefixes include:

Microflows called from entity events

Event	Name format	Notes
Before/after commit	BCO_ / ACO_Name	The microflow name should also reflect the entity name and the effect that it has.
Before/after create	BCR_ / ACR_Name
Before/after delete	BDE_ / ADE_Name
Before/after rollback	BRO_ / ARO_Name
Calculated Attribute	CALC_EntityName_AttributeName
Validation	VAL_

Microflows called at the application level

Event	Prefix	Notes
After application startup	ASU_
Before application shutdown	BSD_
Health check	HCK_
Scheduled event	SCE_
Unit test	TEST_

Microflows called from page events

Event	Prefix	Notes
On enter	OEN_
On change	OCH_
On leave	OLE_
On click	ACT_
On click (navigation)	NAV_	Use in preference to ACT_ where the microflow consists only of a show page action, or a retrieves that is then passed to a show page action with no significant other logic.
On click (new)	NEW_	Use in preference to ACT_ or NAV_ where the microflow is used to create a new object then pass that object to a show page action.
Data source	DS_	Used when the Data source type in a Data view, Data grid, Template view or List view is set to “Microflow”.

Microflows called from API services²

Event	Prefix	Notes
Published Web service operation	WOP_	This is the microflow called by an action in a Published Web or App service document.
Published App service operation	AOP_
Import mapping	INM_	This microflow is used as a datasource in an import or export mapping.
Export mapping	EXM_
Deeplink	DE_

Other microflows

Event	Prefix	Notes
Navigation	NAV_	See On click (navigation)

Appendices

###Appendix 1 – Styling of specific UX components

Modal Dialog

The page should consist of:

1. A container to hold the faux header. This is optional. It should have a class of “modal-dialog-faux-titlebar”, which causes the container to act as a “second line” of the dialog header. It can be used to display dynamic information in addition to the page title.

2. A data view to provide the main data source for the form. As the main data view, it should have the footer turned on and have a class of “footerIsModalFooter”, causing that footer to be stuck to the bottom of the dialog.

3. The data view contains a layout grid, which contains the form controls. This has a class of “modal-dialog-form” to set the spacing around the form controls.

4. A cancel button in the data view footer should have a class “btn-cancel” to identify it. This causes the button to be floated to the right of the footer.

All controls added to the dialog should style correctly with no additional classes, inline styles or HTML widget style blocks.

Overview Page

1. Folders for “Pages”, “Microflows” etc. seem to be less useful IMHO). ↩

2. Contrary to the “Best Practices for Mendix Development” page, section 3.5, I would argue against adding prefixes to give information already implied by the document type. For example adding a prefix “XML_” to an XML schema document. This argument can also be applied to section 3.7.2 (Layouts and Snippets). ↩