[TYPO3-project-formidable] Explaination of events management (repost of prev thread)

[Jerome Schneider]

Events explaination:

There are 3 types of events in formidable : client, server and ajax

Theys are declared on renderlets, and bind to standard javascript events 
on input fields ( like onclick, onmouseover, ... )

Defined like this:

<renderlet:TEXT>
   <onfocus runat="ajax"> <!-- or runat="client" or runat="server" -->
     <userobj>
       <php><![CDATA[

         /* do something here when event is trigerred */

       ]]></php>
     </userobj>
   </onfocus>
</renderlet:TEXT>




CLIENT EVENTS:
--------------

   -> are used when no page refresh nor PHP processing is required to do 
what has to be done ( typically hiding divs in page, but could be a lot 
other things )

   -> are generated as static javascript when the whole HTML is generated

   -> cannot be conditional ( meaning you cannot provide if-conditions 
on wheter to execute task A or task B inside the event when fired )

AJAX EVENTS:
------------
-> requires TYPO3 4.x for it's ajax support thru eID mechanism
-> don't require formidable to refresh the whole page ( meaning a true 
page refresh )
-> are used when :

     1) the things to execute are to complicated to be processed by 
client event only

     OR / AND

     2) you want to execute PHP when event is fired ( like: changing the 
status of something in the database, sending a mail, all you can do with 
PHP actually )

     OR / AND

     3) you may have different tasks executed depending on whatever you 
want ( data in the page, hour of the day, random, you name it ) ; for 
this you can ask the event to fetch data on page, before asking the PHP 
server what to do thru an ajax request, if needed ( params="uid, title, 
..." )





SERVER EVENTS:
--------------
-> are used when the whole page has to be refreshed to process the event
-> typically used to motorize edit buttons, as edition *requires* (for 
now) a page refresh





Let's now have a closer look at what happens when each one of these 
three kinds of event is fired ; imagine a button with an onclick event


CLIENT EVENT: ----------------------------------------------------
You provide a php-userobj to tell Formidable what to do when button 
clicked. This PHP is executed when page is generated, returning an array 
of majix tasks to execute, and resulting JS is statically embeded in the 
page.

Logical scheme:

1 - Formidable reads XML configuration for the button
2 - F. generates the whole collection of majix things to execute as a 
static string of javascript
3 - When clicked, the static JS is executed


SERVER EVENT: ----------------------------------------------------
You provide a php-userobj to tell Formidable what to do when button 
clicked. The PHP is not executed when page is generated. Formidable will 
rather notice that a server event is declared, and will automatically 
attach a tiny piece of JS code (that is, the server-event header) on the 
onclick event for the button. When  the button is clicked, this JS is 
executed, placing data in the POST telling formidable that the 
onclick-event of the button has been fired, and then making the page 
refresh. When PHP receives the POST of the just submitted page, it 
notices that this server event has been thrown, and will then execute 
the attached PHP do what you wanted it to do on button click.

Logical scheme:

1 - Formidable reads XML configuration for the button
2 - F. generates a server-event header ( tiny piece of JS ) and places 
it on our button's onclick event
3 - When clicked, parameters are fetched (if any declared), page 
refreshes and F. executes the PHP code attached to the event fired 
(determined by the sent server-event header)

AJAX EVENT: -------------------------------------------------------
You provide a php-userobj to tell Formidable what to do when button 
clicked. It's a mix of client-event and server event, as it requires no 
page refresh to be processed (like the client event) and still requires 
PHP dynamic execution to process things (like server-event).
Like for the server event, when page is generated, the userobj is not 
executed, but formidable rather notices that an ajax event has been 
declared on the button. And so formidable generates an ajax-event header 
( small piece of javascript ) asking formidable to execute an ajax 
request to the server when the event is fired. When button is clicked, 
ajax request is sent, userobj is executed, and an array of majix tasks 
to execute in the browser are sent back ; kinda like the browser asks 
"This guy clicked the button, what should I do now ?" and the server 
responds "You have to change the value of this, hide this, display this, 
  etc"


Logical scheme:

1 - Formidable reads XML configuration for the button
2 - F. generates an ajax-event header and attach it to the onclick event
3 - When clicked, parameters are fetched (if any declared), and an ajax 
request is sent to the server ( page don't refreshes )
4 - Your PHP-userobj receives the ajax request, inspects the parameters 
(if any) and executes what has to be executed.
5 - If returned by the userobj, the array of majix tasks to execute by 
the browser are sent back thru the ajax request




a lot of things there, but it's quite useful to know it :)
you can experience this at:
http://www.ameos.com/formidable/features/events


Best regards,
Jerome Schneider