diff --git xmlrpc_example/xmlrpc_example.module xmlrpc_example/xmlrpc_example.module index f6609f3..5b9aa3e 100644 --- xmlrpc_example/xmlrpc_example.module +++ xmlrpc_example/xmlrpc_example.module @@ -4,14 +4,14 @@ /** * @file * This is an example of how to implement and XML-RPC server by registering - * callbacks to specific methods and how to make xmlrpc calls using the builtin + * callbacks to specific methods and how to make xmlrpc calls using the built-in * xmlrpc() factory provided by Drupal. * * For experimentation you may be interested in the * @link http://drupal.org/project/xmlrpctester XML-RPC Tester module @endlink. * * Note that the @link http://drupal.org/project/services Services module @endlink - * is probably the more common way to do XML-RPC at this time. + * is another common way to do XML-RPC at this time. * * @see hook_xmlrpc() * @see xmlrpc() @@ -28,10 +28,16 @@ * Register all the demonstration forms. */ function xmlrpc_example_menu() { + $items['examples/xmlrpc'] = array( + 'title' => 'XML-RPC Example', + 'description' => 'Information about the XML-RPC example', + 'page callback' => 'xmlrpc_example_info', + 'access callback' => TRUE, + ); // This is the server configuration form menu entry. This form can be used to // configure the settings of the exposed services. An XML-RPC server does not // require a configuration form, and has been included here as an example. - $items['examples/xmlrpc_server'] = array( + $items['examples/xmlrpc/server'] = array( 'title' => 'XML-RPC Server configuration', 'description' => 'Server configuration form', 'page callback' => 'drupal_get_form', @@ -42,7 +48,7 @@ function xmlrpc_example_menu() { // This is the client form menu entry. This form is used to allow user // interaction with the services, but again, user interface is not required // to create an XML-RPC client with Drupal. - $items['examples/xmlrpc_client'] = array( + $items['examples/xmlrpc/client'] = array( 'title' => 'XML-RPC Client form', 'description' => 'Demonstrates client side XML-RPC calls with Drupal', 'page callback' => 'drupal_get_form', @@ -53,8 +59,8 @@ function xmlrpc_example_menu() { // This part is completely optional. It will allow the modification of services // defined by this or other modules. This configuration form is used to // enable the hook_xmlrpc_alter API and alter current existing services - $items['examples/xmlrpc_alter'] = array( - 'title' => 'XMLRPC Alterations', + $items['examples/xmlrpc/alter'] = array( + 'title' => 'XML-RPC Alterations', 'description' => 'Demonstrates how to alter defined XML-RPC services', 'page callback' => 'drupal_get_form', 'page arguments' => array('xmlrpc_example_alter_form'), @@ -64,12 +70,20 @@ function xmlrpc_example_menu() { return $items; } +/** + * A simple landing-page information function. + */ +function xmlrpc_example_info() { + return array( + '#markup' => t('This XML-RPC example presents code that shows ', array('!server' => url('examples/xmlrpc/server'), 'client' => url('examples/xmlrpc/client'), 'alter' => url('examples/xmlrpc/alter'))), + ); +} // This is the server part of the module, implementing a simple and little // server with just two simple services. The server is divided in two -// different parts: the xml-rpc implementation (required) and a graphical user +// different parts: the XML-RPC implementation (required) and a webform // interface (optional) to configure some settings in the server side. -// +// // The XMLRPC server will define two different services: // // - sub: perform the subtraction of two numbers. The minimum and maximum values @@ -77,13 +91,14 @@ function xmlrpc_example_menu() { // - add: perform the addition of two numbers. The minimum and maximum values // returned by the server can be configured in the server configuration form. // -// If the result value for the operation is over the maximum limit, a custom error -// number 10001 is returned. This is an arbitrary number and could be any number. -// If the result value for the operation is below the minimum limit, a custom error -// number 10002 is returned. Again, this value is arbitrary and could be any other -// number. Client applications must know the meaning of the error numbers returned -// by the server. - +// If the result value for the operation is over the maximum limit, a custom +// error number 10001 is returned. This is an arbitrary number and could be any +// number. +// +// If the result value for the operation is below the minimum limit, a custom +// error number 10002 is returned. Again, this value is arbitrary and could be +// any other number. Client applications must know the meaning of the error +// numbers returned by the server. // The following code is the XML-RPC implmentation of the server part. The fisrt // step is to define the methods. This methods should be associated to callbacks @@ -93,7 +108,7 @@ function xmlrpc_example_menu() { * Implements hook_xmlrpc(). * * Provides Drupal with an array to map XML-RPC callbacks to existing functions. - * This functions may be defined in other modules. The example implementation + * These functions may be defined in other modules. The example implementation * defines specific functions for the example services. * * @see hook_xmlrpc() @@ -113,11 +128,11 @@ function xmlrpc_example_xmlrpc() { // Second operatnd is an integer. 'int', ), - // Include a little description that is shown when XML-RCP server is + // Include a little description that is shown when XML-RPC server is // requested for the implemented methods list. t('Returns the sum of the two arguments.') // Method description ); - // The subtract method is similiar to the addition, only the method name, + // The subtract method is similar to the addition, only the method name, // callback and description are different. $methods[] = array( 'xmlrpc_example.subtract', @@ -133,10 +148,10 @@ function xmlrpc_example_xmlrpc() { // A server may implement methods associated to callbacks like node_load(), // variable_get() or any other existing function (php functions as well). // -// If the callbacks callbacks associated to the methods don't exist they must be +// If the callbacks associated to the methods don't exist they must be // created. This implementation requires two specific callbacks: -// - _xmlrpc_example_server_add -// - _xmlrpc_example_server_subtract +// - _xmlrpc_example_server_add() +// - _xmlrpc_example_server_subtract() // /** @@ -146,7 +161,9 @@ function xmlrpc_example_xmlrpc() { * configured limits. * * @param $num1 + * The first number to be summed. * @param $num2 + * The second number to be summed. * @return * The sum of the arguments, or error if it is not in server defined bounds. * @@ -155,11 +172,13 @@ function xmlrpc_example_xmlrpc() { function _xmlrpc_example_server_add($num1, $num2) { $sum = $num1 + $num2; // If result is not within maximum and minimum limits, return corresponding error - if ($sum > variable_get('xmlrpc_example_server_max', 10)) { - return xmlrpc_error(10001, t("Result is over the upper limit defined by the server.")); + $max = variable_get('xmlrpc_example_server_max', 10); + $min = variable_get('xmlrpc_example_server_min', 0); + if ($sum > $max) { + return xmlrpc_error(10001, t("Result is over the upper limit (@max) defined by the server.", array('@max' => $max))); } - if ($sum < variable_get('xmlrpc_example_server_min', 0)) { - return xmlrpc_error(10002, t("Result is under the lower limit defined by the server.")); + if ($sum < $min) { + return xmlrpc_error(10002, t("Result is below the lower limit defined by the server (@min).", array('@min' => $min))); } // Otherwise return the result. return $sum; @@ -181,20 +200,20 @@ function _xmlrpc_example_server_add($num1, $num2) { */ function _xmlrpc_example_server_subtract($num1, $num2) { $diference = $num1 - $num2; + $max = variable_get('xmlrpc_example_server_max', 10); + $min = variable_get('xmlrpc_example_server_min', 0); + // If result is not within maximum and minimum limits, return corresponding error - if ($diference > variable_get('xmlrpc_example_server_max', 10)) { - return xmlrpc_error(10001, t("Result is over the upper limit defined by the server.")); + if ($diference > $max) { + return xmlrpc_error(10001, t("Result is above the upper limit (@max) defined by the server.", array('@max' => $max))); } - if ($diference < variable_get('xmlrpc_example_server_min', 0)) { - return xmlrpc_error(10002, t("Result is under the lower limit defined by the server.")); + if ($diference < $min) { + return xmlrpc_error(10002, t("Result is below the lower limit (@min) defined by the server.", array('@min' => $min))); } // Otherwise return the result. return $diference; } -// - - // User interface for the XML-RPC Server part. // A server does not require an interface at all. In this implementation we // use a server configuration form to set the limits available for the addition @@ -207,12 +226,12 @@ function _xmlrpc_example_server_subtract($num1, $num2) { function xmlrpc_example_server_form() { $form = array(); $form['explanation'] = array( - '#markup' => "
" . t("This is the XML-RPC server configuration page.
Here you may define the maximum and minimum values for the add or subtraction exposed services.
") . "
", + '#markup' => "
" . t("This is the XML-RPC server configuration page.
Here you may define the maximum and minimum values for the addition or subtraction exposed services.
") . "
", ); $form['xmlrpc_example_server_min'] = array( '#type' => 'textfield', '#title' => t("Enter the minimum value returned by the subtraction or addition methods"), - '#description' => t("if the result of the operation is lower than this value, a custom XML-RPC error will be returned: 10002."), + '#description' => t("If the result of the operation is lower than this value, a custom XML-RPC error will be returned: 10002."), '#default_value' => variable_get('xmlrpc_example_server_min', 0), '#size' => 5, '#required' => TRUE, @@ -225,33 +244,39 @@ function xmlrpc_example_server_form() { '#size' => 5, '#required' => TRUE, ); + $form['info'] = array( + '#type' => 'markup', + '#markup' => '
' . t('Use the XML-RPC Client example form to experiment', array('!link' => url('examples/xmlrpc/client'))), + ); + if (variable_get('xmlrpc_example_alter_enabled', FALSE)) { + $form['overridden'] = array( + '#type' => 'markup', + '#markup' => '
' . t('Just a note of warning: The alter form has been used to disable the limits, so you may want to turn that off if you do not want it.', array('!link' => url('examples/xmlrpc/alter'))) . '
', + ); + } return system_settings_form($form); } // The server part of the module ends here. - - - - - -// This is the client part of the module. If defines a form with two input fields -// to call xmlrcp_example.add or xmlrpc_example.subtract methods on this host. -// Please notice that having a user interface to query an XML-RPC service is not -// required. A method can be requested to a server using the xmlrcp() function -// directly. We have included an user interface to make the testing eassier. +// This is the client part of the module. If defines a form with two input +// fields to call xmlrpc_example.add or xmlrpc_example.subtract methods on this +// host. Please note that having a user interface to query an XML-RPC service is +// not required. A method can be requested to a server using the xmlrpc() +// function directly. We have included an user interface to make the testing +// easier. // The client user interface part of the module starts here. /** - * Present a form to get two arguments, and make a call to an XML-RCP server using - * these arguments as input, showing the result in a message. + * Present a form to get two arguments, and make a call to an XML-RPC server + * using these arguments as input, showing the result in a message. */ function xmlrpc_example_client_form() { $form = array(); $form['explanation'] = array( - '#markup' => "
" . t("This example demonstrates how to make XML-RPC calls with Drupal.
It uses the xmlrpc() function to act as a client, calling itself for some defined methods.
An xmlrpc error will result if the result is out of bounds defined by the server. These error numbers are defined by the server.
") . "
", + '#markup' => "
" . t("This example demonstrates how to make XML-RPC calls with Drupal.
It uses the xmlrpc() function to act as a client, calling the XML-RPC server defined in this same example for some defined methods.
An XML-RPC error will result if the result is out of bounds defined by the server. These error numbers are defined by the server.
") . "
", ); // We are going to call add and subtract methods, and they work with integer values. $form['num1'] = array( @@ -279,6 +304,12 @@ function xmlrpc_example_client_form() { '#value' => t("Subtract the integers"), '#submit' => array('xmlrpc_example_client_subtract_submit'), ); + if (variable_get('xmlrpc_example_alter_enabled', FALSE)) { + $form['overridden'] = array( + '#type' => 'markup', + '#markup' => '
' . t('Just a note of warning: The alter form has been used to disable the limits, so you may want to turn that off if you do not want it.', array('!link' => url('examples/xmlrpc/alter'))) . '
', + ); + } return $form; } @@ -348,12 +379,7 @@ function xmlrpc_example_client_subtract_submit($form, &$form_state) { // The client part of the module ends here. - - - - - -// Here starts the alteration part of the module. The hook_xmlrpc_alter is +// The alteration part of the module starts here. hook_xmlrpc_alter() is // useful when you want to extend, limit or alter methods defined by other // modules. This part is not required to have an XML-RPC server or client // working, but is useful to understand what can we do using current xmlrpc @@ -363,14 +389,14 @@ function xmlrpc_example_client_subtract_submit($form, &$form_state) { // this xmlrpc demonstration server, or can be used to alter methods defined // by other modules implementing hook_xmlrpc() // -// As the rest of the example module, an user interface is not required to make -// use of this hook. A configuration form is included to enable/disable this -// functionality, but this part is optional if you want to implement -// hook_xmlrpc_alter +// As with the rest of the example module, an user interface is not required to +// make use of this hook. A configuration form is included to enable/disable +// this functionality, but this part is optional if you want to implement +// hook_xmlrpc_alter() // This is the XML-RPC code for the alteration part. It will check if an option -// to enable the functionality is enable and then alter the We alter the +// to enable the functionality is enabled and then alter it. We alter the // 'xmlrpc_example.add' and 'xmlrpc_example.subtract' methods, changing the // associated callback with custom functions. The modified methods (with // new callbacks associated) will perform the addition or subtraction of the @@ -379,8 +405,8 @@ function xmlrpc_example_client_subtract_submit($form, &$form_state) { /** * Implements hook_xmlrpc_alter(). * - * Look if xmlrpc_example.add and xmlrpc_example.subtract methods are defined - * and replace their callbacks with custom code. + * Check to see if xmlrpc_example.add and xmlrpc_example.subtract methods are + * defined and replace their callbacks with custom code. * * @see hook_xmlrpc_alter() */ @@ -439,7 +465,7 @@ function _xmlrpc_example_alter_subtract($num1, $num2) { // Our implmementation of hook_xmlrpc_alter will work only if a system variable -// is set to true, and we need a configuration form to enable/disable this +// is set to true, and we need a configuration form to enable/disable this // 'feature'. This is the user interface to enable or disable the hook_xmlrpc_alter // operations. @@ -449,14 +475,17 @@ function _xmlrpc_example_alter_subtract($num1, $num2) { function xmlrpc_example_alter_form() { $form = array(); $form['explanation'] = array( - '#markup' => "
" . t("This is a configuration form to enable the alteration of XML-RPC methods using hook_xmlrpc_alter.
HOOK_XMLRPC_ALTER can be used to alter the current defined methods by other modules. In this case as demonstration, we will overide current add and subtraction methods with others not being limited. Remember that this hook is optional and is not required to create XMLRPC services.
") . "
", + '#markup' => "
" . t("This is a configuration form to enable the alteration of XML-RPC methods using hook_xmlrpc_alter.
hook_xmlrpc_alter() can be used to alter the current defined methods by other modules. In this case as demonstration, we will overide current add and subtraction methods with others not being limited. Remember that this hook is optional and is not required to create XMLRPC services.
") . "
", ); $form['xmlrpc_example_alter_enabled'] = array( '#type' => 'checkbox', '#title' => t("Overide current xmlrpc_example.add and xmlrpc_example.subtraction methods"), - '#description' => t("Enabling this checkbox, the default methods will be replaced with custom methods not considering the XML-RPC server limit restrictions."), + '#description' => t("If this checkbox is enabled, the default methods will be replaced with custom methods that ignore the XML-RPC server maximum and minimum restrictions."), '#default_value' => variable_get('xmlrpc_example_alter_enabled', 0), ); + $form['info'] = array( + '#markup' => '
' . t('Use the client submission form to see the results of checking this checkbox', array('!link' => url('examples/xmlrpc/client'))) . '
', + ); return system_settings_form($form); } diff --git xmlrpc_example/xmlrpc_example.test xmlrpc_example/xmlrpc_example.test index a60674f..9bdd2c4 100644 --- xmlrpc_example/xmlrpc_example.test +++ xmlrpc_example/xmlrpc_example.test @@ -4,10 +4,6 @@ /** * @file * Test case for the XML-RPC example module. - * - * This file contains the test cases to check if module is performing as - * expected. - * */ class XmlrpcExampleTestCase extends DrupalWebTestCase { protected $xmlrpc_url; @@ -32,7 +28,7 @@ class XmlrpcExampleTestCase extends DrupalWebTestCase { } /** - * Perform several calls to the XML-RPC inteface to test the services. + * Perform several calls to the XML-RPC interface to test the services. */ function testXmlrpcExampleBasic() { // Unit test functionality. @@ -57,11 +53,11 @@ class XmlrpcExampleTestCase extends DrupalWebTestCase { function testXmlrpcExampleClient() { // Now test the UI. $edit = array('num1' => 3, 'num2' => 5); - $this->drupalPost('examples/xmlrpc_client', $edit, t('Add the integers')); + $this->drupalPost('examples/xmlrpc/client', $edit, t('Add the integers')); $this->assertText(t("The XML-RPC server returned this response: @num", array('@num' => 8))); $edit = array('num1' => 8, 'num2' => 3); - $this->drupalPost('examples/xmlrpc_client', $edit, t('Subtract the integers')); + $this->drupalPost('examples/xmlrpc/client', $edit, t('Subtract the integers')); $this->assertText(t("The XML-RPC server returned this response: @num", array('@num' => 5))); } @@ -71,11 +67,11 @@ class XmlrpcExampleTestCase extends DrupalWebTestCase { function testXmlrpcExampleServer() { // Set different minimum and maxmimum valuesI. $options = array('xmlrpc_example_server_min' => 3, 'xmlrpc_example_server_max' => 7); - $this->drupalPost('examples/xmlrpc_server', $options, t('Save configuration')); + $this->drupalPost('examples/xmlrpc/server', $options, t('Save configuration')); $this->assertText(t("The configuration options have been saved"), t("Results limited to >= 3 and <= 7")); $edit = array('num1' => 8, 'num2' => 3); - $this->drupalPost('examples/xmlrpc_client', $edit, t('Subtract the integers')); + $this->drupalPost('examples/xmlrpc/client', $edit, t('Subtract the integers')); $this->assertText(t("The XML-RPC server returned this response: @num", array('@num' => 5))); $result = xmlrpc($this->xmlrpc_url, array('xmlrpc_example.add' => array(3, 4))); @@ -95,13 +91,13 @@ class XmlrpcExampleTestCase extends DrupalWebTestCase { function testXmlrpcExampleAlter() { // Enable XML-RPC service altering functionality. $options = array('xmlrpc_example_alter_enabled' => 1); - $this->drupalPost('examples/xmlrpc_alter', $options, t('Save configuration')); + $this->drupalPost('examples/xmlrpc/alter', $options, t('Save configuration')); $this->assertText(t("The configuration options have been saved"), t("Results are not limited due to methods alteration")); // After altering the functionality, the add and subtract methods have no // limits and should not return any error. $edit = array('num1' => 80, 'num2' => 3); - $this->drupalPost('examples/xmlrpc_client', $edit, t('Subtract the integers')); + $this->drupalPost('examples/xmlrpc/client', $edit, t('Subtract the integers')); $this->assertText(t("The XML-RPC server returned this response: @num", array('@num' => 77))); $result = xmlrpc($this->xmlrpc_url, array('xmlrpc_example.add' => array(30, 4))); @@ -110,5 +106,4 @@ class XmlrpcExampleTestCase extends DrupalWebTestCase { $result = xmlrpc($this->xmlrpc_url, array('xmlrpc_example.subtract' => array(4, 30))); $this->assertEqual($result, -26, t('Successfully substracted 4-30 = -26')); } - }