04.08.09

sfAdminDashPlugin - The Symfony Admin Plugin that Makes me Look Professional

Posted by ryan in php, symfony


Nightmares of the ugly backends in my past
Oh the horror!
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.

The sfAdminDashPlugin in action

Play with sfAdminDashPlugin:
http://www.thatsquality.com/backend.php

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 packaged 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...
Thanks for the shares!
  • StumbleUpon
  • Sphinn
  • del.icio.us
  • Facebook
  • TwitThis
  • Google
  • Reddit
  • Digg
  • MisterWong
Posted by stefan on 2009-04-10
does it support theming? because this makes the backend look like Joomla!, and that's quite ugly.
Posted by Ryan on 2009-04-10
@stefan - Ha yes, you hit the nail on the head. The plugin is based directly off of Joomla! No theming at this point - but that just requires someone creative (unlike me) chopping out some CSS. At any rate, a Joomla-looking backend is WAY better than what I had before (see pic at top).

Maybe someone creative can come to my rescue?
Posted by Kevin Bond on 2009-04-10
Ryan, thanks for writing this post and especially the criticisms - I was not aware of some of these. The next version is actually going to be an admin theme and should address the issue of 'manual removal of the symfony admin css'.

A theme system would be great - I hope to implement that in a future version. I am not at all graphically inclined so a Joomla cloned theme was the best I could come up with :).

I should mention that this plugin is an extension of a blog article by Carlos Barrows: http://blog.barros.ws/2008/10/29/joomla-like-theme-for-symfony-admin-generator/ so I shouldn't take full credit.
Posted by Y?lmaz U?urlu on 2009-04-20
It looks like very nice. Breadcrubms, dropdowns really great. With css theming this plugin would be great.
Posted by R on 2009-04-20
Ylmaz, actually it has css theming! check the /web - Dir!
Posted by Adrián on 2009-06-22
Hi, I have installed and configured your plugin, but I do not work correctly using the credentials.

I put a piece of my schema.yml:

"Departures":
credentials: [[admin, stock]]
items:
Departures:
url: departures
image: departures.png
credentials: [[admin, stock]]
Departures Article:
url: departures_x_article
image: departures.png
credentials: [[admin, stock]]
"Orders":
credentials: [[administrator, business]]
items:
Delivery order
url: orders
image: orders.png
credentials: [[administrator, business]]
Items Ordered:
url: orders_x_article
image: orders.png
credentials: [[administrator, business]]

As a business, I still see the icons of the departures.
Posted by Ryan on 2009-06-22
@Adrián

Sorry for my bad commenting - but I can see what you're doing. I can't say what's wrong - your code looks fine to me. I'm not actually the creator of the plugin, but you can find him here: http://www.symfony-project.org/plugins/sfAdminDashPlugin
Posted by Alex Stoneham on 2009-08-12
All menu items shown if not authenticated...... - Make sure you post back to this blog or something if this ever changes.
Posted by Michou on 2010-01-20
If you don't want all menu items to be shown if not authentificated you have to modifie the file plugins/sfadminDashPlugin/lib/sfAdminDash.class.php
You must delete line 24 and 27
Posted by Tanha on 2010-03-11
Hi,
I configured the plugin, but it does not display the menus item on the dashboard page, but the place holder for the menu items is obvious.

The second problem is that the filter on the admin page displays on the top-right, not on the right side of the list.

Any idea please?
Posted by /., on 2011-05-30















/.,