Yesterday I discussed in my post, Navigating Back using State History with BuildIt.Lifecycle, how we needed to extend the state manager concept to understand and track state history. The next challenge that app developers face, that doesn’t fit nicely into the current state manager concept is that you often need to pass data between pages of the application. Think of a simple example where you have a list of contacts on one page; the user taps on one of those contacts and is taken to a new page that shows the details of that person. What you need to pass between pages is information about which contact the user tapped. I’ll discuss later how we can pass data between states, and thus view models, later in the post, but first I wanted to dig into the concept of passing data between pages a bit further.
When the user tapped on the contact in the list, there is a lot of information that we can record about that event:
- Mouse/Touch position (don’t forget we’re not just dealing with mobile devices, apps are a big part of the desktop experience on Mac and PC now)
- List index (the index of the item tapped in the list)
- List item (the object in the list that corresponds to the cell that was tapped)
- Item Id (some sort of unique identifier of the item that was tapped)
With all these pieces of information, the question is which one to pass to the details page. Let’s review them individually:
- Mouse/Touch position – this in itself isn’t very useful as it only has meaning on the page that’s currently in view and that point in time. For example, if the user were to scroll the list, all of a sudden this information is useless as it now points to a different cell in the list
- List index – this is only useful if the details page has a reference to exactly the same list that is used to populate the contacts list page. If the underlying data set changed (eg sync with backend caused new contacts to be downloaded), then the list index might now point to a different item
- List item – if the items in the list contain all the details necessary to populate the details page then passing the list item to the details page is ok. However, if you have a large list off contacts, chances are you only load enough data about each contact to display the item in the list (eg perhaps only photo and name). In this case, passing the whole entity isn’t that useful since the details page has to load the whole contact anyhow. The other point worth considering is about serialization of navigation parameters – depending on the platform there are mechanisms for persisting navigation stack, including data parameters; some of these have size and complexity constraints on the data passed between pages.
- Item Id – this is probably the best choice for this scenario. It contains enough information for the contact to be loaded. If performance is a concern (ie you want the contact summary information to be instantly available when the user arrives at the details page, even if details have to be progressively loaded), then you should cache the contact summary information in memory in a service which can be accessed as soon as the details page is loaded. The cache service might also cache the last X number of loaded contacts in memory to make it quick for a user to go between contacts.
Ok, so this works for this scenario but how do we summarize this into a more generic form. Essentially it comes down to passing the minimal set of information between pages that is required to completely load the next page. Ideally pages (and their corresponding ViewModel) should be self sufficient, relying only on application services to load data. Application services, most likely passed into the ViewModel using some sort of dependency injection, provide an abstraction over loading/saving data both locally (in memory and to disk) and across the network (calling services or performing data sync). To this end, by supplying the minimum set of information (eg item id in the case of the contacts list scenario), the ViewModel is only reliant on that piece of information. This reduces the necessary testing surface area as there are few permutations of input data that need to be teted.
Now that we have an understanding of how to determine what data to pass between pages, we again need to come back to thinking in terms of states and passing data during a transition between states. If you recall, our ViewModels aren’t aware of states or the ability to change between them. All they’re able to do is indicate that they’re complete. In the following code, the MainViewModel exposes a public HelloWithTime property as well as a private AboutWithTime property, the former will be passed into the Settings state, the latter into the About state. You’ll observe that the OnComplete call for settings hasn’t been changed, whilst there is now a call to OnCompleteWithData, passing in the AboutWithTime property value, for completing with the About completion value.
public class MainViewModel : BaseViewModelWithCompletion<MainCompletion>
{
public string HelloWithTime => $"Hello World at {DateTime.Now.ToString("h:mm tt")}";
private string AboutWithTime => $"About information {DateTime.Now.ToString("h:mm tt")}";
public void DisplaySettings()
{
OnComplete(MainCompletion.Settings);
}
public void DisplayAbout()
{
OnCompleteWithData(MainCompletion.About,AboutWithTime);
}
}
Our state declaration now looks like the following:
var group = StateManager.GroupWithViewModels<AppStates>()
.StateWithViewModel<AppStates, MainViewModel>(AppStates.Home)
.OnCompleteWithData(MainCompletion.Settings,vm=>vm.HelloWithTime)
.ChangeState(AppStates.Settings)
.OnCompleteWithData< AppStates, MainViewModel,MainCompletion,string>(MainCompletion.About,null)
.ChangeState(AppStates.About)
.EndState()
.StateWithViewModel<AppStates, SettingsViewModel>(AppStates.Settings)
.OnComplete(DefaultCompletion.Complete).ChangeToPreviousState()
.EndState()
.StateWithViewModel<AppStates, AboutViewModel>(AppStates.About)
.EndState();
(group.Item2.States[AppStates.Settings] as IViewModelStateDefinition<AppStates, SettingsViewModel>)
.WhenChangedToWithData<AppStates, SettingsViewModel, string>((vm, d) => vm.SettingsTitle = d);
(group.Item2.States[AppStates.About] as IViewModelStateDefinition<AppStates, AboutViewModel>)
.WhenChangedToWithData<AppStates, AboutViewModel, string>((vm, d) => vm.AboutTitle = d);
What’s interesting here is that there are two parts to passing data between states. The first is how the data is exposed out of the state that’s being completed. Here I’ve shown two ways – completion with Settings uses the public HelloWithTime property to retrieve the data to pass to the next state; completion with About can’t access the AboutWithTime property, since it’s private, which is why it relies on the MainViewModel to pass out the AboutWithTime value when it invokes OnCompleteWithData. Note that currently in the state declaration you still need to call OnCompleteWithData passing in a null value for the data accessor, otherwise the data value isn’t passed – this will be fixed shortly.
The second part of passing data between states is how the data is passed into the new state. This is done by calling the WhenChangedToWithData and specifying a function that will be invoked with the corresponding data. Note this method is a generic method and you can actually call it multiple times with different data types, which means that you can handle arriving at this state with different data (perhaps from different states). One thing to be aware of is that behind the scenes the data is being serialized to json, so whatever data you pass between states need to be serializable to json. Ideally the data being passed between states should be kept to a minimum.