EXT: extbase_ajax¶

What does it do?¶

This extension provides an easy and unified way to call Extbase controller actions via AJAX and render the Fluid forms in modal dialog boxes. Simple procedures to invoke modal dialog boxes, modal message boxes (replacing javascript alert's) and automatic redirects are included as well.

This is the first release of the extension uploaded to TER. We are using it in various extbase based extensions alongside with fed. You will need to have jQuery loaded. The extension checks by itself, if the required Version and plugins are available.

Example¶

When editing a domain object, this will be done usually in a fluid form. Most users require that this editing process will take place in a “modal” window, that can be handled like an ordinary application window like the one below:

Of course this can be realized by using the dialog() plugin of jQuery, but putting it alltogether will be an annoying task,especially, when you want to easily update elements already present on screen.

The extension gives you the ability to convert any element in your fluid template to a jQuery button, which will automatically call either a modal dialog, a modal message box, a modal confirmation box or a redirect to another page which can be opened in a new window as well.

In order to keep the things as fast as possible, all these functions are delegated to jQuery directly. There are no viewhelpers at this stage of development, but everything can be controlled by attributes added to the respective element.

How does it work?¶

  <img
             class="modalDialog"
             src="EXT:.../edit.png"
alt=""
title="Your title"
extbaseajax=”
     action: 'ajaxEdit',
     controller: 'Appointment',
     appointment: {appointment.uid}”
savetext=”Save”
closetext=”Cancel”
     />

  <img
             class="modalConfirm"
src="EXT:.../delete.png"
alt=""
title="Your title"
extbaseajax=”
     action: 'ajaxDelete',
     controller: 'Appointment',
     appointment: {appointment.uid}”
text=”Delete appointment?”
confirm=”Yes”
cancel=”Cancel”
onconfirm=”$('#appointmentRow{appointment.uid}').fadeOut()”
     />

Minimum requirements¶

For a quick start download and install t3jquery from the TER. Choose version Select the jQuery core, the dialog and the button widget as well as the fade effect. All other settings are optional (at least for extbase_ajax).

Next download and install extbase_jquery. Don't forget to include the static template. Otherwise you will not be able to use the constant editor.

In the constant editor you may leave all settings at the default values. If you are using extbase_ajax with only one extension you should set the following parameters:

pageType = 112233
extensionName = yourextensionname
pluginname = ajax

Please change yourextensionname to the name of your extension listed in the ext_amconf.php file. The name is without the tx_ and just lowercase. Keep this in mind. When the plugin does not work correctly you will have specified the wrong extension name here.

Set the page type to your needs. The default value is 112233.

Configuring your extension¶

Edit the ext_localconf.php file of your extension in the following way: Add a code snippet (preferably at the end of the controller/action definitions generated by the extension builder) of the following form:

Tx_Extbase_Utility_Extension::configurePlugin(
        $_EXTKEY,
        'Ajax',
        array(
                'Controller' =>  'ajaxEdit, ajaxUpdate, ajaxNew, ajaxCreate, … ',
                'Othercontroller' => 'ajaxEdit, ajaxUpdate, ajaxNew, ajaxCreate, … ',
        ),
        array(
                'Controller' =>  'ajaxEdit, ajaxUpdate, ajaxNew, ajaxCreate, … ',
                'Othercontroller' => 'ajaxEdit, ajaxUpdate, ajaxNew, ajaxCreate, … ',
        )
);

Please do not forget to clear the caches after changing ext_localconf.php.

The pluginname 'Ajax' must match the pluginname in the constants setting. Please note that the pluginname has to be in upper camel case in the ext_localconf.php but in lowercase in the the constants section.

The important thing is that you add the actions in the respective controller of the object. The typoscript will automatically take care of the page type and send your AJAX request to the correct controller.

I recommend to call the controllers that will be called by AJAX requests in the form ajaxEdit or ajaxUpdate, but this is not a must of course. Actually it is possible to use the same controllers for AJAX and non-AJAX calls at the same time, because all the header code will be disabled automatically. But in most cases you will refrain from non-AJAX calls anyway.

Configuring the Templates¶

Ordinary actions will return a rendered view in most cases. Using the extbase_ajax extension divides the actions mainly in two groups:

• actions that render a form (or any other fluid view, usually ajaxNew or ajaxEdit )
• actions that return the result of the from processing (usually ajaxCreate or ajaxUpdate )

return json_encode(array('success' => 'ok'));

$result = array(
        'success' => 'ok',
        'lastName345' => 'Last name',
        'firstname345' => 'First name',
);
return json_encode($result);

Modal Dialog¶

The modal dialog is the main feature of extbase_ajax. The subsequent functions are implemented mainly to complete the whole system.

The modal dialog feature requires the following elements:

• Any tag in your template provided with a setting class=”modalDialog”
• Add an attribute extbaseajax (described below)
• Add additional attributes for buttons, title and so on

A typical (plain img tag) will look the following way:

  <img
             class="modalDialog"
             src="EXT:.../edit.png"
alt=""
title="Your title"
extbaseajax=”
     action: 'ajaxEdit',
     controller: 'Appointment',
     appointment: {appointment.uid}”
savetext=”Save”
closetext=”Cancel”
     />

The important attributes are

• extbaseajax
• savetext
• closetext

Additional attributes will be

• onshow
• onsave
• beforesave

The callback functions provided in onsave will be executed only if the save button is pressed and if the result contains the value 'success' => 'ok'.

Modal Confirm¶

The modal confirm is another feature of extbase_ajax.

The modal confirm box feature requires the following elements:

• Any tag in your template provided with a setting class=”modalConfirm”
• Add an attribute extbaseajax (described below)
• Add additional attributes for buttons, title and so on

A typical (plain img tag) will look the following way:

  <img
             class="modalConfirm"
             src="EXT:.../edit.png"
alt=""
title="Your title"
extbaseajax=”
     action: 'ajaxDelete',
     controller: 'Appointment',
     appointment: {appointment.uid}”
confirm=”Delete”
cancel=”Cancel”
onconfirm=”$('#appointment{appointment.uid}'.fadeOut();)
     />

The important attributes are

• extbaseajax
• confirm
• cancel

Additional attributes will be

onconfirm

The callback functions provided in onsave will be executed only if the save button is pressed and if the result contains the value 'success' => 'ok'.

Modal Message¶

The modal message is very simple to control. Normally the modal message will be invoked to call a message box instead of javascript alert(). Please remember that calling a javascript alert() is different to invoking the modalMessage function.

It is actually not possible to open a modal alert box other than alert(). The reason is that javascript can't be stopped without disabling the whole page. The workaround is to block the user interface and open a dialog window that will unblock the UI when you press the OK button.

Under normal circumstances you probably won't invoke the modalMessage explicitly.

<span
      class = "modalMessage clickable"
        extbaseajax = "
                controller: 'Project',
              action: 'showSingle',
               project: {project.uid}"
        title = "Projekt”>
Show Project
</span>

Auto Redirect¶

The auto redirect autogenerates a link the will either redirect to a page or open a new window. This is very useful when displaying previews for pages to be printed. In this case the page will be rendered with its own page header settings in a fresh window or tab.

The content is fetched in the same way via AJAX call.

Prepare your own extension¶

Since extbase_ajax does make sense only if you are programming your own extbase based extension, you should hav one right at hand to test it. The final step will lead you to certain changes in your own templates in order to test it.

Get a copy of jQuery or install t3jquery¶

You must have a working copy of jQuery. jQuery is not part of the extension. If you want to use t3jquery (as we do) you can generate the jQuery library directly from the backend.

Install extbase_ajax¶

Install the extension extbase_ajax.

After installing extbase_ajax be sure to have the static template added to your root page template. The static template is called AJAX for Extbase (extbase_ajax) . Please have a look at the setup.txt file for more information of the values inside the configuration. This will be important when changing the jQuery theme, for instance.

Clear the cache and go to the constant editor.The most important sections to change are:

Edit the ext_localconf.php of your extension¶

Locate the call to the method configurePlugin in this file and make a similar entry after the settings that are already there (possibly auto-inserted by extension_builder)in the form:

Tx_Extbase_Utility_Extension__configurePlugin(
        $_EXTKEY,
        '<Pluginname>',
        array(
                'Controller' => 'action1, action2, …',
                <more Controllers here>,
        ),
        array(
                'Controller' => 'action1, action2, …',
                <more Controllers here>,
        )
);

The <Pluginname> is the name of the plugin as entered in the constant editor. It must be Uppercase and is 'Ajax' when using the default settings.

I recommend to use special controller/action name pairs but you may use the existing controller/action pairs as well. If you have an extension with a main aggregate object order and standard actions (list, show, …) you can address these controller with the following setting:

Tx_Extbase_Utility_Extension__configurePlugin(
        $_EXTKEY,
        'Ajax',
        array(
                'Order' => 'edit, new, create, delete',
        ),
        array(
                'Order' => 'edit, new, create, delete',

        )
);

Please note, that you will have to list the actions also in the non- caching part of the configuration array. Please note as well, that the original name of your extension will not appear in this setting.

When you want to hard-wire the settings for the controller, pagetype and pluginname this can be transferred to the setup.txt of your extension as well. In this case you should take care for the order in which the extensions are loaded.

Adjust the HTML-Template¶

As a final step (before testing) you should change one of your templates. If you have a List.html template somewhere in your Resources section try to insert an edit button by changing the normal <f:link.action>...</f:link> to the following code:

<span
        class=”modalDialog”
        extbaseajax=”
                controller: 'Order',
                action: 'edit',
                order: {order.uid}
        “>Edit</span>

You should see an jQuery style edit button in place of the former link. When clicking the button a modal dialog window with your form data should appear.

((generated))¶

FAQ¶

Q: In which cases will this extension be useful for me?

A: If you are writing your own extension based on extbase/fluid and you need the ability to manipulate objects in “modal” dialog windows based on jQuery.

Q: In which cases will this extension not provide any help?

A: If you are not programming your own extension or if you are using the classical way, you won't be able to use this.

Q: Can I use this extension with other extensions based on extbase/fluid?

A: Of course. As long as the extension is configured to serve the special page type you need in your extension there is not any interference to be expected.

Q: Why is the Ferenderingnot supported by viewhelpers?

A: The viewhelpers won't do anything else than parsing the configuration attributes thus renering the correct values. This will cause additional processing to reach the same goals. That's why I did not wrap the settings once more in view helpers. The result will be processed by jQuery anyway.

((generated))¶

0.0.1¶

0.0.0¶