#web-app-theme

A good administration dashboard is key.  The whole reason behind an admin panel is to allow for human heuristic fine tuning of an app.  We need these either constantly or often, in order to maintain some aspect that just cannot be solved with computer magic (though many will argue that there is always a way, but the tradeoffs in some cases are not worth it).  Because of this, an aesthetically beautiful and equally easy to use admin interface is as important, if not more, than a user facing interface.  For computers, you want them to crank through really gross algorithms that would otherwise be impossible to maintain in your own brain.  For administrators, you want to make the experience of administering a site as pleasant and easy as humanly possible.

The big reason why people neglect and cut corners on admin facing pages is because "nobody ever sees it except us."  But isn't that the most important thing?  If you as employees only see the shittiest parts of your app all the time, or subject poor interns and new hires to this awful task, it just shows how little attention to detail you give to making your app hum like a well oiled engine.  When you develop any part of your code, always ask yourself if this is quality you are proud of, internal and external to your own company.  At some point horrible admin panels will just pile up, and there's no turning back.

If you start with a slick looking admin panel that works great and is easy to maintain when things change, then you will always have an awesomely tuned app with consistently great admin controls.  If you start with quite a grotesque arrangement of links and badly styled form fields, anything slicker than that just makes what you've built already look even uglier.  It's a bad snowball to be in.

It's easy to choose admin pages to cut corners on, because there's never an imminent need for them.  The time it saves is clearly good initially, but leads to plenty of cursing and swearing later on.  So what's the solution?  In some frameworks, such as Ruby on Rails, there are nice little things like Active Scaffold.  Unfortunately DHH and the rails maintainers aren't the world's best designers.  The usability, looks, and consistency are all pretty bad using the built in utilities.  At FanPulse, our current admin looks good, works great, is easy to maintain, and is even easier to expand on.  What we did is we used the somewhat popular web app theme utility for our rails based app called, "web-app-theme" by Pilu.  I guess it's not that clever of a name, but it works like it reads.

The tool is actually a ruby script that can be used with the script/generate command.  It basically sweetens up an existing active scaffold, or any model based controller.  It even creates all the files from scratch to you.  It comes prepackaged with a dozen nice themes that are super clean and easy to use.  It took me less than a day to create an expansive admin panel that can help us keep track of, modify, and add new teams, players, leagues, divisions, conferences, sports, beta users... you name it!  This will save us hundreds and hundreds of hours of work, and make administering the app just a tad less tedious.  Of course, if your app requires tons of administrative work constantly, there's some other decision that has gone wrong.  In our case, we need to do some fine tuning once to make sure all our data is totally perfect.  It's also great for adding new beta users and all that jazz.

The web-app-theme generator is geared towards being a good launch point for an entire web app, not just an admin panel.  I'm not that excited to take these designs and showing them to the world, but they look and feel great for administrative purposes.  So I've tapped into using it exclusively in an admin only side of our app.

They key to making it an admin only app, is to use elegant Rails Namespaces, which came about in the rails Changeset 6594.  This allows you to group controllers for specific models inside a namespace.  I chose the namespace called "admin".  This effectively gave me the ability to create a subdirectory in the app/controllers directory called "admin".  Then under there were all my individual controllers for individual models.  My routes.rb looked as so:

    map.namespace :admin do |admin|

    # The below resource mapping directs /admin/teams/* to Admin::TeamsController (app/controllers/admin/teams_controller.rb)

    admin.resources :teams

    admin.resources :players

    admin.resources :users

  end

  The above snippet shows how I have a model controller for each model.  By doing this, you can maintain a super restful way to setup your controllers, using the usual index, show, edit, update, new, create, destroy actions with their respective get, put, and delete request methods.  Also maintains a great way to use named routes with: admin_teams_path to goto the index action of the teams controller under the admin namespace.  Another example is new_admin_team_path for going to the new controller.  One thing to note is for other mentions of controllers outside of this admin namespace, use a prepended slash to specify no namespace.  For example:

redirect_to :controller => '/session', :action => 'new'

The above takes you out of the admin namespace because of the prepended slash in front of session.  Otherwise it will try to hit you with admin/session controller, which probably doesn't exist.

Once you've installed the web-app-theme generator, and setup your routes, you can then create initial admin layout and styles:

$ ruby script/generate themed admin --theme="drastic-dark"

The generator is called "themed" and the parameter "admin" is what we want the layout to be named, in this case it will automatically create an "admin.html.erb" layout file for you.  The option "--theme" is where you designate what theme style you want to go with.  Pick from here: http://pilu.github.com/web-app-theme

Once that's done, create a view for your first model controller (controller can be created after):

$ ruby script/generate themed admin/teams --layout=admin --with_will_paginate

The above will generate all the views for you under app/views/admin/teams using the layout we generated before as well as scaffolding the views up with will_paginate automatically.  Good if you have more than like 50 entries.  Then create your controller using the usual ActiveScaffold, but give it a namespace as well as a "global" layout:

class Admin::TeamsController < ApplicationController

layout 'admin'

...

The controller should be created inside the app/controllers/admin directory.  Given your routes were setup with admin.resources :teams, it should all be setup.  Oh and one last thing, if you used the will_paginate option, make sure you change the controller finds to paginate.  And that's it!  Do the same for all the other models you want to administer.  If you want to do one offs from models, it's easy to just use the usual template to put whatever you want in there.  Takes minutes, looks consistent, and is much nicer to use and expand on.

Make your employees happy in your startup, make the interns feel like they are not doing really sad work in, but actually being part of a really polished startup company.  Having a solid admin in your app is a huge indication of how well you plan everything you work on, including planning, researching options, and finding the most elegant and robust solution available.  If you can learn to use these tools quickly, you will go far in the rest of your development, user facing or not.