The Mysteries of XAML

I’d like to start with a short story. I’m trying to write a simple Hello World program. I want it to run on Android, and it must use Xamarin Forms, and use XAML to describe the UI. Should be easy, 5 minutes to do, right? Not in my case.

I go into Visual Studio and create a blank app (Xamarin.Forms Portable). I then “Add New/Forms Xaml Page”, which creates Page1.xaml, replace the hard-wired C# code for building the UI in App.cs with “MainPage = new Page1();”, compile and try to run the program. Unfortunately, it doesn’t do what I expected: there is no text displayed. Looking at Page1.xaml, I realize that the code “{Binding MainText}”  isn’t working. What the hell did Visual Studio create?

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="App1Error.Page1">
  <Label Text="{Binding MainText}" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>

Maybe you know–or maybe not, as I didn’t–the explanation is quite simple: If the BindingContext of the XAML-specified UI data structure is null, which is so in this case, there is no object to get the string property “MainText”. Consequently, the Text property of the Label object is initialized to the empty string. There is no runtime error message produced because referencing a property with a null BindingContext is “OK.”

Excuse me, but this is bad. People don’t have a chance in hell if an IDE generates code that doesn’t work. Don’t just take my word on it, others have the same observation. The IDE should generate an empty XAML file, or it should generate stubs for an app that has some structure (MVVM, MVP, MVC, etc).

So, on I go to investigate XAML, because that’s what this is really all about.

What is XAML?

XAML is a language for specifying tree-oriented data structures. Simply stated, XML elements and attributes are mapped into UI classes and properties, respectively. While you can avoid using XAML in your program, people want the UI to have a clean separation from the logic of the program. XAML helps you accomplish this because it is a declarative language.

XAML has a long history. Initially, there was speculation whether it was a replacement of HTML for web browsers, but it was just a language for UI data structures for Microsoft’s desktop. Writing an XAML spec was supposed “to be developed with a visual tool where developers do not even need to understand the underlying markups,” but in the initial release, the tool was terrible. It still is a problem, because there is no designer for Xamarin Forms XAML.

That would be fine, but there is no formal definition of the language to fall back on. If you read Microsoft’s spec on XAML, it is stated that the interpretation is up to individual XAML processors. In other words, the interpretation of the directive is what it is, whatever that is. But, as we shall see, XAML elements map to UI objects, and we can get a good idea what it does by reading the API for Xamarin Forms.

When a program is compiled, linked, and run, the XAML code is embedded in the assembly, then converted at runtime into a data structure by LoadFromXaml. The code that converts the XML to a data structure is, of course, not open sourced, but you can read how it works using a disassembly (e.g., with DotPeek).

I’ll go over several examples which illustrate some of the ways you can specify a view, and connect it up with a model, since that is what you will want to do 99% of the time.

Disassociated View

After creating an app, change the Label Text property assignment with a simple “Hello World”, i.e., a static string. In this case, there is no associated information with the view. Everything in the view is self-contained. I refer to this as a disassociated view.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:diag="clr-namespace:System.Diagnostics;assembly=WindowsBase"
             x:Class="App1.Page1">
  <Label Text="Hello World!" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>

Note, Label is an XML element, but it’s converted into an object of type Xamarin.Forms.Label. Text, VerticalOptions, and HorizontalOptions are XML attributes, properties of the Label object. The declaration x:Class=”App1.Page1″ is a directive that clues the XAML translator to generate C# source code for the class. That’s done while you edit the XAML file in the IDE.

Another important note here. A property of an object can be set one of two ways in XAML:

  • a property element, where the property and assigned value is expressed as a nested XML element of the containing object.
  • a property attribute, where the property and assigned value is expressed as an XML attribute.

Above, you see the property attribute Text. Below, you’ll see property element BindingContext.

View with Binding

Most of the time, a UI needs to get information from a Model. To do that, you need a binding, which is an association of the view to another object. In fact, if the binding is between the UI and an object derived from IObserverableObject, then it can do magic. (Note, for a discussion of MVVM, see So What Exactly is a View-Model?.)

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App2;assembly=App2"
             x:Class="App2.Page1">
  <ContentPage.BindingContext>
    <local:ViewModel />
  </ContentPage.BindingContext>
  <Label Text="{Binding MessageOfTheDay}" VerticalOptions="Center" HorizontalOptions="Center" />
</ContentPage>

A binding consists of (1) a context assignment, and (2) a binding assignment. Note: nowhere are these terms defined in the spec or by anyone else. However, in order to talk about binding, you have to have a terminology. If you are so inclined, you can read how binding is implemented in the MS documentation.

The context assignment in this example is specified in the XML element <ContentPage.BindingContext>…</ContentPage.BindingContext>. In terms of C# code, it would be the same as “BindingContext = …”. Note how the assignment is written–using a contained element.

The binding assignment associates an object with the view: Label=”{Binding MessageOfTheDay}”. When the UI is constructed, a tree walk is performed up the predecessors until a context is found with the property. NB: the property specified in the binding expression must be a property, not a field or method, otherwise the binding fails.

Singletons

Sometimes you may want a binding to be shared between multiple ContentPage, e.g., a model. In this situation, you can use a x:Static extension.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App3;assembly=App3"
             x:Class="App3.Page1"
             BindingContext="{x:Static local:Class1.Singleton}">
  <StackLayout>
    <Label Text="{Binding CurrentValue}" />
    <Label Text="{Binding CurrentValue}" />
  </StackLayout>
</ContentPage>

A singleton property is defined and used in one XAML file.

There is no way to create a singleton tree node, but you can share the tree node using x:Key. XAML extensions are discussed below.

Binding Lists

A list of objects can be consumed by the view. In Xamarin, ListView has the property ItemsSource, which contains an enumerable collection to iterate over and create children. The semantics of setting ItemsSource is not documented, but essentially:

IEnumerable<T> collection = ....;
foreach (T t in collection) {Add(new Label(t));}

If the ListView XAML specifies a <ListView.ItemTemplate>, the ListView will contain a collection of items of the type specified in the template. By default, it creates a Label. See the documentation.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App4;assembly=App4"
             x:Class="App4.Page1">
  <ContentPage.BindingContext>
    <local:Class1/>
  </ContentPage.BindingContext>
  <StackLayout>
    <Label Text="Value"/>
    <ListView ItemsSource="{Binding Values}"></ListView>
  </StackLayout>
</ContentPage>
using System.Collections.Generic;

namespace App4
{
    class Class1
    {
        public List<string> Values { get; private set; }= new List<string>()
        {
            "a", "b", "c"
        };
    }
}

 

Observer/Observable Pattern

After getting used to XAML, at some point, you will want information in the view to update whenever the corresponding model changes while it’s happening. The UI requires the binding object have an INotifyPropertyChanged interface. In the properties that change, OnPropertyChanged() is called to produce the side effect in the view.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App5;assembly=App5"
             x:Class="App5.Page1">
  <ContentPage.BindingContext>
    <local:Class1/>
  </ContentPage.BindingContext>
  <StackLayout>
    <Label Text="{Binding FirstName}"/>
    <Label Text="{Binding LastName}"/>
    <Label Text="{Binding CurrentDateTime}"/>
  </StackLayout>
</ContentPage>
using System;
using System.ComponentModel;
using System.Runtime.CompilerServices;
using App5.Annotations;

namespace App5
{
    class Class1 : INotifyPropertyChanged
    {
        public Class1()
        {
            // Set up timer to tick of current time.
            _timer = new Timer((o) =>
            {
                Xamarin.Forms.Device.BeginInvokeOnMainThread(async () =>
                {
                    CurrentDateTime = DateTime.Now.ToString();
                    LastName = "You should never see this because OnPropertyChanged() is not called!";
                });
            }, null, 0, 1000);
        }

        private Timer _timer;
        public String FirstName { get; set; } = "hi";
        public String LastName { get; set; } = "there";
        private String _current_date_time = DateTime.Now.ToString();
        public String CurrentDateTime
        {
            get
            {
                return _current_date_time;
            }
            set
            {
                _current_date_time = value;
                OnPropertyChanged();
            }
        }

        public event PropertyChangedEventHandler PropertyChanged;

        [NotifyPropertyChangedInvocator]
        protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
        {
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
        }
    }
}

 

View and Commands

There are two schools for handling events when the user clicks a button or enters text in a data text box. The “old school” is to add an event handler to the code-behind file to make some response, e.g., the OnButtonClicked() override. (In fact, Xamarin shows how you would do that in their last example of this introduction to XAML.) The "new school” is to add a Command property assignment to the XAML, and add the handler into the “ViewModel”. (Note, as someone else points out, placing all the handlers in the ViewModel reduces it to a code behind file.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App6;assembly=App6"
             x:Class="App6.Page1">
  <ContentPage.BindingContext>
    <local:Class1/>
  </ContentPage.BindingContext>
  <StackLayout>
    <Button Text="Click me" Command="{Binding Click}"/>
    <Label Text="{Binding MessageOfTheDay}" />
  </StackLayout>
</ContentPage>
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Runtime.CompilerServices;
using System.Windows.Input;
using Xamarin.Forms;

namespace App6
{
    public class Class1 : INotifyPropertyChanged
    {
        public Class1()
        {
            _message_of_the_day = _messages[_i];
            Click = new Command((nothing) =>
            {
                DoWhop();
            });
        }

        private String _message_of_the_day;

        public String MessageOfTheDay
        {
            get
            {
                return _message_of_the_day;
            }
            private set
            {
                _message_of_the_day = value;
                OnPropertyChanged();
            }
        }

        public event PropertyChangedEventHandler PropertyChanged;

        protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
        {
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
        }

        private int _i = 0;

        private List<String> _messages = new List<string>()
        {
            "What's happening?",
            "This is cool, huh?",
            "Working for the weekend.",
            "No time like the present.",
            "Time flies like an arrow.",
            "Microsoft and Xamarin XAML is the best thing since sliced bread!"
        };

        public ICommand Click { protected set; get; }

        private void DoWhop()
        {
            _i++;
            if (_i >= _messages.Count)
                _i = 0;
            MessageOfTheDay = _messages[_i];
        }
    }
}

 

Debugging XAML

Binding problems can be resolved sometimes by modifying the binding assignment. At the moment, there doesn’t seem to be a way to check if a context is null in Xamarin Forms. In WPF, it would be accomplished using PresentationTraceSources: add a trace statement, Text=”{Binding MessageOfTheDay, diag:PresentationTraceSources.TraceLevel=High}”; define the namespace “diag”, xmlns:diag=”clr-namespace:System.Diagnostics;assembly=WindowsBase”.

If you have a non-null binding context, you can debug the binding when it’s accessed, either in the property or with a data converter.

XAML Extensions

XAML has a special namespace for extensions to the XAML processor. We’ve already seen some of those, e.g., x:Class.

 

  • x:Class – generate a C# class with the given name.
  • x:Name – generate a C# property.
  • x:Reference – use a C# property. Goes in hand with x:Name.
  • x:Key – create a value, in the context of a resource.

An example containing some of these directives follows.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:App6;assembly=App6"
             x:Class="App6.Page1">
  <ContentPage.Resources>
    <ResourceDictionary>
      <x:String x:Key="whatever">3</x:String>
    </ResourceDictionary>
  </ContentPage.Resources>
  <StackLayout>
    <Label Text="{StaticResource whatever}"/>
    <Label Text="fun" x:Name="foobar1"/>
  </StackLayout>
</ContentPage>

 

Conclusions

XAML is an expressive tree-oriented data structure language for UI. Unfortunately, there isn’t a specification of the language, but there are some well-known idioms to help you use it effectively. Enjoy!

Additional Information

Nathan, Adam. XAML unleashed. Sams Publishing, 2014.

As usual, I provide the source for all examples, here in git.

 

 

Posted in Tip

Visual Studio 2015 MRU List Cleanup

Somewhere in the many years that Microsoft has been developing Visual Studio, they’ve managed to completely mess up the Most Recently Used (MRU) list of projects in the Start Page. It used to be that if you opened a project, it would appear at the top of the list the next time you open Visual Studio. Unfortunately, that is no longer the case. Visual Studio 2015 now sorts the list in some bizarre manner, and it adds .csproj files (sub-projects) to the MRU list of a solution that I opened. Rather than try to raise the issue with Microsoft, I decided to write a small program that can reorganize and clean the MRU list to what I want.

The program (source in git here) is a WPF application that, when run as administrator, displays a grid of the project, location, whether it exists, date created, and date accessed. By clicking on the column, the registry data for the MRU list is re-ordered by that column. If you want to remove an entry, select the row(s), then hit the Delete key. Double clicking of an item opens the default program for the file.

Enjoy! –Ken

NOTE: I’ve since filed a bug with MS. VS overwrites the MRU list with stale data on the close of VS. https://connect.microsoft.com/VisualStudio/feedback/details/2648192. This is part of the problem with MRU lists in VS.

Posted in Tip

Mongo, Restheart, and Dokku

Mongo is a popular NoSQL database nowadays. It has several advantages compared to relational databases (schema-less, key-value store, scalable, distributed, propagated consistency) but the main advantage, IMHO, is that JSON is the lingua franca for the data structures it stores and the queries you use. JSON is a nice, simple data structure representation. It can be easily passed between the database and the application; and it can be converted to/from a string and an object in the native language you use. Mongo has many native-language APIs available for interfacing your application with the database, so you should be able to connect your application with Mongo.

Unfortunately, Xamarin Forms applications, written in C#, are Portable Class Library (PCL) applications, and the C# API for Mongo can’t work. Unfortunately, PCL apps and libraries can only link with other PCL libraries that have the same or additional target platforms. So, a PCL app that is targeting Windows, Android, and iOS cannot link with a library that only targets Windows, or only Android, or only iOS.

However, all is not lost. Restheart is an open source REST API server for Mongo databases. You can easily write a layer to encapsulate the calls that you need to access your Mongo database. There aren’t many functions you have to write beyond the usual CRUD, and the signatures for the method are just strings.

Setup

The installations instructions are on the Mongo.org website. Get the latest production version of Mongo. Then, execute the installation file. After it completes, create a directory for the database.

md data/db

To run Mongo, type

mongod --dbpath data/db

To set up Restheart, either copy the latest from Restheart.org, or clone the git repository for Restheart. If you are going to build it from scratch, you will need Maven, Java, and various other tools. Note, I highly recommend you build Restheart from git because the documentation is quite poor, and the only really good way to understand the server is to debug it.

To run Restheart, type java -jar ./restheart/target/restheart.jar, or the appropriate jar file. You can specify a configuration file for Restheart as a parameter when executing the jar.

CRUD

In a SQL database, data are stored in tables. In Mongo, data are stored in a collection. As with SQL, Mongo has CRUD statements for access to the database. The equivalent in Mongo of a row in a SQL table is a document, and is simply a JSON string. A projection of a JSON structure is equivalent to a projection in SQL. If you convert the JSON into a Newtonsoft JObject, you can make a projection of one key/value pair using the [] operator. As in SQL, an index can be created to improve search time.

Examples

SQL Op
Operation
Example
Example in Mongo shell
Example in Restheart
 Create database
 Create a database named db1.
 Create a database named db1.
use db1
NOTE: you need to insert a collection to actually create the database while using the Mongo shell.
 PUT
http://localhost:8080/db1/
NOTE: Do not set data or you will create a record with that data in the database. It can’t be deleted!
Create table
Create collection
 Create a collection named “col”.
db.createCollection(“col”)
PUT
http://localhost:8080/db1/col
Insert a row in a table
Insert a document in a collecton
Insert {“a1″:”b1”} in collection col.
 db.col.insert({“a1″:”b1”})
POST
http://localhost:8080/db1/col
payload is {“a1″:”b1”}
header is Content-Type: application/json
NOTE: The record type/value doesn’t have to be unique. So, you can insert duplicates if you like.
Read a row
Read a document
Find {} — find all records in collection col.
db.col.find({})
or just db.col.find()
GET
http://localhost:8080/db1/col
header is Content-Type: application/json
Read a row
Read a document
Find { “a1” : <value> } — find all records with key a1 in collection col.
db.col.find({“a1”:{$regex : “.*” }})
GET
http://localhost:8080/db1/col?filter={“a1″:{$regex:”.*”}}
NOTE: Make sure to note the correct syntax. The Restheart arg parser is very, very poor. E.g., using parentheses instead of equal sign:
http://localhost:8080/db1/col?filter={“a1″:{$regex:”.*”}}
This will return all records with a1, which is not what you intended!
To limit the find to the “first” record (whatever that means), add ‘&pagelimit=1’ to the args of the GET url.
Read a row
Read a document with projection
Find { “a1” : <value> } — find all records with key a1 in collection col, but only show keys of “cc”. For example, suppose there is one record, {{“aa”:”bb”}, {“cc”:”dd”}}. Return {“cc”:”dd”}.
db.col.find({“aa”:{$regex : “.*” }}).projection({“cc”:1})
http://localhost:8080/db1/col?filter={“aa”:{$regex:”.*”}}&keys={“cc”:1}
 Update a row
 Update a document
Update {“a1″:”*.”} to {“a1″:”asdf”}
db.col.update({“a1″:{$regex:”.*”}},{“a1″:”xx”})
PATCH
http://localhost:8080/tb3/col/*?filter={“a1″:”.*”}
header is Content-Type: application/json
payload is {“a1″:”asdf”}
 Delete a row
 Delete a document
 Delete a record with a particular key/value, { “a1” : <value> }.
 db.col.remove({“a1″:{$regex:”.*”}})
 DELETE
http://localhost:8080/db1/col/*?filter={“aa”:{$regex:”.*”}}
 Delete a table
 Delete a collection
 Nuke an entire collection col.
 db.col.drop()
 DELETE
http://localhost:8080/db1/col
 Delete database
 Delete database
 Nuke the entire database db1.
 db.dropDatabase()
 DELETE
header contains If-Match:<the id of the database>, e.g., 570e3dc71d9563251070fab3
http://localhost:8080/tb1/

 

NOTE: Restheart normally requires an “ETag” header entry, i.e., “If-Match: 570e3dc71d9563251070fab3”, where that number is an ID of the record to delete. You can turn off ETag checking in a configuration file, which you can specify on the java command line.

To get a value, you will have to parse the json for the field of interest. You can use projection to help you with that.

Running Mongo and Restheart on Dokku

To run a Mongo database and a Restheart server on Dokku, you can get a copy of my Github example, then modify it for your needs. The example is here.

References

https://softinstigate.atlassian.net/wiki/display/RH/Installation+and+Setup#InstallationandSetup-7.3.MongoDBauthenticationwithjustenoughpermissionsauth-with-jep

https://softinstigate.atlassian.net/wiki/display/RH/Query+Documents

http://www.tutorialspoint.com/mongodb/mongodb_query_document.htm

https://docs.mongodb.org/manual/reference/method/db.collection.find/

https://www.mongodb.org/downloads#production

http://www.codeproject.com/Articles/1087008/Mongo-DB-Tutorial-and-Mapping-of-SQL-and-Mongo-DB

http://stackoverflow.com/questions/tagged/restheart

https://en.wikipedia.org/wiki/MongoDB

 

Posted in Tip

GoDaddy left at the Docker

I’m in the process of checking out the advantages and disadvantages of GoDaddy’s new Cloud Server product, which has just been announced as generally available. It has few features, less compared to DigitalOcean, which has been available for a few years. AWS, which has been available for even longer, is generally the gold standard–if you like, or need, a cloud platform with every conceivable tweakable option. You have to wonder what took GoDaddy so long. And, even with years to think about what to implement in order to compete with DigitalOcean and Amazon, it has at least one problem which the others don’t.

As I am currently a tepid fan of Dokku, I decided to check out how a GoDaddy VPS would perform compared to a VPS on DigitalOcean. However, I spent a day or two figuring out that GoDaddy has a problem with routing Docker container network traffic. You can see a discussion of the type of problem here, and a solution provided by GoDaddy here. The tweek involves some changes to iptables. Below is a script that wraps it all together: it installs Docker and fixes the iptables for a GoDaddy VPS. Enjoy!

#
sudo apt-get update -y
sudo apt-get install -y apt-transport-https ca-certificates
sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
sudo bash -c 'echo deb https://apt.dockerproject.org/repo ubuntu-trusty main > /etc/apt/sources.list.d/docker.list'
sudo apt-get update -y
sudo apt-get purge lxc-docker
sudo apt-cache policy docker-engine
sudo apt-get install linux-image-extra-$(uname -r)
sudo apt-get install -y docker-engine
sudo service docker start
sudo docker run hello-world

# verify ping works
sudo docker run --rm -it ubuntu /bin/bash -c 'ping -c3 8.8.8.8'

# update iptable
export IP=`ip route get 8.8.8.8 | awk '{print $NF; exit}'`
sudo iptables -t nat -I POSTROUTING ! -o docker0 -j SNAT --to $IP
sudo iptables -t nat -I POSTROUTING -s 172.17.0.0/16 -d 208.109.188.8 ! -o docker0 -j SNAT --to $IP
sudo iptables -t nat -I POSTROUTING -s 172.17.0.0/16 -d 208.109.188.9 ! -o docker0 -j SNAT --to $IP

# verify ping works
sudo docker run --rm -it ubuntu /bin/bash -c 'ping -c3 8.8.8.8'

 

Posted in Tip