Symfony has been nominated for the following 3 Community Choice Awards:

• Best Project
• Best Tool or Utility for Developers
• Best Project for the Enterprise

Now, while I don't really understand the importance behind these awards, but if you're half the symfony nerd I am, you should get on over there and vote.

One of the most common and, until recently ugly, sections I develop on most any website is a admin area for my client. Fortunately, with symfony's admin generator, you can skip most of the heavy lifting and feel comfortable with your useful and professional-looking admin areas. Unfortunately, two additional common requirements of most admin areas include 1) a layout and 2) navigation. While simple, these two things should also be attractive and functional. Until I started using the sfAdminDash plugin, mine were ugly. Really really ugly.

The Solution - sfAdminDash for an attractive admin area

The sfAdminDashPlugin is maintained by Kevin Bond (not by me) and as of this morning, is confirmed to be used by 8 people (let's get this up higher!). The best way to get a feel for it, is to play around with the plugin. This admin area let's you play around with the todo list items as well as both the author and publication items seen in previous posts.

Configuring the Plugin

Below are the steps I followed to configure the plugin. The official ReadMe is great (I reference it below) and should be used as well.

1. Create a backend application

While splitting your site into 2 different applications (one for the frontend and one for the backend) isn't necessary, I recommend it. Back in the day, I chose to fit both my frontend and backend modules into the same application so that I could more easily link between the two and control the cache. I now disagree with past-self. If you need to communicate between your applications, you can initialize a new context of the other application, which actually proves to be pretty easy. Fabien illustrates this approach using the routing system here.

  ./symfony generate:app backend

2. Configure Your backend Application

This is the easy housekeeping step, so I won't repeat the obvious. Check the plugin's official page for more details. Here's a concise list of what you need to do:

• Enable the module 'sfAdminDash' in settings.yml
• Run ./symfony plugin:publish-assets
• Customize your layout.php file
• Make the homepage route point to sfAdminDash/dashboard (optional)
• Secure your application via apps/backend/config/security.yml

3. Configuring Your Admin Menu in app.yml

The highly-configurable admin navigation drop-down menu is the real high point of this plugin. Everything is configurable from within the app.yml file. Here's what mine looks like:

all:
  sf_admin_dash:
    web_dir:              /sfAdminDashPlugin
    image_dir:            /sfAdminDashPlugin/images/icons/
    default_image:        config.png
    resize_mode:          thumbnail
    logout:               yes
    site:                 Thatsquality.com Admin
    include_jquery:       yes
    
    categories:
      "Todo List":
        credentials:      [todo_credential]
        items:
          Todos:
            url:          todo
            image:        checkin.png
      "Authors & Books":
        credentials:      [[author_credential, publication_credential]]
        items:
          Authors:
            credentials:  [author_credential]
            url:          author
            image:        users.png
          Publications:
            credentials:  [publication_credential]
            url:          publication
            image:        addedit.png

For a more complete reference, please see the official plugin page. The menu can be configured either by groups (as you see here) or by just a flat list of items. In either case, credentials can be added so that you can control what type of user see which items. The nice part is that these credentials can be added at the group level or at the item level (both are seen above).

One of the most attractive features of this plugin is that it comes with a short list of icons that you can use to really make your admin area shine. These are available in the sfAdminDashPlugin/web/images/icons folder and you can configure each item to use any icon via the image parameter seen above.

4. sfGuardPlugin and Hooking up the Cute Login Screen

While you can use this plugin without it, it's almost always a good idea to use sfGuardPlugin. Information on installing and configuring sfGuardPlugin can be found here. I'll assume you've got this all setup already.

sfAdminDash comes packged with a cute login screen I like to use. With sfGuardPlugin, this is easy. To do this, we'll create an sfGuardAuth module so that we can override a few files from the plugin (specifically the signinSuccess.php template and the actions.class.php file).

  mkdir apps/backend/modules/sfGuardAuth
  mkdir apps/backend/modules/sfGuardAuth/actions
  mkdir apps/backend/modules/sfGuardAuth/templates

// apps/backend/modules/sfGuardAuth/templates/signinSuccess.php
<?php include_partial('sfAdminDash/login', array('form' => $form)); ?>
  
// apps/backend/modules/sfGuardAuth/actions/actions.class.php
<?php
require_once(sfConfig::get('sf_root_dir').'/plugins/sfGuardPlugin/modules/sfGuardAuth/lib/BasesfGuardAuthActions.class.php');
class sfGuardAuthActions extends BasesfGuardAuthActions
{
  public function preExecute()
  {
    sfForm::disableCSRFProtection();
  }
}

The modification to the actions.class.php is necessary because the login form doesn't add the csrf_token, so if you try to use one, an error will be thrown. I think this is a mistake, and the plugin should - at the very least - check to see if our form is using a csrf_token and display it if it is. But maybe I'm not considering something?

A Few Complaints

The beauty of this plugin is that it's quick and dirty, but leaves you with an attractive and functional admin section. On that note, I only have a few complaints, and they're pretty minor. Overall, I think this plugin rocks!

• Manual removal of the symfony admin css
  If you use symfony admin-generated modules, the sfAdminDash plugin includes a css file that will spruce them up in the style of the layout. Unfortunately, for this to work, you need to add a line in your generator.yml file that blocks the symfony default css file from being loaded. I'd like it if this were done automatically (with perhaps a flag in app.yml to disable the automatic removal of the css file).
• All menu items shown if not authenticated
  There's some weirdness here. If a user arrives, unauthenticated, to a module that is NOT named sfAdminAuth (no idea where this module name comes from) or an action NOT named signin, that user will see ALL of the admin menu items (even if app.yml says that they shouldn't see them). This isn't really a security risk (users still cannot access those modules, assuming you've setup your security.yml correctly), but it is kind of a bummer. This is the one line I've hacked in the plugin.
• Drop-down menu heads don't return false
  I hate when I click fake links and I get the hash (#) at the end of my url. The admin menu heads should return false to avoid this. Hmm, this complaint makes me seem whiny...