You can run your model as a local web application and learn how generated AutoForms, adopted ViewModels, columns, nesting, and presentation settings affect the running UI; this chapter is for learners who completed Training:Bootcamp:Chapter 2.

Before you begin

This chapter continues the model created in Training:Bootcamp:Chapter 1 and Training:Bootcamp:Chapter 2. Save your model before starting and save after each change with Ctrl+S.

You will start a local MDriven Turnkey application. For this chapter, use XML as the data source. The play dialog may also offer MDrivenServer as a data source; do not select it for this exercise.

Start the local web application

A local MDriven Turnkey application runs your model in a browser, so you can test the same ViewModels that you edit in MDriven Designer.

1. In MDriven Designer, select the Play button.
2. Select LocalTurnkeyPrototyper.
3. Select Check MDriven Turnkeycore to download the current MDriven Turnkey version for .NET Core. You need this step when you need to download a newer Turnkey version; wait for the download to finish.
4. Select Start local MDriven Turnkeycore.
5. Keep the terminal window open. Note the port that it reports. The default port is 8182.
6. In a browser, open http://localhost:8182, replacing 8182 with the reported port if necessary.
7. Confirm that the index page opens, then use the application menus to inspect the generated UI.

The browser application provides the same type of model-driven UI functionality that you used in the WECPOF prototyper in the previous chapter.

If Turnkey does not start

If the terminal appears broken or closes unexpectedly, a file lock from the installation may be preventing startup.

1. Close MDriven Designer.
2. Start MDriven Designer again.
3. Repeat the local Turnkey startup steps.

Verify that saved model changes reach the browser

1. In the model tree, find the ViewModel named index.
2. Change its text label to I am in control - I own this.
3. Save the model.
4. Return to the browser. Press F5 if the text is not already updated.

This verifies the basic edit-save-test cycle you will use throughout the chapter.

Understand the ViewModel root requirement

A ViewModel defines the data and UI for a screen. Its root class states which model class the ViewModel is built around. A ViewModel that requires a root also expects an actual object of that class when it opens.

1. In the model tree, open the AutoFormPerson ViewModel.
2. In the ViewModel editor, change the root object class from Person to Car.
3. Inspect the errors at the bottom of the editor.
4. Change the root object class back to Person. Confirm that the error disappears.

The static type checking in MDriven Designer checks whether the model follows its rules. In this case, the ViewModel and the actions that open it must agree on the type of object they use.

1. With AutoFormPerson still open, clear the Requires Root check box.
2. Save the model and inspect the error indicator.

Without Requires Root, the ViewModel can know the class Person without expecting a particular Person object. The generated AutoForm actions currently pass a Person object to this ViewModel, so they conflict with that setting.

1. Select Requires Root again.
2. Save the model.
3. Confirm that the model is error-free.

Root-requirement troubleshooting

In some Designer versions, clearing Requires Root does not immediately show an error in the model-wide Check model and report errors tool. The error may instead appear only in the ViewModel editor for Person.

If you need to verify the error:

1. Update MDriven Designer.
2. If the behavior remains unclear, save the model with Requires Root cleared.
3. Restart MDriven Designer.
4. Run the model check and review the reported issue.
5. Select Requires Root again and save to remove the mismatch.

Change an AutoForm temporarily

An AutoForm is a generated ViewModel. You can edit it to explore the UI, but regenerating AutoForms replaces those edits.

1. In the AutoFormPerson ViewModel editor, select ShowGridLines near the lower middle of the editor.
2. Drag the Name widget and a button widget so that they exchange positions.
3. Save the model.
4. In the browser, navigate to the same Person screen and confirm that the layout changed.
5. Make one more small change in Preview and save it.
6. Return to the browser and observe the update.

The running application can discover saved server-side changes and update the UI without a browser refresh. It is not a static HTML page.

1. Return to the diagram.
2. Refresh or regenerate the AutoForms.
3. Open AutoFormPerson again.

Your changes to AutoFormPerson are gone because the AutoForm was generated again. This is expected behavior.

Adopt an AutoForm when you need a maintained view

Adopting an AutoForm creates a ViewModel that you maintain. The adopted ViewModel remains when AutoForms are regenerated.

1. In the green ViewModel tree, expand the yellow action area.
2. Review the actions that lead to the current ViewModel. These actions were generated by AutoForm logic to open the view.
3. Select ShowPersonAction to inspect its action definition.
4. Right-click the green ViewModel header.
5. Select AutoForm, then choose Adopt this Autoform.
6. Make a visible UI change to the adopted ViewModel, such as moving a widget.
7. Save the model and verify the change in the browser.
8. Review Actions-Leading here. The action names no longer use the AutoForm prefix.
9. In the model tree, confirm that the maintained Person ViewModel exists and that the generated AutoFormPerson ViewModel is no longer the view you are editing.
10. Regenerate AutoForms again.

After regeneration, AutoFormPerson returns as a generated view, while the adopted Person ViewModel remains intact. Use the generated AutoForm as a starting point; adopt it before making UI changes that must survive regeneration.

Add model data and expose it in a maintained ViewModel

1. In the diagram, add an attribute named Age to class Person. Set its type to Integer.
2. Regenerate AutoForms.
3. Inspect both Person views.

The generated AutoFormPerson includes the new Age attribute. The adopted Person ViewModel does not change automatically, because it is now your maintained view.

1. Open the Person ViewModel editor.
2. In the green ViewModel tree, right-click the ViewModel columns area.
3. Select Add Column.
4. Find and select Age.
5. Save and test the Person view in the browser.

The new ViewModel column displays the Person object's Age value.

Add and name generic ViewModel columns

A generic ViewModel column is a column you add directly to the ViewModel rather than one generated from a model attribute.

1. In the Person ViewModel editor, select a ViewModel column.
2. Select Add Column, then Generic column. You can also use Alt+C.
3. Inspect the new ViewModel column.
4. Add another generic column and note that Designer gives it a unique name.
5. Rename NewColumn to NewColumn2. Inspect the reported naming error.
6. Change the name back so that the ViewModel has valid, unique column names.
7. Save the model and inspect the view in the browser.

A ViewModel requires unique column names. The editor reports a conflict when a name duplicates an existing column.

Control display names and units

A column's name and its presentation text are separate. The column name identifies it in the ViewModel; the presentation controls what the user sees.

1. Rename a generic column to CamelCaseMeansWePutInSpaces.
2. Save and inspect the browser view. Observe how the UI presents the CamelCase name.
3. Select the CamelCaseMeansWePutInSpaces ViewModel column.
4. Find its presentation property, initially showing <Name>.
5. Change the presentation to <Name>Extra, save, and verify the displayed result.
6. Change the presentation again to I am in control.
7. Save and verify that text in the browser.

For a model attribute, you can also define a unit that accompanies its value.

1. Return to the Age attribute on class Person.
2. Set its PresentationUnit property to years.
3. Save the model.
4. Inspect the Person ViewModel editor and the browser UI to see the Age presentation with its unit.

For example, an Age value of 42 can be presented with the unit years.

Add a nested Cars view

A nested ViewModel class displays related objects below a parent object. In this model, a Person can have related Car objects through the CarsIUsedToOwn association created in Training:Bootcamp:Chapter 1.

1. In the Person ViewModel editor's green tree, right-click where you want to add the nested content.
2. Add a Nested ViewModel Class.
3. Select the association end CarsIUsedToOwn.
4. Inspect the resulting nesting in the ViewModel tree.
5. Inside the new nesting, add a column.
6. Set the column expression to self.RegistrationNumber.
7. Save the model.
8. Open a Person in the browser and verify that the nested view displays registration numbers for the CarsIUsedToOwn collection.

For example, if a Person owns related cars with registration numbers OldCar1 and OldCar2, the nested view can display those two values.

What you learned

You can now:

• Start and test a local MDriven Turnkey web application using XML persistence.
• Use the root class and Requires Root setting to keep a ViewModel compatible with the actions that open it.
• Recognize that generated AutoForms are replaced during regeneration.
• Adopt an AutoForm to create a ViewModel whose UI changes you maintain.
• Add attribute-backed and generic ViewModel columns.
• Control displayed labels with presentation settings and add a presentation unit.
• Display related objects through a nested ViewModel class.

Continue with Training:Bootcamp:Chapter 4.

See also

• Training:Bootcamp:Chapter 1
• Training:Bootcamp:Chapter 2
• Training:Bootcamp:Chapter 4
• Training:Bootcamp:Chapter 5
• Training:Bootcamp:Chapter 7