binding helper

Shield MVVM - BindingHelper

BindingHelper is the main class a developer will interact with in the ContentPageBase<> and DialogPageBase<> classes. It is used to hook up all the bindings between the View Model and the View. It is setup in a way to allow chaining calls to make the code easier to read and maintain. Since the calls all have generic parameters, everything is forced to be type-safe, reducing bugs.

Both *PageBase<> classes create a new instance via the ViewModel that is injected and sets that instance to the "Binder" property. In some other cases, BindingHelper can be created directly and .Once and .For methods used - like creating template controls.

Create

To make creating a new instance easier and not having to deal with the generic parameters, BindingHelper.Create(viewModel) should be used. The ViewModel being bound is a required parameter to create a BindingHelper.

WithControl

To start, .WithControl(control) should be called that defines which control is being bound to. This will hookup the chaining in the next method calls.

WithControls

Rarely, there may be some similar controls that call the same .For/.Once methods. Developers can send in all these controls in a single call and then all the chains calls will apply to all of the controls instead of just one at a time.

For

When bindings (one-way or two-way) need to be in place, .For should be used. The first parameter is a lambda specifying which bindable property to bind to. All of them will start with the "Bind" prefix so they are easier to find in Intellisense.

The second parameter being sent in is the View Model. This will become an expression that is used later to bind the proper path to the View Model, so an actual property on the View Model must be specified. Shield MVVM does allow for nesting, but just realize that a nested property's containing class will need to raise their own INotifyPropertyChanged events for any of those changes to come through. (e.g. vm => vm.SomeVal.ChildVal)

The final overload is for the converter. In the example above, Counter, an int, is bound to a Text field, which is a string. Since these are not the same, a converter must be called - in this case ConvertToString(). A few basic converters ship with Shield MVVM, but feel free to follow whatever naming style that is required and add more. A second overload of the converter allows the View Model to be passed as a parameter, which would look like this:

Binder.WithControl(NumberCounter)
    .For(c => c.BindText(), vm => vm.Counter, (c, vm) => c.ConvertToString(vm.UserCulture));

Once

Once has all the same overloads and parameters as .For, but it has one significant difference. It will set the value as is just once. Also, the second parameter can be any hard-coded value and doesn't need to be a View Model path expression.

.Once and .For can be chained together so all bindings of a specific control can be grouped together, leaving the code easier to read and maintain.

Converters

Converters can be used by both .Once and .For. See more information here.

Behavior

Behaviors are similar to BindableProperties, so a generic version can also be applied here. It has similar overloads as the converters do. See Behaviors.