Enabling MVVM

Basic Concepts

• View:
  A view is the user interface that your user sees. In XmlLayout, the view is constructed through the use of Xml.
• Model:
  The model is the source of your data; whether it be from a database, loaded from a text file, or generated dynamically at run-time.
• ViewModel:
  The ViewModel is the connection between your Model (data source), and your View (data representation). In XmlLayout MVVM, you create your own custom class to store the data which will be used by the view.
• Controller:
  The Controller is a class which XmlLayout will use to, among other things, handle events triggered by the view. In XmlLayout MVMM, the controller provides the reference to the ViewModel which you can use to manipulate ViewModel properties.
• Data Binding:
  Data binding refers to elements within the view being bound to particular view model properties, for example, an input field may get its displayed value from a view model property.
  
  • Two-Way binding: This is the default binding mode. With two-way binding, elements capable of changing value (e.g. input fields, dropdowns, etc.) will automatically update the view model properties they are bound to when their value changes.
  • One-Way binding: This is an optional binding mode. With one-way binding, elements will get their values from a ViewModel property, but if their values are changed in the interface, the view model will not be updated to match (at least, not automatically).

  Details on how to specify which binding type to use for a variable will be shown later.

Creating a simple ViewModel

The first thing you need to do is create a new XmlLayout with its own XmlLayoutController (using the Add New XmlLayout Wizard). If you already have an XmlLayoutController, then you can skip this step.

If you are unsure how to do this; please consult the relevant documentation here.

Your XmlLayoutController should then look something like this:

class MyXmlLayoutController : XmlLayoutController
{    
    public override void LayoutRebuilt(ParseXmlResult parseResult)
    {        
    }
}

Once you've created your controller, you can now create a view model for it to use.

The view model can be created in the same source file as the controller if you wish, or it can be created in its own (which is probably better practice, but this is entirely up to you).

Here is an example of a simple view model:

public class MyViewModel : XmlLayoutViewModel
{
    public string myFirstVariable { get; set; }
    public string mySecondVariable { get; set; }
    public string myThirdVariable { get; set; }
}

The important things to note here are:

• All ViewModels must inherit from the XmlLayoutViewModel class in order to function correctly.
• Variables defined in ViewModels should preferably be properties (although auto-properties, as above, are fine). Fields may also be defined, and will work partially, but will have issues when working with two-way binding.

Now, with the ViewModel created, it must be attached to the controller. You can do so by adjusting the controller's class definition as follows:

class MyXmlLayoutController : XmlLayoutController<MyViewModel>
{

And that's it - your ViewModel has now been created and attached to the controller.

Specifying initial values for a ViewModel

To populate the ViewModels initial data set, the XmlLayoutController provides the PrepopulateViewModelData() method which you can override.

This method will be called the first time ViewModel data is accessed (whether by the view, or by XmlLayout itself), and will only be called once (although you may call it again at any point yourself if you wish).

You can use this method to specify values from the data source (Model) of your choice.

class MyXmlLayoutController : XmlLayoutController<MyViewModel>
{        
    protected override void PrepopulateViewModelData()
    {
        // the 'viewModel' property is provided by XmlLayoutController
        viewModel.myFirstVariable = "My First Value";
        viewModel.mySecondVariable = "My Second Value";
        viewModel.myThirdVariable = "My Third Value";

        // if you wish, you could also do it like this instead:
        viewModel = new MyViewModel()
        {
            myFirstVariable = "My First Value",
            mySecondVariable = "My Second Value",
            myThirdVariable = "My Third Value"
        };
    }
}

Referencing the ViewModel in a View

Basic Example

Here is a very basic example of how you can reference ViewModel values in the view using the vm-dataSource attribute:

<XmlLayout xmlns="http://www.w3schools.com"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="UI/XmlLayout/Configuration/XmlLayout.xsd">

  <Include path="Xml/Styles.xml" />
  
  <Defaults>        
    <InputField textAlignment="MiddleLeft" />
  </Defaults>
  
  <TableLayout class="noCellBackground" width="480" height="240">
    <Row class="headerRow">
      <Cell>
        <Text class="title">ViewModel Example</Text>        
      </Cell>
    </Row>
    <Row class="viewport">
      
      <Cell dontUseTableCellBackground="true">
        <TableLayout class="outlined" padding="8" cellPadding="8" columnWidths="160 0">
          <Row>
            <Cell>
              <Text class="label">My First Variable</Text>
            </Cell>
            <Cell>
              <!-- This InputField is bound to our ViewModel's 'myFirstVariable' property -->
              <InputField vm-dataSource="myFirstVariable" />
            </Cell>
          </Row>

          <Row>
            <Cell>
              <Text class="label">My Second Variable</Text>
            </Cell>
            <Cell>
              <!-- This InputField is bound to our ViewModel's 'mySecondVariable' property -->
              <InputField vm-dataSource="mySecondVariable" />
            </Cell>
          </Row>

          <Row>
            <Cell>
              <Text class="label">My Third Variable</Text>
            </Cell>
            <Cell>
              <!-- This InputField is bound to our ViewModel's 'myThirdVariable' property -->
              <InputField vm-dataSource="myThirdVariable" />
            </Cell>
          </Row>
        </TableLayout>
      </Cell>
    </Row>
              
  </TableLayout>
  
</XmlLayout>

This view, combined with our controller and ViewModel, produces the following result:

Simple MVVM Example Output

As you can see, the values from our ViewModel have been used for each of the InputField elements.

<InputField vm-dataSource="?myFirstVariable" />

Dropdown Lists

Dropdown lists are a special case for MVVM in that they have two datasource attributes; one to determine the available options (vm-options) and one to determine the selected value (vm-dataSource).

Here is an example of how to bind a dropdown list element to a ViewModel (note that you can still set the options using other methods, such as manually specifing them in the view if you wish to do so)

ViewModel

public class MyViewModel : XmlLayoutViewModel
{
    public ObservableList<string> myDropdownOptions { get; set; }
    public string myDropdownValue { get; set; }
}

XmlLayout uses the ObservableList collection (provided by XmlLayout) to monitor for changes and replicate them to the view. For a dropdown list's options, this should always be an ObservableList<string> in order for it to function correctly.

The property providing the dropdown list's value on the other hand can be a string (the text value of the selected option), or an integer (the index of the selected option).

Controller

class MyXmlLayoutController : XmlLayoutController
{        
    protected override void PrepopulateViewModelData()
    {
        viewModel.myDropdownOptions = new ObservableList()
        {
            "Option One",
            "Option Two",
            "Option Three"
        };

        viewModel.myDropdownValue = "Option Three";
    }
}

View

<XmlLayout xmlns="http://www.w3schools.com"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="UI/XmlLayout/Configuration/XmlLayout.xsd">

  <Include path="Xml/Styles.xml" />

  <TableLayout width="480" height="64" cellPadding="8" columnWidths="128 0">
    <Row>
      <Cell>
        <Text class="label">Dropdown List</Text>
      </Cell>
      <Cell>
        <Dropdown vm-dataSource="myDropdownValue" vm-options="myDropdownOptions" />
      </Cell>
    </Row>
  </TableLayout>
      
</XmlLayout>

Simple MVVM Dropdown List Example

<Text>The value of the inline attribute is '{myInlineAttribute}'.</Text>

List Usage

When you need to create multiple elements from a single data source, XmlLayout's new <List> tag has you covered.

The List tag allows you to create multiple copies of any Xml element based on the content of a List in the ViewModel. This 'List' will be kept up to date by XmlLayout, if you remove items from the list, they will be removed from the view, and similarly, if you add new items, make changes to existing items, or re-order items in the list, the view will be updated.

Here is a simple example showing how table rows can be repeated using the List tag (note: any element can be repeated; this is just an example)

ViewModel

public class MyViewModel : XmlLayoutViewModel
{
    public ObservableList<MyListItem> myList { get; set; }

    /// <summary>
    /// List items must extend 'ObservableListItem' in order for XmlLayout 
    /// to be able to monitor their properties for changes.
    /// </summary>
    public class MyListItem : ObservableListItem
    {
        public string itemPropertyOne { get; set; }
        public int itemPropertyTwo { get; set; }
    }
}

The data source for a List tag must always be an ObservableList, although the items in the list can be of any type that extends ObservableListItem.

View

<XmlLayout xmlns="http://www.w3schools.com"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="UI/XmlLayout/Configuration/XmlLayout.xsd">

  <Include path="Xml/Styles.xml" />

  <Defaults>
    <Text class="label" alignment="MiddleCenter" />
  </Defaults>

  <TableLayout width="480" height="256" cellPadding="8">
    <List vm-dataSource="myList">
      <Row>
        <Cell>
          <Text class="label" text="{myList.itemPropertyOne}" />
        </Cell>
        <Cell>
          <Text class="label" text="{myList.itemPropertyTwo}" />
        </Cell>
      </Row>
    </List>
  </TableLayout>
      
</XmlLayout>

The List tag's vm-dataSource propety defines which ObservableList in the ViewModel to bind to (in this case, 'myList').

You can use properties within the item as values for any attribute of any child element within the List tag using the following format:

{listName.propertyName}

As before, if you wish to use one-way binding, then lead with a question mark, e.g.:

{?listName.propertyName}

Please note that while the syntax is similar, list item properties are not inline attributes and do not require a layout rebuild when their values change.

Note: at the moment, the Xml will fail validation if you use one of these properties in a field which does not accept string values (e.g. boolean attributes). However, this will not prevent it from working in Unity/XmlLayout, it is essentially just a warning. This should be fixed in the next XmlLayout update.
Fixed in v1.19

Controller

class MyXmlLayoutController : XmlLayoutController<MyViewModel>
{        
    protected override void PrepopulateViewModelData()
    {
        viewModel.myList = new ObservableList<MyViewModel.MyListItem>()
        {
            new MyViewModel.MyListItem { itemPropertyOne = "One", itemPropertyTwo = 1 },
            new MyViewModel.MyListItem { itemPropertyOne = "Two", itemPropertyTwo = 2 },
            new MyViewModel.MyListItem { itemPropertyOne = "Three", itemPropertyTwo = 3 },
            new MyViewModel.MyListItem { itemPropertyOne = "Four", itemPropertyTwo = 4 },
            new MyViewModel.MyListItem { itemPropertyOne = "Five", itemPropertyTwo = 5 },
            new MyViewModel.MyListItem { itemPropertyOne = "Six", itemPropertyTwo = 6 },
        };
    }
}

Result

Simple MVVM List Example

As you can see, the contents of the List tag have been repeated for each element in myList, using the values from each item where appropriate.

If the contents of the list are changed in any way, the user interface will be updated to match automatically.

DataTable Usage

The DataTable element is a convenient way of rendering data from an ObservableList in a tabular format (using a TableLayout element).

As with the List element, DataTable has been designed to work with MVVM (although it can be used with MVC as well), and as such will respond to any changes made to any ObservableList it is bound to.

At the moment (v1.22), DataTable is only capable of rendering text cells, so any data it is provided with will be converted into strings before being rendered, but in future, additional cell types will be added so that other data types can be rendered correctly.

An example showcasing the DataTable in action can be found in the XmlLayout/Examples/MVVM/DataTable folder.

ViewModel

class DataTableExampleViewModel : XmlLayoutViewModel
{
    public ObservableList myData { get; set; }    
}

class DataTableExampleListItem : ObservableListItem
{
    public DataTableExampleListItem(string c1, string c2, string c3, string c4)
    {
        col1 = c1;
        col2 = c2;
        col3 = c3;
        col4 = c4;
    }

    public string col1 { get; set; }
    public string col2 { get; set; }
    public string col3 { get; set; }
    public string col4 { get; set; }
}

Controller

class DataTableExampleController : XmlLayoutController
{
    protected override void PrepopulateViewModelData()
    {
        viewModel.myData = new ObservableList()
        {
            new DataTableExampleListItem("A", "B", "C", "D"),
            new DataTableExampleListItem("E", "F", "G", "H"),
            new DataTableExampleListItem("I", "J", "K", "L"),
            new DataTableExampleListItem("M", "N", "O", "P"),    
        };                      
    }
        
    void MVVM1_AddItem()
    {
        viewModel.myData.Add(new DataTableExampleListItem("New", "New", "New", "New"));
    }

    void MVVM1_RemoveLast()
    {
        if (viewModel.myData.Any()) viewModel.myData.RemoveAt(viewModel.myData.Count - 1);
    }

    void MVVM1_ChangeLast()
    {
        if (viewModel.myData.Any()) viewModel.myData.Last().col3 = "+++";
    }

    void MVVM1_ReplaceLast()
    {
        if (viewModel.myData.Any()) viewModel.myData[viewModel.myData.Count - 1] = new DataTableExampleListItem("***", "***", "***", "***");
    }
}

View

<Include path="Xml/Styles" />

  <Defaults>
    <Text class="label" alignment="MiddleCenter" fontSize="18" />
    <Cell class="headingCell" overrideGlobalPadding="1" padding="4" />
    <Button tooltipPosition="Above" />

    <DataTableRowTemplate class="header" color="rgb(0.1,0.7,0)" />
    <DataTableRowTemplate class="data" />
  </Defaults>
  
  <TableLayout width="95%" height="95%" cellPadding="16" class="noCellBackground">
    
    <Row preferredHeight="64" class="headerRow">
      <Cell class="headingCell">
        <Text class="label">
          <![CDATA[<b>MVVM #1 (myData)</b>
<size=12>Item Type: DataTableExampleListItem</size>]]>
        </Text>
      </Cell>
    </Row>

    <Row class="viewPort">
      <Cell>
        <VerticalScrollView class="scrollView">
          <DataTable vm-dataSource="myData">
            
            <DataTableRowTemplate templateType="HeaderRow" class="header">
              <DataTableCellTemplate />
            </DataTableRowTemplate>
            
            <DataTableRowTemplate templateType="DataRow" class="data">
              <DataTableCellTemplate />
            </DataTableRowTemplate>
            
          </DataTable>
        </VerticalScrollView>
      </Cell>
    </Row>
    <Row class="viewPort" preferredHeight="80">
      <Cell spacing="4">
        <Button onClick="MVVM1_AddItem">Add Item</Button>
        <Button onClick="MVVM1_RemoveLast">Remove Last</Button>
        <Button onClick="MVVM1_ChangeLast" tooltip="Change one column of the last row.">Change Last</Button>
        <Button onClick="MVVM1_ReplaceLast" tooltip="Replace the last row with a new one.">Replace Last</Button>        
      </Cell>
     </Row>
  </TableLayout>  

As with the List tag, the data source for a DataTable must always be an ObservableList, although the items in the list can be of any type that extends ObservableListItem.

Known issue: at the moment, there is no way to customise the appearance of the text elements in a DataTable, but this will be corrected in the next version of XmlLayout.