Chinook.DataLoader.Abstractions 0.10.0

Chinook.DataLoader

Async data loading made visually pleasant!

Getting Started

Install the latest version of Chinook.DataLoader.Uno in your project.

Create a IDataLoader using the builder (see below on how to use with Chinook.DynamicMvvm).

var dataLoader = DataLoaderBuilder<MyData>
  .Empty
  .WithName("MyDataLoader")
  .WithLoadMethod(LoadData)
  .Build();

Task<MyData> LoadData(CancellationToken ct)
{
  // Your async operation here.
}

Add a DataLoaderView in your xaml.

<dl:DataLoaderView Source="{Binding MyDataLoader}" />

As the task is being executed, the IDataLoader will call its StateChanged event which will be used by DataLoaderView to visually represent the state of the async operation.

Features

Async data loading

The loading method of the IDataLoader must simply return a Task of the data type (here MyData).

Task<MyData> LoadData(CancellationToken ct)
{
  // Your async operation here.
}

This is where you would typically execute an API call or get data from any other async source.

This method receives a CancellationToken as the operation might be cancelled.

• If the IDataLoader is disposed.
• If another request was made and the concurrent mode is CancelPrevious.

Data loader states

At any given time, the IDataLoader can be in a combination of the following states.

Imagine a scenario where you land on a page where the data has never been loaded before from an API.

1. The system would first be on an initial state (not loading, no data, no error).
2. The system would then start loading the data from the API.
3. The system would then show the data returned from the API.
4. You lose connection and refresh the page.
5. The system notifies you that there was an error, but you still have your previous data.

This could be represented by the following state flow.

#1                  #2                 #3                  #4                 #5
IsLoading(false) -> IsLoading(true) -> IsLoading(false) -> IsLoading(true) -> IsLoading(false)
Data(null)       -> Data(null)      -> Data(myData)     -> Data(myData)    -> Data(myData)
Error(null)      -> Error(null)     -> Error(null)      -> Error(null)     -> Error(WebException)

Note: The error is cleared as soon as there is a successful request

Other useful states are available:

Triggers

As the data might need to be updated, you can trigger a new load request on a IDataLoader using triggers.

You can create your own triggers by inheriting from DataLoaderTriggerBase.

Simply call RaiseLoadRequested when a load request should be requested.

Note: DataLoaderView has a AutoLoad property which, as its name suggests, automatically load the data of the DataLoader when it's displayed.

Requests and contexts

To provide metadata on the loading operation, two important pieces are used.

You can get additional information from the IDataLoader by adding the IDataLoaderRequest parameter.

Task<MyData> LoadData(CancellationToken ct, IDataLoaderRequest request)
{
  // This is the trigger that caused that loading operation.
  var sourceTrigger = request.SourceTrigger;

  // This is the context that was passed to the loading operation from the trigger.
  var context = request.Context;

  // Your async operation here.
}

The request is also available as part of the IDataLoaderState.

DataLoaderView

The DataLoaderView represents the different states of the IDataLoader using the following visual states.

You can easily define the template displayed in these states by using the following template properties.

To avoid seeing flickery transitions between the different visual states, the DataLoaderView supports different throttling options.

<dl:DataLoaderView Source="{Binding MyDataLoader}"
                   StateMinimumDuration="0:0:1.5"
                   StateChangingThrottleDelay="0:0:0.100" />

DynamicMvvm

Extension methods are available on Chinook.DynamicMvvm to create data loaders with refresh commands.

Simply add the Chinook.DataLoader.DynamicMvvm package to your project.

public class MyViewModel : ViewModelBase
{
  public IDynamicCommand RefreshData => this.GetCommandFromDataLoaderRefresh(Data);

  public IDataLoader Data => this.GetDataLoader(GetData, b => b
    // You can optionally configure your data loader here
  );

  private async Task<MyData> GetData(CancellationToken ct)
  {
    // Get data from your API...
  }
}

Code Snippets

You can install the Visual Studio Extension Chinook Snippets and use code snippets to quickly generate data loaders when using Chinook.DynamicMvvm. All snippets related to IDataLoader start with ckdl.

Changelog

Please consult the CHANGELOG for more information about version history.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.

Contributing

Please read CONTRIBUTING.md for details on the process for contributing to this project.

Be mindful of our Code of Conduct.