php-e107/e107_handlers/e_ajax_class.php

<?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();
 *   // Merge array into e107.settings javascript object.
 *   $commands[] = $ajax->commandSettings(array('foo' => 'bar'));
 *   // Remove 'disabled' attribute from the '#object-1' element.
 *   $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
{

	/**
	 * 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,
		);
	}

}