Prev: Introduction | Up

Usage¶

This section should give a short overview about how to set up a GUI that uses ExtDirect.

Provide the initial markup for your plugin/module¶

First of all you have to render a HTML markup including your JavaScript files. Therefore you need a fluid based view that may look like this (taken from MvcExtjsSamples):

{namespace ext=Tx_MvcExtjs_ViewHelpers}
<ext:Be.moduleContainer
    pageTitle="Sample Module" 
    loadExtJs="true" 
    loadExtJsTheme="true">
    <!-- load needed CSS Files -->
    <ext:includeCssFile name="module.css" />
    <ext:includeCssFile name="roweditor.css" />
    <ext:includeCssFile name="flashmessages.css" />
    <!-- load needed JS Files -->
    <ext:includeJsFile name="ux.TYPO3.MvcExtjs.UriBuilder.js" extKey="mvc_extjs" />
    <ext:includeJsFile name="ux.TYPO3.MvcExtjs.DirectFlashMessageDispatcher.js" extKey="mvc_extjs" />

    <ext:includeJsFile name="RowEditor.js" />
    <ext:includeJsFile name="DirectProxyPatch.js" />

    <ext:includeJsFolder name="Movie/" />
    <ext:includeJsFolder name="Genre/" />

    <ext:includeJsFile name="Module/FlashMessageOverlayContainer.js" />
    <ext:includeJsFile name="Module/Application.js" />

    <ext:ExtDirectProvider
        name="descriptor" 
        namespace="Ext.ux.TYPO3.MvcExtjsSamples.Remote" 
        cache="false" />
    <!-- create inline JS based on the Domain Model Definitions -->
    <ext:includeExtOnReadyFromFile name="Module/ExtOnReady.js" />
</ext:Be.moduleContainer>

Let's have a closer look at the used ViewHelpers.

• Be.moduleContainer This ViewHelper works like the fluid ViewHelper Tx_Fluid_ViewHelpers_Be_ContainerViewHelper - it uses the t3lib_pagerenderer under the hood to provide the whole markup. There is also a container for the FE, that uses the same approach called Fe.pluginContainer. Inside this ViewHelper you can call several other ViewHelper to add e.g. JS or CSS files.
• includeCssFile Includes a CSS file by default located in your EXT inside Resources/Public/JavaScript. Use the parameters extKey and pathInsideExt to change the source folder.
• includeJsFile Includes a JavaScript file by default located in your EXT inside Resources/Public/JavaScript. Use the parameters extKey and pathInsideExt to change the source folder.
• includeJsFolder Includes all JavaScript files located in the given folder. The default path behaves like the other ViewHelpers that add files to the markup. Use the parameter recursive to include a whole folder structure.
• ExtDirectProvider Renders and registers a ExtDirect descriptor based on your module/plugin configuration. You need this to execute your remote calls.
• includeExtOnReadyFromFile Includes js code from a file and adds it to the inline Ext.onReady function written by the t3lib_pagerenderer.

For more informations related to the ViewHelpers have a look at the source code. They normally do not provide much code and should be readable.

Write a action that should be called by ExtDirect.¶

Now you normally want to call a remote action from within your JavaScript layer using ExtDirect.

Therefore you need a Controller the extends Tx_MvcExtjs_MVC_Controller_ExtDirectActionController. If you don't want to extend it for any reason use the following code in your Controller:

/**
     * Initializes the View to be a Tx_MvcExtjs_ExtDirect_View that renders json without Template Files.
     * 
     * @return void
     */
    public function initializeView() {
        if ($this->request->getFormat() === 'extdirect') {
            $this->view = $this->objectManager->create('Tx_MvcExtjs_MVC_View_ExtDirectView');
            $this->view->setControllerContext($this->controllerContext);
        }
    }

Note: Each ExtDirect call sends the parameter Tx_MvcExtjs_ExtDirectRequest=1, that indicates the RequestHandler to handle the Request. The format is set to 'extdirect' inside the RequestHandler stack. The additional parameter is added in the ExtDirectProviderViewHelper.

The View instance has to be changed, because the RequestHandler likes to render the PHP based JSON after the request is processed instead of rendering a fluid based view file.

The controller may look like this:

class Tx_MyExt_Controller_FooController extends Tx_MvcExtjs_MVC_Controller_ExtDirectActionController {

/**
     * Does something with a FooBar.
     * 
     * @param Tx_MyExt_Domain_Model_FooBar $fooBar
     * @return string JSON output
     * @dontverifyrequesthash
     */
    public function barAction(Tx_MyExt_Domain_Model_FooBar $fooBar) {
        $this->view->setVariablesToRender(array('data', 'success'));
        $this->view->setConfiguration(array(
            'data' =>  array(
                    '_exposeObjectIdentifier' => TRUE,
                    '_only' => array('name')
                )
        ));

        // do bar with your model

        $this->view->assign('success',TRUE);
        $this->view->assign('data',$fooBar);
    }

}

Our FooController provides a barAction that does something with a given FooBar object. What kind of object is reconstructed is provided by the annotation like in normal actions. in addition you have to annotate the action with @dontverifyrequesthash as the HMAC is not supported by MvcExtjs.

The output is handled by the special view. You have to tell which variables should be rendered and how they should be rendered in JSON. A inline comment follows, that describes how to configure the output:

/**
     * The rendering configuration for this JSON view which
     * determines which properties of each variable to render.
     *
     * The configuration array must have the following structure:
     *
     * Example 1:
     *
     * array(
     *        'variable1' => array(
     *            '_only' => array('property1', 'property2', ...)
     *        ),
     *        'variable2' => array(
     *             '_exclude' => array('property3', 'property4, ...)
     *        ),
     *        'variable3' => array(
     *            '_exclude' => array('secretTitle'),
     *            '_descend' => array(
     *                'customer' => array(
     *                    '_only' => array('firstName', 'lastName')
     *                )
     *            )
     *        ),
     *        'somearrayvalue' => array(
     *            '_descendAll' => array(
     *                '_only' => array('property1')
     *            )
     *        )
     * )
     *
     * Of variable1 only property1 and property2 will be included.
     * Of variable2 all properties except property3 and property4
     * are used.
     * Of variable3 all properties except secretTitle are included.
     *
     * If a property value is an array or object, it is not included
     * by default. If, however, such a property is listed in a "_descend" 
     * section, the renderer will descend into this sub structure and
     * include all its properties (of the next level).
     *
     * The configuration of each property in "_descend" has the same syntax
     * like at the top level. Therefore - theoretically - infinitely nested
     * structures can be configured.
     *
     * To export indexed arrays the "_descendAll" section can be used to
     * include all array keys for the output. The configuration inside a
     * "_descendAll" will be applied to each array element.
     *
     * @var array
     */

After that is done the usual action stuff happens - do something and assign variables to the view.

In ExtJS you can execute the action like this, if you have published the ExtDirect descriptor like above:

uid = 4
fooBar = {'__identity': uid}
Ext.ux.TYPO3.MvcExtjsSamples.Remote.FooController.barAction(fooBar, function(provider, response) {
  // callback
});

Prev: Introduction | Up