YamlHelp: a yaml-based help-file Rails plugin

tying on-screen help messages to controller actions

I recently set out to create a plugin for on-screen, context-sensitive help for my Rails applications using YAML formatted files. Example: 

# file doors.yml 
# corresponds to doors_controller.rb
# open/close action messages and icons
  ---
  open:
    text: Help message goes here
    image: open_door.gif
  close:
    text: Another help message
    image: close_door.gif

install: ruby script/plugin install 
  http://yaml-help.googlecode.com/svn/trunk

In a nutshell, the plugin allows you to create a library of yaml help files and tie simple messages and icons on the screen. Think of the '?' marks or "What's this?" links on Google or Amazon. However, instead of having static help messages interlaced in HTML, you maintain the help text in yaml files, structured by Rails controller actions.

The contents of the plugin README follows: 

YamlHelp
========
install: ruby script/plugin install http://yaml-help.googlecode.com/svn/trunk

A lightweight, yaml-based, in-context help system.
	
== VERSION
0.1

== USAGE
* Create a dir under app_root, for instance, app_root/help.
* add yml help files corresponding to controllers.
	- app/controllers/doors_controller.rb ~~ help/doors.yml
* create nodes corresponding to controller actions
	---
	open:
	  text: Help message goes here
	  image: open_door.gif
	close:
	  text: Another help message
	  image: close_door.gif
	  
* create instances of YamlHelp in controller actions, such as 


  

  class DoorsController < ApplicationController
    def open
      help = YamlHelp.new('doors', "#{RAILS_ROOT}/help") 
      @help_msg = help[:doors][:open]["text"]
      @help_image = help[:doors][:open]["image"]
    end
  end







Then reference instance vars in the view:



  

  <!--open.rhtml-->
  <%= image_tag @help_image %>
  <span class="help"><%= @help_msg %></span>







== TROUBLESHOOTING
* There is a known issue with the default path for help files. Make sure to send the 2nd
  argument to the constructor as shown above.
* Make sure your help files have a .yml extension.
* Currently, there is no consideration for namespaced controllers, so Admin::DoorsController 
  and DoorsController correspond to the same help file.

== MORE
* I use the Prototype Window Class (http://prototype-window.xilinus.com/) Tooltip javascript
  lib with YamlHelp and create hidden div's containing, for example, @help_msg above which
  pops up when the user hovers over the image_tag above.
	
== TODO
* DRY up help[:doors][:open]["text"] (too long)
* store YamlHelp object in memory or otherwise cache yaml help files

Posted by Luke on Friday, June 22, 2007

Comments (3)


Michael on Thursday, April 10, 2008

This looks like a great plugin and I’ve given it a go and I love it. I was wonder however does it support internationalisation or will it in the future?

Luke on Monday, April 14, 2008

Michael,

Good question. I’m thinking that you could easily modify the YamlHelp ctor to accept another param, something like ‘en-us’, then pull help files from localization dirs (esp, fr, den, etc.)—same structure as say a Notepad++ ... any other ideas?

Michael on Tuesday, July 29, 2008

Just a Tip for anyone using yamlhelp, you can format your yaml file over multiple lines by using quotes around your strings.

EG: general: heading: General Help text: ” <table> <th>Function</th> <th>Description</th> </table>”