Free yourself from IsBusy=true!
The `TaskLoaderView` and the `TemplatedTaskLoader` are UI components that handle all your UI loading state (Loading, Error, Result, Notification), and removes all the pain of async loading from your view models (try catch / async void / IsBusy / HasErrors / base view models / ...) thanks to its brother the `TaskLoaderNotifier`.
Featuring:
* Default views for all loading states (Loading, Error, Success, Notification, Refresh)
* Snackbar component
* Compose notifiers with CompositeTaskLoaderNotifier
* Stylable views including fonts, accent color, error images, ...
* Any states are overridable with user custom views and easily positionned with AbsoluteLayout properties
* Support for Xamarin.Forms.Skeleton nuget package
* Support for refresh scenarios, and error while refreshing with the ErrorNotificationView
* Supports Async mvvm ICommand through TaskLoaderCommand
* Supports loading task on demand with the NotStarted state
* TaskLoaderNotifier for the ViewModel side taking care of all the error handling and the IsBusy nonsense
The TaskLoaderView is a UI component that handles all your UI loading state (Loading, Error, Result, Notification), and removes all the pain of async loading from your view models (try catch / async void / IsBusy / HasErrors / base view models / ...) thanks to its brother the TaskLoaderNotifier.
MAUI Supported platforms
<img src="Docs/maui_logo.png" height="100" />
:heavy_check_mark: Android
:heavy_check_mark: iOS
:heavy_check_mark: Windows
:heavy_check_mark: macOS
Featuring:
Default layout for all loading states (Loading, Error, Success, Notification, Refresh)
Stylable layouts including fonts, accent colors, error images, ...
Support for async ICommand with TaskLoaderCommand and CompositeTaskLoaderNotifier
Any states are overridable with user custom views and easily positioned with AbsoluteLayout properties
Support for Xamarin.Forms.Skeleton nuget package
Support for refresh scenarios, and error while refreshing with the ErrorNotificationView
Support loading task on demand with the NotStarted state
TaskLoaderNotifier for the ViewModel side taking care of all the error handling and the nonsense
New CompositeTaskLoaderNotifier builder and simplified wiring
You can use the new builder for the CompositeTaskLoader that will wire for you the ShowErrorNotification of your loaders, and the errors from your TaskLoaderCommand:
The task source given to TaskLoaderNotifier is now a Func<bool, Task> (or a Func<bool, Task<T>>) instead of a Func<Task>.
You can simply change your calls from Loader.Load(() => InitializeAsync()) to Loader.Load(_ => InitializeAsync())
The boolean passed now to your task source is a boolean indicating if the notifier is refreshing.
You can use it for invalidating your cache for example.
Loader.Load(LoadItems);
public Task LoadItems(bool isRefreshing)
{
if (isRefreshing || !_cache.ContainsItems())
{
_cache.InvalidateItems();
var items = _httpService.GetItems()
_cache.PutItems(items);
return items;
}
return _cache.GetItems();
}
When the RefreshCommand will be called, it will pass automatically the isRefreshing boolean set to true to your task source.
TaskLoaderView features
Default state views
The TaskLoaderView implements default view for all the task loading states:
Loading, a simple ActivityLoader is displayed
Error, an image with a retry button
Success, your xaml inside the TaskLoaderView
Notification, when an error occurs whereas some information has already been displayed
Refresh, with a RefreshView for example
It is highly stylable, and you can even provide converters to translate an Exception to a meaningful image and message.
You can see that the TaskLoaderView uses an AbsoluteLayout internally. So you can use AbsoluteLayout bounds and flags to position your views.
Support for DataTemplate (since 2.1.0)
You can now add your customs views as View or DataTemplate.
If you choose the latest option, you can now specify your custom views in a ResourceDictionary and set them in your TaskLoaderView style.
It's brilliant! The TaskLoaderView is supporting a simpler use case of the properties by binding directly to the TaskLoaderNotifier. With this method you don't have to create fake item view models in your page view model.
In case of a list: you just have to create a static array of item view models.
public static class Skeletons
{
public static Game[] Games = new[]
{
new Game(
0,
null,
null,
DateTime.Now,
new List<Genre> { new Genre(1, "Genre genre") },
new List<Company> { new Company(1, "The Company") },
"Name name name",
null),
new Game(
0,
null,
null,
DateTime.Now,
new List<Genre> { new Genre(1, "Genre genre") },
new List<Company> { new Company(1, "The Company") },
"Name name name",
null),
new Game(
0,
null,
null,
DateTime.Now,
new List<Genre> { new Genre(1, "Genre genre") },
new List<Company> { new Company(1, "The Company") },
"Name name name",
null),
}
}
If you are not loading a list but a simple object, you don't even have to use a custom LoadingView, you can just use the TaskLoaderType="ResultAsLoadingView" property.
Supports for MVVM async Command with TaskLoaderCommand and Snackbar
You probably read many blogs about how you should implement a AsyncCommand instead of a regular Command for your Task based code.
Of course, like all async mvvm patterns, the original idea comes from Stephen Cleary.
But what if we could merge the power of TaskLoaderNotifier with the classic ICommand interface?
The TaskLoaderCommand will take as parameter a function returning a Task, and will wrap it in a NotifyTaskNotifier. You can then bind your TaskLoaderView to the NotifyTaskNotifier exposed by your TaskLoaderCommand.
It's in fact the missing piece to have a complete UI feedback to all our actions.
The TaskLoaderView Snackbar
We at Sharpnado, created a simple Snackbar component very simple with timer and customization:
You can then very simply bind a TaskLoaderCommand to your Snackbar:
BuyGameCommand = new TaskLoaderCommand(BuyGame);
private async Task BuyGame()
{
LoadingText = "Proceeding to payment";
RaisePropertyChanged(nameof(LoadingText));
await Task.Delay(2000);
throw new LocalizedException($"Sorry, we only accept DogeCoin...{Environment.NewLine}BTW GameStop are still opened");
}
Then when pressing "BUY IT", you will get this
As you can see you can change the auto dismiss timer as you like, but also the font size, color, family, etc...
CompositeTaskLoaderNotifier: a love story with Commands and Snackbar
So with the TaskLoaderCommand you knew you could bind any action to a UI component and have a great UI feedback.
But thanks to the CompositeTaskLoaderNotifier you can now bind SEVERAL async Command states to ONE UI Component.
It makes all your commands UI feedback sooooo easy.
You can bind 1, 2, 3, 4, 423 commands to a unique Snackbar or/and a unique loading dialog \o/
EXAMPLE
Now look at that you just pass as parameters all the notifiers from your commands to the composite constructor:
public class CommandsPageViewModel : ANavigableViewModel
{
private readonly IRetroGamingService _retroGamingService;
public CommandsPageViewModel(INavigationService navigationService, IRetroGamingService retroGamingService)
: base(navigationService)
{
_retroGamingService = retroGamingService;
Loader = new TaskLoaderNotifier<Game>();
BuyGameCommand = new TaskLoaderCommand(BuyGame);
PlayTheGameCommand = new TaskLoaderCommand(PlayTheGame);
CompositeNotifier = new CompositeTaskLoaderNotifier(
BuyGameCommand.Notifier,
PlayTheGameCommand.Notifier);
}
public CompositeTaskLoaderNotifier CompositeNotifier { get; }
public TaskLoaderCommand BuyGameCommand { get; }
public TaskLoaderCommand PlayTheGameCommand { get; }
public TaskLoaderNotifier<Game> Loader { get; }
public string LoadingText { get; set; }
public override void OnNavigated(object parameter)
{
Loader.Load(() => GetRandomGame());
}
private async Task<Game> GetRandomGame()
{
await Task.Delay(TimeSpan.FromSeconds(2));
return await _retroGamingService.GetRandomGame(true);
}
private async Task BuyGame()
{
LoadingText = "Proceeding to payment";
RaisePropertyChanged(nameof(LoadingText));
await Task.Delay(2000);
throw new LocalizedException($"Sorry, we only accept DogeCoin...{Environment.NewLine}BTW GameStop are still opened");
}
private async Task PlayTheGame()
{
LoadingText = "Loading the game...";
RaisePropertyChanged(nameof(LoadingText));
await Task.Delay(2000);
throw new LocalizedException("AHAHAHA! Yeah right...");
}
}
...bind the composite notifier to your loading dialog and snackbar...
Loading task on demand: NotStartedView and TaskLoaderCommand
Another example of using TaskLoaderCommand is the ability to load views on demand.
A NotStartedView state is also available so you can display a view before loading the Task.
It is quite useful for load-on-demand.
Here TaskLoaderType="ResultAsLoadingView" is set cause we are using the skeleton loading for just one object.
public class LoadOnDemandViewModel : Bindable
{
private readonly IRetroGamingService _retroGamingService;
public LoadOnDemandViewModel(IRetroGamingService retroGamingService)
{
_retroGamingService = retroGamingService;
RandomGameLoaderCommand = new TaskLoaderCommand<object, Game>(_ => GetRandomGame());
}
public TaskLoaderCommand<object, Game> RandomGameLoaderCommand { get; }
private async Task<Game> GetRandomGame()
{
await Task.Delay(TimeSpan.FromSeconds(4));
if (DateTime.Now.Millisecond % 2 == 0)
{
throw new NetworkException();
}
return await _retroGamingService.GetRandomGame();
}
}
ErrorNotificationView
We tend to forget a state in our Task loading cycle: the notification view.
Consider this scenario:
we are loading a list of retro game
loading is successful: the list is displayed
we are refreshing the list
oops an error occurs
do we want to see the error view although the items were correctly loaded before?
NO! We just want to see a nice snackbar warning the user about it.
The ErrorNotificationView is also customizable if you like. It's brought to you with a nice TimedVisibilityBehavior so that you can specify how much time it needs to be shown to the user.
The TaskLoaderNotifier is a loading component for your tasks, and is commonly used in your view models.
public class RetroGamesViewModel : ANavigableViewModel
{
private readonly IRetroGamingService _retroGamingService;
public RetroGamesViewModel(
INavigationService navigationService,
IRetroGamingService retroGamingService)
: base(navigationService)
{
_retroGamingService = retroGamingService;
RefreshCommand = new Command(() => Load(null));
Loader = new TaskLoaderNotifier<List<Game>>();
}
public TaskLoaderNotifier<List<Game>> Loader { get; }
public ICommand RefreshCommand { get; }
public override void Load(object parameter)
{
// TaskStartMode = Manual (Default mode)
Loader.Load(InitializeAsync);
}
private async Task<List<Game>> InitializeAsync()
{
...
}
}
And that's all. It wraps all the states of the task (NotStarted, Loading, Fault, Success).
You can just stop worrying about IsBusy, HasErrors, ErrorMessage, IsRefreshing...
You bind your TaskLoaderNotifier to your TaskLoaderView, and the magic happens.
