Add e107::ajax() to provide macro methods for createing Ajax commands.

e107_handlers/e107_class.php

@@ -156,6 +156,7 @@ class e107
 		'e_admin_request'				 => '{e_HANDLER}admin_ui.php',
 		'e_admin_response'				 => '{e_HANDLER}admin_ui.php',
 		'e_admin_ui'					 => '{e_HANDLER}admin_ui.php',
+		'e_ajax_class'                   => '{e_HANDLER}e_ajax_class.php',
         'e_array'                        => '{e_HANDLER}core_functions.php', // Old ArrayStorage. 
 		'e_bbcode'						 => '{e_HANDLER}bbcode_handler.php',
 		'e_bb_base'						 => '{e_HANDLER}bbcode_handler.php',
@@ -1655,6 +1656,16 @@ class e107
 		return self::getSingleton('eMessage', true);
 	}
 
+	/**
+	 * Retrieve ajax singleton object
+	 *
+	 * @return e_ajax_class
+	 */
+	public static function ajax()
+	{
+		return self::getSingleton('e_ajax_class', true);
+	}
+
 	/**
 	 * Retrieve Library Manager singleton object (internal use only. Use e107::library())
 	 *

e107_handlers/e_ajax_class.php

@@ -0,0 +1,284 @@
+<?php
+
+/**
+ * @file
+ * Functions for use with e107's Ajax API.
+ */
+
+
+/**
+ * Class e_ajax_class.
+ *
+ * Functions for e107's Ajax API.
+ *
+ * E107's Ajax API is used to dynamically update parts of a page's HTML
+ * based on data from the server. Upon a specified event, such as a button
+ * click, a callback function is triggered which performs server-side logic and
+ * may return updated markup, which is then replaced on-the-fly with no page
+ * refresh necessary.
+ *
+ * This framework creates a PHP macro language that allows the server to
+ * instruct JavaScript to perform actions on the client browser.
+ *
+ * When responding to Ajax requests, the server should do what it needs to do
+ * for that request, then create a commands array. This commands array will
+ * be converted to a JSON object and returned to the client, which will then
+ * iterate over the array and process it like a macro language.
+ *
+ * Each command item is an associative array which will be converted to a
+ * command object on the JavaScript side. $command_item['command'] is the type
+ * of command, e.g. 'alert' or 'replace'. The command array may contain any other
+ * data that the command needs to process, e.g. 'method', 'target', 'settings',
+ * etc.
+ *
+ * Commands are usually created with a couple of helper functions, so they
+ * look like this:
+ * @code
+ *   $ajax = e107::ajax();
+ *
+ *   $commands = array();
+ *   // Remove 'disabled' attribute from the content of '#object-1' on the page.
+ *   $commands[] = $ajax->commandInvoke('#object-1', 'removeAttr', array('disabled'));
+ *   // Insert HTML content into the '#object-1' element.
+ *   $commands[] = $ajax->commandInsert('#object-1', 'html', 'some html content');
+ *
+ *   // This method returns with data in JSON format. It sets the header for
+ *   // JavaScript output.
+ *   $ajax->response($commands);
+ * @endcode
+ */
+class e_ajax_class
+{
+
+	/**
+	 * Constructor.
+	 * Use {@link getInstance()}, direct instantiating is not possible for signleton
+	 * objects.
+	 */
+	public function __construct()
+	{
+	}
+
+	/**
+	 * @return void
+	 */
+	protected function _init()
+	{
+	}
+
+	/**
+	 * Cloning is not allowed.
+	 */
+	private function __clone()
+	{
+	}
+
+	/**
+	 * Returns data in JSON format.
+	 *
+	 * This function should be used for JavaScript callback functions returning
+	 * data in JSON format. It sets the header for JavaScript output.
+	 *
+	 * @param $var
+	 *   (optional) If set, the variable will be converted to JSON and output.
+	 */
+	public function response($var = null)
+	{
+		// We are returning JSON, so tell the browser.
+		header('Content-Type: application/json');
+
+		if(isset($var))
+		{
+			echo $this->render($var);
+		}
+	}
+
+	/**
+	 * Renders a commands array into JSON.
+	 *
+	 * @param array $commands
+	 *  A list of macro commands generated by the use of e107::ajax()->command*
+	 *  methods.
+	 *
+	 * @return string
+	 */
+	public function render($commands = array())
+	{
+		$tp = e107::getParser();
+		return $tp->toJSON($commands);
+	}
+
+	/**
+	 * Creates an Ajax 'alert' command.
+	 *
+	 * The 'alert' command instructs the client to display a JavaScript alert
+	 * dialog box.
+	 *
+	 * @param $text
+	 *   The message string to display to the user.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 */
+	public function commandAlert($text)
+	{
+		return array(
+			'command' => 'alert',
+			'text'    => $text,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'insert' command.
+	 *
+	 * This command instructs the client to insert the given HTML.
+	 *
+	 * @param $target
+	 *   A jQuery target selector.
+	 * @param $method
+	 *   Selected method fo DOM manipulation:
+	 *   'replaceWith', 'append', 'prepend', 'before', 'after', 'html'
+	 * @param $html
+	 *   The data to use with the jQuery method.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 */
+	public function commandInsert($target, $method, $html)
+	{
+		return array(
+			'command'  => 'insert',
+			'method'   => $method,
+			'target'   => $target,
+			'data'     => $html,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'remove' command.
+	 *
+	 * The 'remove' command instructs the client to use jQuery's remove() method
+	 * to remove each of elements matched by the given target, and everything
+	 * within them.
+	 *
+	 * @param $target
+	 *   A jQuery selector string.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 *
+	 * @see http://docs.jquery.com/Manipulation/remove#expr
+	 */
+	public function commandRemove($target)
+	{
+		return array(
+			'command' => 'remove',
+			'target'  => $target,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'css' command.
+	 *
+	 * The 'css' command will instruct the client to use the jQuery css() method
+	 * to apply the CSS arguments to elements matched by the given target.
+	 *
+	 * @param $target
+	 *   A jQuery selector string.
+	 * @param $argument
+	 *   An array of key/value pairs to set in the CSS for the target.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 *
+	 * @see http://docs.jquery.com/CSS/css#properties
+	 */
+	public function commandCSS($target, $argument)
+	{
+		return array(
+			'command'  => 'css',
+			'target'   => $target,
+			'argument' => $argument,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'settings' command.
+	 *
+	 * The 'settings' command instructs the client to extend e107.settings with
+	 * the given array.
+	 *
+	 * @param $settings
+	 *   An array of key/value pairs to add to the settings. This will be utilized
+	 *   for all commands after this if they do not include their own settings
+	 *   array.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 */
+	public function commandSettings($settings)
+	{
+		return array(
+			'command'  => 'settings',
+			'settings' => $settings,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'data' command.
+	 *
+	 * The 'data' command instructs the client to attach the name=value pair of
+	 * data to the target via jQuery's data cache.
+	 *
+	 * @param $target
+	 *   A jQuery selector string.
+	 * @param $name
+	 *   The name or key (in the key value pair) of the data attached to this
+	 *   target.
+	 * @param $value
+	 *   The value of the data. Not just limited to strings can be any format.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 *
+	 * @see http://docs.jquery.com/Core/data#namevalue
+	 */
+	public function commandData($target, $name, $value)
+	{
+		return array(
+			'command' => 'data',
+			'target'  => $target,
+			'name'    => $name,
+			'value'   => $value,
+		);
+	}
+
+	/**
+	 * Creates an Ajax 'invoke' command.
+	 *
+	 * The 'invoke' command will instruct the client to invoke the given jQuery
+	 * method with the supplied arguments on the elements matched by the given
+	 * target. Intended for simple jQuery commands, such as attr(), addClass(),
+	 * removeClass(), toggleClass(), etc.
+	 *
+	 * @param $target
+	 *   A jQuery selector string.
+	 * @param $method
+	 *   The jQuery method to invoke.
+	 * @param $arguments
+	 *   (optional) A list of arguments to the jQuery $method, if any.
+	 *
+	 * @return array
+	 *   An array suitable for use with the e107::ajax->render() function.
+	 */
+	public function commandInvoke($target, $method, array $arguments = array())
+	{
+		return array(
+			'command'   => 'invoke',
+			'target'    => $target,
+			'method'    => $method,
+			'arguments' => $arguments,
+		);
+	}
+
+}

e107_web/js/core/all.jquery.js

@@ -508,16 +508,6 @@ var e107 = e107 || {'settings': {}, 'behaviors': {}};
 					var $element = $(command.target);
 					$element[command.method].apply($element, command.arguments);
 					break;
-
-				// Command to set attribute for element.
-				case 'attr':
-					$newtarget.attr(command.name, command.value);
-					break;
-
-				// Command to remove attribute from element.
-				case 'removeAttr':
-					$newtarget.removeAttr(command.name);
-					break;
 			}
 		});
 	};