Ray Integration manual

Customizing integration functions

First of all you need to customize some interface functions, collected in “ray/modules/global/inc/customFunctions.inc.php” (as at most these functions are used for generating XML replies “true” and “false” strings are defined as constants and used instead of Boolean values in some custom functions). All functions should consider to accept the defined number of arguments and return the defined answer (as in original functions):

1. loginUser

/**
 * Authorize user by specified ID and Password or Login and Password.
 * @param $sName - user login/ID
 * @param $sPassword - user password
 * @param $bLogin - search for login (true) or ID (false)
 * @return TRUE_VAL/FALSE_VAL
 */
function loginUser($sName, $sPassword, $bLogin = false) { … }

This function authorizes user by ID and password or by nick and password.

$sResult = loginUser(“1”, “12345”);
echo $sResult;
$sResult = loginUser(“nick”, “12345”, true);
echo $sResult;
/////////////////////
true
false

2. loginAdmin

/**
 * Authorize administrator by specified Login and Password.
 * @param $sLogin - administrator login
 * @param $sPassword - administrator password
 * @return TRUE_VAL/FALSE_VAL
 */
function loginAdmin($sLogin, $sPassword) { … }

This function authorizes admin by nick and password.

$sResult = loginAdmin(“admin”, “dolphin”);
echo $sResult;
/////////////////////
true

3. getUserInfo

/**
 * Gets user's information from database by user's id
 * @param $sId - user ID
 * @return $aInfo - user info
 */
function getUserInfo($sId) { … }

This function retrieves user info by given ID.

$aInfo = getUserInfo(“1”);
print_r($aInfo);
/////////////////////
Array("nick" => “Macho”, "sex" => “Male”, "age" => 25, "desc" => “some description goes here”, "photo" => “http://[your_site]/[images_folder]/1.pg”, "profile" => “http://[your_site]/profile.php?ID=1”)

4. searchUser

/**
 * Searches for user by field $sField with value $sValue
 * @param $sValue - value to search for
 * @param $sField - field to search
 * @return $sId - found user ID
 */
function searchUser($sValue, $sField = "ID") { … }

Searches user by $sField field (“ID” by default) for $sValue value and returns user ID.

$sId = searchUser(“Macho”, “Nick”);
echo $sId;
/////////////////////
1

5. getFriends

/**
 * Gets user's friend's IDs
 * @param $sId - user ID
 * @return $aUsers – array friendly users IDs
 */
function getFriends ($sId) { … }

Retrieves user’s friends by given user ID.

$aFriends = getFriends(“1”);
print_r($aFriends);
/////////////////////
Array(“2”, "3", "5", "10")

Ray Base installation

Once you’ve made necessary changes in integration functions, you should install Ray Base. For this go to "http://[your_site]/ray/install/". Go through the Ray installation wizard, accurately filling out all necessary fields.

After this is done, the first part of integration is done. Your Ray admin panel (the login and password you should have set during installation steps) is available at

http://[your_site]/ray/index.php?module=global&app=admin&nick=[admin_login]&password=[admin_password]

It is recommended to require

[path_to_ray]/modules/global/inc/header.inc.php 

and

[path_to_ray]/modules/global/inc/content.inc.php

into every page of your site. Also every page of your site should include integration JavaScript? script “global/js/integration.js”

<script src="[url_to_ray]/modules/global/js/integration.js" type="text/javascript" language="javascript"></script>

Some Ray widgets use information about online status of site users. So you should provide user online status updating. This can be done in two ways:

1. By calling to “updateRayUserStatus([user_ID])” JavaScript? function (“global/js/integration.js” should be included) for HTML pages (as a rule on body onLoad event).

2. By calling to “updateOnline([user_ID])” PHP function (“global/inc/apiFunctions.inc.php” should be required) for PHP scripts.

Ray widget integration

To integrate any widget to your site you should decide what page of your site is containing this widget application. You can integrate widgets directly to your site layout or just provide a link to pop-up window with this widget application.

1. If you want to open the widget application in pop-up window you should set

   “$aModules[application_name][‘inline’]” 
   

variable in “inc/constants.inc.php” of the widget to “false” and then install the widget.

After installation you will be able to open the widget application by calling to JavaScript?

function openRayWidget(module, application, [param1], [param2], …, [paramN])

function (“global/js/integration.js” should be included to this page) with necessary set of parameters passed to this function.

For example Ray chat (by Boonex) should be opened this way: link to chat:

<a href=”#” onClick=” openRayWidget(“chat”, “user”, “1”, “12345”)”>open chat</a>

Clicking on this link user will open Ray chat and login to it with “1”(user ID) and “12345”(user password) login information.

Here are two compulsory for any widget application parameters – widget name (“chat”) and widget application name (“user”). The rest of parameters depend on widget application and can be known from

$aModules[application_name][‘parameters’] 

variable in “inc/constants.inc.php” of the widget.

2. If you want to integrate any widget application directly into your site page you should require on this page

[path_to_ray]/modules/global/inc/header.inc.php

and

[path_to_ray]/modules/global/inc/content.inc.php

files and insert calling to

function getApplicationContent($sModule, $sApp, $aParamValues, $bInline = false)

function where the widget application should appear.

For example to insert Ray chat (by Boonex) in some page (“chat_area.php”) of a site one should make the following changes to this page:

chat_area.php

<?php
	require_once(“[path_to_ray]/modules/global/inc/ header.inc.php”);
	require_once(“[path_to_ray]/modules/global/inc/content.inc.php”);
	//some code
…………………..
$aParamValues = array();
$aParamValues[‘id’] = “1”;//defining user ID
$aParamValues[‘password’] = “12345”;//defining user password
echo getApplicationContent(“chat”, “user”, $aParamValues, true);
…………………..
//some more code
?>

This will display Ray chat and login to it with “1”(user ID) and “12345”(user password) login information directly in the “chat_area.php” page.

If you have questions, suggestions or feedbacks over this manual feel free to write them at Unity Forums for Ray.