PullToRefreshLayout

What is PullToRefreshLayout you may ask? Well it is a type of Xamarin.Forms Layout that can house another Layout. This means that the pull to refresh now can be applied to anything. Do you want to pull to refresh a ScrollView? Sure! How about a StackLayout? Sure! And Grids? GO FOR IT! Heck I even made it so you can do it with custom controls and even the ability to fine tune how the scroll moves up and down. To really really top it off I even made it so PullToRefreshLayout can replace Xamarin.Forms ListView’s built in pull to refresh features.

Alright, so sure you can add it to any view, but what is it really supported on. Well think of the PullToRefreshLayout as a wrapper around any control that is bundled up. However, you really must have something scrollable such as a Xamarin.Forms ScrollView or TableView.

Updated BindingProperties

This time around I did a strict one to one mapping of Xamarin.Forms ListView pull to refresh binding:

public bool IsPullToRefreshEnabled { get; set; } = true;
public bool IsRefreshing { get; set; } = false;
public ICommand RefreshCommand { get; set; } = null;

However, I modified it so IsPullToRefreshEnabled is defaulted to true and I added a few colors that you can set:

public Color RefreshColor { get; set; } = Color.Default;
public Color RefreshBackgroundColor { get; set; } = Color.Default;

If you don’t set anything, don’t worry as they will take on the system defaults.

Common Control

In the past I developed the iOS and Android controls completely separate with different bindings, names, and base types. Well no more! Simply create a new PullToRefreshLayout and you are done!

Here it is in action with a ScrollView:

And here is the code to insert a PullToRefreshLayout:

There you have it, but where can you get it? Well I highly recommend that you actually add either a submodule or copy and paste in the control from GitHub if you want to actively debug or add custom controls that can be pulled to refreshed. So head over to my GitHub page, star the repo, follow me, and read the README! Or if you really really want I have published it to NuGet for your consumption!

See it on Motz Codes Live!

Next Friday Sept 11th at 9AM Pacific I will be showing off all sorts of Pull to Refresh goodness with Xamarin.Forms. RSVP here on Google Hangouts!

I couldn’t explain how it works better than the official release notes: 

When the user triggers a PullToRefresh the Command will be invoked and the Refreshed event emitted. IsRefreshing will be set to true. The ICommand.CanExecute property is respected. The user must either call EndRefresh or assign IsRefreshing to false in order to end the refresh state.

So, how would you implement this in your ViewModel? Well I start all things off with a bool called IsBusy that tracks if we are loading data on the page:

We can use this to bind to our IsRefreshing and use it as a CanExecute flag for our ICommand. Next is to setup some sort of ICommand and method that will be refreshing our data. In this example I am updating my Hanselman.Forms app’s tweets page to have pull to refresh, so here is the code that refreshes tweets:

Notice I am using my IsBusy as a control for CanExecute, and also after I change it I call the Command’s ChangeCanExecute method to ensure anyone listening knows to update their status. You can make this a bit more clever if you desire in the properties getter/setter.

Finally is the DataBinding part and you will need to setup and bind up 3 properties: IsPullToRefreshEnabled, RefreshCommand, and IsRefreshing.

Notice I am only Binding OneWay on IsRefreshing. This means that my ViewModel can notify and change the IsRefreshing, but the Refresh view is not in control of my IsBusy. This is only important because I always check IsBusy ahead of time when I run my refresh logic. I am also using IsBusy to modify the CanExecute so I don’t want any outside forces modifying it.

And there you have it, let’s see it in action:

It is true that I absolutely love cross platform settings for mobile applications built with Xamarin. However, there is something that I love even more… Pull To Refresh!

It all started over year ago when I blogged about how to add a UIRefreshControl to MVVMCross iOS apps. Google then introduced an official SwipeRefreshLayout for Android , so naturally I blogged about adding this new layout to your MVVMCross Android applications. With the release of Xamarin.Forms to build iOS, Android, and Windows Phone apps UIs from one shared C# code base things got a little bit more interesting. Since everything was shared logic even for the UI you had to do a little bit more work to get pull to refresh working on iOS with a custom renderer and view. Yet again I got the source code up and running and blogged about it as well. I am back for a fourth blog after much effort, work, and help from Jason to get a Pull To Refresh for Xamarin.Forms Android apps :)

Getting Started

There are a few things to understand about the SwipeRefreshLayout and also about Xamarin.Forms before we get started. The SwipeRefreshLayout is part of the Support v4 Library, which you can find on NuGet, and at it’s core it is just a ViewGroup and acts as a FrameLayout that you can add Android Views to it. You can read all about it’s properties on Google’s Android documentation website. On the Xamarin.Forms side of things there is a great extensibility model using custom renders to customize controls or add your own controls to Xamarin.Forms. So using this concept I thought it would be a nice idea to use a ContentView as my base control to inherit from and add bindable properties to trigger a refresh and execute a refresh command. This will look very similar to the iOS version except that I had inherited from a ListView for iOS:

Custom Renderer

Normally you would pick from a set of pre-built Renderers that are built into Xamarin.Forms to do your customizations. Or you can inherit from a ViewRenderer for a custom view, which is really nice. The issue here is that we will need access to add and remove Child views from the SwipeRefreshLayout. So, while these base Renderers provide a lot of great things built into the framework such as handling most of the property changes, the issue we will run into is there is no ContentViewRenderer and even using a ViewRenderer we will not be able to accomplish our goal (trust me I have tried). This is when Jason led me onto Xamarin.Forms capability of doing everything yourself by subclassing SwipeRefreshLayout itself and implementing IVisualElementRenderer, which is an interface that enables you to make any control a Xamarin.Forms control.

public class FormsSwipeRefreshLayout : SwipeRefreshLayout,
		IVisualElementRenderer,
		SwipeRefreshLayout.IOnRefreshListener

The caveat here is that you have do ALL of the manual work to set it up and get it working. There are a few helpers though to get you going and once you understand how it actually works it is really simple to create them.

IVisualElementRenderer Implementation

Here is our default implementation of IVisualElementRender:

Now this might look a little scary, but let’s break it down one step at a time. SetElement is actually the largest amount of work. This is where we will setup the control and register for property change events. This method will also fire off the ElementChanged event whenever it is called. In this instance we only ever want to initialize once and we will save the “ViewGroup” that is added as the ContentView to our Xamarin.Forms control so we can add it later on.

The rest of the code is actually really simple and is just a bunch of getters and setters since we already set most of this up in the SetElement Method. The only real work we need to implement is measure any children that we have added as sub views:

Almost there!

With this code in place we are basically done, but we will run into a few issues when we run the sample because the SwipeRefreshLayout doesn’t actually know when it is allowed to be pulled or when it should disable itself. The CanChildScrollUp method of the SwipeRefreshLayout is what handles this, and it usually expects a ListView or ScrollView to be the first child, however there seems to be some quirks with how Xamarin.Forms is laying out the controls (or maybe how we are). So, we just need a bit of logic to tell the SwipeRefreshLayout when the ListView is allowed to scroll up.

That’s it! With the refresh control in place we can now add this into our shared code to see it in action!

Limitations

Mostly, this is really proof of concept and I need to do a bit more work to really make it bullet proof. It is extremely functional, but here are the current limitations.

• Only works with ListView set as Content of ContentView
• IsRefreshing Binding only goes 1 way from ViewModel down to Control (will be fixed in 1.3.X of Xamarin.Forms)
• You must manually SetColorSchemeResources in code behind (no bindings here yet, but I accept PRs)
• No support for other normal bindable properties of a ContentView such as BackgroundColor (again, I support PRs)

Get the Code!

As always ,you can get the code from my GitHub account. I have created a new special repository where this code lives called “Xamarin.Forms Awesome Controls”, that houses a few custom controls I have done and the iOS pull to refresh implementation. This is where I will be putting all of my code in the future to ensure it is easy to find and doesn’t clutter up my GitHub. I hope that you enjoyed this post and find it helpful. It is truly proof of just how extensible Xamarin.forms is.

In iOS6+ land adding pull to refresh is EXTREMELY simple. You can read all about it, but basically you need to just implement 1 method and you can even set a custom string and style it. It is beautiful, however there was no way to bind anything in MvvmCross. So I wanted to create a simple binding to accomplish a few goals:

1.) Execute an ICommand when someone pulls down to refresh

2.) Bind a bool to begin and end the refreshing spinner

3.) Bind a string to set the AttributedTitle (what is displayed to the user) when they pull or when it refreshes.

So I created a very very simple UIRefreshControl, which you can find on Gist RIGHT HERE

The code is as simple to implement as:

var refreshControl = new MvxUIRefreshControl();
this.RefreshControl = refreshControl;

var set = this.CreateBindingSet<MyView, MyViewModel>();
set.Bind(refreshControl).For(r => r.IsRefreshing).To(vm => vm.IsBusy);
set.Bind(refreshControl).For(r => r.RefreshCommand).To(vm => vm.ReloadCommand);
set.Bind(refreshControl).For(r => r.Message).To(vm => vm.BusyMessage);
set.Apply();

I hope this helps