Ideas about in-place editing with datamanager

Greetings!

This is still an incomplete draft, but just to give you an idea what  
I'm planning.

Oh, and another thing. With this plan I would propose making  
Prototype the default JS/AJAX library of MidCOM. We duplicate lots of  
its functionalities now in o.o.helpers, but that can be changed.

Edit-in-place for midcom.helper.datamanager
===========================================

This is a specification on how to enable in-place editing in any  
MidCOM view utilizing the midcom.helper.datamanager component. This  
would make specific editing screens partially obsolete and greatly  
improve the MidCOM user experience. Obviously, like all AJAX  
functionalities, this should be kept optional.

## Inspiration

I've been thinking about this ever since seeing the [Usable  
XMLHttpRequest in Practice][2] article and implementing some of the  
AJAX in-place editors (hour reporting and group member titles) in  
OpenPsa2.

What finally got me into action, however, was the simple tutorial on  
[Edit-in-Place at 24 ways][1].

## Why Datamanager 1?

I've done this specification with Datamanager 1 in mind for three  
reasons:

1. If we want to support in-place editing in MidCOM, we should  
support it everywhere. And most components still use DM1
2. I don't have any practical, or code-level experience with DM2
3. My test environment on the laptop can currently only run MidCOM 2.4

## Enabling in-place editing

As in-place editing should be easy to turn off, it should be a  
boolean configuration parameter in datamanager. Later we could think  
of making the whole "AJAX or no AJAX" choice global user preference  
in MidCOM.

## Hijacking the HTML output

The idea of in-place editing is to hijack user's HTML output of  
datamanager-abstracted fields and insert some DM-related JavaScript  
event handlers there.

When the datamanager array is fetched for display purposes in the  
`get_array()` method we should check for a possible lock. If the  
document hasn't been locked, then in-place editing can be enabled.  
Similar checks should be done for permissions.

Each variable returned by `get_array()` should be surrounded by a  
`<span class="midcom_helper_datamanager_<GUID>  
midcom_helper_datamanager_field_<fieldname>" />`. This will be all  
the trigger that our script will require, as it can then find all the  
instances using `getElementsByClassName`.

### Issues with inserting HTML

Some default templates will display datamanager fields using the `& 
(view['fieldname']);` syntax which will mean that the inserted HTML  
gets quoted. However, we can tune all default templates, and advice  
site designers about it.

### Working before output

We also need to place an `init` call for the in-place editor for each  
datamanager instance on the page. As the only place we can do this is  
before output, it probably should be done in the datamanager `init()`  
function. If some datamanager instance is initialized after output is  
sent, then that instance will not be in-place editable.

Similarly, the return values of the XmlHttpRequest saves must be  
handled before regular output.

## Editing cues

The in-place editor initialization will add an `onMouseOver` event  
handler for all fields managed by editable datamanager instances.  
When user passes her mouse over an editable field, its background  
will turn yellow.

When clicked, the field should be turned into the appropriate  
datamanager widget and an AJAX call made to lock the object.

__TODO:__ How to actually render the correct widget? Should be done  
by DM, maybe via AHAH: Fetching the results of something like the  
following:

     ob_start();
     $widget =& $this->_datatypes[$_GET['show_widget_for_field']]- 
 >get_widget();
     $widget->draw_widget_start();
     $widget->draw_widget();
     $widget->draw_widget_end();
     $ajax_message = ob_get_clean();

To reduce confusion, all other DM in-place editors should be made  
inactive while one is being edited. We can possibly grey them out to  
make this more apparent.

## Handling saves

Saves from the in-place editing should be handled in the datamanager  
`init()` method.

The actual form will store its contents using a HTTP POST, and the DM  
`init()` method will reply using a simple XML message noting success  
or failure.

[1]: http://24ways.org/advent/edit-in-place-with-ajax
[2]: http://www.baekdal.com/articles/usability/usable-XMLHttpRequest/

Henri Bergius
Consultant Partner, Nemein
henri.bergius-ZpG/[email protected]

Midgard CMS
www.midgard-project.org