I have just made my first release to GitHub, majaxPheanstalkPlugin for symfony 1.4.x (possibly will work on older ones). It's a set of tools that help to access Beanstalkd and make building workers much simpler.
The goal is to provide you with simple tools for managing your Beanstalkd integration. Right now it's just worker thread tools and a simple factory, but I hope to grow it into a more complete library as time goes on.
We're going to step things up a notch with this one, so hang on for the ride, because for those of you not already well versed in symfony and jQuery, there will be a lot of new information, and it will go pretty quickly, but I will try to make sure to keep everyone caught up. This is another post I hinted towards back when I first wrote about symfony widgets. Right, so, on to the fun!
First things first, let's talk about requirements. My only real requirement is that it must be seamless. We must be able to only implement the widget, and have everything else work exactly as intended. For a date widget, this means when the user clicks that submit button, an array with 'month', 'day', and 'year' must be sent back. Not a string, not JSON, just that basic array.
It's for the above reason that we will need to make a widget on top of the basic jQuery UI Datepicker Widget. The Datepicker alone would just return a string when we submitted the form, which would then require at least a custom validator, if not much more. So to simplify things later, we'll put in more effort now.
There are four things we will be doing in this tutorial to make this happen. Here's a quick overview:
Set up a new module for us to use with the widget tutorials
Create our widget class
Create our jQuery UI widget that goes along with our widget class
1. Setup majaxJqueryPlugin
We're using my plugin for two reasons:
It's my blog, so of course, I'm using my plugin
We need jQuery UI, both the JavaScript and the CSS, and majaxJqueryPlugin provides that right away
Setting it up is easy:
cd plugins
wget-O majaxJqueryPlugin.zip http://jmather.com/wp-content/plugins/download-monitor/download.php?id=4
cd plugins
wget -O majaxJqueryPlugin.zip http://jmather.com/wp-content/plugins/download-monitor/download.php?id=4
Now we add the plugin to our Project Configuration. Open up your config/ProjectConfiguration.class.php file, and place this line somewhere within your setup() function:
$this->enablePlugins('majaxJqueryPlugin');
$this->enablePlugins('majaxJqueryPlugin');
And one last step, we need to publish the assets:
./symfony plugin:publish-assets
./symfony plugin:publish-assets
Alright, now we're ready to move on to the good stuff.
2. Setting up our plugin
Now we need to make a new plugin, and set up a few directories for future use. It's pretty self-explanatory so we'll cut right to the code, and come back afterwards to talk about some of the extras.
We made our plugin, then we made the directory our jQuery plugins will go in, and the directory where we will store our widgets. The -p flag means "no error if existing, make parent directories as needed" which saved us a few mkdir commands.
3. Making our symfony widget
Now open up plugins/majaxWidgetPlugin/lib/widget/majaxWidgetFormDate.class.php and here's our code:
So, to start out, we extend sfWidgetFormDate, as that will make the controls we need to manage a date submission. The only change we need to do, is to override the render function, which will let us add some custom code around the standard output, to allow us to more easily control the display.
The first thing we do in the render function is to include the required JavaScript. Some will say the widget shouldn't know about the JavaScript, but I say, if the widget shouldn't know... who should? We want to make this as transparent as possible, so why should we have to also remember to add a JavaScript include to use this widget?
Next, we grab our generated ID, and figure out our options (i.e. can the date be null) that we can pass along to Datepicker. After that we wrap the whole deal in a containing div, and then wrap the native controls in another specific div. You will see why we did this in a minute. Lastly, we write the JavaScript to activate the widget.
4. Making our jQuery Plugin
As is the standard, I'll show you the code, then highlight portions that are interesting. This file goes in plugins/majaxWidgetPlugin/web/js/jquery.majax.dateselector.js
You know, looking over, it's pretty clear, I feel, what most parts do. The functions "_hide_real_ctrls", and "_show_real_ctrls" hide and show that wrapping div we built around the original controls, so we can keep them in play, but not have to worry about controlling them. The "_build_facade" function builds our fake interactive Datepicker object, and optionally our 'Clear' button, if our date is allowed to be empty. Functions "_clear_display" and "_update_ctrls" to exactly as you would expect. Cure functions "_create" and "destroy" are from the jQuery UI Widget framework, and are called ... can you guess when? 🙂
We're done!
Once you're done, you can replace any sfWidgetFormDate instance with a majaxWidgetFormDate instance, and everything else is handled. A little bit of effort up front, and many rewards down the road!
Forms in symfony bring some fun to the table. They're very, very powerful, but you have to know how to ask them, and figuring that out isn't always the easiest thing. I have worked with forms extensively for the past several weeks, and primed with this knowledge, I believe I can show you a pretty solid way to start building customized forms.
We're going to have six pieces building our contact form:
Setup -- We make our module
Preparation -- I have a helpful function for you to add to your BaseForm class that makes things easier later on
Form -- We build our form
Action -- We build the action to handle our form
Templates -- We build two templates to handle our contact form, the form page, and the thank you page.
Routing -- All this hard work, let's make it look nice!
So with that being said, let's get on the road to enlightenment!
1. Setup
At this point, I assume the following:
You have a working symfony install
You have an app named 'frontend'
If you haven't made a module before, you're about to expand your horizons!
./symfony generate:module frontend contact_form
./symfony generate:module frontend contact_form
This will create apps/frontend/modules/contact_form, and related subdirectories.
2. Preparation
I promised you a helpful addition to your BaseForm class, and along with that, I will offer an explanation.
The sfForm class (and it's children) will allow you to easily get only hidden fields, but it doesn't offer you a simple way to allow you to easily get only visible fields. This little function solves that inequity.
<?php
/**
* Base project form.
*
* @package your-package
* @subpackage form
* @author YourNameHere
* @version SVN: $Id: BaseForm.class.php 20147 2009-07-13 11:46:57Z FabianLange $
*/
class BaseForm extends sfFormSymfony
{
public function getVisibleFields()
{
$hidden_fields = $this->getFormFieldSchema()->getHiddenFields();
$fields = array();
foreach($this as $name => $field)
{
if (!in_array($field, $hidden_fields))
$fields[$name] = $field;
}
return $fields;
}
}
3. Form
For our contact form, we'll have Name, Email, and Comments. Name and Email will be input fields, and Comments will be a text area. All fields will be required. Let's take a look at what that form looks like:
lib/form/PublicContactForm.class.php
<?phpclass PublicContactForm extends BaseForm
{publicfunction setup(){// this is required, don't forget this!$this->widgetSchema->setNameFormat('contact_form[%s]');$this->setWidget('name',new sfWidgetFormInput());$this->setValidator('name',new sfValidatorString(array('required'=>true)));$this->setWidget('email',new sfWidgetFormInput());$this->setValidator('email',new sfValidatorEmail(array('required'=>true)));$this->setWidget('comments',new sfWidgetFormTextarea());$this->setValidator('comments',new sfValidatorString(array('required'=>true)));
parent::setup();}}
<?php
class PublicContactForm extends BaseForm
{
public function setup()
{
// this is required, don't forget this!
$this->widgetSchema->setNameFormat('contact_form[%s]');
$this->setWidget('name', new sfWidgetFormInput());
$this->setValidator('name', new sfValidatorString(array('required' => true)));
$this->setWidget('email', new sfWidgetFormInput());
$this->setValidator('email', new sfValidatorEmail(array('required' => true)));
$this->setWidget('comments', new sfWidgetFormTextarea());
$this->setValidator('comments', new sfValidatorString(array('required' => true)));
parent::setup();
}
}
Why did I use Public in the name? It reminds me that it's a public facing form, most likely using a custom-ish template, which I may need to update if I change the form much.
4. The Action
Here's a hearty chunk of where we're going to end up. Let's start by taking a look at the final form of the file, and then we'll highlight portions.
<?php/**
* contact_form actions.
*
* @package your-project
* @subpackage contact_form
* @author Jacob Mather
* @version SVN: $Id: actions.class.php 23810 2009-11-12 11:07:44Z Kris.Wallsmith $
*/class contact_formActions extends sfActions
{/**
* Executes index action
*
* @param sfRequest $request A request object
*/publicfunction executeIndex(sfWebRequest $request){$this->form=new PublicContactForm();if($request->hasParameter('contact_form')){// we're getting the parameters for the form, let's bind and see what happens$this->form->bind($request->getParameter('contact_form'));if($this->form->isValid()){$values=$this->form->getValues();$text_msg='You have received a message!'."\r\n\r\n";$html_msg='You have received a message!<br /><br />';foreach($valuesas$name=>$value){$text_msg.=$name.':'."\r\n".$value."\r\n\r\n";$html_msg.=$name.':<br />'.$value.'<br /><br />';}$text_msg.='Thanks!';$html_msg.='Thanks!';$from=array('my-app@example.com'=>'My Application');$to=array('replace-with-your-email@example.com');$message=$this->getMailer()->compose($from,$to,'Contact Form Submission');$message->setBody($html_msg,'text/html');$message->addPart($text_msg,'text/plain');$this->getMailer()->send($message);$this->getResponse()->setTitle('Thanks for contacting me');return'Thanks';}}$this->getResponse()->setTitle('Contact Me');return'Form';}}
<?php
/**
* contact_form actions.
*
* @package your-project
* @subpackage contact_form
* @author Jacob Mather
* @version SVN: $Id: actions.class.php 23810 2009-11-12 11:07:44Z Kris.Wallsmith $
*/
class contact_formActions extends sfActions
{
/**
* Executes index action
*
* @param sfRequest $request A request object
*/
public function executeIndex(sfWebRequest $request)
{
$this->form = new PublicContactForm();
if ($request->hasParameter('contact_form'))
{
// we're getting the parameters for the form, let's bind and see what happens
$this->form->bind($request->getParameter('contact_form'));
if ($this->form->isValid())
{
$values = $this->form->getValues();
$text_msg = 'You have received a message!'."\r\n\r\n";
$html_msg = 'You have received a message!<br /><br />';
foreach($values as $name => $value)
{
$text_msg .= $name.':'."\r\n".$value."\r\n\r\n";
$html_msg .= $name.':<br />'.$value.'<br /><br />';
}
$text_msg .= 'Thanks!';
$html_msg .= 'Thanks!';
$from = array('my-app@example.com' => 'My Application');
$to = array('replace-with-your-email@example.com');
$message = $this->getMailer()->compose($from, $to, 'Contact Form Submission');
$message->setBody($html_msg, 'text/html');
$message->addPart($text_msg, 'text/plain');
$this->getMailer()->send($message);
$this->getResponse()->setTitle('Thanks for contacting me');
return 'Thanks';
}
}
$this->getResponse()->setTitle('Contact Me');
return 'Form';
}
}
I think you'll find the form pretty self explanatory, though I'll cover a couple things.
The first thing to point out, I didn't return sfView::SUCCESS, or sfView::ERROR. Why not? Simple. I wanted to keep the names of the files within the context of what they're doing. We have two views we will use, the form, and the thank you page, so we will use two templates, indexForm.php, and indexThanks.php. I think that keeps things pretty obvious, how about you?
The next thing to point out, is we're just using a single action! Why? Well, why do we need more than one action? We need the form object to display an error, and we can easily detect if someone has submitted the form (that is what $request->hasParameter('contact_form') does), so why not just roll it into one compact bit.
Lastly, yes, I put a lot of effort into the outgoing emails. I always send an HTML and a plaintext part. It's my personal preference, but it takes so little effort to deliver a professional solution even in a simple example, it feels sloppy not to.
5. The Templates
As I mentioned in the last section, we need two templates. indexForm.php and indexThanks.php.
As you can see, it's a pretty simple setup. I did some inline styles for the form, though in a larger project you would want those to be in a stylesheet include. The indexForm.php should serve you well as a base for further forms, as it includes support for a few things we don't use in this form (help, global errors), which should help you make things 'just work' in the future.
6. Routing
Ok, so we've made everything, set it up, made it look visually nice enough to not want to stab our eyes out too much, now it's time to put the icing on the cake: the route.
This is real simple. Open apps/frontend/config/routing.yml
contact_form:
url: /contact-me
param: { module: contact_form, action: index }
contact_form:
url: /contact-me
param: { module: contact_form, action: index }
And you're all set! Clear your cache, and you're ready to go:
./symfony cc
./symfony cc
Now navigate to your /contact-me page, and you will see your contact form!
Let's try something a little new, and show a screencast of the finished product! Let me know how you like it!
Apparently I have been misusing the symfony name. It is "symfony" not "Symfony", not "Symfony 1", just "symfony". I recently went through a slideshow by Kris Wallsmith. Ten of the first thirteen slides are dedicated to this. Anyone else find that oddly statistically significant?
I am terribly sorry, I beg forgiveness, please let me keep my fingers!
Someone pointed out to me (quite correctly) that while the solution I offered before would work, it wasn't testable, so I just wanted to make a quick note on how I would solve that.
The easiest solution I see, would be using the Symfony Event system.
For the sake of simplicity, I'm going to keep the listener and init code within the object. I feel it keeps maintainability better, and it allows for easy mock extension and overriding with explicit test code.
WARNING: I have not played with events yet. This is how I see it playing out, but I'm sure this steps on a few best practices. Feel free to let me know if you have a better implementation idea and I will update this page or give you a direct reference to your blog, whichever you prefer.
Here's how I see the Model looking with this change:
<?phpclass MyObject extends Doctrine_Record
{publicfunction setUp(){
parent::setUp();
static::initEventListener();}protected static $listenerInitialized=false;public static function initEventListener(){if(ProjectConfiguration::hasActive()&&self::$listenerInitialized==false){
static::doInitEventListener();self::$listenerInitialized=true;}}public static function doInitEventListener(){$dispatcher= ProjectConfiguration::getActive()->getEventDispatcher();$dispatcher->connect('MyObject.object_updated',array('MyObject','clearCacheEntries'));}// We could force-type this to sfEvent, but we don't /actually/ look at the event object...//so there is no need to require it.public static function clearCacheEntries($event=null){
cacheAssistant::clearCachePattern('**/**/pages/index');}private$pendingChangeNotification=false;publicfunction preSave($event){if($this->isModified())$this->pendingChangeNotification=true;}publicfunction postSave($event){if($this->pendingChangeNotification&& ProjectConfiguration::hasActive()){$dispatcher= ProjectConfiguration::getActive()->getEventDispatcher();$dispatcher->notify(new sfEvent($this,'MyObject.object_updated'));$this->pendingChangeNotification=false;}}}
<?php
class MyObject extends Doctrine_Record
{
public function setUp()
{
parent::setUp();
static::initEventListener();
}
protected static $listenerInitialized = false;
public static function initEventListener()
{
if (ProjectConfiguration::hasActive() && self::$listenerInitialized == false)
{
static::doInitEventListener();
self::$listenerInitialized = true;
}
}
public static function doInitEventListener()
{
$dispatcher = ProjectConfiguration::getActive()->getEventDispatcher();
$dispatcher->connect('MyObject.object_updated', array('MyObject', 'clearCacheEntries'));
}
// We could force-type this to sfEvent, but we don't /actually/ look at the event object...
//so there is no need to require it.
public static function clearCacheEntries($event = null)
{
cacheAssistant::clearCachePattern('**/**/pages/index');
}
private $pendingChangeNotification= false;
public function preSave($event)
{
if ($this->isModified())
$this->pendingChangeNotification= true;
}
public function postSave($event)
{
if ($this->pendingChangeNotification && ProjectConfiguration::hasActive())
{
$dispatcher = ProjectConfiguration::getActive()->getEventDispatcher();
$dispatcher->notify(new sfEvent($this, 'MyObject.object_updated'));
$this->pendingChangeNotification= false;
}
}
}
This way, you could even attach a mock event listener by overriding doInitEventListener to attach a different processor to the event, or overriding clearCacheEntries. It does add quite a bit of complexity to the setup, but if you're concerned about testability, this would let you accomplish the same goals.