You can build your own client-side UI renderer for an MDriven Turnkey application when you want to integrate model-driven views and navigation into an existing site while continuing to use the model and runtime.
MDriven Turnkey executes the model and renders UI from declarative ViewModels. A custom renderer replaces the standard Turnkey rendering layer; it does not require you to hard-code a list of views. Instead, discover available actions and views from Turnkey metadata, then render the metadata according to your own UI conventions.
When to render Turnkey views yourself
Create a custom renderer when your application needs to control how Turnkey navigation and ViewModels appear within an existing site.
For example, your site may have its own header and navigation. Rather than maintaining a manually coded list of model views, your renderer can discover the current actions from Turnkey and add them to the site's menu. When a user selects an action, the renderer obtains that view's metadata and renders it with the site's own components and styles.
This approach retains the generic nature of a model-driven application: newly added views can be discovered through metadata rather than added to a hard-coded navigation list.
How the metadata-driven rendering flow works
A custom renderer has two distinct responsibilities:
| Responsibility | Turnkey metadata source | What you do |
|---|---|---|
| Discover navigation actions | MDriven/GlobalActionsMeta
|
Read the available global actions and use them to create or merge menu entries. |
| Render one ViewModel | MDriven/ViewMeta?view=RuntimeKey
|
Request metadata for the selected view, then transform its view data tree into your UI. |
A RuntimeKey is the view identifier used by the runtime. Obtain it from the global-actions metadata and pass it as the view parameter when requesting view metadata.
Use the MVC action MDriven/GlobalActionsMeta to obtain the metadata needed to discover global actions.
- Request
MDriven/GlobalActionsMetafrom your Turnkey application. - Read the actions returned by the endpoint.
- Create menu entries for the actions that your site should expose.
- Keep the RuntimeKey associated with each entry.
- When the user chooses an entry, request the corresponding view metadata as described in the next section.
For example, if global-actions metadata identifies an action whose RuntimeKey is PublicJournalSeeker, your menu can store that key with the entry. Selecting the entry causes the renderer to request:
MDriven/ViewMeta?view=PublicJournalSeeker
Do not replace this discovery step with a fixed list of views when your goal is to have the UI follow the model. A view added later to the model can then become available to your renderer through the same metadata flow.
Get metadata for a selected view
Use the MVC action MDriven/ViewMeta?view=RuntimeKey to obtain the metadata required to render one ViewModel.
- Get the selected action's RuntimeKey from
MDriven/GlobalActionsMeta. - Request
MDriven/ViewMeta?view=RuntimeKeyusing that key. - Inspect the returned view metadata and map its view data tree to your renderer's components.
- Bind visibility, styling, selection, and events according to the metadata generated from the ViewModel.
The returned metadata represents the ViewModel definition and the information generated during rendering. It provides the basis for rendering elements such as grids, rows, cells, bindings, visibility, and events in your own client.
For a grid, your renderer can use the view metadata to create a table or another collection component. The row represents the current item in the ViewModel's search results, and the renderer can use the metadata-driven current-row state to apply the appropriate selected-row styling. A row double-click can be routed using the event information provided in the metadata.
The standard Turnkey rendering is a useful implementation reference: it is a transformation of the ViewModel definition into browser rendering instructions. Inspect a deployed application in a debugger when you need to understand how a specific ViewModel feature is expressed by the standard renderer. The Rendering and Overrides walkthrough demonstrates inspecting generated bindings and grid rendering.
Put renderer instructions in the model with TaggedValues
A TaggedValue is metadata that you add in MDriven Designer to carry an instruction that is not part of the ordinary ViewModel property definition. TaggedValues set on ViewModelColumns are included in the view metadata returned by ViewMeta.
Use this to keep renderer-specific instructions close to the ViewModel instead of scattering them through client code.
For example, add a TaggedValue to a ViewModelColumn to identify a presentation instruction used by your custom renderer. When the renderer reads the column metadata, it can check that TaggedValue and choose its corresponding display behavior. The exact tag names and their meaning are defined by your renderer.
Design considerations
- Treat
GlobalActionsMetaas the source for available navigation actions andViewMetaas the source for the selected view's rendering metadata. - Use the RuntimeKey supplied by global-actions metadata. Do not assume that a display caption is the runtime view identifier.
- Keep application-specific rendering conventions in ViewModelColumn TaggedValues when they belong with the model.
- Test metadata changes after changing a ViewModel in MDriven Designer. Your renderer must handle the view structures that your model exposes.
- A custom renderer is responsible for its own transformation of view metadata into UI. Review the standard rendering output and debug a deployed site to understand the generated bindings and event handling before implementing equivalent behavior.
Related rendering options
If you need to render a specific ViewModel in an MVC project rather than build a metadata-driven renderer, see Documentation:Render MVC ViewModel without turnkey. For the standard Turnkey application architecture and deployment choices, see Documentation:Introducing MDriven Turnkey and Documentation:Set up MDriven Turnkey on premise.