fi:styling/@in-place-tip

[Quoin Developers <qu...@gmail.com>]

Motivation:

CForms user would like to display instructions or some other hint to
the end user in the text input widget itself (as opposed to a tool-tip
on-hover). This text should not be submitted, and if a user wants to
enter text into the input, the tip text should automatically disappear
so that the user does not have to manually delete it.

We implemented this for a couple of projects. Most recently Antonio
Gallardo provided some suggestions as to how we might best integrate
this into CForms, and here are the results which we would like to
contribute this back to the cocoon community. We're open to
suggestions, but we'd like to keep it simple. The only additional
thing might be to set a different class attribute value for the input
element when the tip is being displayed. In this way, the tip text
could be styled distinctly.

Regards,
Eric Meyer
Rus Pandey

Implementation:

Add an fi:styling/@in-place-tip to the form template. For example:

<ft:widget id="startDate">
    <fi:styling in-place-tip="mm/dd/yyyy"/>
</ft:widget>


Details:

The forms-field-styling.xsl for fi:field adds some javascript if there
is an fi:styling/@in-place-tip:

xmlns:stringescapeutils="org.apache.commons.lang.StringEscapeUtils"
...
<xsl:if test="fi:styling/@in-place-tip">
  <script type="text/javascript">
    <xsl:text>oacf_createInPlaceTip('</xsl:text>
    <xsl:value-of select="concat(@id, '-input')"/>
    <xsl:text>', '</xsl:text>
    <xsl:value-of
select="stringescapeutils:escapeJavaScript(fi:styling/@in-place-tip)
"/>
    <xsl:text>');</xsl:text>
  </script>
</xsl:if>


In forms-lib.js, some additional javascript code:
/**
* Functions to handle hints in text inputs:
* Remove the widget value if it is the default (tip).
* (oacf refers to org.apache.cocoon.forms)
*/
function oacf_removeDefaultValue(widget, defaultValue) {
    if (widget.value == defaultValue) {
        widget.value = "";
    }
}

/**
* If the widget does not have a value, set it do the default (tip) value.
*/
function oacf_setDefaultValue(widget, defaultValue) {
    if (widget.value == "") {
        widget.value = defaultValue;
    }
    widget.oacf_defaultValue = defaultValue;
}

/**
* Given a widget's id, and the desired in-place-tip  text, set up the
* onfocus, onblur and onsubmit behavior.
* It may also be desirable to change the class attribute of the widget
* when the tip is being displayed so that the tip may be styled differently.
*/
function oacf_createInPlaceTip(id, tipText) {
    var result = {};
    result.forms_id = id;
    result.element = document.getElementById(result.forms_id);

    result.element.onblur = function() { oacf_setDefaultValue(this, tipText); }
    result.element.onfocus = function() {
oacf_removeDefaultValue(this, tipText); }
    result.element.onblur();

    // add to onsubmit handlers
    result.forms_onsubmit = function() {
        this.element.onfocus();
    }
    forms_onsubmitHandlers.push(result);
    return result;
}

Re: fi:styling/@in-place-tip

[Quoin Developers <qu...@gmail.com>]

> Ok. BTW, what about naming it "inline-hint", to be consistent with the
> existing "hint" naming?

Funny, we started with a name like that, but then thought that the
name might be confusing, since it's /not/ displaying the fd:hint.

> >     - if yes, what about adding it besides <fd:hint> and <fd:help> in the
> >     form definition?
> >
> >
> > I recall running into the issue that simply adding a new fd element
> > didn't mean that you could actually access in the xslt for the forms
> > transformation. Is there some magic to ensure that the new element
> > makes it out of the forms generator?
>
> No magic, just code ;-)
>
> It's in AbstractWidgetDefinitionBuilder.setDisplayData(). It needs some
> refactoring though, as the list of elements is fixed when it should
> better be defined by the concrete subclass (i.e. an inline-hint makes
> sense only for fields).

Yes, I was looking for a solution that didn't require patching the
cocoon source and rebuilding the forms block -- keeping my build
process simple and allowing the team to use the latest stable cocoon
build and take advantage of cool things like ajax support.

> > I think that's part of why we put it in the form template. The other
> > reason - it is more display/rendering specific than the more general
> > concept of a hint. I did have the thought that if you want to display
> > the hint text as the the in-place-tip that the in-place-tip could be
> > some magic value such as "fd:hint/text()". That's not implemented, but
> > easy enough to do.
>
> I often have questions of some people that consider that label, help,
> hint, etc don't belong to the definition but to the view. Now it
> actually depends on the point of view, as some other people consider
> that they are related to the data model and its definition.
>
> And actually, CForms allows these display data to be defined in the form
> template too, as you can write:
> <ft:widget id="foo">
>  <fi:help>This help for foo, in the template</fi:help>
> </ft:widget>
>
> We could do the same with the inline-hint
>

Okay, so what is the cforms standard-compliant way?
To add inline-hint to the form definition and allow it in the form template?
Does it show up as fi:inline-hint/text() as output from the forms
generator regardless of whether it's defined in the form definition of
the form template?

Regards,
Eric

Re: fi:styling/@in-place-tip

[Sylvain Wallez <sy...@apache.org>]

Quoin Developers wrote:
>
>      Cool stuff!
>
> Thank you.
>
>     A few questions though:
>     - is the "inline-tip" different from the <fd:hint>?
>
>  
> It might often be the same, but it could also be different. In the 
> example I give, the fd:hint might be "The date that you plan on 
> arriving", while the in-place-tip is "mm/dd/yyyy".

Ok. BTW, what about naming it "inline-hint", to be consistent with the 
existing "hint" naming?

>     - if yes, what about adding it besides <fd:hint> and <fd:help> in the
>     form definition?
>
>  
> I recall running into the issue that simply adding a new fd element 
> didn't mean that you could actually access in the xslt for the forms 
> transformation. Is there some magic to ensure that the new element 
> makes it out of the forms generator?

No magic, just code ;-)

It's in AbstractWidgetDefinitionBuilder.setDisplayData(). It needs some 
refactoring though, as the list of elements is fixed when it should 
better be defined by the concrete subclass (i.e. an inline-hint makes 
sense only for fields).

> I think that's part of why we put it in the form template. The other 
> reason - it is more display/rendering specific than the more general 
> concept of a hint. I did have the thought that if you want to display 
> the hint text as the the in-place-tip that the in-place-tip could be 
> some magic value such as "fd:hint/text()". That's not implemented, but 
> easy enough to do.

I often have questions of some people that consider that label, help, 
hint, etc don't belong to the definition but to the view. Now it 
actually depends on the point of view, as some other people consider 
that they are related to the data model and its definition.

And actually, CForms allows these display data to be defined in the form 
template too, as you can write:
<ft:widget id="foo">
  <fi:help>This help for foo, in the template</fi:help>
</ft:widget>

We could do the same with the inline-hint

>     - how does "onchange" behave when an event listener is attached to the
>     input? I mean we must be sure the tip isn't submitted in that case. 
>
>  
> Good point. Do you mean a server-side fd:on-value-changed, or 
> something else.

I meant exactly that.

> The tip text will be remove when the form is submitted for any reason. 
> We're currently migrating to the latest cocoon RC and 
> forms-field-styling.xsl seems to be out of sync with the formslib.js 
> on the naming of forms_submitForm(element). I fixed that locally, and 
> yep, the tip is remove on submission.

Great!

Sylvain

-- 
Sylvain Wallez                        Anyware Technologies
http://people.apache.org/~sylvain     http://www.anyware-tech.com
Apache Software Foundation Member     Research & Technology Director

Re: fi:styling/@in-place-tip

[Quoin Developers <qu...@gmail.com>]

>
> Cool stuff!

Thank you.

A few questions though:
> - is the "inline-tip" different from the <fd:hint>?

 It might often be the same, but it could also be different. In the example
I give, the fd:hint might be "The date that you plan on arriving", while the
in-place-tip is "mm/dd/yyyy".

- if yes, what about adding it besides <fd:hint> and <fd:help> in the
> form definition?

 I recall running into the issue that simply adding a new fd element didn't
mean that you could actually access in the xslt for the forms
transformation. Is there some magic to ensure that the new element makes it
out of the forms generator? I think that's part of why we put it in the form
template. The other reason - it is more display/rendering specific than the
more general concept of a hint. I did have the thought that if you want to
display the hint text as the the in-place-tip that the in-place-tip could be
some magic value such as "fd:hint/text()". That's not implemented, but easy
enough to do.

- how does "onchange" behave when an event listener is attached to the
> input? I mean we must be sure the tip isn't submitted in that case.

 Good point. Do you mean a server-side fd:on-value-changed, or something
else. The tip text will be remove when the form is submitted for any reason.
We're currently migrating to the latest cocoon RC and
forms-field-styling.xsl seems to be out of sync with the formslib.js on the
naming of forms_submitForm(element). I fixed that locally, and yep, the tip
is remove on submission.
 --
Eric

Re: fi:styling/@in-place-tip

[Sylvain Wallez <sy...@apache.org>]

Quoin Developers wrote:
> Motivation:
>
> CForms user would like to display instructions or some other hint to
> the end user in the text input widget itself (as opposed to a tool-tip
> on-hover). This text should not be submitted, and if a user wants to
> enter text into the input, the tip text should automatically disappear
> so that the user does not have to manually delete it.
>
> We implemented this for a couple of projects. Most recently Antonio
> Gallardo provided some suggestions as to how we might best integrate
> this into CForms, and here are the results which we would like to
> contribute this back to the cocoon community. We're open to
> suggestions, but we'd like to keep it simple. The only additional
> thing might be to set a different class attribute value for the input
> element when the tip is being displayed. In this way, the tip text
> could be styled distinctly.
>   

<snip/>

Cool stuff!

A few questions though:
- is the "inline-tip" different from the <fd:hint>?
- if yes, what about adding it besides <fd:hint> and <fd:help> in the 
form definition?
- how does "onchange" behave when an event listener is attached to the 
input? I mean we must be sure the tip isn't submitted in that case.

Anyway, an interesting addition!

Sylvain

-- 
Sylvain Wallez                        Anyware Technologies
http://people.apache.org/~sylvain     http://www.anyware-tech.com
Apache Software Foundation Member     Research & Technology Director

Re: fi:styling/@in-place-tip

[Antonio Gallardo <ag...@agssa.net>]

Hi Eric and Rus:

Please provide a link, where the community can see this working. As I 
told before, I found very useful this enhancement. :-)

Best Regards,

Antonio Gallardo.

Quoin Developers wrote:

>Motivation:
>
>CForms user would like to display instructions or some other hint to
>the end user in the text input widget itself (as opposed to a tool-tip
>on-hover). This text should not be submitted, and if a user wants to
>enter text into the input, the tip text should automatically disappear
>so that the user does not have to manually delete it.
>
>We implemented this for a couple of projects. Most recently Antonio
>Gallardo provided some suggestions as to how we might best integrate
>this into CForms, and here are the results which we would like to
>contribute this back to the cocoon community. We're open to
>suggestions, but we'd like to keep it simple. The only additional
>thing might be to set a different class attribute value for the input
>element when the tip is being displayed. In this way, the tip text
>could be styled distinctly.
>
>Regards,
>Eric Meyer
>Rus Pandey
>
>Implementation:
>
>Add an fi:styling/@in-place-tip to the form template. For example:
>
><ft:widget id="startDate">
>    <fi:styling in-place-tip="mm/dd/yyyy"/>
></ft:widget>
>
>
>Details:
>
>The forms-field-styling.xsl for fi:field adds some javascript if there
>is an fi:styling/@in-place-tip:
>
>xmlns:stringescapeutils="org.apache.commons.lang.StringEscapeUtils"
>...
><xsl:if test="fi:styling/@in-place-tip">
>  <script type="text/javascript">
>    <xsl:text>oacf_createInPlaceTip('</xsl:text>
>    <xsl:value-of select="concat(@id, '-input')"/>
>    <xsl:text>', '</xsl:text>
>    <xsl:value-of
>select="stringescapeutils:escapeJavaScript(fi:styling/@in-place-tip)
>"/>
>    <xsl:text>');</xsl:text>
>  </script>
></xsl:if>
>
>
>In forms-lib.js, some additional javascript code:
>/**
>* Functions to handle hints in text inputs:
>* Remove the widget value if it is the default (tip).
>* (oacf refers to org.apache.cocoon.forms)
>*/
>function oacf_removeDefaultValue(widget, defaultValue) {
>    if (widget.value == defaultValue) {
>        widget.value = "";
>    }
>}
>
>/**
>* If the widget does not have a value, set it do the default (tip) value.
>*/
>function oacf_setDefaultValue(widget, defaultValue) {
>    if (widget.value == "") {
>        widget.value = defaultValue;
>    }
>    widget.oacf_defaultValue = defaultValue;
>}
>
>/**
>* Given a widget's id, and the desired in-place-tip  text, set up the
>* onfocus, onblur and onsubmit behavior.
>* It may also be desirable to change the class attribute of the widget
>* when the tip is being displayed so that the tip may be styled differently.
>*/
>function oacf_createInPlaceTip(id, tipText) {
>    var result = {};
>    result.forms_id = id;
>    result.element = document.getElementById(result.forms_id);
>
>    result.element.onblur = function() { oacf_setDefaultValue(this, tipText); }
>    result.element.onfocus = function() {
>oacf_removeDefaultValue(this, tipText); }
>    result.element.onblur();
>
>    // add to onsubmit handlers
>    result.forms_onsubmit = function() {
>        this.element.onfocus();
>    }
>    forms_onsubmitHandlers.push(result);
>    return result;
>}
>  
>