muhammadammad / avatar-view

Avatar ImageView with user's name first letter Drawable placeholder

Avatar View

Avatar View library was implemented based on Matt Precious's Don’t Fear the Canvas lecture. I decided to create this library in order to achieve an ImageView which can smoothly display user's profile image or his username/name initial letter (in the case when the image was not provided).

Please take a look at the examples below:

Simple library presentation	ExampleActivity & BindingsExample

Usage

This library can be used in two ways: using standard Android methods and using Android Data Binding.

###Standard:

Step 1

Add gradle dependency:

dependencies {
    compile 'agency.tango.android:avatar-view:{latest_release}'

    //if you want to use Picasso for loading images
    compile 'agency.tango.android:avatar-view-picasso:{latest_release}'
}

Step 2

Add to your xml layout file:

<agency.tango.android.avatarview.views.AvatarView
    android:layout_width="100dp"
    android:layout_height="100dp"
    app:av_border_color="@android:color/white"
    app:av_border_width="4dp"
    app:av_text_size_percentage="35" />

Step 3

Add to your activity:

    AvatarView avatarView;
    IImageLoader imageLoader;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        avatarView = (AvatarView) findViewById(R.id.avatar_view_example);

        imageLoader = new PicassoLoader();
        imageLoader.loadImage(avatarView, "http:/example.com/user/someUserAvatar.png", "User Name");
    }

If you want to use a different library than Picasso for loading images you have to create a loader which extends ImageLoaderBase class. Basically, you have to override one method. Take a look how I have done it in PicassoLoader available in the avatar-view-picasso module.

ImageLoaderBase has two constructors: one with no parameters and second one where you can pass String placeholder in order to change the default "-". You can also set it directly in AvatarPlaceholder constructor. More info about AvatarPlaceholder here.

###Data Binding:

Step 1

Add gradle dependency:

dependencies {
    compile 'agency.tango.android:avatar-view:{latest_release}'
    compile 'agency.tango.android:avatar-view-bindings:{latest_release}'

    //if you want to use Picasso for loading images
    compile 'agency.tango.android:avatar-view-picasso:{latest_release}'
}

Step 2

I will show how to edit your xml file based on User class. Let's see:

<data>
    <variable
        name="user"
        type="User" />
</data>

<agency.tango.android.avatarview.views.AvatarView
    android:layout_width="100dp"
    android:layout_height="100dp"
    bind:av_border_color="@android:color/white"
    bind:av_border_width="6dp"
    bind:av_text_size_percentage="40"
    bind:avatarUrl="@{user.avatarUrl}"
    bind:name="@{user.name}" />

Step 3

Add to your activity:

private ExampleActivityBinding binding;

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    binding = DataBindingUtil.setContentView(this, R.layout.example_activity, new ExampleDataComponent());
    binding.setUser(new User("User Name", "http:/example.com/user/someUserAvatar.png"));
}

private static class ExampleDataComponent implements DataBindingComponent {
    public AvatarViewBindings getAvatarViewBindings() {
        return new AvatarViewBindings(new PicassoLoader());
    }
}

Take a look at AvatarViewBindings class where BindingsAdapter is configured (bind:avatarUrl and bind:name for usage in XML). In order to correctly use AvatarViewBindings you have to create class extending DataBindingComponent and pass it as a third parameter in DataBindingUtil.setContentView() method. This is obligatory because AvatarViewBindings takes an IImageLoader parameter in it's constructor. You can find more information about this topic in Deep dive into Android Data Binding talk.

I have explained PicassoLoader issue in step 3 in Standard Method part.

####AvatarPlaceholder

AvatarPlaceholder is a Drawable which is set as a AvatarView background when the image hasn't been loaded yet. It is a letter on a one-color background (just like in ex. Google, Youtube avatars). Default placeholder String (displayed when the username is null or empty) is "-". TextSizePercentage value sets how big part of the view is taken by the text. Default textSizePercentage is 33. You can change those values by passing another ones in AvatarPlaceholder constructor or not directly by using IImageLoader class methods/constructors.

####Additional information

• Avatar background color is calculated using hashCode() method called on a given name String.
• Default border width is 2dp and default border color is white.
• Placeholder letters are currently always white (in future user will be able to choose a different color).
• It is recommended to set your default placeholder String as short as possible (the best would be one letter).

####Feel free to create issues and pull requests!