MirthLab

Have you ever wanted a simple rollover technique with a form submission button? Something like this:

… without having to resort to a complicated mess of javascript form submission and cross browser compatibility issues?

With jQuery it’s really easy. All you need to do is include a standard image form submission tag, like so:

<input type="image" name="submit" id="submit" src="enter.gif">

… and add the hover behavior to the submit input tag. Something like this:

<script type="text/javascript" charset="utf-8">
    $(document).ready(function(){
        $('#submit').hover(
            function(){ // Change the input image's source when we "roll on"
                $(this).attr({ src : 'enter_over.gif'});
            },
            function(){ // Change the input image's source back to the default on "roll off"
                $(this).attr({ src : 'enter.gif'});             }
        );
    });
</script>

This is just a simple example, but you could definitely spruce it up if you needed something more elaborate by adding/removing CSS attributes and the like. Check out the jQuery documentation for more on the hover event.

The benefit of using this method is that the form will be submitted using the standard form submission action, rather than by calling submit() directly through javascript like with other techniques I’ve seen. This has the added benefit that standard form handlers like “onSubmit” will still work whereas, using the submit() method directly will bypass these handlers.

The concept of “Symfony applications” is sometimes confusing for those new to Symfony, but they can be a very powerful way to break up the functionality of a project. The classic example for this separation is the “front end” and “back end” or “back office” applications. The idea here being that the front-end will be what the normal user sees and he back-end being what the administrator of the site uses to maintain the site through an admin interface. Since these two applications are in the same Symfony project, they can share certain common elements (such as database configurations and schemas), but they can have their own modules and templates. In essence, each application can provide a different “view” of the same data.

If you only have one application, you’re probably content with the way Symfony automatically sets up your first application to use the default index.php controller, but what happens when we add applications? You’ll notice that Symfony adds controllers for each application in the web directory, so you might end up with a set of files like this:

web/index.php
web/frontend_dev.php
web/backend.php
web/backend_dev.php

… assuming you have a “frontend” and “backend” application. Also, note that since we created the “frontend” application first, Symfony automatically used the index.php filename for what would have been called frontend.php.

So, this means that when we view our site at www.mysite.com/ the frontend application is loaded and when we view www.mysite.com/backend.php we get the backend application. This is fine for most uses, but what if we could streamline this a bit so that applications were loaded based on a sub-domain?

That’s exactly what we’ll do.

Setting It Up

First, we’ll rename our index.php file to frontend.php (this will be useful later on) and create a new, blank index.php controller in its stead. Our controllers should now be as follows:

web/index.php (blank!)
web/frontend.php
web/frontend_dev.php
web/backend.php
web/backend_dev.php

Open up the newly created index.php file. We’re going to add a little bit of our own logic here so that Symfony dynamically loads the correct application based on what’s set in the sub-domain:

<?php
// define the standard symfony environment constants
define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);

// get the domain's parts
list($tld, $domain, $subdomain, $subdomain2) = array_reverse(explode('.', $_SERVER['HTTP_HOST']));

// determine which subdomain we're looking at
$app = ($subdomain == 'staging') ? $subdomain2 : $subdomain;
$app = (empty($app) || $app == 'www' ) ? 'frontend' : $app;

// determine which app to load based on subdomain
if (!is_dir(SF_ROOT_DIR.'/apps/'.$app))
{
    define('SF_APP','frontend');
}
else
{
    define('SF_APP',$app);
}

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.
'config'.DIRECTORY_SEPARATOR.'config.php'); // Should be on one line, with the above text
sfContext::getInstance()->getController()->dispatch();

Note: I generally use a “staging” sub-domain for testing on the production server before pushing to the actual production site, so you’ll notice that I check for this sub-domain separately. This is so I can use something like backend.staging.mysite.com and still load the correct back-end application. Feel free to simply remove that step if you want your staging sub-domain to point to an actual Symfony application for some reason.

This controller file should look familiar to you as it’s just a bit of a reworking of a default controller. We simply added some logic to detect a subdomain, check if it’s a valid application and then, if it is, we have Symfony load it dynamically. You’ll notice that instead of using frontend.mysite.com for the front-end we simply check for www or an empty sub-domain field and set the application to “frontend” by hand. If your default application name is something different, you’ll have to change this.

Some Notes About This Method

Firstly, you should know that this method will only work if you have the correct sub-domain addresses as DNS records pointing to your server (or if you have wildcard DNS set up so that anything.yoursite.com is sent to your server).

Also, for clean URL rewriting on each sub-domain, don’t forget to set no_script_name to “on” in each application’s settings.yml file for the “prod” environment:

prod:
  .settings:
    no_script_name:           on

… this allows our sub-domains to use URLs in the form backend.mysite.com/module/action instead of backend.mysite.com/index.php/module/action. This is usually disabled by default for all but the first application you create (in our case, frontend).

Also, remember that file we renamed to frontend.php? Well, we did that for a reason. In previous articles, I’ve stated why I like setting up local development environments, so I won’t go into detail here, but you’ll notice with this method we can still access the frontend application directly by typing something like mysite.dev/frontend.php which may be useful for testing purposes. You could even create an index_dev.php that loads the dev environment for our custom front controller if you needed to. Note though, that I’m specifically not including support for a “dev” sub-domain (or anything that loads the dev environment) since the dev controllers should not live on your production server!

So What?

You might be wondering what all the fuss is about. Why go through the trouble of setting up these dynamic sub-domains linked to Symfony applications? Well, as with many things, necessity is the mother of invention: for a project I’m working on right now, I needed to add an iPhone/iPod Touch specific site to an existing Symfony project. A separate Symfony application makes perfect sense since it will simply be a different view for the same data. It would have been easy enough to just use the default mysite.com/iphone.php controller, but I wanted it to be a separate sub-domain because it just feels better separating it out that way, and you get nice clean URLs and an easy to remember iPhone-specifc domain name to boot.

In another article, I’ll be publishing some tips for incorporating this method into a site that automatically detects an iPhone or iPod Touch and reacts accordingly.

If any of you are using the great sfLucene Plugin, here’s a quick tip on making your search results a bit more intuitive.

This really only applies to model results (not action results) as there’s an option to add a category to each model. Here’s an example search.yml file that would go in your project’s config folder:

MyIndex:
  models:
    Podcast:
      fields:
        id: unindexed
        title:
          type: text
        description:
          type: text
      title: title
      description: description
      validator: isPublished
      categories: [Podcast]

You can see that I’ve added the category “Podcast” to the model’s definition. Now, you can override the plugin’s default display for model results by creating a module in your project named “sfLucene” and overriding the default _modelResult.php partial (in the sfLucene/templates directory) with something like this:

<?php echo link_to($result->getsfl_category() .' &raquo; '. highlight_keywords($result->getInternalTitle(), $query, sfConfig::get('app_lucene_result_highlighter', '<strong class="highlight">%s</strong>')), add_highlight_qs($result->getInternalUri(), $query)) ?> (<?php echo $result->getScore() ?>%)
<p><?php echo highlight_result_text($result->getInternalDescription(), $query, sfConfig::get('app_lucene_result_size', 200), sfConfig::get('app_lucene_result_highlighter', '<strong class="highlight">%s</strong>')) ?></p>

The only thing we’re really changing from the default template is that we’re adding this:

$result->getsfl_category() .' » '.

…to the beginning of the call to the link_to() helper. The category is stored automatically by sfLucene in this field in the lucene document, so we have access to it in the template. This new partial effectively inserts the category in front of the “title” field (along with a “»” for separation) while building the link, which produces something like this:

Podcast » My Great Podcast Title

As you can see, if you have several model definitions this comes in handy while looking at a list of results since you’d get a nice listing that shows which category each link belongs to:

Podcast » My Great Podcast Title

Blog » This Is Some Article

Podcast » Another Awesome Podcast

… instead of just a bunch of titles in a list.

According to the Apple docs, you need to create a 57x57 PNG, name it “apple-touch-icon.png” and upload it to the root of your web directory in order for the iPhone to find and use your icon.

What I found more useful though, was that this can be overridden using a link attribute, similar to the way favicons are handled. This allows us to use symfony’s standard “images” directory to house the icon. So, the head of our layout.php could be updated with the addition of:

<link rel="apple-touch-icon" href="<?php echo image_path('apple-touch-icon') ?>" />

… which would make it look something like this:

Note: as this is a post on symfony, I’m using symfony’s built-in image_path helper, but this can be simply href="/images/apple-touch-icon.png" if you’re not into that.

Taking it a Step Further

The way the real power of symfony gets leveraged is when you want to have different icons for different sections of your site. Let’s say you wanted to have a different touch icon related to every different module in your symfony project. Symfony makes this really simple to do. Replace the existing link tag we made earlier with something like this:

<?php if (file_exists(sfConfig::get('sf_web_dir').'/images/webclip_icons/'.$sf_context->getModuleName().'.png')): ?>
    <link rel="apple-touch-icon" href="<?php echo image_path('webclip_icons/'.$sf_context->getModuleName()) ?>" />
<?php else: ?>
    <link rel="apple-touch-icon" href="<?php echo image_path('webclip_icons/apple-touch-icon') ?>" />
<?php endif ?>

Basically, this code just checks to see if there’s a Web Clip icon with the same name as the current module in /images/webclip_icons and if it finds it, it links to that one instead of the default one.

Of course, this is just an example of how powerful and easy this is. This idea could be extended in many different ways.

More Info

You can read more about iPhone development at Apple’s iPhone Dev Center. One of the more useful pages on that site is the one on Designing Content.

Also, as noted elsewhere, you seem to get a crisper icon if you use a 60x60 image at 72 DPI.

Media Temple’s Grid-Service is a great, low-cost solution for developing and deploying Symfony applications. This article will walk you through setting up a Grid-Server Subversion repository for use with a Symfony project. The main point here is being able to create and use a symfony project hosted on a Grid Server without having to have symfony pre-installed at all locally.

Setting Up Subversion

Symfony is designed to be used with version management software like Subversion. If you’ve never used versioning software, you should read about the benefits right from the Subversion book itself, but in general, it tends to make life easier for developing and maintaining large code bases as it tracks revisions between files and authors. Subversion is already installed in the Grid-Service environment, so all we have to do is set up a new repository. Media Temple has a knowledge base article describing the basic steps, but we’ll be tailoring things a bit to Symfony.

Be sure that you’ve enabled SSH access on your account. Personally, I like creating the repository using the serveradmin user, and then I’ll make commits using a local user on whichever domain I’ll be using. Let’s get started.

Once you’ve logged in via SSH as serveradmin, move into the data directory. This is where we’ll be creating the repository:

cd data

Then, create the base repository like so (substituting your own repository name for mirthlab):

svnadmin create --fs-type fsfs mirthlab

I tend to use separate repositories for each domain. This allows me to use a structure of the form:

mirthlab/
    project1/
        trunk/
        tags/
        branches/
    project2/
        trunk/
        tags/
        branches/
some_other_domain/
    project3/
        trunk/
        tags/
        branches/

… so I can effectively have as many projects related to each domain in version control as I need.

Now that we’ve created the repository, let’s create the base folder for the Symfony project. While still in the data directory, we’ll create a few new folders:

mkdir project1
mkdir project1/trunk
mkdir project1/tags
mkdir project1/branches

… where project1 is the name of your symfony project. This might all look familiar if you’re read through the Subversion documentation, but we’re going to add a couple of folders:

mkdir project1/trunk/lib
mkdir project1/trunk/lib/vendor

It’ll become clear in a moment why we’re doing this, but the short of it is that we’re going to link the Symfony libraries directly to the project itself using the lib/vendor folder. Once you’re done, commit the contents of your project folder to the repo like so:

svn import project1 file:///home/<site_number>/data/mirthlab/project1 --message "Creating initial repo."

Be sure to change <site_number>, mirthlab and project1 appropriately, so that they match your setup. Please note that this assumes you’re starting with a fresh Symfony project. If there’s an existing project you have that you want to import into the repository, these steps would vary slightly since you wouldn’t have to set up a lib folder.

The folder structure was imported into the repository, so you can safely delete the project folder skeleton we made from the data folder:

rm -rf project1

Set Up Additional SVN Users

This step is optional, but would be helpful if you’re going to allow multiple users to work on this repo. There’s also a Media Temple KB article for this if you’re curious. Log in to your Media Temple Account Center for your domain. Click on the “Email Users” button and add some local users.

I created a user “mark” for my domain. Also, be sure to check the “Enable SSH access?” checkbox:

Now, in order to allow other users to use the new repo, we have to give group access to the directory. From within the data directory run this command as serveradmin:

chmod -R g+w mirthlab

Again, being sure to substitute your own repository name for mirthlab.

Setting Up Symfony

Now that you have your base folder structure, it’s time to get the Symfony project initialized. Connect to your Subversion repository and download the trunk of our project by running the following commands locally. I’m on a Mac OS X box, so I’ll use the terminal to do a checkout of my project to the ~/Sites folder:

cd ~/Sites
svn checkout svn+ssh://your_user%your_domain.com@your_domain.com/home/<site_number>/data/mirthlab/project1/trunk project1

Note: svn checkout svn+ssh... should all be on one line. This creates a project1 folder in my Sites folder, which is just what I want. Now let’s get our Symfony project structure set up by linking the Symfony libraries to our lib/vendor folder with a subversion externals link.

cd project1
svn propedit svn:externals lib/vendor/

This should bring up your favorite text editor. Simply paste this line into the file, save and close it:

symfony http://svn.symfony-project.com/branches/1.0

This effectively links lib/vendor/symfony to the stable 1.0 branch of Symfony. Only security and bug fixes go into this branch, so there’s no need to worry about it breaking your app when running an svn up. Now, commit your changes back to the repository:

svn commit --message "Linking Symfony libraries to lib/vendor"

And when that’s done, update the local working copy to get the libraries:

svn up

Since we now have a local copy of symfony, we can use the symfony binary to execute pake tasks. Let’s flesh out our project by creating the initial structure using the init-project task.

lib/vendor/symfony/data/bin/symfony init-project project1

… where project1 is the name of our project. This doesn’t necessarily have to match the name of your repository project, but that’s usually what I use. This project name is used to set up defaults in files like propel.ini and properties.ini.

Also, be sure to change the path for the symfony libraries in config/config.php:

$sf_symfony_lib_dir  = dirname(__FILE__).'/../lib/vendor/symfony/lib';
$sf_symfony_data_dir = dirname(__FILE__).'/../lib/vendor/symfony/data';

… this just sets them up to use a relative path, instead of an absolute one (which we’ll need when we push this code to the production server).

We can now add the rest of the project to source control:

svn add *
svn commit --message "Added initial symfony project structure."

Subversion might complain that the lib folder is already under version control, but that’s ok.

Next Steps

Additional general info on Symfony and Subversion can be gleaned from Dave Dash’s excellent article: Tips for Symfony and Subversion. Read and follow the directions in that article to complete your setup by ignoring files in cache and log as well as other auto-generated files like the model files Propel generates.

Conclusion

With this setup, we now have a Symfony project under source control on a Media Temple Grid-Service account. We also now have symfony installed locally and which we can use by calling simply ./symfony from within our project directory. In the next article, we’ll take a look at getting our local development environment set up for editing on a Mac OS X box.