Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Reactive FeedView updates #2577

Merged
merged 4 commits into from
Oct 9, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 47 additions & 20 deletions doc/Learn/Mvux/FeedView.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ uid: Uno.Extensions.Mvux.FeedView

# The `FeedView` control

The `FeedView` control is one of the main ways to consume Feeds and States within an application. The `FeedView` uses different visual states to control what is displayed on the screen depending on the state of the underlying `IFeed`, or `IState`.
The `FeedView` control is one of the main ways to consume Feeds and States within an application. It uses different visual states to control what is displayed on the screen depending on the state of the underlying `IFeed`, or `IState`.

## How to use the `FeedView` control

Expand Down Expand Up @@ -106,7 +106,26 @@ For example:
</Page>
```

The `Button`'s `Command` property binds to the `FeedViewState`'s `Refresh` property which exposes a special asynchronous command that when called, triggers a refresh of the parent feed (in our example `CurrentContact`, and the data is re-obtained from the server.
The `Button`'s `Command` property binds to the `FeedViewState`'s `Refresh` property, which exposes a special asynchronous command that, when called, triggers a refresh of the parent feed, in our example, `CurrentContact`, and the data is re-obtained from the server.

It's also possible to bind the `Refresh` command to a Control outside the `FeedView` template, as shown below:

```xml
<Page
...
xmlns:mvux="using:Uno.Extensions.Reactive.UI">

<mvux:FeedView x:Name="feedView" Source="{Binding CurrentContact}">
<DataTemplate>
<StackPanel>
<TextBlock Text="{Binding Data.Name}" />
</StackPanel>
</DataTemplate
</mvux:FeedView>

<Button Content="Refresh" Command="{Binding Refresh, ElementName=feedView}" />
</Page>
```

##### Progress

Expand Down Expand Up @@ -192,9 +211,7 @@ But you can customize that by overriding the `ProgressTemplate`:

### NoneTemplate

If you set a template to this property, it will show if the data that was returned from the service contained no entries.
For instance, if an `IFeed<T>` completed its request successfully with the server returning a `null` result, it's important to note that this is not considered an `Error`. Instead, it's still considered a successful result with no data.
Similarly, when using `IListFeed<T>`, the `NoneTemplate` will also display if the collection is empty, as well as if the result is `null.`
Setting a template to this property will show when the data returned from the service contains no entries. For instance, if an `IFeed<T>` completed its request successfully with the server returning a `null` result, it's important to note that this is not considered an `Error`. Instead, it's still considered a successful result with no data. Similarly, when using `IListFeed<T>`, the `NoneTemplate` will also display if the collection is empty, as well as if the result is `null.`
ajpinedam marked this conversation as resolved.
Show resolved Hide resolved

Example:

Expand All @@ -214,31 +231,41 @@ Example:

### ErrorTemplate

The `FeedView` will display this template if an Exception was thrown by the underlying asynchronous operation.

### UndefinedTemplate
The `FeedView` will display this template if the underlying asynchronous operation throws an Exception.

This template is displayed when the control loads before the underlying asynchronous operation has even been called.
As soon as the asynchronous operation is invoked and awaited, the `FeedView` will switch to its `ProgressTemplate`, until the operation has resulted in data, which it will then switch to the `ValueTemplate`, or `NoneTemplate`, depending on the data result.
Example:

Typically, this template will only show for a very short period - a split second or so, depending on how long it takes for the page and its Model to load.
```xml
<FeedView ...>
<DataTemplate>
...
</DataTemplate>

## Other notable features
<ErrorTemplate>
<DataTemplate>
<TextBlock Text="An error has ocurred while loading the data..." />
</DataTemplate>
</ErrorTemplate>
</FeedView>
```

### Refresh command property
### UndefinedTemplate

The `FeedView` provides an asynchronous `Command` you can bind to, which, when executed, will refresh the underlying `Feed` by re-requesting its data source.
This template is displayed when the `FeedView` loads before the underlying asynchronous operation has even been called.
As soon as the asynchronous operation is invoked and awaited, the `FeedView` will switch to its `ProgressTemplate` until the operation has resulted in data, at which point it will switch to the `ValueTemplate` or `NoneTemplate`, depending on the data result.
ajpinedam marked this conversation as resolved.
Show resolved Hide resolved

Here's how to utilize it:
Typically, this template will only show for a very short period - a split second or so, depending on how long it takes for the page and its Model to load.

```xml
<FeedView
x:Name="feedView"
...>
<FeedView ...>
<DataTemplate>
...
</DataTemplate>
</FeedView>

<Button Content="Refresh" Command="{Binding Refresh, ElementName=feedView}" />
<UndefinedTemplate>
<DataTemplate>
<TextBlock Text="Uno Platform FeedView" />
</DataTemplate>
</UndefinedTemplate>
</FeedView>
```
Loading