In the first part I introduced nRoute.Toolkit as nRoute vNext sans Navigation and Composition components - whilst it lacks two of the key features, it introduces a boat-load of new features including Bindable Dependency Objects, Bindable Triggers, Actions and Behaviours for Blend, an IObservable-based Messaging Framework, Services component, View Services component, Modules component, ViewModel component and more. Extending that feature-set, in this post I'll cover some of the other more component-oriented features in the toolkit, like ICommand implementations, ICommand extensions, Weak Eventing handlers, Eventing extensions, and various Relays.
Action(able) ICommands
With regards to MVVM in Silverlight, I believe two interfaces carry a disproportionate share of the "architectural burden" - with the two interface being ICommand and INotifyPropertyChanged. Both these interfaces bridge the chasm between the View and the ViewModel - one signifies an action occurrence, and the other signals a value change. Now, as far as the ICommand related functionality is concerned, they are well represented in the toolkit by two implementations named ActionCommand<T> and ActionableCommand<T>. Both of these implementations are actually refinements of what was earlier available in nRoute, however now they derive from a common interface called IActionCommand.
With reference to the IActionCommand interface, the 'IsActive' property allows you to enable or disable the command, whereas the 'RequeryCanExecute' method allows you re-evaluate as to if the command can be executed, and CommandExecuted event is, well, quite self-explanatory. Both the ActionCommand<T> and ActionableCommand<T> support strongly-type parameters, and take in an Action<T> delegate to handle the command execution. The difference between Action and Actionable Commands is that the latter allows you to designate another delegate to determine as to if the command can be executed. Here's a simple example:
1: // declared
2: public ActionableCommand<string> SearchCommand { get; private set; }
3:
4: // defined
5: SearchCommand = new ActionableCommand<string>((s) => Repository.Search(s),
6: (s) => !string.IsNullOrEmpty(s));
In the example above, we have defined a command that can take in a string value and uses it to search some repository. The command also defines a delegate that ensures that the search string is not null or empty before executing the command.
Now, as show in the class diagram, we also have non-generic versions of these commands that not only drop the generic parameter but also relieve you from having to process the same - so they ask for an Action delegate as opposed to Action<T>. I was surprised how useful these non-generic versions are, in my own use scenarios nowadays almost 95% of all of my commands are of the parameter-less variety.
Command Extensions
Very often you will find that a command's execution is dependent on some other factor, for example a delete command might be dependent on having something selected or like above a search command is dependent on the search-string being not null and not empty. Given a set of dependencies, a single change in any dependency requires us to manually re-evaluate a possibility of change in the executable-status of the command - specifically, with the IActionCommand interface, this is done via its RequeryCanExecute method (which inturn suggests this by raising its CanExecuteChanged event).
So, the point of the command extensions is to explicitly define dependencies which then can automatically trigger the possibility of a change in the executable-state of a command. I think the concept is easier described in code, have a look:
1: var DeleteCommand = new ActionableCommand(
2: () => Repository.Delete(this.ActiveItem),
3: () => this.ActiveItem != null
4: ).RequeryOnPropertyChanged(this, () => ActiveItem);
In the snippet above, the delete command allows us to delete the active item, where an active item is something that has been say selected in a ListBox. And the constrain on the execution of this command is that the ActiveItem property is not null, as shown in line 3. Now every time the selection of the ActiveItem changes, we must re-query the command's executable state - this intent is made explicit with the extension method shown in line 4. Here, the extension method exploits an INotifyPropertyChanged capable ViewModel (this) and listens for 'ActiveItem' property changes, which when changed triggers a re-query of the command's executable-state. Another version of this extension method exists that doesn't require a property name, as it listens to any/all property changes.
Similarly, we have another extension method that re-evaluates the executable-state after the command is executed. In the example below, the command's task is to set the count value to zero and therefore is only executable when the count is not zero. By using the RequeryWhenExecuted extension method we ensure that whenever the command is executed it's state is re-evaluated.
1: var SetCountZeroCommand = new ActionableCommand(
2: () => this.Count = 0,
3: () => this.Count != 0);
4: SetCountZeroCommand.RequeryWhenExecuted();
There is another similar extension method called RequeryOnCommandExecuted which re-evaluates a command's status when another command is executed. So for example:
1: // two commands
2: SubscribeCommand = new ActionableCommand(() => { ... };
3: UnsubscribeCommand = new ActionableCommand(() => { ... };
4:
5: // explict dependencies
6: UnsubscribeCommand.RequeryOnCommandExecuted(SubscribeCommand);
7: SubscribeCommand.RequeryOnCommandExecuted(UnsubscribeCommand);
In the case above, the subscribe and unsubscribe commands' execution-states are re-evaluated when any of the other command is executed. Their respective execution-state is dependent on the whether or not a subject is subscribed or not. Another extension method called RequeryOnCommandCanExecuteChanged can re-evaluate a command by listening to another command's CanExecuteChanged event. However, you must be careful to not peg this extension method onto two commands re-querying against each other, as you will create an infinite loop between the two.
1: // Declared
2: public ActionableCommand CreateItemCommand { get; private set; }
3:
4: public ActionCommand UndoCommand { get; private set; }
5:
6: // Dependency Defined
7: UndoCommand.RequeryOnCommandCanExecuteChanged(CreateItemCommand);
Lastly, we also have a RequeryOnCollectionChanged extension method, that can re-query a command when an INotifyCollectionChanged implementing collection changes. For example below, the command's execution status is dependent on the messages' collection having one or more messages, and so we make that explicit:
1: ClearCommand = new ActionableCommand(() => Messages.Clear(),
2: () => Messages.Count > 0).RequeryOnCollectionChanged(Messages);
These extension methods work by pinging against the IWeakEventListener implementation that both ActionCommand<T> and ActionableCommand<T> support. Basically, the commands uses the ReceiveWeakEvent method to listen to any external suggestions that the command's execution-state might have changed, and so when pinged they raises the CanExecuteChange event to tell others to check their execution-status against the command. And as the interface name suggests, this is weakly/indirectly-referenced so you don't create leaking dependencies. Further, you can also use the same technique to attach explicit dependencies, using custom extension methods or just by making the command listen to any relevant event.
Execute Command Behavior
The ExecuteCommandBehavior does as it reads - with two notable features, one that both the command and command parameter are bindable. And second that it can enable/disable the usage of the associated element if ManageEnableState option is selected (see right).
The ManageEnableState option basically enables or disables a Control-type derived element, based on whether or not the command is executable. It listens to the CanExecuteChanged event and can re-evaluate the execution state of the command. Now, in the case where the element attached to the behaviour is not a Control-type derivative, it enables/disables the "interactivity" of the element - the interactivity concept is the same as one I mentioned in part one except here when the element is disabled we set the opacity to 50% (which might not be appropriate in all cases).
The snapshot above shows the effect of the ExecuteCommandBehavior managing the enable state for you. The "Button Command" reading element is a button control (which is derived from the Control type), whereas as the "Border Command" reading element is a border element (not deriving from the Control type). In both the cases when the command cannot execute, they are non-responsive to user input - however as I've mentioned before there are limitations to how far the the interactivity approach will take you.
Weak / Event Handling
In another previous post I had detailed some of my ideas around weak eventing, with the crux of the idea being that by wrapping event handlers we could make the eventing infrastructure smarter without having to re-imagine the consumption or creation of events. And smarts give us the ability to weakly-reference the consumers, which makes the event consumer's lifetime independent of the event producers. Here's the how-to:
1: source.SomethingHappened += new WeakHandler(Handle_Something,
2: (h) => source.SomethingHappended -= h);
In the snippet above rather than using an EventHandler delegate, we are using the WeakHandler class to handle the SomethingHappened event on the source object. The WeakHandler class implicitly creates the event handler, whilst lifting itself into the handler - and so it sits between the consumer and producer of event. By virtue of having a go-between we can do a lot of interesting things (as we'll see ahead), and so we also provide wrappers for normal handling (ie. non-weak) of the events. Secondly, by having this go-between we also gain the capability to allow consumption of events for non-delegate consumers - specifically, for IWeakEventListener and IObserver<Event<T>> based consumers. Consider:
1: // using Listeners
2: source.SomethingHappened += new WeakListener(weakEventListenerObj,
3: (h) => source.SomethingHappended -= h);
4:
5: // using Observers
6: source.SomethingHappened += new ObserverHandler(weakObserverHanderObj,
7: (h) => source.SomethingHappended -= h);
Also the IActiveCommand component mentioned above that makes uses of the WeakListener handler, similarly the Rx Framework makes use of Event to IObserver<Event<T>> translation for all its magic. Now, I'm not going to go into the depth of the eventing infrastructure, but basically there are six main classes - which allow for handling, listening, and observing of events in both strongly-referenced and weakly-referenced manners.
In all the classes above the type E generic parameter is an EventArg derivative associated with the event handler delegate of type H - for example to handle a size changed event for a Window the parameter E would be SizeChangedEventArgs and the associated parameter H would be SizeChangedEventHandler. To save you some time, there are some pre-defined wrappers available to handle common events based on EventHandler, EventHandler<E>, RoutedEventHandler and PropertyChangedEventHandler delegates. Also note all the given handlers are disposable - so when a handler is called upon to dispose it unregisters from the event and clears all references to the consumer/producer paving the way to be GC'ed.
Eventing Extensions
Like I said earlier, the idea with event handling wrappers was to introduce smarts in the consumption of events - and we have a number of smarts (beyond weak handling) available in the form of extension methods. Now, a lot of this would look like the Rx Framework which is by both by inspiration and design, but functionally it is quite different - here we have a pipeline model as opposed to an event stream model. And it works by the wrapper having pre-handling, post-handling and predicate-type gateways to the actual handling of the event. Also you can use these extensions whilst consuming an event via handlers, listeners or observers.
Handle When
1: this.MouseEnter += new Handler<MouseEventArgs, MouseEventHandler>(
2: (s, e) => StartDragging(e),
3: (h) => this.MouseEnter -= h).
4: When(
5: (e) => e.EventArgs.StylusDevice.DeviceType == TabletDeviceType.Touch);
The When extension is simply a predicate to handling the event, and so when true it handles the event else it ignores the event call.
Skip When
1: this.MouseLeftButtonUp += new ObserverHandler<MouseButtonEventArgs, MouseButtonEventHandler>(
2: _mouseButtonObserver,
3: (h) => this.MouseLeftButtonUp -= h).
4: SkipWhen(
5: (e) => _flagged);
The SkipWhen extension is the simply a negated version of the When predicated, therefore when true it skips the handling else it handles the event.
Handle Once
1: Button1.Click += new RoutedHandler(
2: (s, e) => ProcessQuotation(),
3: (h) => Button1.Click -= h).
4: HandleOnce();
As the name suggests the HandleOnce extension ensures that you handle the event once and only once, it disposes off the handler post the first event. This is quite useful especially when you knowingly will only handle the event once, as in the case of loading or initialization, and with this extension you don't have to worry about unregistering the handler.
Handle Exactly
1: LoginButton.Click += new RoutedHandler(
2: (s, e) => LoginUser(),
3: (h) => LoginButton.Click -= h).
4: HandleExactly(5);
HandleExactly extension will only handle the event a given number of times, thereafter it will unregister and dispose off the handler.
Handle While
1: AuthorizeButton.Click += new RoutedHandler(
2: (s, e) => Authorize(),
3: (h) => AuthorizeButton.Click -= h).
4: While(
5: (e) => User.Session.IsAlive);
Keeping to its name, the While extension method handles an event while the given condition is true. If the condition turns false, it will unregister and dispose off the handler.
Handle Until
1: AuthorizeButton.Click += new RoutedHandler(
2: (s, e) => Authorize(),
3: (h) => Authorize.Click -= h).
4: Until(
5: (e) => User.Session.IsAlive);
The Until extension is basically similar to the While extension, except that it allows for at least handling the event once. The While/Until terminology is akin to similarly-named operators in Visual Basic.
Handle For
1: _model.PropertyChanged += new PropertyChangedHandler(
2: (s, e) => OnCountChanged(),
3: (h) => _model.PropertyChanged -= h).
4: HandleFor(
5: () => _model.Count)
The HandleFor extension method is specifically meant for PropertyChanged event handlers, as it allows you to explicitly handle a property changed event for a given property. Like in the example above it only handles the event when the Count property changes.
Throttle Handling
1: this.DecreaseButton.Click += new RoutedHandler(
2: (s, e) => _viewModel.DecreaseCount(),
3: (h) => this.DecreaseButton.Click -= h)
4: Throttle(
5: TimeSpan.FromSeconds(5d));
The Throttle extension limits the handling the event to once per the given duration, so in the example above the handler will only be allowed to be executed once every five seconds from the execution of last event - with other calls within the same period being ignored.
Handler Timeout
1: this.ConfirmButton.Click += new RoutedHandler(
2: (s, e) => _viewModel.Confirmed(),
3: (h) => this.ConfirmButton.Click -= h).
4: Timeout(
5: TimeSpan.FromSeconds(120), () => ConfirmButton.IsEnabled = false);
The Timeout extension awaits for event to occur within the specified time span, failing which the event handler is deregistered and the handler disposed off. Also you can specify an Action to be executed when the timeout expires. One benefit to this extension is that it brings the timeout semantics to any/all types of event.
Recurring Timeout
1: this.KeyUp += new WeakListenerHandler<KeyEventArgs, KeyEventHandler>(
2: _dharmaInitiativeListener,
3: (h) => this.KeyUp -= h).
4: RecurringTimeout(
5: TimeSpan.FromMinutes(108), () => BlowupLostIsland());
The RecurringTimeout extension is basically like the Timeout extension except that every time the event occurs it resets the timeout and starts counting down again. Similarly, if the timeout were to occur the event handler is deregistered and the handler is disposed off, plus you can also specify a timeout Action delegate.
Lastly, note you can apply one or more of these extensions to a single handler, and equally you can create your own extensions for use with the given handlers in the toolkit.
Relays
My earlier post on relays, introduced IValueConverter and ICommand relays - building on that, we now have a ValueRelays and binding support for all relays types. Simply put, the point of relays is to act as a statistically declared go-between the actual implementation or value that is specified at runtime. The scenarios where this is useful is when you need to delegate the actual implementation/value from some other source such as a ViewModel or into something like a DataTemplate.
Value Converter Relay
Basically you use the ValueConverterRelay as a statistically declared resource that fronts an IValueConverter implementation defined at runtime. Statically, declaring a relay is as simple as:
1: <nComponents:ValueConverterRelay x:Key="DateStringRelayConverter" />
Once the declaration is set, there are multiple ways to set the backing implementation. A direct way to set the implementation is to get the resource in your code-behind and set the converter.
1: ((ValueConverterRelay)this.Resources["DateStringRelayConverter"]).Converter =
2: new ValueConverter<DateTime, string>((d) => d.ToString("DD, MMMM"));
To make the code-behind scenario a bit easy to use there are a couple of extension methods in the toolkit that allow you to set the resource-based relay declared with any FrameworkElement. So in the example below, we are setting the relay defined in the root level element's (this) resource collection:
1: this.SetRelayConverter<DateTime, string>("DateStringRelayConverter",
2: (d) => d.ToString("DD, MMMM"));
Now, this approach for declaring and creating value converters is not an all-purpose solution, however for many simple cases and where the conversion logic is local to your use this compact approach helps. The other benefit of using relays is you can change the implementation at runtime, or as shown below you can have the value-converter's logic rooted in the larger logic of your ViewModel.
The other way of defining a backing implementation for a value-converter relay is to bind the relay by bridging it. To do this, you can use the generously-named BridgeValueConverterBehavior type behaviour, and have it bind to any implementation like say from your ViewModel.
In the screenshot on the right, we have the ValueConverterRelay statistically bound to a local resource (show by the green rectangle), and the converter source is being feed from the ViewModel via binding (show by the yellow rectangle). And back in your ViewModel you can define the value-converter using the generic ValueConverter<TIn, TOut> wrapper class found in the nRoute.Components namespace.
1: // declare
2: public ValueConverter<User, string> UserNameConverter { get; private set; }
3:
4: // define
5: UserNameConverter = new ValueConverter<User, string>(
6: (u) => u.LastName.ToUpper() + ' / ' u.FirstName + ' ' + u.Title);
Above the UserNameConverter is just a property in your ViewModel, which is sourced via bridging and consumed indirectly via the relay. Also notable is the fact that Silverlight doesn't support multi-bindings, so using value-converters like above can come in real handy.
Command Relay
I hope the name gives it away, but the CommandRelay is the equivalent of ValueConverterRelay for use with an ICommand implementation. Functionally, using and declaring them is similar to value converter relays, consider:
1: <!-- Declared as a Resource -->
2: <nComponents:CommandRelay x:Key="UpdateTimeRelayCommand" />
And to define the implementation in the code-behind, we can use an extension method like:
1: this.SetRelayCommand<object>("UpdateTimeRelayCommand", (o) => UpdateTime());
Alternatively, we can also define the implementation by bridging the command using a BridgeCommandBehavior type behaviour available in the toolkit (note, in Blend you will currently have to use xaml to define the source of the command).
1: <i:Interaction.Behaviors>
2: <nBehaviors:BridgeCommandBehavior
3: CommandRelay="{StaticResource UpdateTimeRelayCommand}"
4: CommandSourceBinding="{Binding UpdateTimeCommand, Mode=OneWay}"/>
5: </i:Interaction.Behaviors>
In the case above we are sourcing the implementation of the command from the ViewModel. And one of the primary use scenarios of relayed commands is with DataTemplates in an ItemsControl. Since data templates are statically declared they are impervious to the data context of the View, and moreover their data context is set to the item being enumerated. In such a case, having them trigger commands in the ViewModel can be achieved via relays - so for example with the sample UpdateUserRelayCommand declared and bridged above, we can use it within a DataTemplate as such:
1: <!-- Data Template declared as a Resource -->
2: <DataTemplate x:Key="TimeInfoTemplate">
3: <Grid>
4: <Button Content="Update Time">
5: <i:Interaction.Triggers>
6: <i:EventTrigger EventName="Click">
7: <nBehaviors:ExecuteCommandAction
8: Command="{StaticResource UpdateTimeRelayCommand}"/>
9: </i:EventTrigger>
10: </i:Interaction.Triggers>
11: </Button>
12: </Grid>
13: </DataTemplate>
The Button in the DataTemplate above is rigged to raise a command when clicked - and using the bridge the command is ultimately trigged in your ViewModel. Now, having to first declare, bridge and then use the command may seem burdensome, but that speaks more to the shortcoming of Silverlight than to the solution for it.
Value Relay
A ValueRelay is again like before a statically declared facade for a value sourced at runtime - and its declaration as a resource is a simple as ever:
1: <nComponents:ValueRelay x:Key="CurrentTimeRelayValue" />
And to source the value from a code-behind can be done as such:
1: this.SetRelayValue<DateTime>("CurrentTimeRelayValue", DateTime.Now);
For bridging the value we can make use of the BridgeValueBehaviour type behaviour. It takes in the relay and provides it with a value as defined by either the ValueSource or ValueSourceBinding property (see right).
The ValueRelay implements INotifyPropertyChanged, which ensures that its consumers are updated whenever the source of the value changes. Also, as with the relays earlier, you can use this to convey some value to a DataTemplate from your ViewModel - which at times can be a lifesaver.
Now, the binding syntax to consume the value through a ValueRelay is slightly different than earlier - the main change being that we need to access the Value property of the ValueRelay to get the underlying value.
1: <TextBlock Text="{Binding Value,
2: Source={StaticResource CurrentTimeRelayValue}, Mode=OneWay}" />
Also, all relays support an Initialize event which at times is required, because depending on the use-case the resource-based relay should be available during the parsing of xaml, in which case the Initialize event can be used to setup the value - a
previous post on relays details this scenario.
What's Next
The first release of nRoute specialized in View-level composition and navigation using Url-based routing. Now, as highlighted with this toolkit release, I've tried to include features that provide for Application-level composition using building blocks such as modules, services, view-services, loosely-coupled messaging etc. Additionally, I've also put in lot of infrastructure-level building blocks that tackle some of the bigger shortcomings in the platform like binding support, weak-eventing, relays, data-triggers support etc. With all the three-levels of concerns, the underlying intention is to make nRoute a more wholesome platform that extends beyond the self-defined application-flow role, to more-of a LOB framework designed for MVVM-oriented applications.
Based on that idea, the main highlights of the next drop of nRoute are dynamic application composition using SiteMaps, support for navigation to remotely defined resources, and a much improved Url-based Action infrastructure. Also I've written some extensions to RIA services for use with nRoute, that makes RIA services much more MVVM friendly whilst raising the level of abstraction of the Models provided by RIA Services. Put together, it should hopefully be a good starting point for any LOB application.