RmlUi features a model-view-controller (MVC) approach through data bindings. This is a powerful approach for responding to changes in the data, or in reverse, updating data based on user actions.
In the approach taken in RmlUi, the MVC terms have the following meaning.
ModelThe data model is the interface between the user data through data variables, and the views and controllers assigned to the model.
ViewData views are used to present a data variable in the document by different means.
ControllerData controllers typically respond to user input by setting a new value to a data variable.
Views are automatically updated whenever a variable becomes dirty. This ensures that the document displayed to the user is always synchronized with the application data. Using the MVC appoach, there is no need to handle individual elements, or manually modify the RML.
See the following detailed sections:
- You should not affect the document structure within a data model. This includes manually adding or removing elements. E.g. removing an element inside a
data-forview is undefined behavior and may lead to a crash.
- Currently, only top-level data variables can have a dirty state. That means data addresses can not be used to dirty just an Array index or Struct member. However, sub-values that have not been changed will be ignored inside the relevant views.
data-attributes after the element has been attached to the document has no effect.
constobjects or member functions, or members inherited from a parent class, is not supported.
- Types may need to be re-registered if binding variables in different dynamic libraries.
- Putting the
data-modelattribute on the
<body>tag may cause issues when combined with templates.
- Some special elements internally change the structure of the document. For such elements, data bindings may not work as intended. This includes in particular the
<tab>elements, notably when combined with the
<select>element may not always properly reflect changes in the underlying
valueattributes of its
<option>s, or the content of the options. For dynamically changing the selected option, use the
data-valueview on the
<select>element. Note that, initially populating the options using
data-forshould now work.
- Element attributes starting with
data-are reserved for data bindings in RmlUi.
- All use of
}}inside RML documents are reserved for data bindings.