\Agora_Api

Agora external API interface.

This file defines Agora's external API interface. Other applications can interact with Agora through this API.

Copyright 2003-2017 Horde LLC (http://www.horde.org/)

See the enclosed file LICENSE for license information (GPL). If you did not receive this file, see http://www.horde.org/licenses/gpl.

Summary

Methods
Properties
Constants
listForums()
getForumName()
saveForum()
deleteForum()
getThreads()
getThreadsBatch()
getThreadsByForumOwner()
numMessages()
numMessagesBatch()
renderThreads()
addMessage()
postMessage()
removeMessage()
doComments()
prepareFormData()
moderateForm()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Methods

listForums()

listForums(integer  $forum_id, string  $scope = null) : array

Get back a list of available forums.

Parameters

integer $forum_id

Supplying this parameter will return a list of child forums of the requested forum id.

string $scope

If set, limit the forums to requested application.

Returns

array —

The list of available forums.

getForumName()

getForumName(string  $scope, integer  $forum_id) : mixed

Retrieve the name of a forum

Parameters

string $scope

Scope which form belongs to

integer $forum_id

The forum id to fetch the name for.

Returns

mixed —

The forum name | Pear_Error

saveForum()

saveForum(string  $scope, string  $parent, array  $info) 

Create or modify an agora forum.

This is used for apps to create forums for their own use. They will not show up in the regular agora forum view.

Parameters

string $scope

The Horde application that is saving this forum.

string $parent

The parent forum.

array $info

The forum information to save

deleteForum()

deleteForum(string  $scope, string  $forum_name) : boolean

Allow other applications to delete forums. Used when an object that has been commented on has been deleted.

Parameters

string $scope

The Horde application that the forum belongs to.

string $forum_name

The unique forum name to delete.

Returns

boolean —

True on success.

getThreads()

getThreads(string  $forum_name, string  $sort_by = 'message_timestamp', integer  $sort_dir, boolean  $bodies = false, string  $scope = 'agora', string  $base_url = null, string  $from, string  $count) : array

Returns all messages of a forum, in a threaded order.

Parameters

string $forum_name

The unique name for the forum.

string $sort_by

Return messages sorted by this property.

integer $sort_dir

The direction by which to sort: 0 - ascending 1 - descending

boolean $bodies

Whether to include message bodies in the view.

string $scope

The application that the specified forum belongs to.

string $base_url

An alternate link where edit/delete/reply links point to.

string $from

The thread to begin listing at.

string $count

The number of threads to return.

Returns

array —

All messages of the specified forum.

getThreadsBatch()

getThreadsBatch(array  $forum_names, string  $sort_by = 'message_timestamp', integer  $sort_dir, boolean  $bodies = false, string  $scope = 'agora', string  $base_url = null, string  $from, string  $count) : array

Returns all messages for the forums requested, in a threaded order.

Parameters

array $forum_names

An array of unique forum names.

string $sort_by

Return messages sorted by this property.

integer $sort_dir

The direction by which to sort: 0 - ascending 1 - descending

boolean $bodies

Whether to include message bodies in the view.

string $scope

The application that the specified forum belongs to.

string $base_url

An alternate link where edit/delete/reply links point to.

string $from

The thread to begin listing at.

string $count

The number of threads to return.

Returns

array —

An array of message arrays of the specified forum.

getThreadsByForumOwner()

getThreadsByForumOwner(  $owner, string  $sort_by = 'message_timestamp', integer  $sort_dir, boolean  $bodies = false, string  $scope = 'agora', string  $from, string  $count) : array

Returns all messages of a forum, in a threaded order.

Parameters

$owner
string $sort_by

Return messages sorted by this property.

integer $sort_dir

The direction by which to sort: 0 - ascending 1 - descending

boolean $bodies

Whether to include message bodies in the view.

string $scope

The application that the specified forum belongs to.

string $from

The thread to begin listing at.

string $count

The number of threads to return.

Returns

array —

All messages of the specified forum.

numMessages()

numMessages(string  $forum_name, string  $scope = 'agora', integer  $thread_id = null) : integer

Returns the number of messages in a forum.

Parameters

string $forum_name

The unique name for the forum.

string $scope

The application that the specified forum belongs to.

integer $thread_id

The thread to count, if not supplied it will count all messages

Returns

integer —

The number of messages in the specified forum.

numMessagesBatch()

numMessagesBatch(array  $forum_name, string  $scope = 'agora', integer  $thread_id = null) : mixed

Returns the number of messages for the requested forums.

All requested forums must belong to the same scope.

Parameters

array $forum_name

An array of unique forum names.

string $scope

The application that the specified forum belongs to.

integer $thread_id

The thread to count, if not supplied it will count all messages

Returns

mixed —

An array containing the message counts with the forum name as the key | PEAR_Error

renderThreads()

renderThreads(string  $forum_name, boolean  $bodies = false, string  $scope = 'agora', string  $base_url = null, string  $template_file = false) : string

Returns all threads of a forum in a threaded view.

Parameters

string $forum_name

The unique name for the forum.

boolean $bodies

Whether to include message bodies in the view.

string $scope

The application that the specified forum belongs to.

string $base_url

An alternate link where edit/delete/reply links point to.

string $template_file

Template file to use.

Returns

string —

The HTML code of the thread view.

addMessage()

addMessage(string  $scope, string  $forum_name, string  $callback, array  $params = array()) : mixed

Allows other Horde apps to add/edit messages.

The forum name is constructed by just the $forum_name variable under the data root 'agora.forums.'. It is up to the apps themselves to make sure that the forum name is unique.

If the forum does not exist, it will be automatically created by Agora.

Parameters

string $scope

The application which is posting this message.

string $forum_name

The unique name for the forum.

string $callback

A callback method of the specified application that gets called to make sure that posting to this forum is allowed.

array $params

Any parameters for the forum message posting.

message_id        - An existing message to edit
message_parent_id - The ID of the parent message
message_body      - Message body

Returns

mixed —

Returns message id if the message was posted or PEAR_Error object on error

postMessage()

postMessage(string  $scope, string  $forum_name, string  $callback, array  $params = array(), string  $url = null, array  $variables = null) : mixed

Allows other Horde apps to post messages.

The forum name is constructed by just the $forum_name variable under the data root 'agora.forums.'. It is up to the apps themselves to make sure that the forum name is unique.

If the forum does not exist, it will be automatically created by Agora.

Parameters

string $scope

The application which is posting this message.

string $forum_name

The unique name for the forum.

string $callback

A callback method of the specified application that gets called to make sure that posting to this forum is allowed.

array $params

Any parameters for the forum message posting.

message_id        - An existing message to edit
message_parent_id - The ID of the parent message
title             - Posting title
string $url

If specified, the form gets submitted to this URL instead of the current page.

array $variables

A hash with all variables of a submitted form generated by this method.

Returns

mixed —

Returns either the rendered Horde_Form for posting a message or PEAR_Error object on error, or true in case of a successful post.

removeMessage()

removeMessage(string  $scope, string  $forum_name, string  $callback, array  $params = array(), array  $variables = null) : mixed

Allows other Horde apps to remove messages.

The forum name is constructed by just the $forum_name variable under the data root 'agora.forums.'. It is up to the apps themselves to make sure that the forum name is unique.

Parameters

string $scope

The application which is posting this message.

string $forum_name

The unique name for the forum.

string $callback

A callback method of the specified application that gets called to make sure that posting to this forum is allowed.

array $params

Any parameters for the forum message posting.

message_id        - An existing message to delete
array $variables

A hash with all variables of a submitted form generated by this method.

Returns

mixed —

Returns either the rendered Horde_Form for posting a message or PEAR_Error object on error, or true in case of a successful post.

doComments()

doComments(string  $scope, string  $key, string  $callback,   $bodies = true, string  $base_url = null, string  $url = null, array  $variables = null, string  $template_file = false) : mixed

Allows other Horde apps to post messages.

In most apps we use the same code to make comments possible. This function does most of that. Allow comments to be added to any app. The app itself should check if the agora api is present, determine a key and call this function before app::menu is called (before any output has started. At the end of its output it can print the array returned to show the comments.

Parameters

string $scope

The application which is posting this message.

string $key

Unique key from the object (picture etc we're viewing. It will be used as the forum name.

string $callback

A callback method of the specified application that gets called to make sure that posting to this forum is allowed.

$bodies
string $base_url

Base URL the edit/delete/reply links should point to.

string $url

If specified, the form gets submitted to this URL instead of the current page.

array $variables

A hash with all variables of a submitted form generated by this method.

string $template_file

Template file to use.

Returns

mixed —

array Returns either the rendered Horde_Form for comments and threads for posting/viewing a message or PEAR objects on error.

prepareFormData()

prepareFormData(string  $scope, string  $parent = false, array  $info = array(), string  $callback = null) 

Fill up a form data array.

Parameters

string $scope

The Horde application that is saving this forum.

string $parent

The parent forum.

array $info

The forum information to consisting of: forum_parent_id forum_name forum_description forum_moderated forum_attachments

string $callback

A callback method of the specified application that gets called to make sure that posting to this forum is allowed.

moderateForm()

moderateForm(string  $scope) 

Prepare the moderate form

Parameters

string $scope

The Horde application that is saving this forum.