Home

Awesome

Anvil - reactive views for Android

Join the chat at https://gitter.im/zserge/anvil Build Status Android Weekly

<br/> <div> <img align="left" src="https://raw.githubusercontent.com/zserge/anvil/master/logo/ic_launcher.png" alt="logo" width="96px" height="96px" /> <p> Anvil is a small Java library for creating reactive user interfaces. Originally inspired by <a href="https://facebook.github.io/react/">React</a>, it suits well as a view layer for <a href="https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel">MVVM</a> or <a href="http://redux.js.org/">Redux</a> design patterns. </p> </div> <br/>

Features

¹Reflection is still used to inflate views once (standard XML inflater does the same thing, so no performance loss here).

Installation

// build.gradle
repositories {
    jcenter()
}
dependencies {
    compile 'co.trikita:anvil-sdk15:0.5.0'
}

Anvil comes in multiple builds for different minimal SDK versions:

API levels 16, 17, 18, 22 or 23 are not added because they had very few UI-related methods added.

Examples

Normally you would write your layouts in XMLs, then get your views by their IDs and set their listeners, finally you would observe your data and modify view properties as your data changes.

Anvil simplifies most of this boring routine.

First, add a static import that makes it much easier to write your view:

import static trikita.anvil.DSL.*;

Next, declare your layout, assign event listeners and bind data:

public int ticktock = 0;
public void onCreate(Bundle b) {
    super.onCreate(b);
    setContentView(new RenderableView(this) {
        @Override
        public void view() {
            linearLayout(() -> {
                size(MATCH, MATCH);
                padding(dip(8));
                orientation(LinearLayout.VERTICAL);

                textView(() -> {
                    size(MATCH, WRAP);
                    text("Tick-tock: " + ticktock);
                });

                button(() -> {
                    size(MATCH, WRAP);
                    text("Close");
                    // Finish current activity when the button is clicked
                    onClick(v -> finish());
                });
            });
        }
    });
}

Here we've created a very simple reactive view and added it to our Activity. We've declared our layout (a LinearLayout with a TextView inside). We've defined styles (width, height, orientation and padding). We've set OnClickListener to the button. We've also bound a variable "ticktock" to the text property inside a TextView.

Next, let's update your views as your data changes:

ticktock++;
Anvil.render();

At this point your layout will be updated and the TextView will contain text "Tick-Tock: 1" instead of "Tick-Tock: 0". However the only actual view method being called would be setText().

You should know that there is no need to call Anvil.render() inside your event listeners, it's already triggered after each UI listener call:

public void view() {
    linearLayout(() -> {
        textView(() -> {
            text("Clicks: " + numClicks);
        });
        button(() -> {
            text("Click me");
            onClick(v -> {
                numClicks++; // text view will be updated automatically
            });
        });
    });
}

Made with Anvil

Talalarmo Slide Spot Quilt

You may find more Anvil examples for Java 6, Java 8 and Kotlin at

How it works

No magic. When a renderable object is being constructed there are 3 types of operations: push view, modify some attribute of the current view, and pop view. If you're familiar with incremental DOM - Anvil follows the same approach.

Pushing a view adds it as a child to the parent view from the top of the stack. Attribute modification simply sets the given property to the current view on top of the stack. Pop unwinds the stack.

When you mount this layout (assuming the name is "John"):

linearLayout(() -> {
    textView(() -> {
        text("Hello " + name);
    });
});

It does the following sequence of actions:

Push LinearLayout (adding it to the root view)
Push TextView (adding it to the linear layout)
Attr text "Hello John" (calling setText of the TextView)
Pop
Pop

The only trick is that these actions are cached into a so called "virtual layout" - a tree-like structure matching the actual layout of views and their properties.

So when you call Anvil.render() next time it compares the sequence of actions with the cache and skips property values if they haven't change. Which means on the next Anvil.render() call the views will remain untouched. This caching technique makes render a very quick operation (having a layout of 100 views, 10 attributes each you can do about 4000 render cycles per second!).

Now, if you modify the name from "John" to "Jane" and call Anvil.render() it will do the following:

Push LinearLayout (noop)
Push TextView (noop)
Attr text "Hello Jane" (comparing with "Hello John" from the pervious render,
  noticing the difference and calling setText("Hello Jane") to the TextView)
Pop
Pop

So if you modify one of the variables "bound" to some of the attributes - the cache will be missed and attribute will be updated.

For all event listeners a "proxy" is generated, which delegates its method calls to your actual event listener, but calls Anvil.render() after each method. This is useful, because most of your data models are modified when the user interacts with the UI, so you write less code without calling Anvil.render() from every listener. Remember, no-op renders are very fast.

Supported languages and API levels

Anvil is written in Java 7, but its API is designed to use lambdas as well, so in modern times it's recommended to use Anvil with Java8/Retrolambda or Kotlin.

Syntax is a bit different for each language, but it's very intuitive anyway.

Java 6 without lambdas:

public void view() {
    o (linearLayout(),
      orientation(LinearLayout.VERTICAL),

        o (textView(),
          text("...")),
        
        o (button(),
          text("..."),
          onClick(myListener)));
}

Java 8 + RetroLambda:

public void view() {
    linearLayout(() -> {
        orientation(LinearLayout.VERTICAL);
        textView(() -> {
            text("....");
        });
        button(() -> {
            text(".....");
            onClick(v -> {
                ....
            });
        });
    });
}

Kotlin:

public override fun view() {
    linearLayout {
        orientation(LinearLayout.VERTICAL)
        textView {
            text("....")
        }
        button {
            text("....")
            onClick { v ->
                ...
            }
        }
    }
}

Anvil library contains only a few classes to work with the virtual layout, but most of the DSL (domain-specific language describing how to create views/layouts and set their attributes) is generated from android.jar.

API

Here's a list of classes and methods you need to know to work with Anvil like a pro:

DSL

The bottom part of the iceberg is Anvil DSL.

DSL consists of a few handwritten property setters, but most of it is generated from java classes in the android SDK.

See a full list of the DSL methods for each API level here.

Property setters

The setters are named as the view methods from Android SDK, but without the "set" prefix. E.g. "text(s)" instead of "setText(s)", "backgroundDrawable(d)" instead of "setBackgroundDrawable(d)" and so on.

Event listeners

Event listeners also have names from the Android SDK, but without the "set" prefix and the "Listener" suffix, e.g. "onClick" instead of "setOnClickListener".

Handwritten bindings

For LayoutParams the bindings can't be generated easily, so it was faster to write them manually:

A few bindings have been written for other use cases which we find useful:

If a binding you need is not in the list - please, check issue #27 and report it there.

A special case for animations is added:

Finally, a few low-level DSL functions are there, which you would no need unless you want to write your own property setters or custom view builders:

XML layouts

If you're migrating an existing project to Anvil or if you prefer to keep your view layouts declared in XML - you can do so:

public override fun view() {
    // A designer gave us an XML with some fancy layout:
    // a viewgroup with a button and a progress bar in it
    xml(R.layout.my_layout) {
        backgroundColor(Settings.bgColor) // will modify root layout view color

        withId(R.id.my_button) {
            // button state may depend on some variable
            enabled(isMyButtonEnabled)
                // button click listener can be attached
                onClick { v ->
                    ...
                }
        }

        withId(R.id.my_progress_bar) {
            visible(isMyProgressBarShown)
            progress(someProgressValue)
        }
    }
}

Here xml() creates a view node, much like frameLayout() or textView(), except for it uses an XML file to inflate the views, not the direct view class constructor. Much like view "builders", xml() takes a renderable lambda as a parameter and uses that to modify the created view.

Any attribute setters will affect the root view from the XML layout.

If you want to modify attributes of the child views from the XML - you should use withId() to assign a renderable to a view with the given ID. You may not follow the hierarchy of the child views, e.g. all your withId() calls may be nested as the views are nested in the XML, or may be direct children of the xml() renderable. xml() calls can be nested, too.

xml() also allows you to create views that can not be inflated from Java code but only from XML (such as hostozintal progress bars) or any other views where AttributeSet must be given or the views that rely on the onFinishInflate method to be called.

withId() call is not limited to XML views, it can be used for views declared in code that have IDs. So if you have a custom viewgroup that creates its child views automatically and assigns some IDs to them - you can still modify their properties using withId(). Also, if any views are created inside the withId() or xml() - they will be appeneded to the view group:

v(MyComponent.java, () -> {
    withId(R.id.child_view, () -> {
        // R.id.child_view was implicitely created in MyComponent's constructor
        // but we still can modify it here
    });

    textView(() -> {
        // This textView will be appeneded to MyComponent layout
    });
});

License

Code is distributed under MIT license, feel free to use it in your proprietary projects as well.