==TYPO3 Server Side Stack For Ext Direct==

===What Is Ext Direct?===

"Ext Direct is a platform and language agnostic technology to remote server-side methods to
the client-side. Furthermore, Ext Direct allows for seamless communication between the
client-side of an Ext application and any server-side platform."
Source: http://www.extjs.com/products/extjs/direct.php

This means that you doesn't need to care about the complexity of the call itself, the request
information's like the URL and other boring stuff. It's just like calling a simple function with
the usual parameters and a callback function. Let's compare the old fashioned way of creating
a server-side request in mooTools and with Ext Direct to demonstrate this concept.

'''mooTools Request'''
  var req = new Request({
  	method: 'get',
  	url: 'ajax.php?ajaxID=TYPO3_Backend_MyModule_doSomething&parameter1=someValue',
  	data: { 'do' : '1' },
  	onComplete: function(response) {
  		alert(response);
  	}
  }).send();

'''Ext Direct Request'''
  TYPO3.Backend.MyModule.doSomething('someValue', function(response) {
  	alert(response);
  });

The [http://www.extjs.com ExtJS] developers are already offering a bunch of implementations for
different server-side environments. In particular there are some implementations for PHP, but
none of them could be used in TYPO3 without any additional work.

The first integration work has begun at the [http://t3uxw09.typo3.org/home/ T3UXW09] within
the team 4 as a prerequisite of the new page tree. At the mid of January 2010 the Ext Direct
integration was polished and updated for the core as one of the first results from the T3UXW09.

As we can read on the [http://www.extjs.com/products/extjs/direct.php Ext Direct] web page itself,
there are a lot of optional features that could be implemented by the server-side stack. Our recent
version works asynchronous with a programmatic configuration and a small set of additional features.
Any more enhanced could be implemented in the future by demand. But let's continue the description
of this details inside the next section.

===How Was The Server Side Stack Of TYPO3 Implemented?===

An Ext Direct server-side stack consists of three parts. Let's discuss one after another...

 * Configuration of the client-side components
 * Generator of the client-side descriptors
 * Router that dispatches the incoming calls to the configured classes/methods

====The Configuration====

This part of the stack is needed to define the classes with their methods that should
be declared as client-side components. The configuration is an usual array that is processed
at the next level of the stack into a javascript object for Ext Direct.

An configuration entry consists of a key and value pair. The key contains the javascript object
name that is used on the client-side and the value holds a reference to a php class file. The
name or location of this class doesn't plays a role on the client-side. It's more or less nothing
more than a simple container. The following example shows an configuration entry that could be
used inside an extension. Any configuration entries for the TYPO3 backend can be usually found
inside the file ''t3lib/config_default.php''.

'''TYPO3.Backend'''
  $GLOBALS['TYPO3_CONF_VARS']['BE']['ExtDirect']['TYPO3.Backend.MyModule'] =
  	't3lib/extjs/class.tx_t3lib_extjs_myModule.php:t3lib_ExtJs_MyModule';

====The API Generator====

The API generator processes the previously explained configuration array into a
javascript object for Ext Direct, that on the other hand creates the client-side stubs. Because
we only declared the class references, our API generator must use some reflection mechanisms to
retrieve the methods with their parameters. The generator is executed by an TYPO3 Ajax request.

'''Call Of The API Generator'''
  'ajax.php?ajaxID=ExtDirect::getAPI&namespace=TYPO3.Backend'

As you can see, the API generator accepts a GET parameter named ''namespace''. This parameter
is used to determine the parts of the configuration array, that should be applied as components to
Ext Direct. This means that any configuration entry, that begins with the given namespace inside
it's javascript object name will be processed.

By default, we a are requesting the TYPO3 namespace at each loading of the TYPO3 backend. So each
extension author just needs to add it's additional class references to the configuration array and
he can use the methods in his javascript code.

Afterwards the generated API configuration will be added to the Ext Direct API as additional
component providers. To be sure that the code is executed after the API generator, we are doing
this after the onReady event was thrown.

  $pageRenderer->addExtOnReadyCode(
  	'for (var api in Ext.app.ExtDirectAPI) {
  		Ext.Direct.addProvider(Ext.app.ExtDirectAPI[api]);
  	}',
  	TRUE
  );

====The Router====

The router dispatches the incoming calls from the client-side back to the methods
inside the configured classes.

'''client-side example from above'''
  TYPO3.Backend.MyModule.doSomething('someValue', function(response) {
  	alert(response);
  });

'''server-side equivalent'''
  class t3lib_ExtJs_MyModule {
  	public function doSomething() {
  		return 'Hello!';
  	}
  }

As you can see, the class isn't used at the client-side call. Instead we are
using the defined javascript object name that was introduced in the configuration array.

===How Can I Use Ext Direct In An Own Extension?===

Finally, let's talk about the integration of own components to Ext Direct. You can find
the mentioned demo extension attached at the [http://bugs.typo3.org/view.php?id=13313 RFC] inside
the TYPO3 bugtracker.

At the beginning we need to add our javascript object name / class reference pairs, that should
be used on the client-side. We can do that inside the ext_localconf.php.

'''ext_localconf.php'''
  [...]
  $GLOBALS['TYPO3_CONF_VARS']['BE']['ExtDirect']['TYPO3.Demo.Test'] =
  	'typo3conf/ext/extdirecttest/class.tx_extdirecttest_test.php:tx_ExtDirectTest_test';

  $GLOBALS['TYPO3_CONF_VARS']['typo3/backend.php']['additionalBackendItems'][] =
  	t3lib_extMgm::extPath('extdirecttest', 'backend_ext.php');
  [...]

As you can see, we also have registered an additional backend item that creates and injects
our javascript code into the TYPO3 backend. Also we have named our javascript object
''TYPO3.Demo'' and not ''TYPO3.Backend'' like it should be normally done. Because that,
we need to call the API generator ourself with the TYPO3.Demo namespace.

The following example demonstrates, how you can call the API generator yourself with an
other namespace than ''TYPO3.Backend'' and how to call your own component on the client-side.

'''backend_ext.php'''
  <?php
  if (is_object($TYPO3backend)) {
  	// calling the API generator with the TYPO3.Demo namespace
  	$pageRenderer = $GLOBALS['TBE_TEMPLATE']->getPageRenderer();
  	$pageRenderer->addJsFile('ajax.php?ajaxID=ExtDirect::getAPI&namespace=TYPO3.Demo');

  	// calling of our own method on the client-side
  	$pageRenderer->addExtOnReadyCode('
  		TYPO3.Demo.Test.concatenateStrings("Hello", "World!", function(result) {
  			if (typeof console == "object") {
  				console.log(result);
  			} else {
  				alert(result);
  			}
  		});
  	');
  }
  ?>

The executed method on the client-side will be routed to the registered class of the following
example code. That's all that you must know about the usage of the TYPO3 server side stack
of the Ext Direct API in your own extension.

'''class.tx_extdirecttest_test.php'''
  [...]
  class tx_ExtDirectTest_test {
  	public function concatenateStrings($string1, $string2) {
  		return $string1 . ' ' . $string2;
  	}
  }
  [...]