tmVisualControlsPlugin - 1.1.1

Visual Controls Plugin

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

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