blog.barros.ws » city picker http://blog.barros.ws web development tips Sun, 06 Jun 2010 00:34:52 +0000 http://wordpress.org/?v=2.9.2 en hourly 1 Country/State/City picker in Symfony 1.1 http://blog.barros.ws/2008/10/26/countrystatecity-picker-in-symfony-11/ http://blog.barros.ws/2008/10/26/countrystatecity-picker-in-symfony-11/#comments Sun, 26 Oct 2008 14:49:03 +0000 Carlos Barros http://blog.barros.ws/?p=38 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:

<table width="50%" align="center" border="1">
	<tr>
		<th>ID</th>
		<th align="left">Name</th>
		<th align="left">Country</th>
		<th align="left">State</th>
		<th align="left">City</th>
	</tr>
	<?php foreach ($users as $user): ?>
		<tr>
			<td align="center"><?=link_to($user->getId(),'citypicker/edit?id='.$user->getId()) ?> - <?=link_to('del','citypicker/del?id='.$user->getId()) ?></td>
			<td><?=esc_entities($user->getName()) ?></td>
			<td><?=$user->getCountry() ?></td>
			<td><?=$user->getState() ?></td>
			<td><?=$user->getCity() ?></td>
		</tr>
	<?php endforeach; ?>
</table>
<p align="center"><?=button_to('New user','citypicker/edit') ?></p>

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:

<form method="post" action="<?=url_for('citypicker/edit?id='.$form->getObject()->getId()) ?>">
  <?=$form["id"]->render() ?>
  <table>
  	<?php if ($errors): ?>
    <tr>
    	<td colspan="2">
    		<ul>
    			<?php foreach ($errors as $error): ?>
					<li><?=$error ?></li>
				<?php endforeach; ?>
    		</ul>
    	</td>
    </tr>
	<?php endif; ?>
    <tr>
      <th><?=$form["name"]->renderLabel() ?></th>
      <td><?=$form["name"]->render() ?></td>
    </tr>
    <tr>
      <th>Address</th>
      <td>
        <div id="address">
        	<?=include_partial('address_edit',array('form'=>$form)) ?>
        </div>
      </td>
    </tr>
    <tr>
      <td colspan="2">
        <input type="submit" name="submit" value="save"/>
        <?=button_to('cancel','citypicker/index') ?>
      </td>
    </tr>
  </table>
</form>

_address_edit.php:

<?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).

]]> http://blog.barros.ws/2008/10/26/countrystatecity-picker-in-symfony-11/feed/ 34