Commit 917ed3c4 authored by aaronwinborn's avatar aaronwinborn

this used to be hub.module, with some minor improvements. still in development.

parents
// $Id$
Drupal Hub
Created by Aaron Winborn
winborn@advomatic.com
Begun 16 January 2006
Drupal Hub is an api to allow a server to act as a portal to other web servers.
It associates a specific CCK content type with web listings, and optionally
allows the client servers to create and update their own listings, using xml.
------------
Installation
------------
1) Copy the drupal_hub folder into the modules directory of your Drupal 5.0 installation.
2) Go to the modules administration page and activate the desired modules. drupal_hub.module
is required at a minimum.
Hub Server
----------
If you wish to act as a Drupal Hub server
3) Create a CCK type with the fields you wish to collect from other servers.
At a minimum, you will need fields for the title (corresponds to site name),
url, and description/mission.
4) Go to the Drupal Hub administration page and link the new type to your hub.
5) Link specific fields with the fields to collect information about.
6) Set the other configuration options as appropriate.
Hub Client
----------
If you wish your site to register with & update another specific Hub server
7) Fill in the information for each server you wish to notify.
-----
Usage
-----
Because this module is tied to CCK functionality, administrators of a Hub server may
use other modules to control listing functionality. For instance, they may use the
Views module to display listings as they wish, or they may create an event node type
with nodereference to allow clients to create events tied to their client servers.
As the module provides an API, other modules may extend the Hub module functionality.
For instance, RPG Hub will allow Hub servers to collect game statistics and information.
-----------------
Technical Details
-----------------
When the administrator of a client server enters the information of the hub server they
wish to register with, the client will request an xml document from the hub server. This
document will contain the information the hub server requires, plus a unique code.
After the administrator submits the required information, the information is stored in
the client server (and may be modified at any time). After any submission or modification,
the client again pings the hub server with the unique code.
After confirmation, the hub server will periodically check client servers, using the cron (and
a configurable time duration). It will request an xml document from the client, which must
contain both the unique identifier code and the other required information.
------------------------
Hub Server Configuration
------------------------
A Hub server will associate individual clients with nodes of a specific content type.
So first, an administrator must create and assign a node type to hub clients. They will
need, at a minimum, fields for the client site's title, url, and description. They may
assign any other fields as desired. From the Hub server administration page, the
administrator will then assign the node type for clients.
After this, when Hub clients have registered with the site, they will be available as a
paginated listing from the administration page, with various options available for mass
edits, such as ping, publish/unpublish, promote, or block.
Using the Views module, various listing pages and blocks can be created to harness the
power of the Hub module. If the Views module is enabled, some basic views will be made
available to the Views administration page.
------------------------
Hub Client Configuration
------------------------
After initially registering with a Hub server, a hub client will respond to periodic pings,
giving the status of that server, plus any special messages. An administrator may update
their information at any time from their admin screens, and the client will notify the Hub
server at the next ping that the info needs to be updated.
A Hub client may optionally display a block/page of information of the Hub servers they
are linked to. The Hub servers will send an html block to be displayed with a link. This
may, for instance, have a small image or brief description. This information will be
configurable by the client administrator.
-------------
Specification
-------------
All communication between the Hub server and client will use XML scripting. $clienthash and
$serverhash will be unique random variables created by each specific server. All communication will
be verified on both ends by checking these values.
Registration:
The Hub client (www.example.com) will access a page from the hub server (www.examplehub.com)
as follows:
http://www.examplehub.com/hub/xml/register?url=http://www.example.com&clienthash=xe3Fi8cPq914sQ5cORv3
In response, the Hub server will send an XML document similar to the following:
<xml>
<clienthash>xe3Fi8cPq914sQ5cORv3</clienthash>
<serverhash>ichEH83Cde492Ipz4H1d</serverhash>
<huburl>http://www.examplehub.com</huburl>
<hubversion>hub.module#1.0.72</hubversion>
<fields>
<title>
<type>textfield</type>
<title>Site Name</title>
<default>site_name</default>
<required>1</required>
</title>
<description>
<type>textarea</type>
<title>Site Description</title>
<default>site_mission</default>
<required>1</required>
</description>
<logo>
<type>textfield</type>
<title>Logo</title>
<description>You may add a link to a logo for your site, which must be an image no larger
than 80x120 pixels.</description>
<required>0</required>
</logo>
</fields>
<hubblock>
<title>Example Hub</title>
<logo>http://www.examplehub.com/files/hublogo.png</logo>
<description>We're listed at the best Example hub ever!</description>
</hubblock>
</xml>
After this, the Hub client administrator will now see a form (in a fieldset under the new Hub server)
on the administration page at /admin/hub/client. The form will look something like the following:
Hub Server: http://www.examplehub.com
Hub Server Version: hub.module#1.0.72
Site Name: *
+-----------------------------+
| Example dot com |
+-----------------------------+
Site Description: *
+---------------------------------------+
| This is the site mission for Example |
| dot com, the most used site for |
| example tutorials on the Internet! |
+---------------------------------------+
Logo:
+---------------------------------------+
| http://www.example.com/files/logo.jpg |
+---------------------------------------+
Status:
(Dropdown w/ following:
Active
Offline
)
Hub Server Block:
A new block will be created for you to optionally display. As currently configured, it will
appear as follows:
{=================} Example Hub
{ H U B - L O G O } We're listed at the best Example hub ever!
{=================}
Hub Title:
+---------------------+
| Example Hub |
+---------------------+
Hub Logo:
+---------------------------------------------+
| http://www.examplehub.com/files/hublogo.png |
+---------------------------------------------+
Hub Description: *
+---------------------------------------+
| We're listed at the best Example hub |
| ever! |
| |
| |
+---------------------------------------+
+------+ +--------+
| Ping | | Delete | (NOTE: these buttons only appear after initially submitted.)
+------+ +--------+
This form will also have a #value of hub_client_hash_c_123 = xe3Fi8cPq914sQ5cORv3,
and #value of hub_client_hash_s_123 = ichEH83Cde492Ipz4H1d. (The _123 is a unique value chosen
by the client to correspond to this hub server, and is used only internally.)
After this, the Hub server will ping the Hub client for the new information, either when the Hub
client administrator hits the Ping button, or on a cron from either server. Note that the client
will not respond until the information has been reviewed and submitted by the administrator,
which it checks for with variable_get('hub_client_active_123', false).
Once the information has been submitted, the Hub server asks for the following document:
http://www.example.com/hub/xml/client/ping?hub=http://www.examplehub.com&serverhash=ichEH83Cde492Ipz4H1d
The Hub client responds with the following information:
<xml>
<clienthash>xe3Fi8cPq914sQ5cORv3</clienthash>
<hubversion>hub.module#1.0.58</hubversion>
<status>1</status>
</xml>
Status may be:
0 = Offline or Not configured (this will be returned until the initial registration form has been submitted).
1 = Active
Once the status is 1, the Hub server will the request the client's registration information. (This may be
asked on other occassions, such as when the client pings with new information, or on a regular cron run.)
http://www.example.com/hub/xml/client/info?hub=http://www.examplehub.com&serverhash=ichEH83Cde492Ipz4H1d
The Hub client responds as follows:
<xml>
<clienthash>xe3Fi8cPq914sQ5cORv3</clienthash>
<hubversion>hub.module#1.0.58</hubversion>
<status>1</status>
<fields>
<title>Example dot com</title>
<description>This is the site mission for Example dot com, the most used site for example tutorials on the
Internet!</description>
<logo>http://www.example.com/files/logo.jpg</logo>
</fields>
</xml>
At this point, the Hub server will create a node with the required information. The Hub server may then display
that information in various ways as configured by its adminstrator, most likely using Views and blocks, or
even simply promoting it to the front page.
-------------
Extensibility
-------------
The Drupal Hub module includes certain hooks, allowing for an API to be extended by other modules. For
instance, the RPG Hub module allows for game statistics to be automatically passed between the
Hub servers.
\ No newline at end of file
; $Id$
name = "Drupal Hub"
description = "Provides API for servers to act as portals to other sites, and/or as xml clients to other portal hubs."
version = "$Name$"
dependencies = content
package = Drupal Hub
\ No newline at end of file
<?php
// $Id$
function drupal_hub_install() {
switch ($GLOBALS['db_type']) {
case 'mysql':
case 'mysqli':
db_query("
CREATE TABLE {drupal_hub_types} (
type varchar(32) NOT NULL default '',
hub longtext,
PRIMARY KEY (type)
) /*!40100 DEFAULT CHARACTER SET utf8 */;
");
break;
case 'pgsql':
db_query("
CREATE TABLE {drupal_hub_types} (
type varchar(32) NOT NULL default '',
hub text NUT NULL,
PRIMARY KEY (type)
);
");
db_query("CREATE INDEX {drupal_hub_types}_type_idx ON {drupal_hub_types}(type);");
break;
}
}
<?php
// $Id$
if (variable_get('drupal_hub_is_client', false)) {
include_once(drupal_get_path('module', 'hub') .'/inc/drupal_hub_client.inc');
}
if (variable_get('drupal_hub_is_server', false)) {
include_once(drupal_get_path('module', 'hub') .'/inc/drupal_hub_server.inc');
}
/**
* implement hook_menu
*/
function drupal_hub_menu($may_cache) {
$items = array();
if ($may_cache) {
$admin_access = user_access('administer hub');
$items[] = array(
'path' => 'admin/hub',
'title' => t('Hub configuration'),
'description' => t('Adjust Hub portal configuration options.'),
'position' => 'right',
'weight' => -5,
'callback' => 'system_admin_menu_block_page',
'access' => $admin_access,
);
$items[] = array(
'path' => 'admin/hub/global',
'title' => t('Global Hub configuration'),
'description' => t('Global Hub settings.'),
'callback' => 'drupal_get_form',
'callback arguments' => 'drupal_hub_admin_settings',
'access' => $admin_access,
);
if (variable_get('drupal_hub_is_client', false)) {
$items[] = array(
'path' => 'admin/hub/client',
'title' => t('Hub client configuration'),
'description' => t('Client Hub settings.'),
'callback' => 'drupal_get_form',
'callback arguments' => 'drupal_hub_client_admin_settings',
'access' => $admin_access,
);
}
if (variable_get('drupal_hub_is_server', false)) {
$items[] = array(
'path' => 'admin/hub/server',
'title' => t('Hub server configuration'),
'description' => t('Server Hub settings.'),
'callback' => 'drupal_get_form',
'callback arguments' => 'drupal_hub_server_admin_settings',
'access' => $admin_access,
);
}
}
return $items;
}
/**
* Display global Hub admin settings
*/
function drupal_hub_admin_settings() {
// we have to rebuild the menu, because certain menu items are built or removed accordingly
menu_rebuild();
$form = array();
// Allow the admin to turn on or off all services offered by various Hub modules on the server.
$form['services'] = array(
'#type' => 'fieldset',
'#title' => t('Active Services'),
'#description' => t('Check the box for each Hub portal service you wish to activate for this host.'),
'#collapsible' => true,
'#collapsed' => false,
);
$services = module_invoke_all('hubapi', 'list services');
$service_descriptions = module_invoke_all('hubapi', 'describe services');
foreach ($services as $service => $title) {
$form['services'][$service] = array(
'#type' => 'checkbox',
'#title' => $title,
'#description' => $service_descriptions[$service],
'#default_value' => variable_get($service, false),
);
}
return system_settings_form($form);
}
/**
* Implements hook_hubapi:
* $op
* 'list services': This will return an array of the hub services offered by this module.
* This is used by the Hub server when associating node types to the server, so when a
* client requests the listing options offered, they will also see which modules & services
* are required to be included in that server's listings.
* 'describe services': This is a brief description of the services offered.
* 'field defaults': This returns an array of variables offered as defaults for listings.
* Each field has a prefix that determines the type of variable passed:
* v: signifies a variable stored as variable_get('variable', ...);
* $: signifies a variable stored as a global $variable;
* c: signifies a variable stored as a CONSTANT variable;
* f: signifies a variable that will be returned by a function call;
* s: signifies special handling for the variable, which must be determined by the calling module.
* Note that anything other than v: must be handled by the calling module; the prefixes are for the
* benefit of human programmers.
* 'server defaults': A Hub module may define one or more default servers to list for
* clients. This will return an array of $key => array('name' => $name, 'xmlrpc' => $xmlrpc),
* where $key is a unique code, $name is the name of the server, and $xmlrpc is the
* address for the server's xmlrpc calls. This server should be configured as a
* Hub server.
*
* return values for $op:
* 'list services': This should return an array of strings of the services offered by
* the module, keyed by the variable for whether that service has been activated by the
* client module. For instance, the Hub module allows two services, 'client' and 'server'.
* The client service is activated with variable_get('drupal_hub_is_client', false), so the
* resulting array is array('drupal_hub_is_client' => t('Hub client service'), 'drupal_hub_is_server'
* => t('Hub server service')).
* 'describe services': This returns a keyed array of strings for the descriptions offered
* by the module, keyed by the same service variables as for 'list services'.
*/
function drupal_hub_hubapi($op) {
switch ($op) {
case 'list services':
return array(
'drupal_hub_is_client' => t('Hub: Client service'),
'drupal_hub_is_server' => t('Hub: Server service')
);
case 'describe services':
return array(
'drupal_hub_is_client' => t('Hub Clients may be listed on Hub Servers they have registered with through admin screens on the client. Once registered, the Hub servers will periodically update their listing information.'),
'drupal_hub_is_server' => t('A Hub Server may list clients who have registered with their server, associating the clients with configurable nodes, so the nodes may be displayed through various views and blocks.'),
);
case 'field defaults':
return array(
'v:site_name' => t('Site Name'),
'$:base_url' => t('Site URL'),
'v:site_mission' => t('Site Mission'),
'v:site_slogan' => t('Site Slogan'),
'v:site_mail' => t('Site Mail'),
'c:VERSION' => t('Version'),
);
case 'server defaults':
return array(
'drupal_hub_default_server_drupal_hub' => array(
'name' => t('Drupal Hub'),
'url_xmlrpc' => 'http://drupalhub.org/xmlrpc.php',
),
);
}
}
/**
* Implementation of hook_xmlrpc().
*/
function drupal_hub_xmlrpc() {
// TODO
$xmlrpc = array();
if (variable_get('drupal_hub_is_server', false)) {
$xmlrpc += _drupal_hub_server_xmlrpc();
/* $xmlrpc[] = array(
'drupal_hub.client.ping',
'drupal_hub_client_ping',
array('array', 'array', 'array'),
t('Handling ping request')
);
*/
}
return $xmlrpc;
// TODO:
if (variable_get('drupal_hub_is_client', false)) {
$xmlrpc = _drupal_hub_client_xmlrpc();
/* $xmlrpc[] = array(
'drupal.login',
'drupal_login',
array('int', 'string', 'string'),
t('Logging into a Drupal site')
);*/
}
return $xmlrpc;
}
<?php
// $Id$
function drupal_hub_client_admin_settings() {
$form = array();
// Allow the admin to turn on or off all services offered by various Hub modules on the server.
$form['servers'] = array(
'#type' => 'fieldset',
'#title' => t('Known Drupal Hub Servers'),
'#description' => t('This is a list of known Drupal Hub Servers, and their last known status. You may add or delete a listing with them from here. Once you\'ve added and submitted the form, you may configure a server below.'),
'#collapsible' => true,
'#collapsed' => false,
);
$servers = module_invoke_all('hubapi', 'server defaults');
foreach ($servers as $server => $info) {
$form['servers'][$server] = array(
'#type' => 'checkbox',
'#title' => $info['name'],
'#description' => xmlrpc($info['url_xmlrpc'], 'drupal_hub.server.info'),
'#default_value' => variable_get($server, false),
);
if (variable_get($server, false)) {
$form['config_' . $server] = array(
'#type' => 'fieldset',
'#title' => t('@name Configuration Options', array('@name' => $info['name'])),
'#collapsible' => true,
'#collapsed' => false,
);
$types = xmlrpc($info['url_xmlrpc'], 'drupal_hub.server.register.info');
foreach($types as $type) {
$form['config_' . $server][$server . '_type_' . $type['type']] = array(
'#type' => 'checkbox',
'#title' => $type['name'],
'#description' => $type['description'],
'#default_value' => variable_get($server . '_type_' . $type['type'], false),
);
}
}
}
return system_settings_form($form);
}
<?php
// $Id$
function drupal_hub_server_admin_settings() {
$form = array();
// Allow the admin to turn on or off all services offered by various Hub modules on the server.
$form['cck'] = array(
'#type' => 'fieldset',
'#title' => t('Content Types'),
'#collapsible' => true,
'#collapsed' => false,
);
$form['cck']['current'] = array(
'#type' => 'fieldset',
'#title' => t('Current Hub Listing Types'),
'#description' => t('The following content types have been set to store Hub client listings. You may configure them individually below.'),
'#collapsible' => true,
'#collapsed' => false,
);
$types = drupal_hub_server_type_load();
if (empty($types)) {
$form['cck']['current']['#description'] = t('No content types are currently configured to store Hub client listings. You may select one or more content types from below.');
}
$cck = content_types();
$defaults = array(0 => t('(No Automatic Value)'));
$defaults += module_invoke_all('hubapi', 'field defaults');
foreach ($types as $type) {
$form['cck']['current']['drupal_hub_server_type_' . $type['type']] = array(
'#type' => 'fieldset',
'#title' => $type['name'],
'#description' => $type['description'],
'#collapsible' => true,
'#collapsed' => false,
);
$form['cck']['current']['drupal_hub_server_type_' . $type['type']]['auto'] = array(
'#type' => 'fieldset',
'#title' => t('Automatic Values'),
'#description' => t('Please select the automatic values for each desired field here. When an automatic value has been selected, the client site will automatically enter its corresponding value of the appropriate variable.'),
'#collapsible' => true,
'#collapsed' => true,
);
if ($type['has_title']) {
$form['cck']['current']['drupal_hub_server_type_' . $type['type']]['auto']['drupal_hub_server_' . $type['type'] . '_auto_title'] = array(
'#type' => 'select',
'#title' => $type['title_label'],
'#options' => $defaults,
'#default_value' => variable_get('drupal_hub_server_' . $type['type'] . '_auto_title', 'v:site_name'),
);
}
if ($type['has_body']) {
$form['cck']['current']['drupal_hub_server_type_' . $type['type']]['auto']['drupal_hub_server_' . $type['type'] . '_auto_body'] = array(
'#type' => 'select',
'#title' => $type['body_label'],
'#options' => $defaults,
'#default_value' => variable_get('drupal_hub_server_' . $type['type'] . '_auto_body', 'v:site_mission'),
);
}
foreach($type['fields'] as $field) {
$form['cck']['current']['drupal_hub_server_type_' . $type['type']]['auto']['drupal_hub_server_' . $type['type'] . '_auto_' . $field['field_name']] = array(
'#type' => 'select',
'#title' => $field['widget']['label'],
'#options' => $defaults,
'#default_value' => variable_get('drupal_hub_server_' . $type['type'] . '_auto_' . $field['field_name'], '0'),
);
}
}
$options = array();
foreach ($cck as $type) {
$options[$type['type']] = $type['name'];
}
$form['cck']['drupal_hub_server_cck_types'] = array(
'#type' => 'checkboxes',
'#title' => t('Add Hub Listing Types'),
'#options' => $options,
'#default_value' => variable_get('drupal_hub_server_cck_types', array()),
'#description' => t('To enable a content type as a Hub listing type, check the box for the type and hit submit. You will then be able to modify its specific settings above. Likewise, to remove a type, uncheck the box and submit. It will then be removed from the listings above.'),
);
return system_settings_form($form);
}
function drupal_hub_server_type_load($type_name = NULL) {
static $types = array();
if (empty($types)) {
$drupal_hub_types = variable_get('drupal_hub_server_cck_types', array());
foreach ($drupal_hub_types as $type => $value) {
if ($value) {
$cck_type = content_types($value);
$types[$cck_type['type']] = $cck_type;
}
}
}
if ($type_name) {
return $types[$type_name];
}
return $types;
}
/**
* This is called by a client hub as an xmlrpc to request registration info.
* The server will respond with an xmlrpc message to the client with the appropriate info.
*/
function _drupal_hub_server_test($bool) {
if ($bool) { $output = 'true'; } else { $output = 'false'; }
return $output . t(' testing drupal_hub_server_register_request');
}
/**
* This returns the Hub server's info, in response to a ping from client servers
* wishing to list basic information about why they should register with a particular
* Hub server.
*/
function _drupal_hub_server_info() {
return variable_get('drupal_hub_server_info', variable_get('site_mission', ''));
}
/**
* This xml function will return the descriptions of the cck listing types
*/
function _drupal_hub_server_register_info() {
return drupal_hub_server_type_load();
}
/**
* Implementation of hook_xmlrpc().
* call like:
* $url = 'http://drupalhub.org/xmlrpc.php';
* $xml = xmlrpc($url, 'hub.server.register.request', $arg1, $arg2, ..., $argN);
*/
function _drupal_hub_server_xmlrpc() {
// TODO
$xmlrpc = array();
$xmlrpc[] = array(
'hub.server.test',
'_drupal_hub_server_test',
array('string', 'boolean'), // array($return_value_type, $arg1, $arg2, ..., $argN);
t('Test Hub server'),
);
$xmlrpc[] = array(
'hub.server.info',
'_drupal_hub_server_info',
array('string'),
t('Request Hub server\'s info'),
);
$xmlrpc[] = array(
'hub.server.register.info',
'_drupal_hub_server_register_info',
array('struct'),
t('Request Hub server\'s info'),
);
/* $xmlrpc[] = array(
'drupal.login',
'drupal_login',
array('int', 'string', 'string'),
t('Logging into a Drupal site')
);*/
return $xmlrpc;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment