Inline Edit Samples?

[Anastasia Cheetham]

[Side comment: I am so pleased to have someone looking at our  
documentation and asking questions! It is making the holes in the  
documentation very apparent, and I'm looking forward to plugging them.]

On 30-Jul-09, at 8:53 AM, Aaron Zeckoski wrote:

> I was actually hoping for something a little like jquery does with
> their docs where they show simple usage. The tutorial seems to mostly
> just talk about the markup and how it needs to be changed to work with
> the inline edit stuff. That was somewhat helpful but it did not
> actually include the sample JS I was looking for.

Aaron, this is a good point regarding our docs. We do need some very  
straightforward, complete examples along the line of "If you want to  
do this, write that." And our tutorials and samples are definitely  
lacking information about the event handlers.

> 1) I mark all my things I want to be editable with an id like
> "some-thing_date_111" (where 111 is the id of the thing to be edited)
> and a class "fluidInlineEdit".

Another hole in the documentation... We don't really explain the  
various parts of markup that the InlineEdit component is interested  
in, and how they relate to each other, and which  parts are required  
and which are optional.

What is the basic markup that you want to make editable? If you  
provide a snippet, I can clarify which bits will need to have some  
kind of id or class on them.

But basically:
Yes, what you've described should work: On the container of each  
editable text, you could attach an id or a class, and use that id or  
class to identify the first parameter to fluid.inlineEdit() (see  
comment A below for more).

> 2) I use jquery to get all the thing elements and then call (where
> thingElement is my componentContainer which holds the text to be
> edited):
> fluid.inlineEdit(thingElement, {
>    useTooltip : true,
>    tooltipDelay : 500,
>    listeners: {
>       onFinishEdit: saveThing
>    }
> });

This is basically right, but with a few tweaks.

A) You don't need to "use jQuery to get all the thing elements"  
yourself. The first parameter to fluid.inlineEdit() can be a jQuery  
object, but it could alternatively be a selector (e.g. "#some- 
thing_date_111") or a DOM element. If you don't pass a jQuery object,  
the component will create one for you.

B) If you have multiple things that you would like to have configured  
as inline-editable in the same fashion, there is a convenience method  
that will do all of them for you in one go:

     fluid.inlineEdits(editables, options)

In this form, the editables parameter is an *array* of the elements/ 
selectors/jQuery objects that you want to be editable. The return  
value will be an *array* of the InlineEdit components.

C) There are two events associated with the 'finish edit':  
onFinishEdit and afterFinishEdit. The difference between 'on' and  
'after' events is *when* they are fired in relation to the thing they  
are referring to. 'on' events fire *before* the action in question  
actually happens, and 'after' events are fire *after*. In your case,  
since you want to trigger a save, you should use the 'afterFinishEdit'  
event. The 'on' event is more suitable for validation-type handlers  
that might want to actually prevent the action from happening. In  
fact, in this particular case, the 'onFinishEdit' is fired before the  
new value is even stored in the model, so if you save then, you  
wouldn't be saving the new value.


> 3) I get the id from the viewNode and do the save in my saveThing  
> function.

You do not need to access the element to retrieve the new value. Your  
afterFinishEdit event handler, saveThing(), will be passed four  
parameters: newValue, oldValue, editNode, viewNode. (This is described  
in the Supported Events section of the API documentation.) You can  
simply save the newValue, if you like.


I hope this helps. Please keep the questions coming!

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto