TYPO3 Core

==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;

}

}

[...]