0 user Sign-in to change your status

A plugin to allow PHP controls to be painted as html output in a template. Attaching client events to these controls produces unobtrusive javascript, which allows client controls to handle events in the browser and/or post data back to callback functions on the server. Upon processing the data, the server generates an automatic javascript response for any changes made to controls on the page. JavaScript Forms

• Repository
• Download package
• Browse source

Developers

Name	Status	Email
Todd MARTIN	lead	moc.liamg <<ta>> zn.nitram.ddot

License

Copyright (c) 2008 Todd Martin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Releases for sf 1.1

Releases for sf 1.0

Join this plugin team

Other releases

Release 1.1.1 - 17/03/2009

Release 1.1.0 - 31/10/2008

Release 1.0.2 - 23/10/2008

Release 1.0.1 - 07/08/2008

Release 1.0.0 - 07/08/2008

tmVisualControlsPlugin

Overview

This plugin is an alternative to the widgets and form objects provided in the Symfony framework. These visual controls wrap Symfony form helpers, so they can be painted in a template, and permit client/server event driven programming. In the particular case where an ajax event is attached to a control, the auto-generated javascript event handler posts data back to the server, where it is handled by a user-defined PHP callback function.

The plugin utilises a mediator design pattern, where event handlers are defined in the mediator class and are attached to controls as events. A control can be associated with only one mediator, so that each control obtains a unique id with respect to the web page. The complete behaviour of a web page is handled by the web page manager (a singleton design pattern), which stores each mediator in the session for a stateful response to browser events.

The objective of this plugin is to enable the developer to focus on writing PHP event handlers which interact with the model objects of the application, rather than creating disjointed partial templates to support ajax actions. Hopefully others will be inspired to add their own controls to the plugin, by extending and customising the existing class structure.

Javascript patch

In symfony 1.0, this plugin requires json.js to work. However, json.js causes a problem with prototype 1.5.0, unless you add a conditional statement at line 915 in prototype.js as follows

     for (var name in headers)
+      if (typeof headers[name] != 'function')
       this.transport.setRequestHeader(name, headers[name]);

Installation

To install the plugin for a symfony project, the usual process is to use the symfony command line:

$ php symfony plugin:install tmVisualControlsPlugin

or for symfony 1.0.x

$ php symfony plugin-install http://plugins.symfony-project.com/tmVisualControlsPlugin

Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory.

• Enable the tmAjax module in your settings.yml

    all:
      .settings:
        enabled_modules:      [tmAjax](default,)
  

• Enable the visual controls filter in filters.yml

    # generally, you will want to insert your own filters here
    visualcontrols:
      class: tmVisualControlsFilter
  

• Clear the cache

    symfony cc
  

• Optionally add the following rule to routing.yml

  tm_visual_controls_ajax:
    url: /ajax
    param: {module: tmAjax, action: callback} 
  

  You can customize the url parameter of the route. The default route is automatically registered by the plugin, when the tmAjax module is enabled.

• Customise some script and session variables in app.yml (optional)

  all:
    tm_visual_controls_plugin:
      file: %sEventHandler.php
      namespace : visual/controls/plugin
      ajax_function: handleAjaxEvent          
  

• You're done. Now you can play with some examples.

Examples

These examples utilise the tmButton control, but you can experiment with the other controls found in lib/controls/tmStandard.php and lib/controls/tmExtended.php. The paint() method permits a control's html to be output anywhere in a template in a similar manner to a helper function.

Simple Example

Let's try a simple client side "hello world" example, where a message box is displayed when the user clicks a button. Firstly create a simple module and an example action. Then put the following code in the exampleSuccess.php template :

    <?php
      $manager=tmWebPageManager::getInstance();
      $mediator=new tmWebMediator('main',$manager);
      $button=new tmButton('button_one',$mediator,'click here');

      $onClick=new tmJavascriptEvent(tmEventType::CLICK,new tmMessageFunction($manager,'"Hello World"'));
      $button->attachEvent($onClick);
      echo $button->paint();

View the page in your favourite web browser and click the button, to display the "Hello World" message.

Ajax Example

The example above can be altered to make the button call back to the server. In this case we create an ajax event, which requires a callback function. Change the code in the exampleSuccess template to match that shown below.

    <?php
      $manager=tmWebPageManager::getInstance();
      $mediator=new tmWebMediator('main',$manager);
      $button=new tmButton('button_one',$mediator,'click here');

      $onClick=new tmAjaxEvent(tmEventType::CLICK,$manager,'handleClick');
      $button->attachEvent($onClick);
      echo $button->paint();

Next create the file /modules/simple/lib/exampleEventHandler.php to define the callback function handleClick.

    <?php
      function handleClick($ASender, &$AParameterArray)
      {     
        srand(microtime(true) * 1E6);      
        $red = rand(0, 255);
        $green = rand(0, 255);
        $blue = rand(0, 255);  
        $ASender->setStyle('background-color',sprintf('#%X%X%X',$red,$green,$blue));  
      }

So, by introducing an ajax event and implementing the callback function, you've created a working client/server application that randomly changes the button's colour when clicked.

There's nothing to stop you attaching both the first javascript event and the second ajax event to the button at the same time. Try it!

TODO

• connect controls to model object properties

Changelog

===1.1.1===

• Allowed an image control to accept a raw source path
• Implemented extended javascript controls for date/time selectors.
• Updated javascript syntax for prototype 1.6
• Added methods to set datetime selector value as an array.
• Browser control is now accessed by special $C function.
• Converted defined constants to class constants.
• Simplified mediator responseText() operation, by moving logic to ajax action.
• Removed ability to find another control from tmWebControl
• Added the control class tmTextBlock for error messages
• tmDataControlInterface::setValue() takes an additional parameter for synchronization.
• Moved validation exception handling into mediator->validate() and added control->validate().
• Passed parameter array by reference to control->dispatch().
• Modified javascript events to always add them to the web page scripts.
• Simplified javascript functions invocation() and definition().
• Removed ajax script from controls and made the mediator responsible instead.
• Introduced validation event handlers.
• Added post and get options for ajax events.
• Introduced label and error text panels attached to data controls.
• Removed array parameters from javascript functions
• Refactored common features between javascript functions and javascript objects into parent class
• Changes to separate client javascript events from server event handlers
• Simplified abstract page manager and passed all session storage handling to web page manager
• The filter now removes session mediator/control data from the page, if the referer has changed, before processing the current view

1.1.0

• Remove dependence on json.php
• Allow image control to output raw url as source
• Ajax events need hard coded lib directory. Ajax routing now configured by router onload event.
• Branch from 1.0.2