Talash:Dev

= Developer Notes =

The documentation regarding the codebase so that developers can hack, extend and contribute to this plugin development.

= Plugin Structure =

The plugin structure allows an easy to extend format that will allow more and more address books to be tapped in. Following is the structure of directories.

/Friend config.php /api/ /Google /Twitter /classes /actions /lib /daemons The api directory contains the services into which the the plugin can tap in to find users address books, or friends (example, twitter).

The classes directory contains the database object wrappers.

The actions directory contains the UI to control the plugin.

The lib directory contains the various library functions that can be used by the plugin to tap into various services using apis and display and serve the various functionalities used by the plugin.

The daemons contains certain scripts that will be a major part in the Delayed Connect phase of the plugin.

The plugin itself contains a config file in which the developer can install interfaces to various services from which address books and friends information can be retrieved. The details of config file are discussed in api section.

= Tables =

This is a description of different tables used in the plugin. These tables provide enough scope for extending the plugin by using configurable attributes.

Token Store
FriendTokenStore class constructs the table friend_token_store

This stores the access tokens of every oauth access to external address books. Each user keeps one access token and secret token per service. The table structure is as follows.

Attribute      Information -  -    user_id         user id of the user who data can be accessed by the tokens service_name   service name to which this token is associated access_token   access token of size upto 300 characters secret_token   token secret of size upto 300 characters Currently the insert method of this class enqueues the token for the queue handler to extract the users contacts in background.

Connect Store
FriendConnectStore class constructs the table friend_connect_store

This stores the contacts extracted per user from various services like Google and Twitter. This store is the focal point of this plugin because its used to connect the user to his friends who have other OStatus accounts, and later on search for more subscriptions. The table structure of this table is as follows.

Attribute      Information -- -    user_id         user id of user to whom the contacts belong friend_id      unique id of a friend contact, can be email address or twitter uri e.t.c.    profile_loc     whether unknown 0, local 1, or remote 2 friend_id_type whether the friend_id is email address or uri score          an integer value determining the priority with which the friend is being recommended to our user by our system state          upon initialization no action 0 (default), ignore 1 friend_email   email address if friend_id is a uri friend_nick    nick name of the username as retrieved created_date   the date when the contact was created hit_date       last updated date of the contact

Graph Cache
FriendGraphCache class is the most important table of this plugin. This table is a database caches of different repeated HTTP queries that are fired for the social graph api. It provides faster processing after one time query fires. The data in the cache is invalidated time to time.

The cache mainly stores the users social graph, as friend-&gt;friend-of-friend tuple. It makes sense to store this social graph only for those profiles which are * users of the site * users subscribe to

Attribute      Information -  -    profile_id      Profile ID of the user whose friends are to be stored friend_uri     Subscribable profile location of the friend of friend on the web created        Date the cache entry was created The graph cache is used to find new friends, and all major social graph parsing and querying functions are made as a part of this class so as to encapsulate their use and pass all the queries through the cache itself.

Friend Preference
FriendPreference class is a pseudo filter for the plugin. It provides three options to the user. * Recommend me friends I know on other social networks * Recommend me interesting friends * Recommend me friends in my geographical proximity

They are each given a bit value and stored in the DB as their decimal form of three bit representation. So selecting first and second option by the user would make it 101 in its binary form and store 5 in the database.

Attribute      Information -  -    user_id         User ID of the user preference     Preference of the user in decimal format last_cache     Date the cache of the user was updated notification   Any notification to the user The notification is currently implemented as the notification class. Its not being documented since we would like to move to this table to store the notification per user.

= Action =

The plugin contains Three main action renderers.

  Connect /connect This action uses the config file to find all the external services to which the site is connected and from which the users contacts can be extracted   New /new This page displays all the new recommended friends of the user. The friends have either a local or remote OStatus account. Those contacts which do not have a recognised OStatus uri are not recommended.   Manage /manage This page displays all the contacts the user knows. He is given the option of inviting friends who dont have an OStatus account. He can ignore or un-ignore friends. Ignored friends are not recommended to the user in the New friends page. 

= API =

The API (Probably wrongly named) contains the classes which describe the code to use different services from Google, Twitter and Yahoo! etc. to get the user details. The plugin uses a specific format of code structure so that new services can be easily connected to retrieve user data.

The plugin uses a config file to define the new services being added. It further uses a config file in each service specific directory. This config defines the various router specific informations and class names and files for autoLoading these classes. We define how do conenct to a service in following steps.

Creating New Service
To begin creating a new service which can extract user data from his external accounts, create a unique directory name inside the api directory.

mkdir api/Orange In the config file of the plugin add a line.

$conAPI[] = &quot;Orange&quot; Inside the api/Orange directory create a new config.php file and insert this into it.

&lt;?php

$connect[&quot;Orange&quot;] = array; With this the Service is initialized and ready to use.

The config file uses the following attributes to define the structure of the service access and the UI.

'startup'   =&gt; array('name' =&gt; 'startupAction')

'action' =&gt; array('name'       =&gt; 'action',                      'className'   =&gt; 'ActionClassName',                      'classpath'   =&gt; 'actionclassname.php',                      'url'         =&gt; 'orange/action')

'adminform' =&gt; array('name'        =&gt; 'adminform',                      'className'   =&gt; 'AdminFormName',                      'classPath'   =&gt; 'adminformname.php')

'queueman'  =&gt; array('name'        =&gt; 'friendsync',                      'className'   =&gt; 'FriendOrangeSync',                      'classPath'   =&gt; 'orangesync.php') The startup defines the action page to which users are first directed when the service is being used. This name is listed on the talash/connect url.

The action attribute defines the various actions that are being used by the service. The plugin internally initiallizes the router based on the parameters of the action given. The url is appended after the base url of the plugin e.g /talash/connect/orange/action.

The adminform is an attribute that determines the AdminForm that is to be defined for the service. This is an optional attribute, only if an admin form is really required in the plugin admin section.

The queueman attribute specifies the class that will handle the background syncing of user information like contacts. The class is appropriately called based on the information in the access tokens.

Service Action Classes
We use three specific pages to determine the users interaction.

  Connect The Connect page often is the first welcome page of the service. Here we give instructions to the user as to what is going to happen next. The user is then allowed to click a button to move forward. To make this page the inaugral page of the service make sure that the &lsquo;startup&rsquo; attribute in the config of the API is set to this action.   Auth The Auth page initiates the correct authorization mechanism using which the users data is extracted. This is usually done using OAuth. A new design of OAuth library is being used, and hopefully will be used as default OAuth library in future releases of StatusNet. New OAuth Design BasicOAuth   Data This page gives the final data response to the user. It might be a simple page saying &ldquo;your data is being synced, please keep doing what you were doing before&rdquo; or give a paginated response of contacts extracted. These paginated contacts can be used to onspot subscribe, ignore or invite contacts in the address book. 

Any more action classes can be added easily, and entered into the cofig file to register them into the router.

Please note that all the actions that are connected to a particular service will occur at the url /talash/connect/orange/action where action is the name of the action used in this service. This is to avoid clash of names with other plugins which might use similar nomenclature.

Admin Panel
The admin form for each of the service is also pluggable. To add the admin form a entry like below should be made in the config file of each service. This defines the Admin Form class name and the class file used. Note the nomenclature which makes the entries key as &lsquo;adminform&rsquo; and its name also as &lsquo;adminform&rsquo;. This is done so that it can be detected by the FriendadminpanelAction class in /lib.

'adminform' =&gt; array('name'        =&gt; 'adminform',                      'className'   =&gt; 'AdminFormName',                      'classPath'   =&gt; 'adminformname.php') The above &lsquo;adminform&rsquo; entry can be skipped if your service does not require the admin form.

Inside the FriendadminpanelAction define a new key value pair for the setting attribute in saveSetttings method which gives the unique name to your service and unique form elements required. A following template is used.

static $settings = array( 'friendgoogle' =&gt; array('gconsumerkey', 'gsecret'), 'friendtwitter'=&gt; array('tconsumerkey', 'tsecret'), 'friendyahoo'=&gt; array('yconsumerkey', 'ysecret'));

Back Ground Syncing Of User Information
A Queue handler for a queue with name &lsquo;friendsync&rsquo; is provided to sync user information in the background. This takes a token, which is instance of the class FriendConnectToken, as its argument. A token is automatically inserted into the queue whenever it is inserted into the database. The handler function for each service is defined in the service config file by an entry as below.

'queueman' =&gt; array('name'     =&gt; 'friendsync',          'className' =&gt; 'FriendGoogleSync',          'classPath' =&gt; 'googlesync.php') Note that the key should be &lsquo;queueman&rsquo; and the name should be &lsquo;friendsync&rsquo;.

The class which handles this is a normal class which does not inherit anything from any other class. This makes it an independent processing unit.

= Library =

Some of the important library functions used in the development are listed in the libraries page