Contents:

1. Sample project to demonstrate a coding pattern based on MVVM with focus on
   1. Easy composition of views
   2. Minimising boilerplate of setting up views
   3. Reuse of presentation logic
2. A library with essential tools for the pattern

1. Android Data Binding
2. RxJava
   • 2-minute intro to Rx
   • Grokking RxJava
   • Intro to Reactive Programming by André Staltz
   • Comprehensive list
3. Introduction to this pattern @DroidconIN

Getting Started provides a tutorial to setup the library and gives an idea about its functionality. As the main deliverable of this library is the pattern, it is important to understand the principles behind it, so that the pattern can be applied even at places where the library APIs aren't available.

This pattern makes use of Data Binding, such that views contain exactly 1 variable vm i.e. ViewModel. Idea is that the ViewModel should have all information required to display the View. Multiple views can share a single view model. This helps in reusing functionality for a different layout.

Using a single variable vm provides a consistent mechanism to configure any View:

viewBinding.setVariable(BR.vm, viewModel)

Note that this mechanism needs to be configured by providing an instance of ViewModelBinder interface. This interface describes how a ViewModel is bound to a View. The variable name to be used in xmls (vm in this example) should be specified here.

BindingUtils.setDefaultBinder(new ViewModelBinder() {
    @Override
    public void bind(ViewDataBinding viewDataBinding, ViewModel viewModel) {
        viewDataBinding.setVariable(BR.vm, viewModel);
    }
});

This code can be placed in your onCreate method of Application/Activity.

A view model is a POJO formed by fields for storing data (for input/output) and event listeners. In MVVM, interaction between ViewModel and View happens via changes in data OR method calls. These interactions can be categorized based on direction & type of data flow:

1. Output Data (ViewModel -> View) ViewModel changes its data, View listens for changes & updates itself Example: ViewModel is running a timer, and updating its timeText variable. View is listening for changes and updating itself whenever it gets a callback.

2. Input Data (View -> ViewModel) View requests ViewModel to update its data (such as capturing text input) Example: Form containing various inputs like text for EditText, isChecked for Checkbox.

3. Input Events (View -> ViewModel) View invokes functions on ViewModel when certain events occur (such as onSwipe/onClick/onFocused) Note the difference between Data and Event. Any input can be represented as an Event. However, wherever there is persistence in input, representing them as Data is convenient. For example, if a user has typed Googl in EditText, this input is represented as a String variable with value Googl. When user types e, the text changed "event" causes the data to change to Google. Working with data is better in this example. Consider an example of a Button click. There is no data change that's implicitly happening on click. Hence, this input is represented as an Event.

Now, we'll see how these three interactions are implemented in this pattern.

This is stored as a field in the ViewModel class. If the value is constant, it can be simply declared as a final TYPE. If its changing, it is declared as an ObservableField<TYPE>, provided by data binding. Example for displaying text (String)

public class OutputDataViewModel {
  public final String constantOutput = "";
  public final ObservableField<String> changingOutput = new ObservableField<String>("");
}

Note that everything is final. To modify the changingOutput, its set function is used. Example: this.changingOutput.set("new value");. Data binding takes care of adding listeners and updating the view.

In XML, this data is displayed by referring to these fields.

<TextView ...
  android:text="@{vm.constantOutput}" />

<TextView ...
  android:text="@{vm.changingOutput}" />

As input data implies that it cannot be constant, it is always stored as an ObservableField<TYPE>.

public class InputDataViewModel {
  public final ObservableField<String> inputText = new ObservableField<String>("");
}

Because we want the view to update the value of this ObservableField, Two Way Binding is used.

<EditText ...
  android:text="@={vm.inputText}" />

The @= enables two way binding

EventListeners can be implemented simply as methods in ViewModel

public class EventViewModel {
  MessageHelper messageHelper; // This is an external dependency

  public void onClick() {
    messageHelper.show("Something got clicked");
  }  
}

<Button
  android:onClick="@{(v) -> vm.onClick()}"/>

Another approach is to implement listeners as Runnable fields inside ViewModel.

public class EventViewModel {
  MessageHelper messageHelper; // This is an external dependency

  public final Runnable onClick = () -> {
    messageHelper.show("Something got clicked");    
  };
}

<Button
  android:onClick="@{vm.onClick}"/>

For this to work, a BindingConversion between View.OnClickListener and Runnable needs to be defined.

@BindingConversion
public static View.OnClickListener toOnClickListener(final Runnable runnable) {
    if (runnable != null) {
        return () -> runnable.call();
    } else {
        return null;
    }
}

This static function can be placed anywhere in your code.

Using a BindingAdapter/BindingConversion, click event can be bound through a PublishSubject.

class ItemViewModel {
  public final PublishSubject<ItemViewModel> onSelect;
}

// When working with a list of view models, its easy to merge events.
Observable<Item> onAnyItemSelect = itemViewModels.map { vm -> vm.onSubmit }.merge().map { vm -> vm.item };

There are various ways to define Event handlers. There are no compelling points to stick to a fixed way. Use the approach which suits you the best

This is the core principle behind MVVM. Naturally, ViewModel cannot have a reference to View or any subclass. In addition to these, ViewModel cannot know about any platform-specific implementation details. Thus, Android classes such as Activity, Fragment, Context cannot be referenced.

This also means that the ViewModel logic is same across different platforms such as iOS or web

Any platform-dependent functionality is abstracted into an interface and then provided to ViewModel. In the above example, MessageHelper is an interface for displaying a message to user. The activity can choose to implement it using Toast or any other mechanism. Keeping these implementations outside allows sharing them. For example, MessageHelper can be implemented in a BaseActivity, which could be a base class for all activities.

In a deep hierarchy, fulfilling such dependencies can result in a lot of boilerplate. In that case, it is recommended to use dependency injection libraries to keep things clean. A minimal example using Dagger2 is available on extras/dagger branch.

As ViewModels do not reference Android classes, testing them is straight forward. Tests are written as plain Unit Tests. As all dependencies are interfaces, they get easily mocked.

@Test
public void detailsPage_isOpened_onClick() throws Exception {
    Item item = new Item("Item 1", null);
    Navigator mockNavigator = mock(Navigator.class);
    ItemViewModel viewModel = new ItemViewModel(item, mockNavigator);

    viewModel.itemClicked.call();

    verify(mockNavigator).openDetailsPage(item);
}

This example uses Mockito framework for mocking

RxJava provides a great bunch of operators for handling changes. For example, if a dynamic field of a model needs to be formatted before displaying, it is convenient to store it as an io.reactivex.Observable<TYPE>. The map operator can be used to format the values.

FieldUtils class provides methods for converting between RxJava's Observable and Data Binding's ObservableField types. This allows the use of RxJava's operators to manipulate the data.

Example: Cart has a getTotalAmount() method that returns an Observable<Float>. Amount needs to be formatted before displaying. This can be implemented as follows:

public final ReadOnlyField<String> totalAmountText;
public CartViewModel(Cart cart) {
  totalAmountText = FieldUtils.toField(cart.getTotalAmount().map(a -> a + " Rs"));
}

The toField method returns an instance of ReadOnlyField which extends ObservableField. Note that set method in ReadOnlyField does nothing. See Observables And Setters for the rationale behind this.

Example: Error needs to be shown if input text is empty.

static import FieldUtils.toObservable;
static import FieldUtils.toField;

public final ObservableField<String> inputText = new ObservableField<>("");
public final ReadOnlyField<Boolean> errorVisible = toField(toObservable(inputText).map(text -> text.isEmpty()));

<EditText
  android:text="@={vm.inputText}"/>
<ErrorView
  android:visibility="@{vm.errorVisible}"/>

A binding adapter would be required to use boolean for visibility attribute.

@BindingAdapter("android:visibility")
public static void bindVisibility(@NonNull View view, @Nullable Boolean visible) {
    int visibility = (visible != null && visible) ? View.VISIBLE : View.GONE;
    view.setVisibility(visibility);
}

See SearchViewModel.java and the corresponding activity_search.xml for another example in which the search results get updated as user updates the query.

Both RxJava 1.x and 2.x are supported. For RxJava 1.x support, an additional dependency needs to be added:

compile 'com.manaschaudhari.android-mvvm:rxjava-compat:x.y.z'

// Under android config
android {
    packagingOptions {
        exclude 'META-INF/rxjava.properties'
    }
}

Note that rxjava-compat internally depends on both RxJava2 and RxJava

This adds equivalent BindingAdapters for rx.Observable. This also includes rxjava.FieldUtils class for conversions between rx.Observable and databinding.ObservableField. Thus, the syntax is same except for the imports.

See SearchViewModel.java(rxjava-compat) for an example implemented using rxjava-compat.

Views are setup using XML ONLY. This is the core idea behind this pattern. BindingAdapters are used to create a declarative API with essential arguments.

Thus, whenever it is required to write code for setting up a view, create a BindingAdapter instead and use XML attributes.

This also applies to complex views such as RecyclerView/ViewPager which need setting up adapters. These views are containers which display (multiple) child views. This particular operation of nesting views is termed as View Composition. As the choice of pattern (MVVM/MVP) greatly affects how View Composition is done, this library provides tools to deal with this aspect. However, there are other scenarios where code is required to setup views. Such code gets moved to a BindingAdapter and the view is setup using XML attributes.

The BindingUtils file contains BindingAdapters provided by this library. These are good examples to learn about this approach.

If this is not doable in some case, it implies that you need a functionality that's not provided by existing views. Create a custom View in that case.

Just like code, UI also needs to be reused at multiple pages. Just like classes are split into smaller classes, views are split into smaller views to make them reusable.

Lets say a page requires to combine 3 functionalities. There can be 1 ViewModel to represent each functionality. Similar to how layout hierarchy is created using <include>, a parent ViewModel is created that contains child ViewModels as fields. Data Binding allows binding included layout's variables.

<ParentLayout>
  <include layout="@layout/child_view"
    bind:vm="@{vm.childVm}" />
</ParentLayout/>

Thus, with a simple <include>, this layout gets added on the page. The only Java code required is to add the childVm field in the outer ViewModel.

It is very common to display a dynamic number of views in a RecyclerView or a ViewPager. The type of each child view could also vary based on some data. Writing a new adapter to support different view types results in duplicate code.

With MVVM, as we have a consistent mechanism to setup any view, it is now possible to write abstract adapters, which can be used for displaying any type of views. This reduces a lot of boilerplate. For example, a RecyclerView can be setup with these two inputs:

• Observable<List<ViewModel>>: A list of ViewModels. The adapter notifies itself when the list updates
• ViewProvider: An interface which decides which View should be used for a ViewModel

Using Data Binding, we can create attributes so that these inputs can be provided in XML:

<android.support.v7.widget.RecyclerView
    bind:items="@{vm.itemVms}"
    bind:view_provider="@{@layout/row_item_without_image}" />

This creates a nice declarative API to setup views like RecyclerView/ViewPager.

Static methods are defined which return custom instances of ViewProvider.

public class ViewProviders {
  public static ViewProvider getItemListing() {
    return new ViewProvider() {
              @Override
              public int getView(ViewModel vm) {
                if (vm instanceof ItemViewModel) {
                  return ((ItemViewModel) vm).hasImage() ? R.layout.row_item_with_image : R.layout.row_item_without_image;
                } else if (vm instanceof SomeOtherViewModel) {
                  return R.layout.some_other_view;
                }
                return 0;
              }
            };
  }
}

This method is referenced in XML when setting up the view.

<import type="ViewProviders" />

<!--Example with dynamic views-->
<android.support.v7.widget.RecyclerView
    bind:items="@{vm.itemVms}"
    bind:layout_vertical="@{true}"
    bind:view_provider="@{ViewProviders.itemListing}" />

Following attributes are provided with this library.

@BindingAdapter({"items", "view_provider"})
public static void bindAdapterWithDefaultBinder(RecyclerView recyclerView, Observable<List<ViewModel>> items, ViewProvider viewProvider);

@BindingAdapter({"items", "view_provider"})
public static void bindAdapterWithDefaultBinder(ViewPager viewPager, Observable<List<ViewModel>> items, ViewProvider viewProvider);

@BindingConversion
public static ViewProvider getViewProviderForStaticLayout(@LayoutRes final int layoutId);

@BindingConversion
public static <T extends ViewModel> Observable<List<ViewModel>> toListObservable List<T> specificList);

@BindingAdapter("layout_vertical")
public static void bindLayoutManager(RecyclerView recyclerView, boolean vertical);

Check the source (BindingUtils.java) to know how these work.

Every application has different requirements. It may not be feasible to create a generic API that works well for all usecases. This project aims to provide a pattern so you can build your own custom XML attributes that fulfill your usecase. You can use BindingUtils.java as a reference to roll out your own attributes.

Although BindingAdapters can be overridden, it hasn't been specified how databinding resolves the conflicts. Based on experiments, adapters in client project are preferred over adapters from library. However, having identical adapters in a same module will result in undeterministic results.

The sample project overrides these BindingAdapters to check memory leaks.

Here are some scenarios, and the way in which this pattern resolves them:

A common view model that can bind to all views.

There are many ways depending on the situation.

• Extract common functionality into one child ViewModel. Both view models keep a reference of child ViewModel
• Two view models, one extending the other
• Two view models which extend from a common base
• Single view model with all functionality
  • This approach is possible only because ViewModel has no dependency to a view. In architectures like MVP, this is difficult, as the Presenter has a dependency on a View

RxJava provides several operators to compose Observables. Conversion between rx.Observable and ViewModel fields, enables the use of all these operators in ViewModels, which eliminates the need for mutable state (in most cases).

Consider an example of showing ProgressBar while api is loading. Traditional example:

void load() {
  displayProgress();
  service.loadData(new Callback<String>() {
    @Override
    void onSuccess(String data) {
      displayData(data);
    }

    @Override
    void onError() {
      displayError();
    }
  });
}

By keeping loadedData as an Observable, we can derive progressVisibility by making use of the Using operator. From progressVisibility and loadedData, errorVisibility can be derived. Thus, there are no mutable states, only mapping from one Observable to other. Also, note that there is no need for subscriptions inside ViewModel as View will subscribe to the data after binding.

See DataLoadingViewModel.java for this example.

ViewModels are unaware about lifecycle of View. This means that ViewModel code comes into action only when View invokes it. ViewModel simply defines the logic of transforming inputs to outputs. This is similar to pure functions from functional programming, which provide output based on its inputs only.

There are scenarios where ViewModel needs to know about lifecycle of the View. This feature is in the roadmap. Do contribute!

Wiki contains links to more content around this topic.