blog.barros.ws

Convert lat, lng and zoom values to pixel (x,y) on a map

Carlos Barros — Fri, 06 Mar 2009 12:33:14 +0000

Working on a project this week, that involves Google Maps, I needed to, given a latitude, a longitude and a zoom level, calculate the pixel position (x,y) within the map. If you need to do this using javascript, it’s pretty easy, as GMap API provides a handy method to do this:

var pixel = map.getCurrentMapType().getProjection().fromLatLngToPixel(new GLatLng(10,20),map.getZoom());

Unfortunately, my need was to convert lat, lng and zoom into pixel position from PHP. I “googled” about this subject for a while, and it’s incredible how frequent this need is, and how this information lacks. I saw a lot of people asking for similar things, and also some people that claim that got it working, but without providing any code for this. Googling a bit more I figured out that google uses one thing called Mercator Projection, but even this being a standard, I didn’t find anything that does what I needed. After a lot of time searching about this, I finally stumbled upon a perl script with a set of methods that accomplishes the task. Actually, this perl script is more focused on working with map “tiles”, but there are two methods that does exactly what I needed. It was just a matter of converting these perl methods into php and we’re done.

Here’s the “magic” perl script:

# Calculate tile characteristics given a bounding box of coordinates and a zoom...
# Author. John D. Coryat 01/2008...
# USNaviguide LLC.
# Published under Apache 2.0 license.
# Adapted from: Google Maps API Javascript...
##
# In order to correctly locate objects of interest on a Custom Map Overlay Google Maps, 
# the characteristics of each tile to build are required.
##
# Google_Tiles					# Calculate all tiles for a bounding box and zoom
# Google_Tile_Factors				# Calculate the factors needed ( Zoom, Tilesize )
# Google_Tile_Calc				# Calculate a single tile features from a tile name and zoom
# Google_Tile_to_Pix				# Calculate tile name to pixel
# Google_Coord_to_Pix				# Calculate coordinate to Pixel
# Google_Pix_to_Tile				# Calculate a tile name from a pixel location and zoom
 
require 5.003 ;
package USNaviguide_Google_Tiles ;
use strict ;
use Math::Trig ;
 
BEGIN {
 use Exporter ;
 use vars qw ( $VERSION @ISA @EXPORT) ;
 $VERSION	= 1.0 ;
 @ISA		= qw ( Exporter ) ;
 @EXPORT	= qw ( 
 Google_Tiles
 Google_Tile_Factors
 Google_Tile_Calc
 Google_Tile_to_Pix
 Google_Coord_to_Pix
 Google_Pix_to_Tile
 ) ;
}
 
#
# Call as:  = &Google_Tiles(, , , , , [], []) ;
# Partial/Whole option: (Default: Partial)
#	Partial: Include the edge to create partial tiles
#       Whole: Include only tiles that are contained by the bounds
#
#          Returned Array Specifications:
#            Each element is a reference to a Hash:
#              NAMEY - Tile Name y
#              NAMEX - Tile Name x
#              PYS - Pixel South
#              PXW - Pixel West
#              PYN - Pixel North
#              PXE - Pixel East
#              LATS - South Latitude
#              LNGW - West Longitude
#              LATN - North Latitude
#              LNGE - East Longitude
#
#          Note: X is width, Y is height...
#
 
sub Google_Tiles
{
 my $latS	= shift ;
 my $lngW	= shift ;
 my $latN	= shift ;
 my $lngE	= shift ;
 my $zoom	= shift ;
 my $tileSize	= shift ;
 my $parwho	= shift ;
 my $ty		= 0 ;
 my $tx		= 0 ;
 my @ret	= ( ) ;
 my %first	= ( ) ;				# First Results Hash
 my %last	= ( ) ;				# Last Results Hash
 
 my $value	= &Google_Tile_Factors($zoom, $tileSize) ; # Calculate Tile Factors
 
 if (!defined($parwho) or !$parwho)
 {
  $parwho = 'Partial' ;
 }
 
 # NW: Convert Coordinates to Pixels...
 
 ($first{'NORTH'},$first{'WEST'}) = &Google_Coord_to_Pix( $value, $latN, $lngW ) ;
 
 # Convert Pixels to Tile Name...
 
 ($first{'NAMEY'},$first{'NAMEX'}) = &PixtoTileName( $value, $first{'NORTH'}, $first{'WEST'}, 'N', 'W', $parwho ) ;
 
 # SE: Convert Coordinates to Pixels...
 
 ($last{'SOUTH'},$last{'EAST'}) = &Google_Coord_to_Pix( $value, $latS, $lngE ) ;
 
 # Convert Pixels to Tile Name...
 
 ($last{'NAMEY'},$last{'NAMEX'}) = &PixtoTileName( $value, $last{'SOUTH'}, $last{'EAST'}, 'S', 'E', $parwho ) ;
 
 # Calculate tile values for all tiles...
 
 if ( $first{'NAMEX'} > $last{'NAMEX'} )			# Across the date line
 {
  for ( $ty = $first{'NAMEY'} ; $ty <= $last{'NAMEY'} ; $ty++ )
  {
   for ( $tx = $first{'NAMEX'} ; $tx <= $$value{'max'} ; $tx++ )
   {
    push( @ret, {&Google_Tile_Calc( $value, $ty, $tx)} ) ;
   }
   for ( $tx = 0 ; $tx <= $last{'NAMEX'} ; $tx++ )
   {
    push( @ret, {&Google_Tile_Calc( $value, $ty, $tx)} ) ;
   }
  }
 } else
 {
  for ( $ty = $first{'NAMEY'} ; $ty <= $last{'NAMEY'} ; $ty++ )
  {
   for ( $tx = $first{'NAMEX'} ; $tx <= $last{'NAMEX'} ; $tx++ )
   {
    push( @ret, {&Google_Tile_Calc( $value, $ty, $tx)} ) ;
   }
  }
 }
 
 $ret[0]{'NORTH'} = $first{'NORTH'} ;
 $ret[0]{'WEST'} = $first{'WEST'} ;
 
 $ret[$#ret]{'SOUTH'} = $last{'SOUTH'} ;
 $ret[$#ret]{'EAST'} = $last{'EAST'} ;
 
 return ( @ret ) ;
}
 
# Calculate Tile Factors...
 
sub Google_Tile_Factors
{
 my $zoom	= shift ;
 my $tileSize	= shift ;
 my %value	= ( ) ;
 
 # Validate and correct input parameters...
 
 if ( !defined($zoom) or $zoom < 0 )
 {
  $zoom	= 0 ;
 }
 
 if ( !defined($tileSize) or !$tileSize )
 {
  $tileSize	= 256 ;
 }
 
 # Calculate Values...
 
 $value{'zoom'}	= $zoom ;
 $value{'PI'}	= 3.1415926536 ;
 $value{'bc'}	= 2 * $value{'PI'} ;
 $value{'Wa'}	= $value{'PI'} / 180 ;
 $value{'cp'}	= 2 ** ($value{'zoom'} + 8) ;
 $value{'max'}	= (2 ** $value{'zoom'}) - 1 ;		# Maximum Tile Number
 $value{'pixLngDeg'}= $value{'cp'} / 360;
 $value{'pixLngRad'}= $value{'cp'} / $value{'bc'} ;
 $value{'bmO'}	= $value{'cp'} / 2 ;
 $value{'tileSize'} = $tileSize ;
 
 return \%value ;
}
 
# Calculate tile values from Name...
 
sub Google_Tile_Calc
{
 my %result	= ( ) ;
 my $value	= shift ;
 $result{'NAMEY'} = shift ;
 $result{'NAMEX'} = shift ;
 
 # Convert Tile Name to Pixels...
 
 ($result{'PYN'},$result{'PXW'}) = &Google_Tile_to_Pix( $value, $result{'NAMEY'}, $result{'NAMEX'} ) ;
 
 # Convert Pixels to Coordinates (Upper Left Corner)...
 
 ($result{'LATN'},$result{'LNGW'}) = &PixtoCoordinate( $value, $result{'PYN'}, $result{'PXW'} ) ;
 
 $result{'PYS'} = $result{'PYN'} + 255 ;
 $result{'PXE'} = $result{'PXW'} + 255 ;
 
 # Convert Pixels to Coordinates (Lower Right Corner)...
 
 ($result{'LATS'},$result{'LNGE'}) = &PixtoCoordinate( $value, $result{'PYS'}, $result{'PXE'} ) ;
 
 return %result ;
}
 
# Calculate a tile name from a pixel location and zoom...
 
sub Google_Pix_to_Tile
{
 my $value	= shift ;
 my $ty		= shift ;
 my $tx		= shift ;
 
 # Convert Pixels to Tile Name...
 
 ($ty,$tx) = &PixtoTileName( $value, $ty, $tx, 'N', 'W', 'Partial' ) ;
 
 return ( $ty,$tx ) ;
}
 
# Translate a coordinate to a pixel location...
 
sub Google_Coord_to_Pix
{
 my $value	= shift ;
 my $lat	= shift ;
 my $lng	= shift ;
 my @d		= ( ) ; 
 my $e		= 0 ;
 
 $d[1] = sprintf("%0.0f", $$value{'bmO'} + $lng * $$value{'pixLngDeg'} ) ;
 
 $e = sin($lat * $$value{'Wa'}) ;
 
 if( $e > 0.99999 )
 {
  $e = 0.99999 ;
 }
 
 if( $e < -0.99999 )
 {
  $e = -0.99999 ;
 }
 
 $d[0] = sprintf("%0.0f", $$value{'bmO'} + 0.5 * log((1 + $e) / (1 - $e)) * (-1) * $$value{'pixLngRad'} ) ;
 
 return (@d) ;
}
 
# Translate a pixel location to a tile name...
 
sub PixtoTileName
{
 my $value	= shift ;
 my $y		= shift ;
 my $x		= shift ;
 my $yd		= shift ;				# Y Direction: N or S
 my $xd		= shift ;				# X Direction: W or E
 my $parwho	= shift ;				# Partial / Whole
 my $yn		= 0 ;					# Y Name
 my $xn		= 0 ;					# X Name
 
 $yn = int( $y / $$value{'tileSize'} ) ;		# Round Down
 $xn = int( $x / $$value{'tileSize'} ) ;		# Round Down
 
 if ( $parwho ne 'Partial' )
 {
  if ( $yd eq 'N' )
  {
   $yn++ ;
  } else
  {
   $yn-- ;
  }
  if ( $xd eq 'W' )
  {
   $xn++ ;
  } else
  {
   $xn-- ;
  }
 }
 
 # Make sure tile numbers are sane...
 
 if ( $yn > $$value{'max'} )
 {
  $yn = $$value{'max'} ;
 } elsif ( $yn < 0 )
 {
  $yn = 0 ;
 }
 
 if ( $xn > $$value{'max'} )
 {
  $xn = $$value{'max'} ;
 } elsif ( $xn < 0 )
 {
  $xn = 0 ;
 }
 
 return( $yn, $xn ) ; 
}
 
# Translate a tile name to a pixel location...
 
sub Google_Tile_to_Pix
{
 my $value	= shift ;
 my $y		= shift ;
 my $x		= shift ;
 return( (sprintf("%0.0f", $y * $$value{'tileSize'} ), sprintf("%0.0f", $x * $$value{'tileSize'} )) ) ; 
}
 
# Translate a pixel location to a coordinate...
 
sub PixtoCoordinate
{
 my $value	= shift ;
 my $y		= shift ;
 my $x		= shift ;
 my @d		= ( ) ;
 my $e		= (($y - $$value{'bmO'}) / $$value{'pixLngRad'}) * (-1) ;
 
 $d[1]	= sprintf("%0.6f",($x - $$value{'bmO'}) / $$value{'pixLngDeg'}) ;
 
 $d[0]	= sprintf("%0.6f", (2 * atan(exp($e)) - $$value{'PI'} / 2) / $$value{'Wa'}) ;
 return (@d);
}
 
1;
 
__END__
 
=head1 SYNOPSIS
 
#!/usr/bin/perl -w
# Test Program:
 
# Google Tile Calculator Test Program...
# Author. John D. Coryat 01/2008 USNaviguide LLC
 
use strict;
use USNaviguide_Google_Tiles ;
 
my $latS        = 34.177442 ;
my $lngW        = -91.318359 ;
my $latN        = 35.797300 ;
my $lngE        = -88.681641 ;
my $zoom        = 8 ;
my $x           = '' ;
my %tile        = ( ) ;
my $i           = 0 ;
 
my @d = &Google_Tiles($latS, $lngW, $latN, $lngE, $zoom,0,'Whole');
 
print "Total: " . scalar(@d) . "\n" ;
 
for ( $i = 0; $i <= $#d; $i++ )
{
 print "Tile # $i Y: $d[$i]{'NAMEY'} X: $d[$i]{'NAMEX'}\n" ;
 
 %tile = %{$d[$i]} ;
 
 foreach $x (sort keys %tile)
 {
  print "\t$x: $tile{$x}\n" ;
 }
}
 
=cut

Original link to this code is: http://www.usnaviguide.com/google-tiles.htm

The interesting methods in the script are:

Google_Tile_Factors: This method receives a zoom level and the tile size (256 in google maps) and return an array with some values that are used in next method.
Google_Coord_to_Pix: This method receives the array returned by the previous method, a latitude and a longitude, and will return an array with a (x,y) pair that correspond to the pixel position in the map. Note that it won’t return a pixel position relative to the current view, but relative to the entire map.

What about the PHP version?? Well, unfortunately my code is part of a project and I can’t post it here, but it’s pretty easy to convert these perl methods into PHP (I don’t have ANY experience with perl, and did it in a few minutes).

That’s it, I hope this helps you as it helped me.

Carlos

sfPropelActAsSortableBehaviorPlugin group patch

Carlos Barros — Fri, 20 Feb 2009 14:17:33 +0000

I guess that most Symfony developers should know this Symfony plugin, but for those who not, here’s an small quote:

“The sfPropelActAsSortableBehaviorPlugin is a symfony plugin that provides a new Propel behavior.Model classes with this behavior enabled become sortable, which means that they have new methods to deal with a position attribute.”

This Symfony plugin is really useful as it can save you a lot of code if you need to sort your objects, but in a recent project I worked on, I noticed this plugin lacks one functionality: it can’t handle “sorting groups” within the same object. For instance, suppose you have an Product and Category tables, and that each product belongs to a single category. Then, suppose you want to be able to sort your products so you can control how they show up in your pages. Using sfPropelActAsSortableBehaviorPlugin you can only sort the entire Product table, and that’s not really what we want. We need to be able to sort products within each category.
I guess this problem is really common, and as I had to handle this in a recent project, I decided to write a patch for this plugin, and I’d like to share it. Before one ask me why I didn’t submit it as a official ticket, the reason is that there is already a patch submitted to handle this issue, from almost a year ago, that was not released yet, and I bet most people (including me) is not aware of, so I’m writing this post to tell about this for other users, and maybe make Kris Wallsmith (current leader) release his version, that in fact seem to be more powerful than mine, as it support creating sorting groups using more than one column.

So, how does it work?? sfPropelActAsSortableBehaviorPlugin is really simple to use, all you need is a Integer column in your model, and then activate the new behavior for you class using something like this:

sfPropelBehavior::add('Item', array('act_as_sortable' => array('column' => 'rank')));

After applying this patch, the only thing you need to do is to add one more element to the above array:

sfPropelBehavior::add('Item', array('act_as_sortable' => array('column' => 'rank','group' => 'category_id')));

And that’s it. New sfPropelActAsSortableBehaviorPlugin will use “category_id” as a “sorting group”.

You can now use all methods provided by the new behavior to sort your objects, just like you used to do without the patch. Also, if you don’t have a group category, just omit it from behavior initialization, and it will work as if u didn’t apply this patch.

Find below the full patch:

diff -ur sfPropelActAsSortableBehaviorPlugin-0.6.1/lib/sfPropelActAsSortableBehavior.class.php sfPropelActAsSortableBehaviorPlugin-0.6.1-new/lib/sfPropelActAsSortableBehavior.class.php
--- sfPropelActAsSortableBehaviorPlugin-0.6.1/lib/sfPropelActAsSortableBehavior.class.php	2007-08-07 10:56:57.000000000 -0300
+++ sfPropelActAsSortableBehaviorPlugin-0.6.1-new/lib/sfPropelActAsSortableBehavior.class.php	2009-02-20 10:59:25.000000000 -0300
@@ -21,14 +21,18 @@
    *
    * @return mixed sortable object
    **/
-  public static function retrieveByPosition($peerClass, $position, $con = null)
+  public static function retrieveByPosition($peerClass, $position, $con = null, $group = null)
   {
     $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_column', 'rank');
-    $rankColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $rankColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    $rankColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $rankColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_group');
+    if($groupColumnName) $groupColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $groupColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
     $c = new Criteria;
-    $c->add($rankColumnPhpName, $position);
+    $c->add($rankColumnPhpName, $position);
+    if($groupColumnName) $c->add($groupColumnPhpName, $group);
 
     return call_user_func(array($peerClass, 'doSelectOne'), $c, $con); 
   }
@@ -41,16 +45,26 @@
    *
    * @return integer maximum position
    **/
-  public static function getMaxPosition($peerClass, $con = null)
+  public static function getMaxPosition($peerClass, $con = null, $group = null)
   {
-    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_column', 'rank');
+    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_column', 'rank');
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_group');
+    
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
     $sql = sprintf('SELECT MAX(%s) AS max FROM %s', 
       $rankColumnName,
       constant("$peerClass::TABLE_NAME")
-    ); 
-    $rs = $con->prepareStatement($sql)->executeQuery();
+    ); 
+    
+    if($groupColumnName)
+    {
+    	$sql .= sprintf(" WHERE %s = ?",$groupColumnName);
+    	$stmt = $con->prepareStatement($sql);
+    	$stmt->setString(1,$group);	
+    }
+    else $stmt = $con->prepareStatement($sql);
+    $rs = $stmt->executeQuery();
     $rs->next();
 
     return $rs->getInt('max');
@@ -66,10 +80,13 @@
    *
    * @return array list of sortable objects
    **/
-  public static function doSelectOrderByPosition($peerClass, $order = Criteria::ASC, $criteria = null, $con = null)
+  public static function doSelectOrderByPosition($peerClass, $order = Criteria::ASC, $criteria = null, $con = null, $group = null)
   {
     $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_column', 'rank');
-    $rankColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $rankColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    $rankColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $rankColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.self::getClassFromPeerClass($peerClass).'_group');
+    if($groupColumnName) $groupColumnPhpName = call_user_func(array($peerClass, 'translateFieldName'), $groupColumnName, BasePeer::TYPE_FIELDNAME, BasePeer::TYPE_COLNAME);
+    
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
     if ($criteria === null) 
@@ -90,7 +107,8 @@
     else
     {
       $criteria->addDescendingOrderByColumn($rankColumnPhpName);
-    }
+    }
+    if($groupColumnName) $c->add($groupColumnPhpName,$group);
 
     return call_user_func(array($peerClass, 'doSelect'), $criteria, $con); 
   }
@@ -159,6 +177,32 @@
   public function setPosition($object, $position)
   {
     return $object->setByName(sfConfig::get('propel_behavior_act_as_sortable_'.get_class($object).'_column', 'rank'), $position, BasePeer::TYPE_FIELDNAME);
+  }
+  
+  /**
+   * Gets the group of a sortable object
+   * 
+   * @param mixed sortable object
+   * 
+   * @return mixed group of the sortable object
+   */
+  public function getGroup($object)
+  {
+   	$groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.get_class($object).'_group');
+   	if($groupColumnName) return $object->getByName($groupColumnName, BasePeer::TYPE_FIELDNAME);
+   	else return null;
+  }
+  
+  /**
+   * Sets the group of a sortable object
+   * 
+   * @param mixed sortable object
+   * @param mixed group value
+   */
+  public function setGroup($object, $group)
+  {
+  	$groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.get_class($object).'_group');
+  	if($groupColumnName) return $object->setByName($groupColumnName, $group, BasePeer::TYPE_FIELDNAME);
   }
 
   /**
@@ -170,7 +214,7 @@
    **/
   public function getNext($object)
   {
-    return self::retrieveByPosition(get_class($object).'Peer', self::getPosition($object) + 1);
+    return self::retrieveByPosition(get_class($object).'Peer', self::getPosition($object) + 1, null, self::getGroup($object));
   }
 
   /**
@@ -182,7 +226,7 @@
    **/
   public function getPrevious($object)
   {
-    return self::retrieveByPosition(get_class($object).'Peer', self::getPosition($object) - 1);
+    return self::retrieveByPosition(get_class($object).'Peer', self::getPosition($object) - 1, null, self::getGroup($object));
   }
 
   /**
@@ -206,7 +250,7 @@
    **/    
   public function isLast($object)
   {
-    return self::getPosition($object) == self::getMaxPosition(get_class($object).'Peer');
+    return self::getPosition($object) == self::getMaxPosition(get_class($object).'Peer', null, self::getGroup($object));
   }
 
   /**
@@ -286,31 +330,36 @@
   {
     $class = get_class($object);
     $peerClass = $class.'Peer';
-    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_group');
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
     $oldPosition = self::getPosition($object);
     if ($oldPosition == $newPosition) return $oldPosition;
-
+
     try
     {
       $con->begin();
 
       // Move the object away
-      self::setPosition($object, self::getMaxPosition($peerClass) + 1);
+      self::setPosition($object, self::getMaxPosition($peerClass,null,self::getGroup($object)) + 1);
       $object->save();
 
       // Shift the objects between the old and the new position
-      $query = sprintf('UPDATE %s SET %s = %s %s 1 WHERE %s BETWEEN ? AND ?',
+      $query = sprintf('UPDATE %s SET %s = %s %s 1 WHERE %s BETWEEN ? AND ?%s',
         constant("$peerClass::TABLE_NAME"),
         $rankColumnName,
         $rankColumnName,
         ($oldPosition < $newPosition) ? '-' : '+',
-        $rankColumnName
-      );
+        $rankColumnName,
+        $groupColumnName?" AND $groupColumnName = ?":""
+        
+      );
+      
       $stmt = $con->prepareStatement($query);
       $stmt->setInt(1, min($oldPosition, $newPosition));
-      $stmt->setInt(2, max($oldPosition, $newPosition));
+      $stmt->setInt(2, max($oldPosition, $newPosition));
+      if($groupColumnName) $stmt->setString(3,self::getGroup($object));
       $stmt->executeQuery();
 
       // Move the object back in
@@ -357,9 +406,9 @@
   public function moveToBottom($object, $con = null)
   {
     $class = get_class($object);
-    $peerClass = $class.'Peer';
-
-    return self::moveToPosition($object, self::getMaxPosition($peerClass), $con);
+    $peerClass = $class.'Peer';
+    
+    return self::moveToPosition($object, self::getMaxPosition($peerClass,null,self::getGroup($object)), $con);
   }
 
   /**
@@ -378,7 +427,8 @@
   {
     $class = get_class($object);
     $peerClass = $class.'Peer';
-    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_group');
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
     try
@@ -386,14 +436,16 @@
       $con->begin();
 
       // Shift the objects with a position higher than the given position
-      $query = sprintf('UPDATE %s SET %s = %s + 1 WHERE %s >= ?',
+      $query = sprintf('UPDATE %s SET %s = %s + 1 WHERE %s >= ?%s',
         constant("$peerClass::TABLE_NAME"),
         $rankColumnName,
         $rankColumnName,
-        $rankColumnName
+        $rankColumnName,
+        $groupColumnName?" AND $groupColumnName = ?":""
       );
       $stmt = $con->prepareStatement($query);
-      $stmt->setInt(1, $position);
+      $stmt->setInt(1, $position);
+      if($groupColumnName) $stmt->setString(2,self::getGroup($object));
       $stmt->executeQuery();
 
       // Move the object in the list, at the given position
@@ -427,7 +479,7 @@
     // new records need to be initialized with position = maxPosition +1 unless position is already set
     if(!$object->getId() && !$object->isColumnModified($rankColumnPhpName))
     {
-      self::setPosition($object, self::getMaxPosition($peerClass)+1);
+      self::setPosition($object, self::getMaxPosition($peerClass,null,self::getGroup($object))+1);
     }
   } 
 
@@ -442,17 +494,20 @@
   {  
     $class = get_class($object);
     $peerClass = $class.'Peer';
-    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $rankColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_column', 'rank');
+    $groupColumnName = sfConfig::get('propel_behavior_act_as_sortable_'.$class.'_group');
     if(!$con) $con = Propel::getConnection(constant("$peerClass::DATABASE_NAME"));
 
-    $query = sprintf('UPDATE %s SET %s = %s - 1 WHERE %s > ?',
+    $query = sprintf('UPDATE %s SET %s = %s - 1 WHERE %s > ?%s',
       constant("$peerClass::TABLE_NAME"),
       $rankColumnName,
       $rankColumnName,
-      $rankColumnName
+      $rankColumnName,
+      $groupColumnName?" AND $groupColumnName = ?":""
     );
     $stmt = $con->prepareStatement($query);
-    $stmt->setInt(1, $object->getPosition());
+    $stmt->setInt(1, $object->getPosition());
+    if($groupColumnName) $stmt->setString(2, self::getGroup($object));
     $stmt->executeQuery();
   }
 }

You can also download the patch here.
For those who want to take a look at Kris Wallsmith’s patch, just click here.

This site may harm your computer???

Carlos Barros — Sat, 31 Jan 2009 15:27:45 +0000

Today (actually a few minutes ago), I was googling about some random subjects, when I clicked on a link and got that well known Google anti-phishing page alerting me that the website I was about to view could harm my computer. Well, nothing wrong here so far, BUT…. I went back to Google results I noticed that ALL results was marked as harmful. That was weird, so to be sure, I started a new search for the word Google, and guess what?? I got the same warnings, even for Google pages. This is clearly some guy doing something really wrong at Google. A few minutes (less than 4 minutes) later, the problem was solved, but I had a chance to take some screenshots .. Well, this is an really off-topic and useless post, but this was, at least, funny to witness this!

Using embedFormForEach in Symfony, Part II

Carlos Barros — Thu, 01 Jan 2009 21:58:18 +0000

In my last post I talked about embedFormForEach method, that will embed a form inside another N times, and in the end of that article, I promised a new post on this subject to show how to use it to dynamically add/remove/sort cars, and here it is. As usual, I put live an example here (I integrated this new form on the old city picker form). In this example, when you create (or edit) an user, you will see a new control called Cars, and a green plus icon. If you click that icon, it will add a new “car form” into the user form. You can add as many cars as you want. Each new form has a set of controls that can be used to sort and remove cars from the form. Let’s take a look on how it all works.

Before we start, as this example is integrated into previous city picker system, I recommend that you read it before, and also the previous article on embedFormForEach.

Ok, let’s start with database model:

config/schema.yml:

  cp_users:
    _attributes:     { phpName: User, idMethod: native }
    id:              ~
    name:            { type: varchar(100), required: true }
    country_id:      { type: integer, required: true, foreignTable: cp_countries, foreignReference: id }
    state_id:        { type: integer, required: true, foreignTable: cp_states, foreignReference: id }
    city_id:         { type: integer, required: true, foreignTable: cp_cities, foreignReference: id }
    cars:            { type: longvarchar }
    created_at:      ~
    updated_at:      ~

Only thing I added here was at line 8, a new column where we’ll store cars information. Notice that it’s a single column of longvarchar type, and we’ll save car information as a serialized array. As we’re going to store car information as a serialized array, we need to overwrite getCars and setCars methods to make it do the conversion for us:

lib/model/User.class.php:

	public function setCars($cars,$raw=false)
	{
		if(!$raw) $cars = array_values($cars);
 
		parent::setCars(serialize($cars));
	}
 
	public function getCars()
	{
		return @unserialize(parent::getCars());
	}
 
	public function getNumberOfCars()
	{
		$cars = $this->getCars();
 
		$ncars = 0;
		if(is_array($cars))
		{
			foreach($cars as $k=>$v)
				$ncars = max($ncars,intval($k)+1);
		}
 
		return $ncars;
	}

setCars will receive an array as parameter and serialize it, and getCars will do the opposite, get a string from database and unserialize it into an array. Notice that setCars expects another parameter, called $raw. If this value is false (default), it will rebuild the array keys, to ensure a sequential value. But as you will see later on, there will be one place that it’s not desired, so we need to instruct setCars to not rebuild keys, passing $raw = true. getNumberOfCars, as the name suggests, returns the number of cars the object has. You might wonder why didn’t I just use return count($this->getCars()) for this… This method won’t return the actual number of cars, but the highest key + 1 in the array, and the reason for this will be explained later on.

To receive input from the user, we’re gonna use the CarForm we created in previous article. Notice that it’s exactly the same form:

lib/form/CarForm.class.php:

class CarForm extends sfForm
{
	public function configure()
	{
		$this->setWidgets(array(
			'make'		=> new sfWidgetFormSelect(array('choices'=>array('ferrari'=>'Ferrari','bmw'=>'BMW','porsche'=>'Porsche'))),
			'model'		=> new sfWidgetFormInput(),
		));
 
		$this->setValidators(array(
			'make'		=> new sfValidatorChoice(array('required'=>true,'choices'=>array('ferrari','bmw','porsche'))),
			'model'		=> new sfValidatorString(array('required'=>true),array('required'=>'Please enter model')),
		));
 
		$this->widgetSchema->setLabels(array(
			'make'		=> 'Make:',
			'model'		=> 'Model:',
		));
 
		$this->widgetSchema->setNameFormat('%s');
    	$this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
	}	
}

Again, if you look into previous example, you’ll find another form called CarsForm (plural), that was responsible to get the number of cars user wanted to input. This form won’t be used in this new example, rather, we’ll embed CarForm inside CPUserForm:

lib/form/CPUserForm.class.php:

class CPUserForm extends sfFormPropel
{
  private $ncars = 0;
 
  public function __construct($object = null, $options = array(), $CSRFSecret = null)
  {
  	parent::__construct($object,$options,$CSRFSecret);
 
  	// calculate number of cars
  	$this->ncars = $object->getNumberOfCars();
 
  	// embed cars form
  	if($this->ncars)
  	{
  		$cars_form  = new CarForm();
		$this->embedFormForEach('cars',$cars_form,$this->ncars,'%content%','%content%');
 
  		// set default
  		$this->setDefault('cars',$object->getCars());
  	}
  	else $this->embedForm("cars",new sfForm(),"%content%");  	
  }
 
  public function configure()
  {
  	// build state criteria
  	$stateC = new Criteria();
  	$stateC->add(StatePeer::COUNTRY_ID,$this->getObject()->getCountryId());
 
  	// build city criteria
   	$cityC = new Criteria();
  	$cityC->add(CityPeer::STATE_ID,$this->getObject()->getStateId());
 
    $this->setWidgets(array(
      'name'   			=> new sfWidgetFormInput(),
      'country_id'		=> new sfWidgetFormPropelSelect(array('model'=>'Country','add_empty'=>'-- Country --','order_by'=>array('Name','asc'))),
      'state_id'		=> new sfWidgetFormPropelSelect(array('model'=>'State','add_empty'=>'-- State/Province --','order_by'=>array('Name','asc'),'criteria'=>$stateC)),
      'city_id'			=> new sfWidgetFormPropelSelect(array('model'=>'City','add_empty'=>'-- City --','order_by'=>array('Name','asc'),'criteria'=>$cityC)),
      'id'				=> new sfWidgetFormInputHidden(),
    ));
 
    $this->setValidators(array(
    	'name'			=> new sfValidatorString(
    							array(
    								'trim'		=> true,
    								'required'	=> true,
    							),array(
    								'required'	=> '- Please enter name',
    							)
    					),
    	'country_id'	=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'Country',
    								'column'	=> 'id',
    							),array(
    								'required'	=> '- Please choose country',
    								'invalid'	=> '- Invalid country',
    							)
    					),
    	'state_id'		=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'State',
    								'column'	=> 'id',
    								'criteria'	=> clone $stateC,
    							),array(
    								'required'	=> '- Please choose state',
    								'invalid'	=> '- Invalid state',
    							)
    					),
    	'city_id'		=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'City',
    								'column'	=> 'id',
    								'criteria'	=> clone $cityC,
    							),array(
    								'required'	=> '- Please choose city',
    								'invalid'	=> '- Invalid city',
    							)
    					),
    	'id'			=> new sfValidatorNumber(array('required'=>false)),
    ));
 
	$this->widgetSchema->setLabels(array(
		'name'	=> 'Name',
	));
 
	$this->widgetSchema->setNameFormat('user[%s]');
    $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
  }
 
  public function bind(array $taintedValues = null, array $taintedFiles = null)
  {
  	for($i=0;$i<$this->ncars;$i++)
  	{
  		if(!isset($taintedValues["cars"][$i]))
  		{
  			unset($this->widgetSchema["cars"][$i],$this->validatorSchema["cars"][$i]);
  		}
  	}
 
  	return parent::bind($taintedValues,$taintedFiles);
  }
 
  public function getModelName()
  {
  	return 'User';
  }
}

This form is the same we used in the city picker article, with some new things added in order to handle car form. In fact, configure method is exactly the same. Only __constructor and bind methods were added. Let’s talk about each method:

  private $ncars = 0;
 
  public function __construct($object = null, $options = array(), $CSRFSecret = null)
  {
  	parent::__construct($object,$options,$CSRFSecret);
 
  	// calculate number of cars
  	$this->ncars = $object->getNumberOfCars();
 
  	// embed cars form
  	if($this->ncars)
  	{
  		$cars_form  = new CarForm();
		$this->embedFormForEach('cars',$cars_form,$this->ncars,'%content%','%content%');
 
  		// set default
  		$this->setDefault('cars',$object->getCars());
  	}
  	else $this->embedForm("cars",new sfForm(),"%content%");  	
  }

__constructor is where we actually embed the CarForm into CPUserForm. As we’ll use embedFormForEach, we need to know, beforehand, the number of times we’ll embed the form. To determine this number, we use the getNumberOfCars method, and also, we store resulting value in a private variable ncars, that will be used inside bind method. If any car was defined, we embed CarForm $ncars times, and then set default values, otherwise, we just embed a generic sForm form.

As I talked before, getNumberOfCars is a bit different and the reason is not hard to explain. Every time you use the green plus icon to add a new car form, it will add a new user[cars][N] element, where N is a sequential number, starting from 0. Suppose you add 4 car forms, and then you remove the third one. You would end up with: user[cars][0], user[cars][1], users[cars][3]. You see the gap? We don’t have [2] anymore. In this case, if getNumberOfCars returns 3 (the actuall number of cars), CPUserForm would embed only three CarForm, and user[cars][3] would become invalid, as it would be the forth form. That’s the reason we must return the highest key (plus 1), in ths case, 4. And now is where bind method takes place:

  public function bind(array $taintedValues = null, array $taintedFiles = null)
  {
  	for($i=0;$i<$this->ncars;$i++)
  	{
  		if(!isset($taintedValues["cars"][$i]))
  		{
  			unset($this->widgetSchema["cars"][$i],$this->validatorSchema["cars"][$i]);
  		}
  	}
 
  	return parent::bind($taintedValues,$taintedFiles);
  }

Still using the same scenario (added 4 cars, then removed the third). As I said, we’ll still need to embed four forms in order to make it work, but you might think: in CarForm, make and model are required, wouldn’t it throw an error?? The answer is YES. We embed 4 forms, but supply data only for 3, so it will throw an validation error. To avoid this, we need to implement a conditional validation. Remember on constructor we saved the variable ncars? We’ll use it here to remove removed (uh?) cars. For this, we traverse through cars values, and if we don’t find it, we unset both widget and validator for that index. Doing this, the form won’t try to validate a removed field, and also, will remove the widget from the form, preventing it from appear again.

Ok, what about the actions?

apps/frontend/modules/citypicker/actions/actions.class.php:

  public function executeEdit($request)
  {
  	if($request->getParameter('id')) $user = UserPeer::retrieveByPK($request->getParameter("id"));
  	else $user = new User();
  	$this->forward404Unless($user);
 
  	$this->errors = array();
  	if($request->isMethod('post'))
  	{
  		// pre-populate country, state and city in order to filter select boxes
  		$data = $request->getParameter('user');
  		$user->setCountryId(@$data['country_id']);
  		$user->setStateId(@$data['state_id']);
  		$user->setCityId(@$data['city_id']);
 
  		// check validity
  		if(!$user->getCity() || ($user->getCity()->getStateId() != $user->getStateId())) $user->setCityId(0);
  		if(!$user->getState() || ($user->getState()->getCountryId() != $user->getCountryId())) $user->setStateId(0);
  		if(!$user->getCountry()) $user->setCountryId(0);
 
  		// pre-populate cars so we can get number of cars entered
  		$user->setCars(@$data['cars'],true);
 
  		$this->form = new CPUserForm($user);
  		$this->form->bind($request->getParameter('user'));
  		if($request->getParameter('refresh') != "Y")
  		{
  			if($this->form->isValid())
  			{
  				$this->form->save();
 
  				// if we are handling a Soap request, do NOT redirect
  				if(!$this->isSoapRequest()) return $this->redirect('citypicker/index');
  			}
 
		  	// get errors into array
		  	foreach($this->form->getFormFieldSchema()->getError() as $e)
		  		$this->errors[] = $e;
  		}
  		else
  		{
  			// render city/state/country
  			return $this->renderPartial('address_edit',array('form'=>$this->form));
  		}
  	}
  	else 
  	{
  		$this->form = new CPUserForm($user);
  	}
  }

Again, most code on this action is to handle city picker and was detailed in another article. Only thing that’s related to CarForm is at line 22. Remember we use getNumberOfCars on CPUserForm constructor? So, we need to pre-populate user object we’ll send to the form with received car information, so it can determine beforehand the number of forms it need to embed. Also, we set $raw=true when calling setCars method, in order to preserve keys, or we’ll break the system.

Now only thing that’s missing is the template, where we’ll add all the javascripts needed to make it work.

apps/frontend/modules/citypicker/templates/editSuccess.php:

url_for('citypicker/edit?id='.$form->getObject()->getId()) ?>">
  $form["id"]->render() ?>
   if ($errors): ?>
     endif; ?>
    
  	
    	
    		
    			 foreach ($errors as $error): ?>
					$error ?>
				 endforeach; ?>
    		
    	
    
	
      $form["name"]->renderLabel() ?>
      $form["name"]->render() ?>
    
    
      Address
      
        
        	include_partial('address_edit',array('form'=>$form)) ?>
        
      
    
    
    	
    		Cars
    		url_for('citypicker/addCar') ?>', {parameters: {number: ncars}, asynchronous:true, evalScripts:false, insertion:Insertion.Bottom, onSuccess:function(request, json){ncars++;}});; return false;">
    			image_tag(sfConfig::get('sf_admin_web_dir').'/images/add.png',array('alt'=>'Add new car','border'=>'0')) ?>
    		
    	
    	
    		$form["cars"]->getWidget()->setFormFormatterName('options') ?>
   			$form["cars"] ?>
    	
    
    
      
        
        button_to('cancel','citypicker/index') ?>

Ok, you just need to pay attention on code from line 27 on, everything above it is to handle citypicker (once again)…. In this template, we place the gren plus icon and attach a JavaScript event to it. This JavaScript will request an action using AJAX and will append the result in the fieldset_cars container (the action will result in HTML code). Notice that I didn’t use symfony helper to build this ajax call. The reason is that we need to send to the action current number of cars we have in the form, so it can return correct HTML code (field index), and I didn’t find any means to make it work with the helper, so I wrote the Ajax.Updater by myself. It will request the addCar action, and send value stored in ncars variable as a parameter, and then will increment it on success (so we keep track of how many cars we have). ncars is initialized at line 48, retrieving the number of embedded forms.
Another important detail is at line 35. Here we change the FormatterName for CarForm (I could have set it inside CarForm configure method, but this would break previous example). This new formatter will add sort/remove controls to the form:

lib/widget/sfWidgetFormSchemaFormatterOptions.php:

class sfWidgetFormSchemaFormatterOptions extends sfWidgetFormSchemaFormatter
{
	protected $rowFormat = "";
 
	public function __construct(sfWidgetFormSchema $widgetSchema)
	{
		$this->rowFormat = " 
	
	
		
			Car
		    " href="#" onclick="if($(this).up('table').previous('table')) $(this).up('table').previous('table').insert({before: $(this).up('table')}); return false">".image_tag('sf_admin/uparrow.png',array('border'=>0,'alt'=>'Move up'))."
		    <a title="Move down" href="#" onclick="if($(this).up('table').next('table')) $(this).up('table').next('table').insert({after: $(this).up('table')}); return false">".image_tag('sf_admin/downarrow.png',array('border'=>0,'alt'=>'Move down'))."
			<a title="'Remove this option" href="#" onclick="if(window.confirm('Are you sure you want to remove this option?')) $(this.parentNode.parentNode.parentNode).remove(); return false;">".image_tag(sfConfig::get('sf_admin_web_dir').'/images/delete.png',array('border'=>0,'alt'=>'Remove this option'))."a>
		th>
	tr>
	%field%
	table>";
 
		parent::__construct($widgetSchema);
	}
}

This formatter is a little bit different from normal formatters. Usually we only define a few variables inside the class, but we can’t do this here (well, we can, but we would need to write the s by hand). The reason I defined the variable inside class __constructor is because I’m using image_tag helper to build the string, and we can’t to this when defining a variable in a class. Other than that, it’s a normal formatter, that wraps the form into a set of controls. Remember in setCars method, we rebuild array keys? The reason is explained here.. If you look at the javascript that sort the form, it simply swap the 
 elements, but field indexes will be kept the same. For instance, we have two cars added: user[cars][0] and user[cars][1]. If we swap it, we’ll have: user[cars][1] and user[cars][0]. Also, we can have gaps on the keys, so we need to rebuild the keys.
Ok, the last step now is the addCar action, that’s responsible to add a new form into the CPUserForm when u click the green plus icon:
apps/frontend/modules/citypicker/actions/actions.class.php:




1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  public function executeAddCar($request)
  {
  	$this->forward404unless($request->isXmlHttpRequest());
 
  	// get next number
  	$number = intval($request->getParameter("number"));
 
  	// build widget
  	$form = new CarForm();
  	$widgetSchema = new sfWidgetFormSchemaDecorator(new sfWidgetFormSchema(array(
  		'user[cars]['.$number.']' => new sfWidgetFormSchemaDecorator($form->getWidgetSchema(), "%content%")
  	),array(),array(),array()), "%content%");
  	$widgetSchema->setFormFormatterName('options');
 
	$this->form = $widgetSchema;
  }

At line 6 we get the number of cars we already have, in order to build the next field index. Then, we need to build the form object that will be rendered by the template and sent back. One important point is: we need to build this widget as so the fields name is prefixed by: user[cars][$number]. For this, we wrap CarForm into a sfWidgetFormSchemaDecorator. Also, we need to set FormatterName to add the controls to the new form. Finally, we render it in the template:
apps/frontend/modules/citypicker/templates/addCarSuccess.php:

1
$form->render(null) ?>

And that’s it, our new form is ready to work. For this example I didn’t put attention to the design, but you can make it look nicer but changing the options formatter, and by using other formatter for the forms than the table one I’m using.
I’m not sure If I explained very well all the details of this implementation, so if you have any doubts, or comments, feel free to drop me a line on the comments section.



Using embedFormForEach in Symfony
Carlos Barros — Mon, 01 Dec 2008 23:07:14 +0000
The new Form sub-framework, introduced in Symfony 1.1, is really great, and the more I work with it, the more I like it. One of the nicest feature of form sub-framework is the ability to embed a form inside another one, using the embedForm method. Also, symfony provides another method, called embedFormForEach that will embed a form inside another one N times. At first glance this method doesn’t seem to be very useful, but I found it really useful in a project I worked a few weeks ago. Consider the following scenario: you want a form to ask users to input information about all cars they have (make and model). In this form you have a select box (this can be an input box too, but I’m using a select box in this example) where users specify how many cars they have and then it will show X fields where users can input cars model and make (X = number of cars user selected), using ajax to load fields. You can see an example here.  

For this example, we will need two forms: one containing the number of cars, and another one containing car details (that will be embedded into first one).
lib/CarsForm.class.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class CarsForm extends sfForm
{
    public function __construct($defaults = array(), $options = array(), $CSRFSecret = null)
    {   
        parent::__construct($defaults,$options,$CSRFSecret);
 
        $this->embedFormForEach('cars',new CarForm(),in_array($defaults['cars_count'],array(1,2,3,4,5))?$defaults['cars_count']:1);
    }   
 
    public function configure()
    {   
        $this->setWidgets(array(
            'cars_count'        => new sfWidgetFormSelect(array('choices'=>array(1=>1,2=>2,3=>3,4=>4,5=>5))),
        ));     
 
        $this->setValidators(array(
            'cars_count'        => new sfValidatorChoice(array('choices'=>array(1,2,3,4,5))),
        ));     
 
        $this->widgetSchema->setLabels(array(
            'cars_count'        => 'Number of Cars',
        ));     
 
        $this->widgetSchema->setNameFormat('cars[%s]');
        $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
    }   
}

This is the main form, where we ask for number of cars and where we will embed details form. All the trick is done in the form constructor, specifically in line 7. embedFormForEach expect three parameters:

name
form to embed
number of times to embed

Our form expect to receive the number of cars in $defaults array, that stores default values of fields in the form, but before assigning it, we check if the number is within our list of allowed value. Note that list of values is hardcoded into the form. I just did it for the sake of simplicity, but I recommend creating a static method somewhere that will return these values. Ok, if our test succeed, we use received value and create requested number of CarForm form, otherwise we just create one (default).
lib/CarForm.class.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class CarForm extends sfForm
{
    public function configure()
    {   
        $this->setWidgets(array(
            'make'        => new sfWidgetFormSelect(array('choices'=>array('ferrari'=>'Ferrari','bmw'=>'BMW','porsche'=>'Porsche'))),
            'model'        => new sfWidgetFormInput(),
        ));     
 
        $this->setValidators(array(
            'make'        => new sfValidatorChoice(array('choices'=>array('ferrari','bmw','porsche'))),
            'model'        => new sfValidatorString(array('required'=>true),array('required'=>'Please enter model')),
        ));     
 
        $this->widgetSchema->setLabels(array(
            'make'        => 'Make:',   
            'model'        => 'Model:', 
        ));     
 
        $this->widgetSchema->setNameFormat('%s');
        $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
    }   
}

This is the form with car details, called CarForm. This is a simple for, with nothing special, but there’s just one detail. At line 20, we set NameFormat to “%s”. Again, allowed values are hardcoded in the form, this should be avoided in real applications.
Ok, now that we already have the forms, we need to create the action and templates to handle the forms. 
apps/frontend/modules/cars/actions/actions.class.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 /**
  * Executes index action
  *
  * @param sfRequest $request A request object
  */
  public function executeIndex($request)
  {
  	// prepare form
  	if($request->isMethod('post'))
  	{
  		$this->form = new CarsForm($request->getParameter('cars'));
  		$this->form->bind($request->getParameter('cars'));
  		if($this->form->isValid())
  		{
  			$this->cars = $this->form->getValue("cars");
  			return $this->setTemplate('result');
  		}
  	}
  	else $this->form = new CarsForm(array('cars_count'=>1));
  }

This looks like a common action that handles form submission, but with one little change: we have to send default values to form constructor. If we are handling a GET request, we just set it to 1 (line 19), as we want just 1 form to be displayed at the beginning, but if we are handling a POST, we send entire form values to constructor (line 11), as our constructor will need to know beforehand how many cars are being submitted.

In the template, we will add a small piece of JavaScript to update the form, using AJAX, based on the number of cars the user selected:
apps/frontend/modules/cars/templates/indexSuccess.php

url_for('cars/index') ?>" method="post">
  $form["cars_count"]->renderRow(array('onchange'=>"new Ajax.Updater("cars_table", '".url_for('cars/refresh')."', { parameters: { cars_count: $F('cars_cars_count') } } )")); ?>
    
            
                    
         include_partial('car_form',array('form'=>$form)) ?>
         
                          
                   
           
  
  


apps/frontend/modules/cars/templates/_car_form.php:

$form["cars"]->renderRow() ?>

In template, I added an listener to the onchange event of number of cars select box that will send a request to the refresh action, sending selected number of cars as parameter, and finally update cars_table container  (all using prototype library). refresh action will receive the number of cars, instantiate the form, sending the number to the constructor, and then render _car_form partial.
apps/frontend/modules/actions/actions.class.php:

  /**
  * Update cars form
  *
  * @param sfWebRequest $request Web request object
  */
  public function executeRefresh($request)
  {
  	$this->form = new CarsForm(array('cars_count'=>$request->getParameter('cars_count')));
  	return $this->renderPartial('car_form');
  }

That’s it, the form is complete. After you validate it, getField(‘cars’) will return an associative array containing cars details submitted by the user. In this example I just write it back to the user, but you can do anything you want with this data, like serializing and then saving into DB.
apps/frontend/moduled/cars/templates/resultSuccess.php

Selected cars:
 foreach($cars as $car): ?>
	Make: $car["make"] ?>
Model: $car["model"] ?>
 endforeach; ?>

Well, this example is a very simple one, but I think it’s a good start to understand how embedFormForEach can be used in your Symfony applications. Say, what if you want to remove the number of cars select box and rather have controls to dynamically add, delete and even sort car details?? Yes, that’s possible too, but I’ll leave this for a next article, that I should write as soon as I have some free time, for now I’ll leave this idea as an challenge  



SOAP WebService in Symfony
Carlos Barros — Mon, 17 Nov 2008 01:05:34 +0000
One interesting topic on web development is webservice development. There are several techniques to implement a webservice out there, and today I’ll talk about one technique that I worked in the recent past that I really like: SOAP. As per wikipedia:
SOAP, originally defined as Simple Object Access Protocol, is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks. It relies on Extensible Markup Language (XML) as its message format and usually relies on other Application Layer protocols, most notably Remote Procedure Call (RPC) and HTTP for message negotiation and transmission. SOAP forms the foundation layer of the web services protocol stack providing a basic messaging framework upon which abstract layers can be built.
The plan for this tutorial is to build a complete set of webservice methods to interact with the citypicker, built in a previous post. For this, I’ll use a great symfony plugin called ckWebService. This plugin enables the developer to expose your actions as a SOAP webservices. Another great functionality is the built-in WSDL generator, that parses module’s doc comment in order to identify which actions should be exposed and it’s input/output parameters. 

Let’s start by installing ckWebService plugin in our symfony project. I’ll not install the latest release, instead I’ll checkout from trunk svn, as it contains some nice improvements if compared to latest release:

barrosws@barros.ws [~/symfony/blog]# cd plugins/
barrosws@barros.ws [~/symfony/blog/plugins]# svn co http://svn.symfony-project.com/plugins/ckWebServicePlugin/trunk ckWebServicePlugin

OBSERVATION: Current trunk version has a small bug (actually a wrong variable name) that must be fixed before continuing:

  public function getResultProperty()
  {
    - return $this->resultMember;
    + return $this->resultProperty;
  }

Now we need to configure the plugin in order to make it work. The read-me located at plugin page provides a complete guide to configure it. For this project we use a basic configuration:
apps/frontend/config/app.yml:

soap:
  enable_soap_parameter: on
  ck_web_service_plugin:
    wsdl: soap.wsdl 
    handler: ckSoapHandler
    persist: %SOAP_PERSISTENCE_SESSION%
    render: off
    result_callback: getSoapResult
    soap_options:
      encoding: utf-8
      soap_version: %SOAP_1_2%

apps/frontend/config/filters.yml:

soap_parameter:
  class: ckSoapParameterFilter
  param:
    condition: %APP_ENABLE_SOAP_PARAMETER%

apps/frondend/config/factories.yml:

soap:
  controller:
    class: ckWebServiceController

Done! That’s all we need to start exposing actions as SOAP webservices. For now on we can expose any of our previously created action by adding a special tag to the doc comment, like this:

  /**
  * Action description
  * @ws-enable
  *
  * @param string $name
  * @return boolean
  */
  public function executeSomeAction($request)
  {
  	/* action here */
  }

This doc comment will expose the action and instruct the WSDL generator that this action expects a string input parameter, called $name and that it will return a boolean value. An interesting thing about this plugin is that it will place all input parameters in the $request object, so the action can access it as if it was called from a browser, passing name as a query string or a post value:

    ...
    $name = $request->getParameter('name');
    ...

Also, notice that $request parameter was removed from the doc comment. This is necessary because if we keep it, the WSDL generator will add $request as a parameter to the webservice, what is not the case here.
Let’s start the implementation for this project. We have three actions that will be exposed:

executeIndex: to list users;
executeEdit: to insert/edit users;
executeDel: to delete users.

One might think that we will need to add @ws-enable to these actions doc comment… well, yes, that’s the original idea, but I prefer using a different approach. My approach is to create a new module, called soap (or whatever you want) and create wrappers to actual actions. This will reduce the number changes needed to be done in the actual actions (sometimes it won’t require any change at all) and will make it possible for the developer to code the entire system without even caring about webservice, all adjustments can be easily made only when actually implementing the webservice. In some emails I exchanged with Christian Kerl, the plugin author, he said me that this is not the best way to achieve this result. The correct way to do this is to create a custom SoapHandler, but this will kill WSDL generator (he said work is in progress), so I’ll stick to my way by now (trunk version has all the necessary changes to make this possible – it’s not the case with latest release).
So, let’s create our new module:

barrosws@barros.ws [~/symfony/blog]# symfony generate:module frontend soap
>> dir+      /home/barrosws/symfony/blog/apps/frontend/modules/soap/templates
>> file+     /home/barrosws/symfony/blog/app...soap/templates/indexSuccess.php
>> dir+      /home/barrosws/symfony/blog/apps/frontend/modules/soap/actions
>> file+     /home/barrosws/symfony/blog/app.../soap/actions/actions.class.php
>> file+     /home/barrosws/symfony/blog/tes...al/frontend/soapActionsTest.php
>> tokens    /home/barrosws/symfony/blog/tes...al/frontend/soapActionsTest.php
>> tokens    /home/barrosws/symfony/blog/app...soap/templates/indexSuccess.php
>> tokens    /home/barrosws/symfony/blog/app.../soap/actions/actions.class.php

The first action will expose is executeIndex, that will return a list of all users registered in the system. This is the simplest one and I’ll use to explain some important points:
apps/frontend/modules/soap/actions/actions.class.php:

  /**
  * Get users
  *
  * @ws-enable
  * 
  * @return SoapUser[]
  */
  public function executeGetUsers($request)
  {
  	// call actual action
  	$this->getController()->forward('citypicker','index');
 
  	// set result
  	$actionInstance = $this->getLastActionInstance();
  	$actionInstance->result = $actionInstance->users;
  }

As I said before, we will create wrappers to actual actions. For this action, we don’t have any input parameter, so we don’t need any extra processing. First thing the action does is a forward to actual action. Note that I use the forward method from the controller instead of forward method from sfAction. This is necessary because we need continue our execution flow AFTER actual action returns (sfAction’s forward won’t return control to us). Return value is expected to be located in the deepest action instance, in our case, citypicker/index action, in a property called result (in our case, we store the result of a UserPeer::doSelect() call – made in citypicker/index action and stored in users property). In order to do this we need to get this action’s instance and that’s what getLastActionInstance method do: 
apps/frontend/modules/soap/actions/actions.class.php:

  /**
   * Get last action instance
   * 
   * @return sfActionInstance
   */  
  private function getLastActionInstance()
  {
  	return $this->getController()->getActionStack()->getLastEntry()->getActionInstance();
  }

This method will simply return last actions instance from the action stack, and we will use it in all of our wrappers.  If you look at doc comments, you will notice return value is declared as an array of SoapUser objects. SoapUser class is defined as follows:
lib/soap/SoapUser.class.php


class SoapUser
{
	/**
	 * User name
	 * 
	 * @var string
	 */
	public $name;
 
	/**
	 * Country ID
	 * 
	 * @var integer
	 */
	public $country_id;
 
	/**
	 * State ID
	 * 
	 * @var integer
	 */
	public $state_id;
 
	/**
	 * City ID
	 * 
	 * @var integer
	 */
	public $city_id;
}
?>

Doc comments are REQUIRED here too, because WSDL generator will use it to build the object definition. When sending result back, our result (array of User objects) will be converted into SoapUser objects, making these properties available.
Our first method is complete. In order to start using it, we need to generate the WSDL definition, using the built-in WSDL generator. The generator will also create the frontend dispatcher, in web/ directory:

barrosws@barros.ws [~/symfony/blog]# symfony webservice:generate-wsdl frontend soap http://blog.barros.ws/symfony
>> file-     /home/barrosws/symfony/blog/web/soap.php
>> file+     /home/barrosws/symfony/blog/web/soap.php
>> tokens    /home/barrosws/symfony/blog/web/soap.php
>> file+     /home/barrosws/symfony/blog/web/soap.wsdl

In order to test it we can use a nice piece of software called SoapUI. This software will read soap.wsdl and build the request, all using a nice GUI. I recommend downloading the trial of PRO version, as it is capable of generating forms (web like) where you can input parameters:

executeDel actions is similar to executeIndex:
apps/frontend/modules/soap/actions/actions.class.php:

  /**
  * Deletes an user
  *
  * @ws-enable
  * @param integer $id
  * 
  * @return boolean
  */
  public function executeDelUser($request)
  {
  	// call actual action
  	$this->getController()->forward('citypicker','del');
 
  	// set result
  	$actionInstance = $this->getLastActionInstance();
  	$actionInstance->result = true;
  }

Now, executeEdit (executeNewUser in our wrapper) is a bit trickier:
apps/frontend/modules/soap/actions/actions.class.php:

  /**
  * Creates a new user in the system
  *
  * @ws-enable
  * @param SoapUser $user
  * 
  * @return boolean
  */
  public function executeNewUser($request)
  {
  	// convert input param from OBJECT to ARRAY
  	$request->setParameter('user',get_object_vars($request->getParameter('user')));
 
  	// call actual action
  	$this->getController()->forward('citypicker','edit');
 
  	// check errors
  	$actionInstance = $this->getLastActionInstance();
  	if(!$actionInstance->form->isValid()) $this->throwSoapFormException($actionInstance->form);
 
  	$actionInstance->result = true;
  }

First difference we can note is the fact this action requires one input parameters. In doc comment we declare that this action expects an SoapUser object as input, but the actual action expects an simple array. The first step then is to convert received object into an array. For this we use get_object_vars and after conversion, we set it back to the $request object. Finally we call actual action, that will act as if the user had submitted the form. Next difference is that we need to check if there was any error processing input data. We do this by checking if form, in actual action instance, is valid, and if not return an error message. In order to throw an exception with detailed errors, I created an small method called throwSoapFormException, that will iterate through all errors in the form and build  single string, with one error per line:
apps/frontend/modules/soap/actions/actions.class.php:

  /**
   * Throw a SoapFault error based on form errors
   * 
   * @param sfForm $form
   */
  public function throwSoapFormException($form)
  {
	foreach($form->getFormFieldSchema()->getError() as $e)
		$errors[] = $e;
 
	throw new SoapFault('ERROR',implode("n",$errors));
  }

And that’s it, we can now create new users using the new SOAP interface:

Well, actually one small thing is missing to make it really work… Did u notice that I didn’t touch actual actions yet? Sometimes we don’t need to touch it, but that’s not our case. If you look at citypicker post you will notice that both “del” and “edit” actions redirect the user back to index page on success. We can’t do this when running on soap mode, or we will lose control and we won’t be able to send correct result back to the client. To fix this, we just need to make an small change:

if(!$this->isSoapRequest()) return $this->redirect('citypicker/index');

isSoapRequest is a new method added by ckWebservicePlugin and it will return true when executing the actions via SOAP. Adding this check we just perform the redirect when NOT in SOAP mode.
That’s all we need to talk about how to expose your actions via SOAP, but in order to complete our example, we need to create some methods to fetch countries/states/cities informations. For this we create 6 new actions:

  /**
  * Get countries list
  * @ws-enable
  *
  * @return SoapGeo[]
  */
  public function executeGetCountries($request)
  {
  	$this->result = CountryPeer::doSelect(new Criteria());
  }
 
  /**
  * Get a country
  *
  * @ws-enable
  * @param integer $id
  * 
  * @return SoapGeo
  */
  public function executeGetCountry($request)
  {
  	$this->result = CountryPeer::retrieveByPK($request->getParameter('id'));
  }
 
  /**
  * Get states list
  *
  * @ws-enable
  * @param integer $country_id
  *
  * @return SoapGeo[]
  */
  public function executeGetStates($request)
  {
  	$country = CountryPeer::retrieveByPK($request->getParameter('country_id'));
  	if(!$country) throw new SoapFault('ERROR','Invalid country');
 
  	$this->result = $country->getStates();
  }
 
  /**
  * Get a state
  *
  * @ws-enable
  * @param integer $id
  * 
  * @return SoapGeo
  */
  public function executeGetState($request)
  {
  	$this->result = StatePeer::retrieveByPK($request->getParameter('id'));
  }
 
  /**
  * Get cities list
  *
  * @ws-enable
  * @param integer $state_id
  *
  * @return SoapGeo[]
  */
  public function executeGetCities($request)
  {
  	$state = StatePeer::retrieveByPK($request->getParameter('state_id'));
  	if(!$state) throw new SoapFault('ERROR','Invalid state');
 
  	$this->result = $state->getCitys();
  }
 
  /**
  * Get a city
  *
  * @ws-enable
  * @param integer $id
  * 
  * @return SoapGeo
  */
  public function executeGetCity($request)
  {
  	$this->result = CityPeer::retrieveByPK($request->getParameter('id'));
  }

And to finish, we need to create the SoapGeo class, that will store country name and id:
lib/soap/SoapGeo.class.php:


class SoapGeo
{
    /**
     * ID
     *
     * @var integer
     */
    public $id;
 
    /**
     * Name
     *
     * @var string
     */
    public $name;
}

And we’re done. With this we can now build an external app to create/edit/delete users in the database. I spent several days working with the plugin before coming up with this solution and I hope this will save other developers some time dealing with SOAP implementations. Also, I’d like to thank Christian Kerl for all new changes made to trunk version that is making this plugin even better.
If one wants to test our SOAP interface, the .wsdl file is located at http://blog.barros.ws/symfony/soap.wsdl



Conditional validator in Symfony, another approach
Carlos Barros — Wed, 05 Nov 2008 12:10:27 +0000
Today morning I was reading the Symfony blog, more specifically A week of symfony #96 and then I came across a tutorial talking about conditional validators.This is very usefull, I find myself using this technique very often, so I decided to write about another techinique I use sometimes to implement a conditional validation, but for a different scenario. Imagine the following: you have a contact form where the users specify how they want to be contacted, email or phone, throught a select box. Then you have two input boxes where the users can enter both email and phone. If the user opts to be contacted via email, email field becomes mandatory and phone number optional, and the opposite happens if the user opts to be contacted via phone. So, how to implement such a form in symfony? 


A normal form would look like this:
lib/form/ContactForm.class.php:

class ContactForm extends sfForm
{
  public function configure()
  {
    $this->setWidgets(array(
      'method'	=> new sfWidgetFormSelect(array('choices'=>array('phone'=>'Phone','email'=>'Email'))),
      'email'	=> new sfWidgetFormInput(),
      'phone'	=> new sfWidgetFormInput(),
      'msg'	=> new sfWidgetFormTextarea(),
    ));
 
    $this->setValidators(array(
      'method'	=> new sfValidatorChoice(array(
			'choices'=>array('phone','email'),
		)),
      'email'	=> new sfValidatorEmail(array(
			'required'=>true,
		),array(
			'required'=>'Please enter your email address',
			'invalid'=>'Invalid email address'
		)),
      'phone'	=> new sfValidatorString(array(
			'required'=>true,
		),array(
			'required'=>'Please enter your phone number',
		)),
      'msg'	=> new sfValidatorString(array(
			'required'=>true,
		),array(
			'required'=>'Please enter your message',
		)),
    ));
 
    $this->widgetSchema->setLabels(array(
	'email'		=> 'Email:',
	'phone'		=> 'Phone:',
	'method'	=> 'Contact type:',
	'msg'		=> 'Message:',
    ));
 
    $this->widgetSchema->setNameFormat('contact[%s]');
    $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
  }

The problem with this form is the fact that both phone and email are ALWAYS mandatory, regardless of the value of method. So, what we need is a way to intercept method’s value and update validators. So, what we need is intercept the bind method in order to check method’s value:
lib/form/ContactForm.class.php:

  public function bind(array $taintedValues = null, array $taintedFiles = null)
  {
    if(@$taintedValues["method"] == 'phone') $this->validatorSchema["email"]->setOption('required',false);
    else $this->validatorSchema["phone"]->setOption('required',false);
 
    return parent::bind($taintedValues,$taintedFiles);
  }

As can be seen, we create our own bind method, overriding parent one, and before calling the actual bind method, we inspect the values sent by the user and if method is phone, we remove the required option from email validator, otherwise we remove the required option from phone validator and finally call parent method.
The resulting form can be seen here!



Joomla like theme for symfony admin generator
Carlos Barros — Wed, 29 Oct 2008 21:52:43 +0000
When I first started working with symfony admin generator, I searched for some nice themes that I could use in my project, and for my surprise, I didn’t find anything. Searching a bit more I came across a blog post on SymfonyLab (http://www.symfonylab.com/backend-generator-theme/) asking about themes. In the post the author pointed an joomla like theme (http://www.symfony-project.org/forum/index.php/m/16515), created by a user called Draven, that I really liked, but it’s outdated. I’m not really a joomla fan, but I must admin I like their backend design, so I decided to do a new implementation of this theme. It’s based on Draven’s implementation, in fact the css is almost the same, with some changes here there, and some small layout changes as well (specially in the edit page). Just one note that’s worth saying, it’s not really a THEME, but just a css, some layout templates and a collection of images, that changes the look of generated admin module. Here are some screenshots:






Also you can see it in action here (use anything as username/password).

It’s pretty simple to install and use this theme, just download the files here. This package contains a web directory with a set of images, javascripts and css, all stored in a dir called sf_admin. Also, it contains a set of layout templates that you must add to your backend application. Note that along with the layout templates, there are two files that are NOT layout templates, but templates that you should moved to the appropriated action, loginSuccess.php and dashboardSuccess.php. loginSuccess.php is the login screen and should be moved to your login module, and dashboard is the main admin screen and should be moved to your main module.
First file that needs to be changed is the main view.yml file for the backend app, in order to add the custom javascripts, css and set the layout.
app/backend/config.view.yml:

  stylesheets:    [sf_admin/main,sf_admin/theme]
  javascripts:    [sf_admin/JSCookMenu_mini,sf_admin/theme]
 
  has_layout:     on
  layout:         layout

Note that loginSuccess.php template must NOT have a layout because it has a different look, so, don’t forget to set has_layout: off to the correct view.yml when using it. Now, for each module, you must set a new css in the generator.yml config file:
app/backend/modules/some_module/config/generator.yml:

generator:
  class:              sfPropelAdminGenerator
  param:
    model_class:      SomeModel
    theme:            default
    css:              sf_admin/main

Also in generators, I suggest to ALWAYS add a fieldset caption to the edit page, otherwise it will not look as expected. You can do something like:
app/backend/modules/some_module/config/generator.yml:

    edit:
      title:          User manager: edit
      display:
        "Details":             [id,name]
      fields:
        name:           { name: Name, help: "Enter name here" }
      actions:
        _delete:        { name: Delete }
        _list:          { name: Close }
        _save_and_list: { name: Save }

One drawback this theme has is the fact that all “actions” have absolute positioning, in order to place it at top right. This means that each action as a static location, thus, you cannot add an save action as the first button in one view, and then add as the second button in another view, they will ALWAYS be placed in the same position (btw, to change actions location/order/etc, just edit css/sf_admin/main.css file and search for .sf_admin_action_create – or any other action name – and change the right value). I tried to move it’s container and then set contents to float:right, but it didn’t work as expected. Actually it worked just fine, but the problem was with the delete button. Delete button is in a different container, because it needs to live in a new 
 tag, so it was not possible to make it float. But as original author (Draven) said, it’s not a real theme. One can create a complete new theme to address these small details, but for me, this works like a charm  .



Country/State/City picker in Symfony 1.1
Carlos Barros — Sun, 26 Oct 2008 14:49:03 +0000
Have you ever seen those forms where you select a country, then it populates a list of states, then you pick a state and it populate a list of cities? I’ve seem many of these and I really like them. In one of my past projects I was asked to add a similar form to the system, using symfony, and I’ll show how I accomplished this, making use of the excellent new symfony 1.1 form system. For those who want to see what it looks like before keep on reading, I put very simple sample online in this link.

Let’s start with the database model (config/schema.yml):

propel:
  _attributes:   { noXsd: false, defaultIdMethod: none, package: lib.model }
 
  cp_users:
    _attributes:     { phpName: User, idMethod: native }
    id:              ~
    name:            { type: varchar(100), required: true }
    country_id:      { type: integer, required: true, foreignTable: cp_countries, foreignReference: id }
    state_id:        { type: integer, required: true, foreignTable: cp_states, foreignReference: id }
    city_id:         { type: integer, required: true, foreignTable: cp_cities, foreignReference: id }
    created_at:      ~
    updated_at:      ~
 
  cp_countries:
    _attributes:     { phpName: Country, idMethod: native }
    id:              ~
    code:            { type: varchar(2), required: true }
    name:            { type: varchar(100), required: true }
 
  cp_states:
    _attributes:     { phpName: State, idMethod: native }
    id:              ~
    country_id:      { type: integer, required: true, foreignTable: cp_countries, foreignReference: id, onDelete: "CASCADE" }
    name:            { type: varchar(100), required: true }
 
  cp_cities:
    _attributes:     { phpName: City, idMethod: native }
    id:              ~
    state_id:        { type: integer, required: true, foreignTable: cp_states, foreignReference: id, onDelete: "CASCADE" }
    name:            { type: varchar(100), required: true }

This is a very simple database model, with user, country, state and city. In this schema, each city is related to a single state and each state is related to a single country. You may ask why I did add all these three elements in the user model, as we can get these info from the city. Honestly, there’s no reason for this, but I left if there just for the sake of simplicity. We can remove state and country and create a getState() and getCountry() methods on User class to get these informations, but I’ll leave it as an exercise for the readers. So, first step is to build this model and then generate SQL script:

$ symfony propel:build-model
$ symfony propel:build-sql
$ symfony propel:insert-sql

Also, for this example I created a module called citypicker, inside frontend application:

$ symfony generate:module frontend citypicker

First step in this sample is to create the list view, I’ll not explain in details about it because it’s just a simple list view with nothing special, I’ll just put the action and template code here:
actions.class.php:

  public function executeIndex($request)
  {
    $this->users = UserPeer::doSelect(new Criteria());
  }
 
  public function executeDel($request)
  {
  	$user = UserPeer::retrieveByPK($request->getParameter("id"));
  	$this->forward404Unless($user);
 
  	$user->delete();
  	return $this->redirect('citypicker/index');
  }

indexSuccess.php:

 foreach ($users as $user): ?>
		 endforeach; ?>

	
		ID
		Name
		Country
		State
		City
	
	
			link_to($user->getId(),'citypicker/edit?id='.$user->getId()) ?> - link_to('del','citypicker/del?id='.$user->getId()) ?>
			esc_entities($user->getName()) ?>
			$user->getCountry() ?>
			$user->getState() ?>
			$user->getCity() ?>
		
	
button_to('New user','citypicker/edit') ?>

Now we need to create the edit view, where the citipicker will be shown. For this, we need to create the form that will handle user input. In this example I didn’t use propel:build-forms command, instead I created the form from scratch (that’s one point to improve). The resulting code is as follows:
lib/form/CPUserForm.class.php:

class CPUserForm extends sfFormPropel
{
  public function configure()
  {
  	// build state criteria
  	$stateC = new Criteria();
  	$stateC->add(StatePeer::COUNTRY_ID,$this->getObject()->getCountryId());
 
  	// build city criteria
   	$cityC = new Criteria();
  	$cityC->add(CityPeer::STATE_ID,$this->getObject()->getStateId());
 
    $this->setWidgets(array(
      'name'   			=> new sfWidgetFormInput(),
      'country_id'		=> new sfWidgetFormPropelSelect(array('model'=>'Country','add_empty'=>'-- Country --','order_by'=>array('Name','asc'))),
      'state_id'		=> new sfWidgetFormPropelSelect(array('model'=>'State','add_empty'=>'-- State/Province --','order_by'=>array('Name','asc'),'criteria'=>$stateC)),
      'city_id'			=> new sfWidgetFormPropelSelect(array('model'=>'City','add_empty'=>'-- City --','order_by'=>array('Name','asc'),'criteria'=>$cityC)),
      'id'				=> new sfWidgetFormInputHidden(),
    ));
 
    $this->setValidators(array(
    	'name'			=> new sfValidatorString(
    							array(
    								'trim'		=> true,
    								'required'	=> true,
    							),array(
    								'required'	=> '- Please enter name',
    							)
    					),
    	'country_id'	=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'Country',
    								'column'	=> 'id',
    							),array(
    								'required'	=> '- Please choose country',
    								'invalid'	=> '- Invalid country',
    							)
    					),
    	'state_id'		=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'State',
    								'column'	=> 'id',
    								'criteria'	=> clone $stateC,
    							),array(
    								'required'	=> '- Please choose state',
    								'invalid'	=> '- Invalid state',
    							)
    					),
    	'city_id'		=> new sfValidatorPropelChoice(
    							array(
    								'model'		=> 'City',
    								'column'	=> 'id',
    								'criteria'	=> clone $cityC,
    							),array(
    								'required'	=> '- Please choose city',
    								'invalid'	=> '- Invalid city',
    							)
    					),
    	'id'			=> new sfValidatorNumber(array('required'=>false)),
    ));
 
	$this->widgetSchema->setLabels(array(
		'name'	=> 'Name',
	));
 
	$this->widgetSchema->setNameFormat('user[%s]');
    $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);
  }
 
  public function getModelName()
  {
  	return 'User';
  }
}

This form is not much different from a common form, using sfWidgetFormPropelSelect to show a list of available objects, except by the new option I added, criteria. As can be seen at the top of the code, I build two criterias that are used to filter state and city, based on current selection. This will make the state select only display states belonging to selected country, and cities belonging to selected state. Also, if no country is selected, state and city list will be empty.

Another important step that must be done in order to use sfWidgetFormPropelSelect is to create the magic method __toString to Country, State and City objects. Just add the following code to ALL three classes:
lib/model/Country.class.php, lib/model/State.class.php, lib/model/City.class.php:

	public function __toString()
	{
		return $this->getName();
	}

The template needs a special attention as well. As will we use AJAX to update the select boxes without reloading the page, we need to split the edit template in two files, the main file and a partial file that will contain the select boxes and the ajax calls:
editSuccess.php:

url_for('citypicker/edit?id='.$form->getObject()->getId()) ?>">
  $form["id"]->render() ?>
   if ($errors): ?>
     endif; ?>
    
  	
    	
    		
    			 foreach ($errors as $error): ?>
					$error ?>
				 endforeach; ?>
    		
    	
    
	
      $form["name"]->renderLabel() ?>
      $form["name"]->render() ?>
    
    
      Address
      
        
        	include_partial('address_edit',array('form'=>$form)) ?>
        
      
    
    
      
        
        button_to('cancel','citypicker/index') ?>
      
    
  


_address_edit.php:

 use_helper('Javascript') ?>
$form["country_id"]->render(array(
	'onchange'	=> '$(this.form).request({
						parameters: {refresh: "Y" },
						onComplete: function (r) { $("address").update(r.responseText) }
					});'
)) ?>
$form["state_id"]->render(array(
	'onchange'	=> '$(this.form).request({
						parameters: {refresh: "Y" },
						onComplete: function (r) { $("address").update(r.responseText) }
					});'
)) ?>
$form["city_id"]->render()?>

This code submits the form every time the user changes either country or state boxes. Note that it will append an extra parameter to the form, called refresh, in order to tell the action that it’s only updating the boxes, and not actually submitting the form. Also, when the call is finished, it will update the #address (div container defined in editSuccess.php template file) element with the response received.
Now, the only piece missing to make this work is the actual edit action, that will handle both form submission and boxes update. 
actions.class.php:

  public function executeEdit($request)
  {
  	if($request->getParameter('id')) $user = UserPeer::retrieveByPK($request->getParameter("id"));
  	else $user = new User();
  	$this->forward404Unless($user);
 
  	$this->errors = array();
  	if($request->isMethod('post'))
  	{
  		// pre-populate country, state and city in order to filter select boxes
  		$data = $request->getParameter('user');
  		$user->setCountryId(@$data['country_id']);
  		$user->setStateId(@$data['state_id']);
  		$user->setCityId(@$data['city_id']);
 
  		// check validity
  		if(!$user->getCity() || ($user->getCity()->getStateId() != $user->getStateId())) $user->setCityId(0);
  		if(!$user->getState() || ($user->getState()->getCountryId() != $user->getCountryId())) $user->setStateId(0);
  		if(!$user->getCountry()) $user->setCountryId(0);
 
  		$this->form = new CPUserForm($user);
  		$this->form->bind($request->getParameter('user'));
  		if($request->getParameter('refresh') != "Y")
  		{
  			if($this->form->isValid())
  			{
  				$this->form->save();
  				return $this->redirect('citypicker/index');
  			}
 
		  	// get errors into array
		  	foreach($this->form->getFormFieldSchema()->getError() as $e)
		  		$this->errors[] = $e;
  		}
  		else
  		{
  			// render city/state/country
  			return $this->renderPartial('address_edit',array('form'=>$this->form));
  		}
  	}
  	else 
  	{
  		$this->form = new CPUserForm($user);
  	}
  }

Again, this action is not much different from a common edit action, but there are some extra code to handle the box update. At first, we extract selected country, state and city from the parameters array and populate the user object with these values. This step is needed in order to make the criterias (defined in the form) to work, as it fetches data from the object. Also, we validate these data in order to ensure that selected state belongs to selected country, and that selected city belongs to selected state (well, I guess this can be removed as the criterias will filter it, but I’ll leave it as I didnt test – another point to improve). Another change is the check for the refresh parameter. If it’s set to Y, we skip form validation and just render the _address_edit partial. This partial will be received by the ajax call and will update the form with new select boxes values. Another small detail on this sample is the error handling. After validation, if there’s any error, I get the list of error messages and create an array with these values, then send it to the template, that in turn will render a unordered list with the messages. I did this because this form has a special design and putting the error messages together with the fields would mess the box design.
Well, that’s it, now you have the form working. There are some things that can be done in order to improve user experience. Actually experience told me that it MUST be done. One thing is to disable ALL boxes as soon as the user changes it’s value and only re-enabling after update is finished. Also, you can add an ajax indicator somewhere to tell the user that it’s still working. If you don’t do this, it’s most likely that users will get confused with the boxes (and they WILL, trust me, hehe). 
This small tutorial maybe looks a bit confuse, with lots of code with not much explanation, but I hope this can be useful for you. It would be nice to hear feedback from the readers, specially comments about how to improve the form (I’m not really an symfony expert). 



Overlabel with Prototype
Carlos Barros — Thu, 31 Jul 2008 00:44:19 +0000
Some time ago I was searching for some overlabel script to use in a project and found a great script, created by Mike Brittain (here), and since then I’ve used this script in all my projects. But last week I was working in a project that uses Prototype library and I wondered if there was an overlabel plugin for prototype. After some time googling about the subject, I only came up with a JQuery plugin (here), that is a port of Mike Brittain script to JQuery library. So, as I didn’t find what I was looking for, I decided to make my own port and created a prototype plugin. This took me less than 15 minutes to get a working version of it.
This is the resulting code:

var overLabelPlugin = {
 overlabel: function (obj)
 {
  var  field;
 
  obj = $(obj);
 
  // check for attribute
  if(!obj.readAttribute('for') ||
   !(field = $(obj.readAttribute('for'))))
    return false;
 
  // apply overlabel style
  obj.className = 'overlabel-apply';
  if(field.value != '')
   $$('label[for='+$(field).readAttribute('id')+']').invoke('hide');
 
  // setup event handlers
  field.onfocus = function ()
  {
   $$('label[for='+$(this).readAttribute('id')+']').invoke('hide');
  }
 
  field.onblur = function ()
  {
   if($(this).value === '')
    $$('label[for='+$(this).readAttribute('id')+']').invoke('show');
  }
 
  obj.onclick = function ()
  {
   $($(this).readAttribute('for')).focus();
  }
 }
}
 
Event.observe(window,'load',function ()
{
 Element.addMethods(overLabelPlugin);
});

The only change I made to the original technique was the usage of hide() and show() instead of text-ident:-1000px; to hide/show overlabels.
To activate overlabel, you can do something like:

<html>
 <head>
  <title>Overlabel with Prototype</title>
  <style rel="stylesheet" type="text/css">
  label.overlabel-apply {
    position:absolute;
    top:3px;
    left:5px;
    z-index:1;
    color:#999;
    font-family:verdana serif sans-serif;
    font-size:10pt;
  }
  div.overlabel_container {
    position:relative;
  }
  </stype>
  <script src="prototype.js" type="text/javascript"></script>
  <script src="overlabel.js" type="text/javascript"></script>
  <script type="text/javascript">
  Event.observe(window,'load',function ()
  {
   $$('.overlabel').invoke('overlabel');
  });>
 
  </script>
 </head>
 <body>
  <div class="overlabel_container">
   <label class="overlabel" for="uname">Username</label>
   <input id="uname" name="uname" type="text" />
  </div>
 </body>
</html>

I’m by no means a Prototype expert, so if there’s some better way to do this, please let me know.