You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by Tim Colson <tc...@cisco.com> on 2003/02/18 16:06:59 UTC
RE: [VELTOOLS] Documentation - struts tool naming/docs
I'm catching up after 4 days spent moving into a new home.
+1 on Nathan's proposal to keep naming shortened and Velocity-like (ex.
$form.token)
---
On the topic of simple and clean naming - I do not understand why
form.getBean() exists.
http://crufty.happysearch.com/velocity/tools/struts/docs/FormTool.html
"getBean() Retrieve and return the form bean associated with this request."
QUESTION: Does a Designer really need to know about 'beans'?
"This is a convenience method. The form bean is automatically available in
the Velocity context under the name defined in the Struts configuration."
QUESTION: Why would a Designer ever use a generic $form.bean.username
instead of $LoginForm.username (assuming the Struts form name is
"LoginForm")
"If the form bean is used repeatedly, it is recommended to create a local
variable referencing the bean rather than calling getBean() multiple times."
QUESTION: What is the benefit of doing this local assignment?
Optimization/speed
QUESTION: Should the "Tools" documentation be written for reading by
Designers or Developers?
QUESTION: Similar to Velocity Main which has separate User and Developer
Guides, perhaps we should have a Guide that is devoted to the Struts
Designer who is now in VelocityStruts land?
-Tim
---
---
Nathan Bubna wrote:
> I would suggest as a general rule that we go with the more elegant and
> less java-like syntax everywhere possible. for example, things like:
>
> $form.token instead of $form.getToken()
> $msg.foo instead of $msg.get('foo')
> #set( $tool.foo = 'bar' ) instead of $tool.setFoo('bar')
> and so on...
> things are just shorter, cleaner, and prettier this way.
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Nathan Bubna <na...@esha.com>.
Gabe said:
...
> BTW, I want to mention that I really like the diagram on the
> overview page of the VelocityStruts documentation. Great job!
+1 :)
...
> > QUESTION: Should the "Tools" documentation be written for reading by
> > Designers or Developers?
>
> Designers! Do you see many things that are more aimed at developers?
> I hope not. :-)
>
> > QUESTION: Similar to Velocity Main which has separate User and
Developer
> > Guides, perhaps we should have a Guide that is devoted to the Struts
> > Designer who is now in VelocityStruts land?
>
> Which would be things that are only relevant for the developers? Download
> and installation? All the rest is pretty much aiming the designers.
For developers, i think the primary issue is probably creating their own
tools and dealing with the toolbox (yes, designers might do the latter to
some extent).
so some other suggestions might be... perhaps a brief section on tool
scoping, the ViewTool interface (esp. what's passed to init() based on
scope). the <create-session> element in the toolbox definition might
deserve mention. there could be mention of the ChainedContext's search
order (and even taking advantage of that to wrap and/or hide the
request/response/session/servletContext objects from designers).
obviously, nothing here so urgent or important to document that it would
hold up doing a release, but i think some sort of developer's guide could be
useful. and there are other things i can imagine going in there someday as
this project grows and evolves.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Nathan Bubna <na...@esha.com>.
Anthony said:
...
> > > BTW - Anybody figure out if multiple forms might exist which would
> > screw
> > > that default alias trick up a bit?
> >
> > you can put multiple forms on a page, but you can only submit one at
> > a time,
> > so afaik, struts only supports one form-bean per action mapping.
> >
>
> The DTD for struts 1.0 and 1.1 has the form bean as an attribute, of
> which there can only be one. Therefore, your individual _action_ can
> only have one form; however, if is possible that a single display page
> could be used as the output of more than one action, with the potential
> for different forms. This would really be ugly, in that you would need
> to code the page itself to detect which form it was working
> on...clearly not a good practice. Either way, it would not screw up the
> default alias trick.
heh, it'd screw up $form.bean too! :) i don't think we should concern
ourselves with this. if Struts wants to add support for it, then we can
care.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Anthony Kay <aw...@yahoo.com>.
--- Nathan Bubna <na...@esha.com> wrote:
> Tim said:
> ...
> > I guess now I'm starting to think I like the lazy idea of every
> form being
> > $form.*
> > instead of $MyWidgetForm, $MyStupidForm, etc.
>
> it is tempting, eh? i'm just not convinced it's a good idea. maybe
> something like $form.field('username') would be better than the
> $form.bean
> bit.
>
> > > that said, back in the day, i lobbied for using reflection
> > > trickery to pull of $form.* and now i can't recall the
> > > arguments involved. hmm. offhand, that could cause trouble
> > > if someone had a method in their ActionForm that collided
> > > with one of the standard FormTool methods.
> >
> > Ok. Understood. We could just change the tool key to $formtool and
> then
> > forms could be either $MyStupidForm or just $form as built-in
> alias. That
> > trickery must be possible in the backend since a few emails back we
> were
> > talking about doing it in the front end view, right? i.e. #set
> ($myform =
> > $form.bean)
>
> -1
> aesthetically, i weary of the oh-so-generic 'tool' being in names.
> the
> current #set( $defaults = $form.bean ) is trivial and optional.
> also, it
> provides free choice of context keys. automatically setting $MyForm
> to
> $form would hard-code another context key.
>
> > BTW - Anybody figure out if multiple forms might exist which would
> screw
> > that default alias trick up a bit?
>
> you can put multiple forms on a page, but you can only submit one at
> a time,
> so afaik, struts only supports one form-bean per action mapping.
>
The DTD for struts 1.0 and 1.1 has the form bean as an attribute, of
which there can only be one. Therefore, your individual _action_ can
only have one form; however, if is possible that a single display page
could be used as the output of more than one action, with the potential
for different forms. This would really be ugly, in that you would need
to code the page itself to detect which form it was working
on...clearly not a good practice. Either way, it would not screw up the
default alias trick.
__________________________________________________
Do you Yahoo!?
Yahoo! Tax Center - forms, calculators, tips, more
http://taxes.yahoo.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> I guess now I'm starting to think I like the lazy idea of every form being
> $form.*
> instead of $MyWidgetForm, $MyStupidForm, etc.
it is tempting, eh? i'm just not convinced it's a good idea. maybe
something like $form.field('username') would be better than the $form.bean
bit.
> > that said, back in the day, i lobbied for using reflection
> > trickery to pull of $form.* and now i can't recall the
> > arguments involved. hmm. offhand, that could cause trouble
> > if someone had a method in their ActionForm that collided
> > with one of the standard FormTool methods.
>
> Ok. Understood. We could just change the tool key to $formtool and then
> forms could be either $MyStupidForm or just $form as built-in alias. That
> trickery must be possible in the backend since a few emails back we were
> talking about doing it in the front end view, right? i.e. #set ($myform =
> $form.bean)
-1
aesthetically, i weary of the oh-so-generic 'tool' being in names. the
current #set( $defaults = $form.bean ) is trivial and optional. also, it
provides free choice of context keys. automatically setting $MyForm to
$form would hard-code another context key.
> BTW - Anybody figure out if multiple forms might exist which would screw
> that default alias trick up a bit?
you can put multiple forms on a page, but you can only submit one at a time,
so afaik, struts only supports one form-bean per action mapping.
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Tim Colson <tc...@cisco.com>.
> blech. that kind of utter redundancy gives me gas. :)
I haven't ever met you in person, but I can only imagine we'd want to avoid
that. ;-)
> very best, if everyone around here agreed, i might not -1 a
> proposal to just change getToken() to getTokenValue().
Ok, I propose that. :-)
> $WidgetEditForm is an ActionForm.
Understood. So being ridiculously lazy, does ActionForm.getName() exist?
<grin>
> first off, allow me to remind you once again that we have no
> control over the $WidgetEditForm's API. this project only
> provides the FormTool.
Thanks, I'm trying to keep that clear in my head.
I guess now I'm starting to think I like the lazy idea of every form being
$form.*
instead of $MyWidgetForm, $MyStupidForm, etc.
> that said, back in the day, i lobbied for using reflection
> trickery to pull of $form.* and now i can't recall the
> arguments involved. hmm. offhand, that could cause trouble
> if someone had a method in their ActionForm that collided
> with one of the standard FormTool methods.
Ok. Understood. We could just change the tool key to $formtool and then
forms could be either $MyStupidForm or just $form as built-in alias. That
trickery must be possible in the backend since a few emails back we were
talking about doing it in the front end view, right? i.e. #set ($myform =
$form.bean)
BTW - Anybody figure out if multiple forms might exist which would screw
that default alias trick up a bit?
Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> 1) Can we add getTokenValue() as an alias for getToken() to make the
naming
> consistent and pretty?
blech. that kind of utter redundancy gives me gas. :) at very best, if
everyone around here agreed, i might not -1 a proposal to just change
getToken() to getTokenValue().
> 2) Does $WidgetEditForm.Name even exist? Should it? Can it?
$WidgetEditForm is an ActionForm. if you want that member, you have to
either subclass it yourself or lobby struts-dev to get them to add it.
> 3) Why would there be $form.TokenName and $WidgetEditForm.username versus
> just having $form.* or $WidgetEditForm.*? What is more consistent with
the
> Struts paradigm?
first off, allow me to remind you once again that we have no control over
the $WidgetEditForm's API. this project only provides the FormTool.
that said, back in the day, i lobbied for using reflection trickery to pull
of $form.* and now i can't recall the arguments involved. hmm.
offhand, that could cause trouble if someone had a method in their
ActionForm that collided with one of the standard FormTool methods. yes,
they could probably get around it by avoiding the "short" or "informal"
velocity syntax, but this could be very confusing.
> 3) What would the action really look like? $link.foo
$WidgetEditForm.Action
> ?
$link.setAction('foo')
> (I don't know. All of the examples are hard-coded, and I'm not clear form
> the various docs.)
then we definitely need to improve the LinkTool docs! :-)
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Tim Colson <tc...@cisco.com>.
> Cool! Put all the boxes away? :-)
I'm typing on my laptop - on my lap - if that gives any indication of how
many boxes are put away. ;-)
> BTW, I want to mention that I really like the diagram on the
> overview page of the VelocityStruts documentation. Great job!
Thanks. :-)
> -0 on Nathan's proposal.
Ok, I understand now and also agree that both formal/informal should be
documented.
Perhaps the simple form should be more prominent in a Designer guide, with
both forms in a Developer guide.
> two parameters: This is not an exotic case but quite a common thing.
<soapbox>I've seen a lot of funky template stuff, I'm not going to lecture,
but geez it's so much easier to put the heavy lifting in the backend. But
hey, that's just my goofy need to keep things simple. Do whatever makes you
happy. :-P </soapbox>
> We could do this: Instead of showing both notations in most
> examples, we could just mention this in one place, for
> example in an additional section in the user guide.
+1
> Yes, I don't see are reason either and I don't remember why I
> originally added it.
Ha. Looks like Nathan likes it so he can lazily write $form.bean.* instead
of looking up the form name in the struts-config.xml <grin>
> But, I just noticed, that nowwhere else the form bean is
> mentioned. I suggest that the form bean is mentioned in the
> section "Access to Struts Framework Resources" of the users guide.
+1
> Do you see many things that are more aimed at developers?
Well, specifically, the FormTool docs talk about HTTP Requests, versions,
JAR, Classes, Toolbox config, methods with return types.
http://crufty.happysearch.com/velocity/tools/struts/docs/FormTool.html
(BTW: getTokenName says it returns 'int' which is wrong, eh?)
I'm thinking Designers have attention spans even shorter than gnats and
Managers, so maybe basic HOWTO info on the main Struts Tools page would be
good?
Could describe how to use the Form/Msg/Error tags, and how to handle
transaction tokens - which are wildly different from the Struts Taglib
forms, right?
Example:
----------------------------------
The Struts <html:form> tag automatically provides a feature which can help
prevent users from accidentally submitting a form twice with the same data.
This feature, called "transaction tokens", is turned on by the developer in
the application configuration and handled by the tag. When the tag is
converted to HTML, a <form> is created and a hidden field is placed into the
form with a one-time-use token.
The token will look something like this:
<input type="hidden" name="org.apache.struts.taglib.html.TOKEN"
value="224e7d7071ece4280bff018afcd41ec">
VelocityStruts only uses standard <form> tags, but this means that if
Transaction Tokens are being used in the application, the template must
manually include the hidden field.
Fear not! This is easy, simply add the following hidden field to the form.
<input type="hidden" name="$form.TokenName" value="$form.TokenValue">
So if the page has a form called "WidgetEditForm", the Velocity template
would look like this:
<form name="$WidgetEditForm.name" action="$WidgetEditForm.action"
method="POST">
<input type="hidden" name="$form.TokenName" value="$form.TokenValue">
<!-- other input fields here -->
</form>
-----------------------------------
That brings up some questions.
1) Can we add getTokenValue() as an alias for getToken() to make the naming
consistent and pretty?
2) Does $WidgetEditForm.Name even exist? Should it? Can it?
3) Why would there be $form.TokenName and $WidgetEditForm.username versus
just having $form.* or $WidgetEditForm.*? What is more consistent with the
Struts paradigm?
3) What would the action really look like? $link.foo $WidgetEditForm.Action
?
(I don't know. All of the examples are hard-coded, and I'm not clear form
the various docs.)
Cheers,
Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Gabriel Sidler <si...@teamup.com>.
Tim Colson wrote:
> I'm catching up after 4 days spent moving into a new home.
>
Cool! Put all the boxes away? :-)
BTW, I want to mention that I really like the diagram on the
overview page of the VelocityStruts documentation. Great job!
> +1 on Nathan's proposal to keep naming shortened and Velocity-like (ex.
> $form.token)
-0 on Nathan's proposal.
I don't want to stop you from simplyfing this but here is the reason I
chose to mention the formal and the informal syntax in the docs:
The formal and the informal syntax are not equally powerful. There
are cases where the informal syntax doesn't work, for example if you
need to pass two or more parameters to a method, etc. This is not an exotic
case but quite a common thing. My opinion is that a designer will need
to know how Velocity maps variables to method names in Java. On the
velocity-user list, the mapping of Velocity variables to Java methods
is quite frequently a topic that creates questions. Showing both
notations in the docs makes users familiar with them.
We could do this: Instead of showing both notations in most examples,
we could just mention this in one place, for example in an additional
section in the user guide. But, I strongly feel that designers need
to be made aware of the two notations. Formal vs. information syntax
is something that always leads to difficulties for new users. Unfortunately
you don't get by with the informal notation only.
> ---
> On the topic of simple and clean naming - I do not understand why
> form.getBean() exists.
>
> http://crufty.happysearch.com/velocity/tools/struts/docs/FormTool.html
Yes, I don't see are reason either and I don't remember why I
originally added it.
But, I just noticed, that nowwhere else the form bean is mentioned.
I suggest that the form bean is mentioned in the section
"Access to Struts Framework Resources" of the users guide.
> QUESTION: Should the "Tools" documentation be written for reading by
> Designers or Developers?
Designers! Do you see many things that are more aimed at developers?
I hope not. :-)
> QUESTION: Similar to Velocity Main which has separate User and Developer
> Guides, perhaps we should have a Guide that is devoted to the Struts
> Designer who is now in VelocityStruts land?
Which would be things that are only relevant for the developers? Download
and installation? All the rest is pretty much aiming the designers.
I actually think that the tool reference pages are pretty cool.
http://crufty.happysearch.com/velocity/tools/struts/docs/FormTool.html
But I am always open for improvements.
Gabe
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Konstantin Priblouda <kp...@yahoo.com>.
> >it's one more thing that needs to be sync'ed to the
> struts-config.xml.
> Hmm... lazy Developer. <grin>
There is XDoclet for such lazy developers [like me :)]
regards,
=====
Konstantin Priblouda ( ko5tik ) Freelance Software developer
< http://www.pribluda.de > < play java games -> http://www.yook.de >
< render charts online -> http://www.pribluda.de/povray/ >
__________________________________________________
Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day
http://shopping.yahoo.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Tim Colson <tc...@cisco.com>.
>> QUESTION: Does a Designer really need to know about 'beans'?
>does it hurt?
Dunno. Potential for harm exists in everything from knives to cotton balls.
<grin>
> whether using the form bean's name or using $form.bean,
> the object is the same. isn't this question just
> complaining about the term being used?
Oh, no complaining meant. It was the first time I'd seen the nomenclature.
So I'm just wondering if it's necessary, or just a shortcut that is
optional. Looks like the latter in this case. But I also avoid telling my
Designers about 'beans', so maybe I must admit to some lurking complaining
after all. :-)
> using the form bean's attribute and/or name is a little extra work.
Hah ha... I can pull out an old quote, "A little extra work... For whom?"
:-)
>it's one more thing that needs to be sync'ed to the struts-config.xml.
Hmm... lazy Developer. <grin>
> it's one more thing to remember to change if you change the config.
Both Developer and Designer stuff, but the Developer instigated the change.
> having $form.bean available means that you always have a consistent
interface.
> not a big deal in this case, but i think it's nice to have handy.
Hmm... Consistent from template to template maybe. It might even be arguably
easier to remember, but I don't believe this is consistent with how Struts
works without Velocity. And what if there are two forms on a page?
(Actually...not sure that can happen.)
I'm just thinking "as simple as possible"... $form.bean.username is
understandable to me the Dev dude, but I wonder if that'll throw the
Designer. And I wonder if it'll throw folks who are used to 'doing it the
Struts + JSP' way?
It might be just fine... I'm not sure I mind either way. :-)
>> QUESTION: What is the benefit of doing this local assignment?
>> Optimization/speed
> yep. the ActionForm is not cached in the FormTool, so every
> $form.bean.whatever would repeat the whole lookup process.
Ok. Maybe addressable on the Developer side? I wouldn't expect Designers to
understand why they should do that trick to speed things up.
>> QUESTION: Should the "Tools" documentation be written for reading by
>> Designers or Developers?
> hmm. must think on this... what are your thoughts here?
Nothing much, I always ask, "Who's my audience?" before writing stuff.
When I look at the Struts Tools docs, they are nicely organized by
Gabe...but they look like they might be intimidating for a Designer.
My personal bias is to provide an alternative that's so freakin' simple
people will start fleeing from JSP in droves. <grin>
So maybe a quick and simple page for the Designers, with grittier details
for Developers left in the reference docs?
> so, for instance, i know only enough about JSP to
> know that i don't like it. :-)
lol
Timo
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - struts tool naming/docs
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> On the topic of simple and clean naming - I do not understand why
> form.getBean() exists.
>
> http://crufty.happysearch.com/velocity/tools/struts/docs/FormTool.html
>
> "getBean() Retrieve and return the form bean associated with this
request."
> QUESTION: Does a Designer really need to know about 'beans'?
does it hurt? whether using the form bean's name or using $form.bean, the
object is the same. isn't this question just complaining about the term
being used?
> "This is a convenience method. The form bean is automatically available in
> the Velocity context under the name defined in the Struts configuration."
>
> QUESTION: Why would a Designer ever use a generic $form.bean.username
> instead of $LoginForm.username (assuming the Struts form name is
> "LoginForm")
using the form bean's attribute and/or name is a little extra work. it's
one more thing that needs to be sync'ed to the struts-config.xml. it's one
more thing to remember to change if you change the config. having
$form.bean available means that you always have a consistent interface. not
a big deal in this case, but i think it's nice to have handy.
> "If the form bean is used repeatedly, it is recommended to create a local
> variable referencing the bean rather than calling getBean() multiple
times."
> QUESTION: What is the benefit of doing this local assignment?
> Optimization/speed
yep. the ActionForm is not cached in the FormTool, so every
$form.bean.whatever would repeat the whole lookup process. i don't
particularly recall why it's not cached there.
> QUESTION: Should the "Tools" documentation be written for reading by
> Designers or Developers?
hmm. must think on this... what are your thoughts here?
> QUESTION: Similar to Velocity Main which has separate User and Developer
> Guides, perhaps we should have a Guide that is devoted to the Struts
> Designer who is now in VelocityStruts land?
sounds good to me. i can't say i'll be of much use in this particular area.
i came into this project from Turbine-land. so, for instance, i know only
enough about JSP to know that i don't like it. :-)
Nathan Bubna
nathan@esha.com
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org