Atlas

• Tenor Gif Integration

##Overview

Atlas is an open source framework of customizable UI components for use with the Layer SDK designed to get messaging tested and integrated quickly. This repository contains the Atlas library. For a fully-featured messaging app, see the open source Atlas Messenger project, which uses this Atlas library and the Layer SDK.

Requirements

Atlas requires Android API Level >= 14 (OS v4.0). The Layer SDK version requirements for each release are tightly coupled. See the release notes for details about specifics.

Key Concepts

With Atlas, Messages have types. One type might be rich text, and another might be a map location or photo. Anything that can be packaged into a set of MIME Types and data can be represented by Atlas.

Under the hood, MessageSenders send individual Message types, and AtlasCellFactories render them. Additional Message types can be added to your app by extending these classes. For a list of default types, see the messagetypes subpackage.

API Quickstart

The Atlas library is located in the layer-atlas directory. The table below details the most important classes in Atlas and is hyperlinked directly to the current java file.

Views
AtlasConversationsRecyclerView	A list of Conversations
AtlasMessagesRecyclerView	A list of Messages within a Conversation
AtlasMessageComposer	A View used to compose and send Messages
AtlasAddressBar	Participant selection with dynamic filtering
AtlasTypingIndicator	Displays TypingIndicator information for a Conversation
Factories and Senders
AtlasCellFactory	Classifies, parses, and renders Messages
MessageSender	Sends Messages
AtlasTypingIndicator. TypingIndicatorFactory	Renders typing indicators

Installation

Add the following to the build.gradle:

repositories {
    maven { url "https://raw.githubusercontent.com/layerhq/releases-android/master/releases/" }
    maven { url "https://raw.githubusercontent.com/layerhq/Atlas-Android/master/releases/" }
}

dependencies {
    compile 'com.layer.atlas:layer-atlas:0.4.15'
}

Libraries

Atlas uses Picasso for image caching, resizing, and processing, and Subsampling Scale Image View for image its in-app lightbox. Other dependencies include the Android recyclerview, appcompat, and design libraries.

Component Details

Atlas is divided into five basic View components, typically presented on a screen with a user's conversations, a screen with messages within a conversation, and a component that lets the user select participants.

Conversations

AtlasConversationsRecyclerView

The AtlasConversationsRecyclerView is a list of Conversations.

XML

<com.layer.atlas.AtlasConversationsRecyclerView
    android:id="@+id/conversations_list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

Java

conversationsList = ((AtlasConversationsRecyclerView) findViewById(R.id.conversations_list))
	.init(layerClient, picasso)
	.setOnConversationClickListener(new OnConversationClickListener() {
		public void onConversationClick(AtlasConversationsAdapter adapter, Conversation conversation) {
			launchMessagesList(conversation);
		}
		
		public boolean onConversationLongClick(AtlasConversationsAdapter adapter, Conversation conversation) {
		    return false;
		}
	})
    .addCellFactories(new TextCellFactory(),
    new ThreePartImageCellFactory(layerClient, picasso),
    new LocationCellFactory(picasso),
    new SinglePartImageCellFactory(layerClient, picasso));

Messages

AtlasMessagesRecyclerView

The AtlasMessagesRecyclerView is list of Messages, rendered by AtlasCellFactories.

XML

<com.layer.atlas.AtlasMessagesRecyclerView
    android:id="@+id/messages_list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

Java

messagesList = ((AtlasMessagesRecyclerView) findViewById(R.id.messages_list))
	.init(layerClient, picasso)
	.setConversation(conversation)
	.addCellFactories(
		new TextCellFactory(),
		new ThreePartImageCellFactory(this, layerClient, picasso),
		new LocationCellFactory(this, picasso));

AtlasMessageComposer

The AtlasMessageComposer is a text entry area for composing messages and a menu of AttachmentSenders.

XML

<com.layer.atlas.AtlasMessageComposer
    android:id="@+id/message_composer"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    />

Java

messageComposer = ((AtlasMessageComposer) findViewById(R.id.message_composer))
	.init(layerClient)
        .setConversation(conversation)
	.setTextSender(new TextSender())
	.addAttachmentSenders(
		new CameraSender("Camera", R.drawable.ic_photo_camera_white_24dp, this, getApplicationContext().getPackageName() + ".file_provider"),
		new GallerySender("Gallery", R.drawable.ic_photo_white_24dp, this),
		new LocationSender("Location", R.drawable.ic_place_white_24dp, this));

AtlasTypingIndicator

The AtlasTypingIndicator presents the user with active typists.

XML

<com.layer.atlas.AtlasTypingIndicator
    android:id="@+id/typing_indicator"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    />

Java

typingIndicator = new AtlasTypingIndicator(this)
	.init(layerClient)
	.setTypingIndicatorFactory(new BubbleTypingIndicatorFactory())
	.setTypingActivityListener(new AtlasTypingIndicator.TypingActivityListener() {
		public void onTypingActivityChange(AtlasTypingIndicator typingIndicator, boolean active) {
			messagesList.setFooterView(active ? typingIndicator : null);
		}
	});

Message Types

By default, Atlas supports the following types of messages.

Type	Description
Generic	Default handler for unknown message types. Displays the mimetype and the content size
Text	Handler for text/plain content.
Location	Handler for location/coordinate content. Given lat/lon information, displays the location image (from Google maps), with a hyperlink that launches Maps application
ThreePartImage	Handler for 3 part JPEG image, with preview & dimensions. By default, displays the preview image. On tap, downloads and renders the full resolution image
SinglePartImage	Handler for any mime type that starts with image tag

We expect to add support for other handlers in future. If you would like to build a handler, please check doc on message handlers.

Identity

An application server can directly upload user information to Layer server. This user information is called Identity. AtlasAddressBar and AtlasAvatar are controls that are used to render the Identity information.

AtlasAddressBar

AtlasAddressBar can be used to show a list of users. For eg, the list of users in a Conversation or to show a user list for creating a new Conversation.

XML

<com.layer.atlas.AtlasAddressBar
    android:id="@+id/address_bar"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

Java

addressBar = (AtlasAddressBar) findViewById(R.id.address_bar)
	.init(layerClient, picasso)
	.setOnConversationClickListener(new OnConversationClickListenertener() {
		public void onConversationClick(AtlasAddressBar addressBar, Conversation conversation) {
			setConversation(conversation);
		}
	})
	.setOnParticipantSelectionChangeListener(new OnParticipantSelectionChangeListener() {
		public void onParticipantSelectionChanged(AtlasAddressBar addressBar, List<Identity> participants) {
			if (participants.isEmpty()) {
				setConversation(null);
				return;
			}
			try {
				ConversationOptions options = new ConversationOptions().distinct(true);
				setConversation(layerClient.newConversation(options, new HashSet<>(participants)), false);
			} catch (LayerConversationException e) {
				setConversation(e.getConversation(), false);
			}
		}
	});

AtlasAvatar

AtlasAvatarcan be used to show information about one user, or as a cluster of multiple users. AtlasAvatar uses Picasso to render the avatar image. So, you need to init

XML

        <com.layer.atlas.AtlasAvatar
            android:id="@+id/avatar"
            android:layout_width="@dimen/atlas_avatar_item_single"
            android:layout_height="@dimen/atlas_avatar_item_single"
            android:layout_margin="@dimen/atlas_padding_normal"/>

Java

	    // To create an avatar
            mAvatarCluster = (AtlasAvatar) itemView.findViewById(R.id.avatar);

	    // To initialize Picasso
	    viewHolder.mAvatarCluster
		.init(mPicasso)
		.setStyle(conversationStyle.getAvatarStyle());

	    // To set identites meant for the avatar cluster
	    HashSet<Identity> participants = new HashSet<>(conversation.getParticipants());
	    viewHolder.mAvatarCluster.setParticipants(participants);

Contributing

Atlas is an Open Source project maintained by Layer. Feedback and contributions are always welcome and the maintainers try to process patches as quickly as possible. Feel free to open up a Pull Request or Issue on Github.

License

Atlas is licensed under the terms of the Apache License, version 2.0. Please see the LICENSE file for full details.

Contact

Atlas was developed in San Francisco by the Layer team. If you have any technical questions or concerns about this project feel free to reach out to Layer Support.

Credits

• Amar Srinivasan
• Steven Jones
• Peter Elliott

Tenor Gif Integration

All java classes that are needed for gif integration are put under com.layer.atlas.tenor package.

• Initialize Tenor Service
  • Customized User-Agent
  • Customized Interceptor
• Register CellFactory, Sender and MimeType classes
• Implement Smart Gif Suggestion

Initialize Tenor Service

On the onCreate() of you Application class, add:

if (BuildConfig.DEBUG) {
    ApiClient.setProtocolType(ApiClient.HTTP);
    ApiClient.setServer("qa-api");
}

// put your tenor API key here
ApiClient.setApiKey("");

// initialize ApiClient and request keyboard id
ApiClient.init(this);

Customized User-Agent

If you want to customize the User-Agent of all your API requests, you need to supply an Interceptor when initializing the ApiClient:

/*
 * initialize custom user-agent for all requests
 * by using CustomUserAgent and UserAgentInterceptor
 */
AbstractNetworkUtils.initUserAgent(
        new CustomUserAgent.Builder(BuildConfig.APPLICATION_ID, BuildConfig.VERSION_NAME, BuildConfig.VERSION_CODE)
                .locale(AbstractLocaleUtils.getCurrentLocaleName(this))
                .build()
);
final Interceptor interceptor = new UserAgentInterceptor(this, AbstractNetworkUtils.getUserAgent(this));

// request keyboard id with custom user-agent interceptor
ApiClient.setInterceptor(interceptor);
ApiClient.init(this);

Customized Interceptor

You can also construct and supply your own Interceptor when initializing the ApiClient:

final Interceptor interceptor = new Interceptor() {
    @Override
    public Response intercept(Chain chain) throws IOException {
        return null;
    }
};

// request keyboard id with custom interceptor
ApiClient.setInterceptor(interceptor);
ApiClient.init(this);

Register CellFactory, Sender and MimeType classes

1. on your AtlasMessagesRecyclerView or its subclass, add:

.addCellFactories(new ThreePartGifCellFactory(this, getLayerClient()))

2. on your AtlasMessageComposer or its subclass, add:

.setGifSender(new GifSender(R.string.attachment_menu_gif, R.drawable.ic_logo_white, this))

3. on your LayerClient.Options(), add:

.autoDownloadMimeTypes(Arrays.asList(
    ThreePartGifUtils.MIME_TYPE_GIF_INFO,
    ThreePartGifUtils.MIME_TYPE_GIF_PREVIEW,
    ThreePartGifUtils.MIME_TYPE_GIF));

Implement Smart Gif Suggestion

1. on the onCreate() of your MessagesListActivity or equivalent, add: SmartGifsUtils.clear();