Tuesday, May 6, 2014

The FORUMS libre SDK

The FORUMS libre SDK is a Software Development Kit that makes it simple to add forums to your own mobile application or website.

The SDK currently provides two components. The first is a Java Connection API that makes it easy to access FORUMS libre from a Java environment such as Android, or a Java web server. The second component is a set of Android activities that you can add to your own Android app, or copy/customize in your own app.

The SDK is developed under Project Libre an open source project hosted on GitHub

Connection API

You can create a connection to the FORUMS libre server using the SDKConnection class. You need to pass your connection Credentials, which includes your application ID. You can obtain an application from the FORUMS libre website, from your user details page.

SDKConnection connection =
        new SDKConnection(new FORUMSlibreCredential("12345");

The SDK includes a set of data objects that represent the FORUMS libre object model.
The data objects are in the com.paphus.sdk.config package, and include the following,

  • UserConfig - Defines a user's credentials and info.
  • ForumConfig - Defines a forum's details.
  • ForumPostConfig - Defines a forum post.
  • BrowseConfig - Defines a search query criteria.
  • ChannelConfig - Defines a live chat channel's details.
  • InstanceConfig - Defines a bot's details.
  • DomainConfig - Defines a domain's details.
  • ChatConfig - Input for chat bot messaging.
  • VoiceConfig - Defines a chat bot's voice.
  • ChatResponse - Response for chat bot messaging.
  • ContentConfig - Defines a tag/category request.


The API allows you to connect a user, or create a new user.

Use the connect() API to connect a user, the user's details will be returned, or an error message if the connect fails. The returned user details will not include the password, but will include a token, that can be used in place of the password. After connecting a connection, all subsequent requests will use the user credentials, until you call disconnect().

UserConfig user = new UserConfig();
user.user = "test";
user.password = "password";
user = connection.connect(user);

Use the create() API to create a new user. A user id and password are required. You can also pass the user's name, email, bio, and other details. The user details are returned, with a token in place of the password.

UserConfig user = new UserConfig();
user.user = "test";
user.password = "password"; = "Test Account"; = "";
user = connection.create(user);


The API allows you to browse forums, forums posts, and create forum posts and replies.

The browse() API is used to browse or search the set of forums in the domain.

BrowseConfig browse = new BrowseConfig();
browse.type = "Forum";
browse.typeFilter= "Public";
browse.tag= "cool";
browse.sort = "name";
List forums = connection.browse(browse);

The getPosts() API is used to browse or search a forum's posts.

BrowseConfig browse = new BrowseConfig();
browse.typeFilter = "Public";
browse.tag= "cool";
browse.sort = "date";
List posts = connection.getPosts(browse);

The fetch() API is used to get a forum's, or forum post's details.

ForumConfig forum = new ForumConfig(); = "12345";
forum = connection.fetch(forum);
ForumPostConfig post = new ForumPostConfig(); = "12345";
post = connection.fetch(post);

The create() API is used to create a new forum post. You must set the post's forum's id, and the post's details will be returned, including its id.

ForumPostConfig post = new ForumPostConfig(); = "12345";
post.topic = "Party tonight";
post.details = "Party at Rick's place tonight.";
post.tags = "party";
post = connection.create(post);

The createReply() API is used to create a new forum post reply. You must set the post's id you are replying to, and the reply's details will be returned, including its id.

ForumPostConfig reply = new ForumPostConfig();
reply.parent = "12345";
reply.details = "I'll be there.";
post = connection.createReply(post);

Android Activities

The SDK includes a set of Android activities you can reuse, or modify in your own app. The MainActivity contains the SDKConnection and some shared data, so you will need to include it even if not using the activity. The forums activities include, BrowsePostsActivity, ChooseForumActivity, ChoosePostActivity, CreateForumPostActivity, CreateReplyActivity, EditForumPostActivity, ForumActivity, ForumBrowseActivity, and ForumPostActivity.

Here is an example of launching a ForumActivity.

MainActivity.current = new MainActivity();
ForumConfig config = new ForumConfig(); = "12345";
HttpAction action = new HttpFetchAction(this, config);

Note, because of the way Android does its packaging, you will need to search/replace the "com.paphus.sdk.activity.R" import with your own application's unique package. This will resolve the generated R class dependencies.

You can use the SDK to access any of FORUMS libre's services, for personal, academic, or commercial applications. You cannot use them for spam, or to violate the FORUMS libre terms of service. FORUMS libre's services are also provided as a commercial service on Paphus Live Chat.

No comments:

Post a Comment