h1. Overview

TinyRss is an Android library for working with RSS feeds. It contains a fast parser and customizable ListView output.

h2. Why?

It seems like the standard Java library for RSS/Atom is "Rome":http://rometools.org/, which apparently doesn't work on Android (there's an incomplete port I guess). Besides Rome, there are plenty of resources online for implementing your own parser. I decided to do just that, but package it as a customizable and reusable library.

Because there's already a de facto standard implementation for regular Java projects, I decided to focus TinyRss specifically on Android development. Therefore, it's an Android library project, not a regular jar. It's integrated tightly with Android API's and is specifically designed to show an RSS feed in an Android ListView (although you don't have to use this functionality).

h2. Features

• Fast SAX-based parser for RSS 2.0 feeds
• Object-Oriented model to store feed and item data
• Default ListView implementation for displaying feeds, including: Title Publication Date Description Image
• Asynchronously download and cache item images

h1. Integration

The following instructions are for integrating TinyRss into an existing Android application. They assume you're using Eclipse with ADT.

Clone TinyRss to your machine

Import the TinyRssLib project into your Eclipse workspace

Add TinyRssLib as a reference in your project's Properties -> Android -> Library section

Create a new class in your project that extends com.tinymission.rss.FeedActivity

Make sure to add your new activity to your manifest file

Make sure your manifest file specifies the internet permission: <uses-permission android:name="android.permission.INTERNET" >

Go to Properties -> Java Build Path -> Libraries and click Add JARs..., then select jsoup-1.6.1.jar from the TinyRssLib/lib directory

FeedActivity is an abstract class that has one abstract method, getFeedUrl, which you must override to specify the url of the feed to parse:

public class MyActivity extends FeedActivity {
    @Override
    public String getFeedUrl() {
        return "[feed url]";
    }
}

That's it! You now have a simple activity that will present a ListView with the contents of the specified feed. See the next section for information about customizing the ListView.

h1. Customization

The feed ListView can be customized by overriding methods on the FeedActivity class and by changing the Android resources that are sued to compose the view.

h2. FeedActivity Overrides

The following table shows the methods that can be overridden on a subclass of FeedActivity to control its behavior.

|. Type |. Name |. Description |. Default | | int | getListLayoutId() | The resource id of the layout used as the content view for the activity (must contain a ListView with id @android:id/list) | R.layout.feed | | int | getItemLayoutId() | The resource id of the layout used to render each feed item | R.layout.feed_list_item | | boolean | isImageVisible() | Whether or not to display an image in each feed item | false | | boolean | isDateVisible() | Whether or not to display the item pub date under the title | false | | FeedImageSource | getImageSource() | Specifies where to get the image urls from the feed | FeedImageSource.MediaContent | | int | getMaxItems() | Specifies the number of items to show in the feed, or a negative value to show all items | -1 |

Note: Currently, feed images can only be pulled from the media:content or media:thumbnail tags by returning FeedImageSource.MediaContent or FeedImageSource.MediaThumbnail from getImageSource(). Other possible image sources will be added soon.

h2. Resource Overrides

The following table shows the Android resources that be be overridden to control the appearance and layout of the feed ListView.

|. Name |. Description | | @layout/feed | The content layout for feed activity (must contain a ListView with id @android:id/list) | | @layout/feed_list_item | The layout used to render each feed item | | @style/FeedList | Style for the ListView in R.layout.feed | | @style/FeedListItem | Style for the default ListView item | | @style/FeedItemTitle | Style for the TextView that renders the feed item title | | @style/FeedItemDate | Style for the TextView that renders the feed item date | | @style/FeedItemDescription | Style for the TextView that renders the feed item description | | @style/FeedItemImage | Style for the ImageView that renders the feed item image | | @drawable/feed_list_background | The background drawable for @layout/feed_list_item. By default, a vertical linear gradient | | @color/feed_bg_top | The top color of the default background gradient for @drawable/feed_list_background | | @color/feed_bg_bottom | The bottom color of the default background gradient for @drawable/feed_list_background | | @color/feed_text | The default text color for all TextViews in @layout/feed_list_item |

h1. License

TinyRss is licensed under a 3-clause BSD license. See "LICENSE":https://github.com/ajselvig/TinyRss/blob/master/LICENSE.