Latest revision as of 21:49, 16 August 2010

Introduction

The Cross Site Publishing and Receiving API and GUI (Referred to as `CSPR` from here on) allows plugins to accomplish the following:

• Publish and receive any type of data among not only Geeklog sites but any application (web or desktop) that support the ATOM protocol and implement the REQUEST commands.

Using the CSPR is extremely easy, and all work can usually be done in a few API calls (for integrating support) or in a few clicks (using the GUI).

NOTE: This guide is IN PROGESS so until this message is removed then the information is NOT COMPLETE

Overview, Groups, Feeds, Data

The CSPR contains three main components - repositories, groups and feeds.

• Repositories are a collection of groups, most likely a Geeklog site (or could be another application).
• Groups are collections of feeds, usually about a standard topic (eg. News, Alerts, etc).
• Feeds hold data, and are derived from the group, eg. a `Main Geeklog News Feed` and a `VVT News Feed` for the group News.

Groups and Feeds can either be private or public. Public groups and feeds allow anyone to subscribe to them. Private on the other hand forces subscribers to be approved for access to various feeds. Anyone is able to subscribe to a repository, however depending on the type (Public or Private) a different thing happens. Each subscription is based on the actual repository - a public subscription means that only public groups and feeds are able to be joined, while a private subscription allows both public and private feeds to which the subscription is allowed.

Private subscriptions are assigned security groups. A security group is a collection of feeds that members of the group have access to. Private subscriptions can be assigned more than one security group. This allows an administrator of the repository to break down access into smaller chunks, and if a pay-subscription was wanted by the repository, it could offer different packages which then would match up to security group configurations.

The CSPR is modified through two interfaces. There is a GUI for the server and for the client (publishing and receiving respectively) which allow all basic tasks to be performed, eg. approving subscriptions, assigning security groups, creating groups and feeds, etc. The only thing the GUI does not support is adding data to a feed. The API on the other hand allow total manipulation of every aspect of the CSPR functionality. As well, the API allows plugins to hook into some of the GUI parts (subscribing, joining feeds) so the plugin does not have to recreate the wheel every time, however if the plugin developers so want to, it is easy to do.

Plugins and using the API

NOTE: @Result, directions for including lib files if not integrated into geeklog

Using the API differs depending on what side of the exchange you are developing for. For example, there are the PublishingControlManagement classes and methods that deal with repository or server end of things, and the ReceivingControlManagement classes and methods that deal with the joining/client end of things.

All data (Group, Feed, Subscriber, and Data information) are passed to and from methods using objects. These objects are GroupObject, FeedObject, DataObject, SecurityObject.

MAKE SURE TO READ THE DOCUMENTATION FOR EACH METHOD

Following is a list of classes for manipulating the basic structures for publishing

• Managing groups - PublishingGroupControl
• Managing feeds - PublishingFeedControl
• Managing data - PublishingDataControl
• Managing security and subscriptions - PublishingSecurityManagement
• Managing types - TypeObject

For receiving, there is only one class

• ReceivingControlManagement

Plugins are able to utilize the API and structure into their existing code in any way they want to allow communication across the internet. Since most plugins will not need groups, there is a way to have one main group for the entire plugin, that is not visible to the administrators, and looks to be part of the plugin. This feature is called `no display`.

If you decide that you only want one group for the plugin (so no display is for you), then in the plugin's auto install, create the group with the no display flag set to true as the parameter, and the name to be unique. To ensure the name is unique, it MUST have a `%` symbol (percent) in it somewhere. This is a reserved character that is only available for no display groups. The format for a unique group name is:

`Plugin Full Name - plugin_dir_name - % - randomvalue` 
eg. `Cross Site Publishing and Receiving - cspr - % - 0.30`. 

You can then always get the group id for this group by using the

PublishingGroupControl::getIdForNDTitle($title)

method that matches the unique title against the database to retrieve the ID for the group.

Code Study - Autoinstall and creating a no display group

$pgc = new PublishingGroupControl();
$groupObject = new GroupObject();

// Fill the group object
$groupObject->_Title = "Cross Site Alert Plugin - csa - % -100";
$groupObject->_Summary = "Cross site alert plugin only group";
$groupObject->_Type = TypeObject::O_PUBLIC; // Always make the no display group public

// Create the group
try {
    $pgc->createGroup($groupObject, TRUE); // Create the group with no display on. Since no display is on, the % sign is OK. However if it was no a no display group, the % is reserved.
} catch(PublishingException $p) {
    echo "HELP";
}

The basis to any successful integration of the CSPR is understanding the two sections - the server or repository and the client. You may only want one or both of the sections depending on what your plugin is designed to do. The actual data in a feed is bound to a unique Access Code that identifies the destination for the data. For example, the access code will determine what plugin or use the data is used for. You can register a new access code at the main geeklog site for use with your plugin. You are also able to use an existing access code for your plugin if you want to use data intending for another use.