# WebFeeds

Opera supports different web feed formats like RSS and ATOM. To access the storage

## Primitive value types

### integer

An integer, positive value.

### string

A normal JavaScript string except that only the part before a null character will be used.

### boolean

A normal JavaScript boolean value.

### function

A normal JavaScript function value. Can be a named or anonymous function.

## Class overview

`WebFeeds` - The administration class for all feeds.
`FeedList` - A list of feeds.
`Feed` - A class representing one feed.
`FeedEntryList` - A list of entries in a feed.
`FeedEntry` - A class representing one entry in a feed.
`FeedContent` - A class representing a block of content in an entry.
`FeedListener` - An interface for implenting callbacks used by some of the methods for fetching feeds.
`FeedReaderList` - A list of available external feed readers.
`FeedReader` - A class representing an external feed reader.

### WebFeeds class

This class is used for keeping track of subscribed feeds and for loading single feeds. It can be accessed from `opera.feeds` in a script.

class WebFeeds { // Properties:

| integer | maxAge;
| integer | maxEntries;
| integer | maxSize;
| boolean | showImages;
| FeedList | subscribedFeeds;
| integer | updateInterval;

// Methods:

Feed | getFeedById(integer id);
void | loadFeed(string url, FeedListener listener);
void | updateFeeds(FeedListener listener);

}

#### Property description

maxAge
  Represents the default maximum expiration time in minutes for messages in a feed where this is not explicitly set. Can be any positive integer value. If set to 0 messages will not be stored after they have been read.
maxEntries
  Represents the default maximum number of messages in a feed where this is not explicitly set. Can be any positive integer value. If set to 0 messages will be deleted as soon as they are read.
maxSize
  Represents the maximum storage size of the web feed storage in bytes. Can be set to any positive integer value. Setting it to ~0 is stupid.
showImages
  Represents the default value of the flag that indicates whether images in feeds should be shown if this is not explicitly set for the feed.
updateInterval
  Represents the default update interval in minutes of a feed where this is not explicitly set. Can be any positive integer value. If this is lower than the minimum value specified by the feed server it will be ignored.

#### Method description

getFeedById(integer id)
  Will fetch a feed by its unique id
  id
    A unique id number for a feed. Returned by Feed.id.
  Returns: The feed object of the feed with the give id or `null` if there is no feed with that id.
loadFeed(string url, FeedListener listener)
  Loads a feed, subscribed or not. If the feed is already loaded the stored data will be used. If the feed is loaded within the minimum update interval and already deleted an error will be reported to the listener.
  The method is asynchronous and will return before the feed is created or loaded. When the feed is loaded and created the listener object will be notified.
  url
    The URL where the feed can be fetched.
  listener
    A listener object with callbacks.
  Returns: nothing.
updateFeeds(FeedListener listener)
  Triggers an update of all the feeds. If less time than the minimum update interval for the feed sent from the server is passed since the last update the stored data will be used.
  listener
    A listener object with callbacks.
  Returns: nothing.

### FeedList class

This class is used to hold lists of feeds.

class FeedList { // Properties:

readonly | integer | length;

// Methods:

Feed | item(integer index);

}

#### Property description

length
  The number of feeds in the list.

#### Method description

item(integer index)
  Used to fetch a feed at a given index in the feed list. PS: The array notation (`[n]`) can be used instead of this method.
  index
    The index of the wanted Feed object into the feed list. The index is 0-based.
  Returns: The Feed object of the feed with the given index or `null` if there is no feed at that index.

### Feed class

This class represents a single feed, subscribed or not. Can be fetched from the list of subscribed feeds or by loading a single feed.

class Feed { Constants enum {

STATUS_OK,
STATUS_ABORTED,
STATUS_REFRESH_POSTPONED,
STATUS_NOT_MODIFIED,
STATUS_OOM,
STATUS_SERVER_TIMEOUT,
STATUS_LOADING_ERROR,
STATUS_PARSING_ERROR

} Properties:

readonly | string | author;
readonly | FeedEntryList | entries;
readonly | string | icon;
readonly | integer | id;
readonly | boolean | isSubscribed;
readonly | Date | lastUpdate;
readonly | string | logo;
| integer | maxAge;
| integer | maxEntries;
readonly | integer | minUpdateInterval;
| boolean | showImages;
readonly | integer | size;
readonly | integer | status;
readonly | FeedContent | title;
readonly | integer | total;
readonly | integer | unread;
| integer | updateInterval;
readonly | string | uri;
| boolean | prefetchPrimaryLink;
| string | userDefinedTitle;

Methods:

FeedContent | getProperty(string property);
void | subscribe();
void | unSubscribe();
void | subscribeNative();

}

#### Constant description

STATUS_OK
  Feed loaded ok.
STATUS_ABORTED
  Feed loading was aborted (usually by user)
STATUS_REFRESH_POSTPONED
  Not loaded, due to too little time passed since last update. Feed object is still valid, but will only contain older data.
STATUS_NOT_MODIFIED
  Server returned not modified, feed unchanged since last update
STATUS_OOM
  OOM during loading. When memory has been freed up, you can retry loading.
STATUS_NOT_MODIFIED
  Server returned not modified, feed unchanged since last update Opera may still be OOM if a callback is called with this status, so don't allocate any more memory.
STATUS_SERVER_TIMEOUT
  No answer from server.
STATUS_LOADING_ERROR
  Loading failed.
  Feed loaded, but contained uncorrectable errors (usually misformed XML).

#### Property description

author
  Returns the author of the feed.
entries
  A list of the entries in the feed.
icon
  Returns the URI of the icon of the feed.
id
  Returns the unique id of the feed.
isSubscribed
  Returns `true` if the feed is subscribed.
lastUpdate
  Last time this feed was updated from source
logo
  Returns the URI of the logo of the feed.
maxAge
  Represents the maximum expiration time in minutes for messages in the feed. Can be any positive integer value. If set to 0 messages will not be stored after they have been read.
maxEntries
  Represents the maximum number of messages in the feed. Can be any positive integer value. If set to 0 messages will be deleted as soon as they are read.
minUpdateInterval
  Returns the minimum update interval specified by the server.
showImages
  If true the images contained or pointed to by the message will be shown when viewing the feed.
size
  Returns the size of the feed.
status
  Returns a status value for the feed. The values returned are the ones described in the constants section of this class.
title
  Returns the title of the feed as set by the author.
total
  Returns the total number of entries in the feed.
unread
  Returns the number of unread entries in the feed.
updateInterval
  Represents the update interval in minutes of the feed. Can be any positive integer value. If this is lower than the minimum value specified by the feed server it will be ignored when updating.
uri
  Returns the URI of the feed.
prefetchPrimaryLink
  If enabled then the linked article and its inline elements will be prefetch each time a new entry in this feed is loaded. When the article is prefetched it will be put in Opera's cache and should load fast if loaded and also be available offline. The article loaded is the same as the one given by the entry's uri.
userDefinedTitle
  Represents the title the user has set himself for this feed.

#### Method description

getProperty(string property)
  Returns the value of the property described by the property string. The property can be the contents of a certain tag (like <dc:author>) or a significant attribute. Not all properties will be stored so this method may return null even though the property is in the message item.
  string
    The string describing the property.
  Returns: A FeedContent object representing the value of the property.
subscribe()
  Adds the feed to the list of feeds that will be loaded at regular intervals Returns: nothing.
unSubscribe()
  Removes the feed from the list of feeds that will be loaded at regular intervals Returns: nothing.
subscribeNative()
  Subscribes to the feed with the native newsreader for the current platform, for example the native newsreader on a device or M2 on desktop (not available on all platforms) Returns: nothing.

### FeedEntryList class

This class is used to hold lists of entries.

class FeedEntryList { // Properties:

readonly | integer | length;

// Methods:

FeedEntry | item(integer index);

}

#### Property description

length
  The number of entries in the list.

#### Method description

item(integer index)
  Used to fetch an entry at a given index in the entry list. PS: The array notation (`[n]`) can be used instead of this method.
  index
    The index of the wanted FeedEntry object into the entry list. The index is 0-based.
  Returns: The FeedEntry object of the entry with the given index or `null` if there is no entry at that index.

### FeedEntry class

This represents a single entry in a feed. Can be fetched from the list of entries in a feed or from the callback in the listener when loading.

class FeedEntry { Constants: enum {

STATUS_UNREAD
STATUS_READ
STATUS_ERROR

} Properties:

readonly | string | author;
readonly | FeedContent | content;
readonly | integer | id;
| boolean | keep;
readonly | Date | publicationDate;
| integer | status;
readonly | string | title;
readonly | string | uri;

Methods:

FeedContent | getProperty(string property);

}

#### Constant description

STATUS_READ
  The user has read the entry.
STATUS_UNREAD
  The user has not read the entry.
STATUS_ERROR
  There is something wrong with the entry.

#### Property description

author
  Returns the author of the entry.
content
  Returns a FeedContent object that contains the content of the entry.
id
  Returns a unique id for the entry.
keep
  Returns `true` if this entry is marked to be kept when it is expired. Set it to `true` if you want to keep it.
publicationDate
  Returns a Date object describing telling the time when the entry was created or last updated
status
  Returns the status value for the entry. The values returned are the ones described in the constants section of this class.
title
  Returns the title of the entry.
uri
  Returns the URI of the entry. The URI is the first link element or a guid element with permaLink=true. Will be empty string if entry has no such link.

#### Method description

getProperty(string property)
  Returns the value of the property described by the property string. The property can be the contents of a certain tag (like <dc:author>) or a significant attribute. Not all properties will be stored so this method may return null even though the property is in the message item.
  string
    The string describing the property.
  Returns: A FeedContent object representing the value of the property.

### FeedContent class

Represents complex content of an entry. Can contain textual data, markup or binary data encoded as base64. TODO: Will be a base64 encoded string if binary. Is returned by some functions on the FeedEntry

class FeedContent { Properties:

readonly | string | data;
readonly | boolean | isBinary;
readonly | boolean | isMarkup;
readonly | boolean | isPlainText;
readonly | string | type;

}

#### Property description

data
  The textual data of the content. TODO: Will be a base64 encoded string if binary
isBinary
  Is `true` if the content is binary.
isMarkup
  Is `true` if the content contains markup.
isPlainText
  Is `true` if the content is text/plain.
type
  The MIME type of the content.

### FeedListener interface

Set of callback functions used by the listeners when loading or updating feeds. Any ECMAScript object can be used as a listener as long as they have the specified methods on them.

interface FeedListener { Properties:

function | updateFinished;
function | feedLoaded;
function | entryLoaded;

}

#### Method description

updateFinished [updateFinished()]
  Holds the function to be called when all the feeds have been loaded. Takes no parameters and returns no value.
feedLoaded [feedLoaded(Feed, Feed.Status)]
  Holds the function to be called when a feed and all its entries are fully loaded. Takes two parameters:
  Feed
    The Feed object of the feed that has been loaded
  Feed.Status
    The status of the feed
  Returns no value.
entryLoaded [entryLoaded(Entry, Entry.Status)]
  Holds the function to be called when an entry is fully loaded. Takes two parameters:
  Entry
    The FeedEntry object of the entry that has been loaded
  Entry.Status
    The status of the entry
  Returns no value.

### FeedReaderList class

This class is used to hold lists of external feed readers. If available, it can be accessed from `opera.feedreaders` in a script.

class FeedReaderList { Properties:

readonly | integer | length;

Methods:

FeedReader | item(integer index);

}

#### Property description

length
  The number of entries in the list.

#### Method description

item(integer index)
  Used to fetch a feed reader at a given index in the reader list. PS: The array notation (`[n]`) can be used instead of this method.
  index
    The index of the wanted FeedReader object into the reader list. The index is 0-based.
  Returns: The FeedReader object with the given index or `null` if there is no reader at that index.

### FeedReader class

This represents an external feed reader. Can be fetched from the list of feed readers.

class FeedReader { Properties:

readonly | string | name;

Methods:

string | getTargetURL(string feed_url);

}

#### Property description

name
  Returns the human-readable name of the feed reader.

#### Method description

getTargetURL(string feed_url)
  Returns the URL that can be used to subscribe to the specified feed_url using this feed reader.
  feed_url
    The URL of the feed that needs to be subscribed.
  Returns: A string that contains the URL to subscribe to the feed_url using this feed reader.

## Examples of use

The documentation above should be enough to understand how the JavaScript bindings work but but we'll throw in some example code. Learning by example is so much easier.

### Get a property from the feed manager

var maximum = opera.feeds.maxEntries;

### Set a property on the feed manager

opera.feeds.maxSize = 4000; // sets maximum storage used to 4000 bytes

### List the subscribed feeds

for (var i = 0; i < opera.feeds.subscribedFeeds.length; i++) { writeOutFeed(opera.feeds.subscribedFeeds[i].title); }

### List the messages of a feed

var feed = opera.feeds.subscribedFeeds[0]; if (feed) { for (var i = 0; i < feed.entries.length; i++) { var message = feed.entries.item(i); document.writeln("<a onclick='showMessage()'>" + message.title + "</a><br/>"); } }

### Load a single feed

var listener = new Object(); listener.feedLoaded = function (feed, status) { alert("feed " + feed.title + " done."); } opera.feeds.loadFeed("http://some.server/some.feed", listener);

### Update all the feeds and show them, entry by entry

var listener = new Object(); listener.feedLoaded = function (feed, status) { finishFeed(feed); } listener.entryLoaded = function (entry, status) { displayEntry(entry); } opera.feeds.updateFeeds(listener);

WebFeeds backend bindings in JavaScript, 2007 (stighal@opera.com)