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/08 08:13:44 UTC
[VELTOOLS] Documentation - proposed update
Howdy -
It's taken me way too long, but I've finally managed to get some work
done on the documentation for Velocity Tools.
I mostly just cleaned up from the excellent starting point Gabe created.
Did a bit of weeding, created a smaller Velocity Tools specific logo,
and then added some bits that were missing for
installation/setup/description...and then tried to organize things a bit
better. (ex. The setup I wrote for the StrutsView really applied mostly
to the basic ViewServlet, there isn't much extra to do for Struts really
when you come right down to it.)
I posted the current docs as well as the xdocs directories here:
http://crufty.happysearch.com/velocity/tools/docs/
I could provide cvs diffs if my arm was twisted, but geez I
changed/added/renamed quite a few files to make this happen. It would be
easier to just send a tarball. ;-)
Also moved the tree inside /velocity/tools/ to make it easier to type
and/or reference. This of course makes a bit of an issue for the
velocity/tools/tools directory (it works of course...just seems a bit
bit redundant redundant.
I'm going to work on cleaning up the VelocityLayoutServlet docs some
more tomorrow (whilst packing to move!)...and I hope to get an example
.war created that shows how it works.
I sure hope folks like what I've done.
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] Naming Conventions
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> > i have proposed that Velocimacro libraries be placed into
> > their associated tree (struts/view/tools).
...
>
> Sorting into separate trees for macros could make classification
> difficult, but since it seems we're talking about removing tools/tools,
> so I think separate trees would probably be dandy. I'll bet 95% will
> fall into the general tools/view/macros tree.
even if tools/tools didn't go, i think the classification would be fairly
straightforward. any macro that used a tool in tools/tools would go in
tools/tools/macros, and any that used a struts tool would go in
tools/struts/macros. all tool-less macros would be under tools/view/macros.
if tools/tools is folded into tools/view, then we'll still probably maintain
some division of macros (tool dependent vs. general) either by file naming
or folders or both.
> > > Saying "VelocityStruts" may not provide a clear picture to
> > > Struts folks of using Velocity for the Struts View Layer.
> >
> > Velocity is designed to be a view technology. Struts is
> > designed to be a controller technology.
> > I think 'VelocityStruts' is pretty clear.
> Go tell that to the legions of Struts folks who are using Struts for
> Control as well as Struts JSP Taglibs for the View. <grin>
>
> Here's my last argument, then I'll shut up. I'm talking to a Developer
> who is using Struts with Eeeevil JSP's...and so I say:
>
> "I suggest looking at the Velocity subproject called 'VelocityStruts'
> for the Struts View layer."
> or
> "I suggest looking at the Velocity subproject called 'StrutsView' for
> the Struts View layer."
>
> I like #2 better. ;-)
and #1 still sounds better to me. :) otherwise, who can tell which 'view
technology' is being used? afaik, the standard 'struts view' is JSP.
> (optional: add "...because JSP and Taglibs are eeeeevil, and Velocity
> with Macro's rock!" to both.)
ah, it's so true.
> But we may have to agree to disagree on this one...and since I don't
> have commit status, I'm prolly going to lose the argument anyway. <grin>
life is so unfair, eh? ;-) but who knows, i'm not the only committer
'round here.
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] Naming Conventions
Posted by Tim Colson <tc...@cisco.com>.
> Unless/until someone has some sort of idea
> or plan for [Velocity Utilities] (perhaps Gabe or Geir recall what
this was
> meant to be),
> then i think this should be dropped from the documentation.
+1
> > Velocimacros
> i have proposed that Velocimacro libraries be placed into
> their associated tree (struts/view/tools).
Sorry, been meaning to reply but was trying to bust out docs. :-)
Sorting into separate trees for macros could make classification
difficult, but since it seems we're talking about removing tools/tools,
so I think separate trees would probably be dandy. I'll bet 95% will
fall into the general tools/view/macros tree.
> > Saying "VelocityStruts" may not provide a clear picture to
> > Struts folks of using Velocity for the Struts View Layer.
>
> Velocity is designed to be a view technology. Struts is
> designed to be a controller technology.
> I think 'VelocityStruts' is pretty clear.
Go tell that to the legions of Struts folks who are using Struts for
Control as well as Struts JSP Taglibs for the View. <grin>
Here's my last argument, then I'll shut up. I'm talking to a Developer
who is using Struts with Eeeevil JSP's...and so I say:
"I suggest looking at the Velocity subproject called 'VelocityStruts'
for the Struts View layer."
or
"I suggest looking at the Velocity subproject called 'StrutsView' for
the Struts View layer."
I like #2 better. ;-)
(optional: add "...because JSP and Taglibs are eeeeevil, and Velocity
with Macro's rock!" to both.)
But we may have to agree to disagree on this one...and since I don't
have commit status, I'm prolly going to lose the argument anyway. <grin>
> it would probably be org.apache.velocity.tools.view.tools.*
I like it.
> > = label tools/view - "VelocityView"
> including the word 'servlet' doesn't address the hope/quasi-plan for
> extending/applying the toolbox management and non-servlet
> tools to other environments.
Agreed.
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] Naming Conventions
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
> Thread to clear up agree on naming conventions for the tools
> subproject(s).
>
> First a quick summary of where we are now:
> ----
> Tools subproject lists 5 areas:
> http://jakarta.apache.org/velocity/toolsubproject.html
> View -> "a standalone servlet that can be used for template
> rendering in Web Applications" references the VelocityViewServlet, and
> the ToolBox Manager
> Struts -> "set of tools, examples and documentation" references the
> View package
> Tools -> "library of generic tools"
> Utilities-> "library of Velocity-related utilities"
To my knowledge, there are presently no "velocity-related utilities" either
proposed or under development. Unless/until someone has some sort of idea
or plan for these (perhaps Gabe or Geir recall what this was meant to be),
then i think this should be dropped from the documentation.
> Velocimacros
i have proposed that Velocimacro libraries be placed into their associated
tree (struts/view/tools). at this point, only Bill Burton has addressed
(and affirmed) that proposal. if no one else cares soon, i am going to move
in that direction. this will affect how/where these should be documented.
...
>
> Other thoughts just to confuse things:
...
> Saying "VelocityStruts" may not provide a clear picture to Struts folks
> of using Velocity for the Struts View Layer.
Velocity is designed to be a view technology. Struts is designed to be a
controller technology. I think 'VelocityStruts' is pretty clear. It is
certainly more descriptive than the monikers or acronyms that get attached
to most projects (things like 'Velocity' or 'Struts' :-)).
...
> "VelocityServlet" as mentioned here in the subproject is NOT the same as
> the "VelocityServlet" in the Velocity Developer's Guide - confusing, eh?
agreed, and it doesn't really address the (potential) full scope of the
library.
...
> Some possible changes (grab-bag, not all mutually exclusive):
...
> = REMOVE tools/tools -> roll it into tools/view
> +1 from Tim (the more I look at it, this would be simple and clean)
+1 i suppose i should make a separate proposal for this.
> = move org.apache.velocity.tools.tools.* to pkg
> org.apache.velocity.tools.view.?.?
> +1
it would probably be org.apache.velocity.tools.view.tools.*
> = label tools/view - "VelocityView"
> +1
+1
including the word 'servlet' doesn't address the hope/quasi-plan for
extending/applying the toolbox management and non-servlet tools to other
environments.
> = label tools/struts - "StrutsView"
> +1 (answers the question "What is this thing? A StrutsView tool."
-1 afaic, it's no better then saying "a VelocityStruts tool"
> = label tools/struts - "StrutsVelocity"
-1 let's keep it as VelocityStruts
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
[VELTOOLS] Naming Conventions
Posted by Tim Colson <tc...@cisco.com>.
Thread to clear up agree on naming conventions for the tools
subproject(s).
First a quick summary of where we are now:
----
Tools subproject lists 5 areas:
http://jakarta.apache.org/velocity/toolsubproject.html
View -> "a standalone servlet that can be used for template
rendering in Web Applications" references the VelocityViewServlet, and
the ToolBox Manager
Struts -> "set of tools, examples and documentation" references the
View package
Tools -> "library of generic tools"
Utilities-> "library of Velocity-related utilities"
Velocimacros
----
Gabriel Sidler's whiteboard has the following sub-sub-projects:
http://www.teamup.com/jakarta-velocity-tools/docs/index.html
VelocityLibrary tools/tools
"a library of reuseable and well documented view tools. Most tools are
optimized for use with an automatically managed toolbox (see
VelocityServlet). "
VelocityStruts tools/struts
"a set of view tools, examples and documentation for using the Velocity
template engine as a view layer technology for the Jakarta Struts web
application framework. It is based on the VelocityServlet project."
VelocityServlet tools/view
"a standalone servlet that can be used for template rendering in Web
applications. It offers automatic population of the Velocity context and
automatic, configurable management of view tools. Other efforts within
this project are the development of a toolbox manager and the definition
of a set of interfaces for view tools, thereby enabling the efficient
handling and reuse of view tools."
Utilities tbd
Velocimacros tbd
----
Now a quick look at where Tim Colson's whiteboard went:
VelocityViewServlet
"A standalone servlet that can render templates for Web applications. It
offers automatic population of the Velocity context and configurable
management of tools. Within this project, a toolbox manager component
and defined interfaces are under development to enable efficiecy and
reusability. Also included is a subclassed servlet
(VelocityLayoutServlet) that will render primary content inside a common
shared screen layout template."
StrutsView
"A packaged set of tools for using the Velocity template engine as a
view layer technology for the Jakarta Struts web application framework.
This work extends the VelocityViewServlet to make it easy to integrate
the two technologies. Several example hybrid applications are included
in the distribution."
VelocityLibrary
"A library of reuseable and documented tools that can be added to a
Velocity context. A tool is simply a class which can perform various
tasks when made available to the Velocity engine. Most tools are
optimized for use with an automatically managed toolbox (see
VelocityViewServlet)."
VelocityUtilities
"A repository of Velocity-related utilities - under development. "
Velocimacros
"A repository of useful Velocity macros for Velocity templates - under
development. "
------
Some thoughts brought up by Mr. Nathan Bubna on consolidation:
> > Nathan wrote:
> > > i think it'd be nice to cut things down to just VelocityView
> > > and VelocityStruts (or whatever [we] want to call them).
> > > can anyone give a really good reason to maintain a separate
> > > library just for these tools? after all, they are "view tools."
> > Aren't the tools supposed to be able to live without
> > VelocityViewServlet, so folks using other frameworks can
> leverage them without the extra baggage?
>
> yes, that's the idea. but as i said, one of the four tools in there
> (ParameterParser) is already dependent on the view package
> (the home of the
> VVS). so, if they want to compile the tools library or use the
> ParameterParser, they already need the view package. so
> what's the harm in
> combining the two? if they don't want to use the
> servlet-tied stuff, then
> they can just ignore it and use only the tools they want.
------
Other thoughts just to confuse things:
The Struts integration requires the View package(specifically the
ToolboxMgr, VelocityViewServlet) and some specific Tools (ex.
link/mesg/form/errors).
Saying "VelocityStruts" may not provide a clear picture to Struts folks
of using Velocity for the Struts View Layer.
One tool already in the VelocityLibrary requires the View package.
"VelocityServlet" as mentioned here in the subproject is NOT the same as
the "VelocityServlet" in the Velocity Developer's Guide - confusing, eh?
(The tools subproject is really talking about the "VelocityViewServlet"
which is an extension of the "VelocityServlet" from Velocity proper.)
-------
-------
Some possible changes (grab-bag, not all mutually exclusive):
= leave all well enough alone, stick with Sidlers names.
= rename tools/tools to tools/toolbox (or tools/something) and label
"Toolbox"
= REMOVE tools/tools -> roll it into tools/view
+1 from Tim (the more I look at it, this would be simple and clean)
= move org.apache.velocity.tools.tools.* to pkg
org.apache.velocity.tools.view.?.?
+1
= label tools/view - "VelocityViewServlet"
= label tools/view - "VelocityView"
+1
= label tools/struts - "StrutsView"
+1 (answers the question "What is this thing? A StrutsView tool."
= label tools/struts - "StrutsVelocity" (i.e. leave alone)
Whew...whole lotta typin' goin' on... where's Gabe I wonder?
Cheers,
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> Speaking of size, which project do I send a patch to reduce the big
> honkin' Jakarta logo to leave a little room for a project logo? <grin>
i'm pretty sure that general@jakarta.apache.org is the place.
also see: http://jakarta.apache.org/site/jakarta-site2.html
...
> Nathan wrote:
> > i think it'd be nice to cut things down to just VelocityView
> > and VelocityStruts (or whatever you want to call them).
> > can anyone give a really good reason to maintain a separate
> > library just for these tools? after all, they are "view tools."
> Aren't the tools supposed to be able to live without
> VelocityViewServlet, so folks using other frameworks can leverage them
> without the extra baggage?
yes, that's the idea. but as i said, one of the four tools in there
(ParameterParser) is already dependent on the view package (the home of the
VVS). so, if they want to compile the tools library or use the
ParameterParser, they already need the view package. so what's the harm in
combining the two? if they don't want to use the servlet-tied stuff, then
they can just ignore it and use only the tools they want.
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 - proposed update
Posted by Tim Colson <tc...@cisco.com>.
> the time to do some major reorganization, but *only* if we
> can come up with and agree on a satisfactory system of names and
paths.
I agree completely.
> it's not the CVS work. it's a matter of inertia and
> consistency. we have to maintain a common "language"
Ok. That makes sense.
> i suppose. however, though it is related to documentation,
> it really should precede it and thus probably deserves
> a new thread and proposal.
Ok. I'll start one.
> morning Pandora was let out of her box. :-(
> oh. sorry. :-/
No worries. I'll stick a big fat disclaimer on them to try preventing
confusion, "THIS IS JUST A TESTING WHITEBOARD AREA - THESE DOCS ARE NOT
NECESSARILY CORRECT NOR ENDORSED IN ANY WAY!"
> you've probably also missed out on <create-session> and
> <data> too, eh?
Ayep, I remember seeing that patch, but I tend to filter out stuff that
isn't causing me any direct pain.
> > JavaDocs might be good to pull up into the documentation pages?
I'll go have a look at the JavaDocs, and specifically the ones
mentioned.
> i tend to primarily use javadoc to explain things.
You're a good man for it! :-) (Apologies for ignoring the javadoc, I've
just been burned so often by poor javadocs like "setFoo : is used to set
the variable Foo with the value in String myFoo" that I don't usually go
there.)
I do like how manuals/docs can give a narrative that can span across
serveral bits of code. If I don't know anything about a code package, I
don't know where to start looking in JavaDoc, whereas a manual/readme
can give me a roadmap of what to do/read.
> > BTW - did no one like my logo artwork?
> i'm fairly ambivalent when it comes to logos. but i am
> curious, what's up with the arrow-circle?
> reminds me of the recycling logo.
Ha, I see now that you're right. I wanted a wrench, but arrows were
simpler and seemed to evoke 'velocity'. Main goal: smaller size and add
"Tools".
Speaking of size, which project do I send a patch to reduce the big
honkin' Jakarta logo to leave a little room for a project logo? <grin>
> ah, but then one must wonder why the ToolboxManager & co.
> aren't in the toolbox package, but the tools are. :-(
Ah. Hadn't looked that deep into the src, my eyes glaze over on the
Toolbox emails... so long as the simple config works, I'm happy. ;-)
Nathan wrote:
> i think it'd be nice to cut things down to just VelocityView
> and VelocityStruts (or whatever you want to call them).
> can anyone give a really good reason to maintain a separate
> library just for these tools? after all, they are "view tools."
Aren't the tools supposed to be able to live without
VelocityViewServlet, so folks using other frameworks can leverage them
without the extra baggage?
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 - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> > why all the renaming? (e.g. VelocityStruts -> StrutsView?)
> Well, when I started looking at the soup of names, it was confusing to
> me, and considering I've been following along for quite a while,
> concluded it might confuse others even more.
hmm. i do agree that the current naming and organization of the project is
at times confusing, ugly, and/or inconsistent. i think it might be worth
the time to do some major reorganization, but *only* if we can come up with
and agree on a satisfactory system of names and paths.
> I tried to keep the name changes as minimal as possible, but produce
> more logical sense.
...
> Consistency was and is the tough part with so many re-uses of "view"
> "servlet" "library" "tool"... I'm trying :-)
>
> I'm want to help sort things out. And I don't know the best approach,
> but I certainly don't want to stay with a confusing status quo just to
> avoid a couple cvs delete/adds. ;-)
it's not the CVS work. it's a matter of inertia and consistency. we have
to maintain a common "language" (i.e. system of terms and names) in order to
communicate effectively. even if the existing "language" is not ideal, it's
not wise to rewrite it all without some common agreement and understanding
first.
...
> > i think it'd be best to stay consistent on naming or at least
> > discuss such changes.
> Well, please consider this the discussion. :-)
i suppose. however, though it is related to documentation, it really should
precede it and thus probably deserves a new thread and proposal.
> Obviously I'm not a committer, so it's not like I went out and made the
> changes in CVS. <grin> Also that's why the subject line is "proposed
> update"... and why I only sent it to the DEV list, not V-USERS. Wanted
> feedback from you folks first before regular users knew anything about
> my proposed changes. But alas, looks like as of this morning Pandora was
> let out of her box. :-(
oh. sorry. :-/
> We can wordsmith the docs until they are more suitable for everyone. My
> goal is to help get clear docs out there so a 1.0 release can be made.
> (Gabriel wisely has docs listed as one of the req'ts before a release.)
...
> > none of the toolbox configuration snippets (that i noticed)
> > demonstrate using the <scope> attribute.
>
> I didn't even know the scope attrib existed. Ha!
this is one reason docs need be a requirement before release! :-)
you've probably also missed out on <create-session> and <data> too, eh?
> Agree, that should be added to the docs somewhere. How's it work?
...
> Say - speaking of stuff that might only exist in JavaDocs... what other
> JavaDocs might be good to pull up into the documentation pages?
hmm. probably plenty from ServletToolboxManager, there might be a nugget or
two hiding in XMLToolboxManager. ChainedContext talks about the internal
context search order (note: i just fixed that javadoc), and the various
ToolInfo interfaces and implementations have some meaningful comments. oh,
and the javadocs of the various tools-tools and struts-tools are definitely
worth a look.
> (I find that generally JavaDocs beyond the JSDK usually suck or don't
> exist, so I normally don't go there first. I'm betting others folks are
> perhaps lazy like me and wanting to see some docs first before they
> invest the time to CVS checkout and look at JavaDoc. )
i think that's a shame. personally, i use javadocs quite heavily.
especially since i'm not a huge fan of doing html docs myself (though i
don't really mind writing README's), i tend to primarily use javadoc to
explain things.
...
> Before I start sending in patches, I'd prefer to get some confirmation
> that they are even wanted.
help with docs is always appreciated around here :)
...
> As for the finished product... I'm in the dark as to how Jakarta stuff
> works.
heh. me too. i know the java, but i've yet to really look into how things
work around here with jakarta-site, xdocs, dvsl, or what-have-you. i
suppose i'll have to pay more attention to that stuff now that i'm a
committer.
> Right now, there isn't a link to the sub-projects, except for a single
> page link:
> http://jakarta.apache.org/velocity/toolsubproject.html
> (Speaking of consistency again, notice how the VelocityViewServlet is
> referenced from there as simply "View" subproject. ;-)
>
> Obviously that won't be the production link for the new sub-project,
> right?
hopefully not.
> The velocity CVS package is NOT what we see on the website.
> Ergo:
> If module "jakarta-velocity" becomes /velocity
> I figured "jakarta-velocity-tools" might become /velocity/tools
>
> How wrong am I?
frankly, i don't know. geir? any wisdom regarding the website/docs?
> The reason I needed to care, btw, was so I could change the top logo
> link from "Velocity" to "Velocity Tools" and send links back to the
> correct directory.
>
> BTW - did no one like my logo artwork?
i'm fairly ambivalent when it comes to logos. but i am curious, what's up
with the arrow-circle? reminds me of the recycling logo.
...
> > although i've always hated the /tools/tools too. though it would
> break
> > b.c., i admit i'd be willing to support & implement a change to
> > /tools/library.
>
> "Tool/Tool" or "Tool/Library" seems like a poor analogy.
>
> Howabout "tools/toolbox"? Seems a better analogy since tools do live in
> a toolbox, and of course there is already a ToolBoxManager :-)
...
ah, but then one must wonder why the ToolboxManager & co. aren't in the
toolbox package, but the tools are. :-(
you know, as i think about it, i'm not really sure why we even have a
separate folder tree/jar/et. al. for the non-struts tools. there's all of
three useful classes in there, and one of them is already dependent on the
view package. i'm seriously thinking we ought to fold them into the view
tree/package. i think it'd be nice to cut things down to just VelocityView
and VelocityStruts (or whatever you want to call them).
can anyone give a really good reason to maintain a separate library just for
these tools? after all, they are "view tools."
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 - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> Would just like to know from Nathan/Gabriel that generally speaking this
> bag of proposed stuff looks mostly ok.
apart from the naming issues, i think they're mostly ok.
> I thought it would be easier for folks to eyeball the overall structure
> with a built html version, rather than each person applying a dozen
> separate patches just to get a quick look before saying, "no thanks".
for documentation changes of this degree, i do appreciate this.
...
> That said, do folks want me to start sending in each page's diff?
probably not yet. the naming thing is still a hang-up IMHO.
> Should they be attached to a bugzilla bug report?
> What makes folks happy, one bug report or multiple?
> (BTW I hate calling documentation changes bugs, because aside from the
> true bug Nathan pointed out, the other stuff is largely subjective.)
as far as i'm concerned, there can be bugs (typos or out-of-sync info) in
documentation, but at this point, there is little documentation and
velocity-tools doesn't really exist in bugzilla at this point, so i'm ok
with posts to the dev-list.
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 - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Ted wrote:
> The underlying premise is that we are all team players here,
> and we all have to do what is easiest for the team.
I'm not trying to be difficult, I'll say again, I'll be happy to send in
diffs. Really. :-)
Would just like to know from Nathan/Gabriel that generally speaking this
bag of proposed stuff looks mostly ok.
I thought it would be easier for folks to eyeball the overall structure
with a built html version, rather than each person applying a dozen
separate patches just to get a quick look before saying, "no thanks".
> If its a controversial
> change, you can post the patch to the DEV list for discussion.
Again - that what I'm doing. Just looking for a "that looks generally
okay, send in patch files" or "Yuck, you're all wet, please go away.".
That said, do folks want me to start sending in each page's diff?
Should they be attached to a bugzilla bug report?
What makes folks happy, one bug report or multiple?
(BTW I hate calling documentation changes bugs, because aside from the
true bug Nathan pointed out, the other stuff is largely subjective.)
Cheers,
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - proposed update
Posted by Ted Husted <hu...@apache.org>.
Tim Colson wrote:
> I'm want to help sort things out. And I don't know the best approach,
> but I certainly don't want to stay with a confusing status quo just to
> avoid a couple cvs delete/adds. ;-)
As Nathan mentioned, the best thing is to start with some diffs so that
everyone can see what you would like changed.
Jakarta, like the original Apache product, works mainly on patches. When
a change is made, the diff is emailed to everyone who cares. This shows
us exactly what changes are being proposed (or made).
The underlying premise is that we are all team players here, and we all
have to do what is easiest for the team. As Nathan pointed out, it may
be easiest for you to send a tarball, but then everyone watching the
product has to figure what has changed (or is proposed to be changed).
If you had made the changes in CVS, then there would in fact be less
controversary, since we would have been sent the DIFFs and could follow
the changes.
The way things work is fairly simple. You check out the product for CVS.
You make whatever changes you would like to the product (or
documnetation, it all the same thing). When ready, you create a patch
that shows what changes you would like to make. Most products now like
these attached to a Bugzilla ticket. If its a controversial change, you
can post the patch to the DEV list for discussion. If you are a
Committer, and it's a "typical" change, you can often commit it directly
and discuss it afterwards (if need be).
The Commons has a pretty good description of the process.
http://jakarta.apache.org/commons/patches.html
-Ted.
--
Ted Husted,
Struts in Action <http://husted.com/struts/book.html>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Nathan wrote:
> and here comes feedback... :-)
Thanks...was beginning to think nobody cared. ;-)
> why all the renaming? (e.g. VelocityStruts -> StrutsView?)
Well, when I started looking at the soup of names, it was confusing to
me, and considering I've been following along for quite a while,
concluded it might confuse others even more.
I tried to keep the name changes as minimal as possible, but produce
more logical sense.
Ex. VelocityServlet link pointed to the /view/ directory but references
the "VelocityViewServlet". VelocityLibrary (which brings to mind
"velocity.jar") really contains Tools and lives in /tools/, but calling
it VelocityTools causes the redundant tools/tools reference anyway. Ugh.
I proposed a change to "VelocityViewServlet", leave view/ alone, and
call the menu entry ViewServlet since most everything can be prefixed in
this sub-project as VelocitySomethingOrOther. (Perhaps the menu entry
though should remain consistent despite the ugly long length.)
Consistency was and is the tough part with so many re-uses of "view"
"servlet" "library" "tool"... I'm trying :-)
I'm want to help sort things out. And I don't know the best approach,
but I certainly don't want to stay with a confusing status quo just to
avoid a couple cvs delete/adds. ;-)
> most of these names were somewhat informally decided upon
> in dev list discussions.
Hmm... Okay, I go on/off v-dev and might have missed that, so of course
do what folks think is best.
> think it'd be best to stay consistent on naming or at least
> discuss such changes.
Well, please consider this the discussion. :-)
Obviously I'm not a committer, so it's not like I went out and made the
changes in CVS. <grin> Also that's why the subject line is "proposed
update"... and why I only sent it to the DEV list, not V-USERS. Wanted
feedback from you folks first before regular users knew anything about
my proposed changes. But alas, looks like as of this morning Pandora was
let out of her box. :-(
We can wordsmith the docs until they are more suitable for everyone. My
goal is to help get clear docs out there so a 1.0 release can be made.
(Gabriel wisely has docs listed as one of the req'ts before a release.)
> i know typos are hard to avoid, but a few in there are
> somewhat critical.
> says the VelocityLayoutServlet's reference for screen content is
> $BODY_CONTENT when it's actually hardcoded as $screen_content)
Thanks, I'm sure there are other errors too. That one is easily fixed.
In fact, it's now done. ;-)
> none of the toolbox configuration snippets (that i noticed)
> demonstrate using the <scope> attribute.
I didn't even know the scope attrib existed. Ha!
Agree, that should be added to the docs somewhere. How's it work?
Say - speaking of stuff that might only exist in JavaDocs... what other
JavaDocs might be good to pull up into the documentation pages?
(I find that generally JavaDocs beyond the JSDK usually suck or don't
exist, so I normally don't go there first. I'm betting others folks are
perhaps lazy like me and wanting to see some docs first before they
invest the time to CVS checkout and look at JavaDoc. )
> I could provide cvs diffs if my arm was twisted, but geez I
> changed/added/renamed quite a few files to make this happen. It would
be
> easier to just send a tarball. ;-)
> yeah, but easier for who? :-)
I anticipated this reponse, that's why I said I'd provide them if asked.
;-)
Before I start sending in patches, I'd prefer to get some confirmation
that they are even wanted. And of course, I'll happily get in the habit
of sending patches for corrections like that $screen_content error that
are no-brainers.
> Also moved the tree inside /velocity/tools/ to make it easier to type
> and/or reference. This of course makes a bit of an issue for the
> velocity/tools/tools directory (it works of course...just seems a bit
> bit redundant redundant.
> moving trees == renaming. see previous comments :)
If it's merited, renaming in CVS isn't _that_ hard. <grin>
Seriously though... I honestly did this directory change mostly so I
could post a version for folks to eval that had links that worked.
As for the finished product... I'm in the dark as to how Jakarta stuff
works.
Right now, there isn't a link to the sub-projects, except for a single
page link:
http://jakarta.apache.org/velocity/toolsubproject.html
(Speaking of consistency again, notice how the VelocityViewServlet is
referenced from there as simply "View" subproject. ;-)
Obviously that won't be the production link for the new sub-project,
right?
The velocity CVS package is NOT what we see on the website.
Ergo:
If module "jakarta-velocity" becomes /velocity
I figured "jakarta-velocity-tools" might become /velocity/tools
How wrong am I?
The reason I needed to care, btw, was so I could change the top logo
link from "Velocity" to "Velocity Tools" and send links back to the
correct directory.
BTW - did no one like my logo artwork?
Incidentally, I made the smaller logo(s) to help navigation and allow
the browser to resize a bit narrower than with the big VELOCITY logo.
But still, the printed out version causes an issue since the Apache
Jakarta Project logo takes up 85% of the page. :-(
> although i've always hated the /tools/tools too. though it would
break
> b.c., i admit i'd be willing to support & implement a change to
> /tools/library.
"Tool/Tool" or "Tool/Library" seems like a poor analogy.
Howabout "tools/toolbox"? Seems a better analogy since tools do live in
a toolbox, and of course there is already a ToolBoxManager :-)
Now that I look at it, if that name change was made, then it would make
more sense to move the Toolbox configuration from the tools/view docs:
http://crufty.happysearch.com/velocity/tools/view/docs/index.html#Instal
lation
To:
/velocity/tools/toolbox/docs/index.html
Thoughts?
Also - I hope to hear more feedback both postive/negative. Really
excited here to be able to help any way I can. :-)
Cheers,
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> It's taken me way too long, but I've finally managed to get some work
> done on the documentation for Velocity Tools.
>
> I mostly just cleaned up from the excellent starting point Gabe created.
> Did a bit of weeding, created a smaller Velocity Tools specific logo,
> and then added some bits that were missing for
> installation/setup/description...and then tried to organize things a bit
> better. (ex. The setup I wrote for the StrutsView really applied mostly
> to the basic ViewServlet, there isn't much extra to do for Struts really
> when you come right down to it.)
>
> I posted the current docs as well as the xdocs directories here:
> http://crufty.happysearch.com/velocity/tools/docs/
and here comes feedback... :-)
why all the renaming? (e.g. VelocityStruts -> StrutsView?) most of these
names were somewhat informally decided upon in dev list discussions. i
think it'd be best to stay consistent on naming or at least discuss such
changes.
i know typos are hard to avoid, but a few in there are somewhat critical.
(e.g. http://crufty.happysearch.com/velocity/tools/view/docs/index.html
says the VelocityLayoutServlet's reference for screen content is
$BODY_CONTENT when it's actually hardcoded as $screen_content)
none of the toolbox configuration snippets (that i noticed) demonstrate
using the <scope> attribute. yes, it's optional (and "request" is the
default), but i think best practice would always define it explicitly. the
docs should reflect that.
> I could provide cvs diffs if my arm was twisted, but geez I
> changed/added/renamed quite a few files to make this happen. It would be
> easier to just send a tarball. ;-)
yeah, but easier for who? :-)
diff -u is the standard for altered files, added files can be sent as-is.
i'm not excited about renaming files/libraries without list discussion.
> Also moved the tree inside /velocity/tools/ to make it easier to type
> and/or reference. This of course makes a bit of an issue for the
> velocity/tools/tools directory (it works of course...just seems a bit
> bit redundant redundant.
...
moving trees == renaming. see previous comments :)
although i've always hated the /tools/tools too. though it would break
b.c., i admit i'd be willing to support & implement a change to
/tools/library.
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 - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Tim said:
...
> QUESTION: When we get the 'beta' docs up and available on
> jakarta.apache.org/velocity/xxxx so that we can point users at them to
> get more feedback? (both on the docs and presumably on the code, since
> the docs will I believe spur more developers to give it a try.)
>
> I don't want to put the cart before the horse, so if the answer to that
> question is, "Not until we release a 1.0" - I'd be ok with that.
as long as the docs are correct and to date with the existing code, i see no
reason to wait for a release to put the docs out there.
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 - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Claude said:
...
> > Could build a Model 1 webapp using only *.vm files and a few tools added
> > into the context via the toolbox. Example, a "SQL" tool, #set ($results
> > = $SQL.select("foo, bar from tableFoo") ) )
>
> that's *precisely* what I'm doing, using my "velosurf" tool that I'm very
eager to share...
>
> right now it is not referenced on the jakarta site, but I'd really like it
to be. It could be in the "powered by" main section, but
> what about a "Contrib" section in the tools ? It would be more accurate...
i say go ahead and offer a patch to the "powered by" section, and if/when we
get a contrib section in veltools, we'll try and get it thrown in there.
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 - proposed update
Posted by Claude Brisson <cl...@savoirweb.com>.
> > aware of the fact that Velocity does not support model 1
> Heh heh..well, the VelocityViewServlet does make it possible, eh?
>
> Could build a Model 1 webapp using only *.vm files and a few tools added
> into the context via the toolbox. Example, a "SQL" tool, #set ($results
> = $SQL.select("foo, bar from tableFoo") ) )
that's *precisely* what I'm doing, using my "velosurf" tool that I'm very eager to share...
right now it is not referenced on the jakarta site, but I'd really like it to be. It could be in the "powered by" main section, but
what about a "Contrib" section in the tools ? It would be more accurate...
CloD
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - proposed update
Posted by Anthony Kay <aw...@yahoo.com>.
Tim,
While working on the patch last night, I found that the current
tools has a built-in dependency on the 1.3 velocity jar. This
version apparently does NOT accept the newer key for the
velocity configuration file (I could only get it to read
the config file using the old name). You may want to leave
the example web.xml in the older form and make a note that
the key is changing.
I have the current cvs version of velocity, and when I try to use
that with the tools, I get a NullPointerException. I'm still
trying to work out if I caused that with my proposed patch,
or if it was already a problem.
Perhaps someone else could comment on the relation between Tools
and the current Velocity source tree?
--- Tim Colson <tc...@cisco.com> wrote:
> Hey there Gabe!
>
> I was getting worried that you'd left us for FreeMarker. <grin>
>
> > Finally I found some time to look at your documentation. It
> > looks great! Thanks a lot for your contribution!
> Thanks for the kind words. I'm happy to finally be able to bring
> something to the table, however small.
>
> > - You changed the name of the VelocityStruts subproject to
> StrutsView.
> > I actually prefer the original name. I feel Struts view is too
> generic
> > and the connection to Velocity is lost.
> Alrighty, I'll concede on this since both Nathan and you have the
> same
> opinion, and have also noted that the list majority agrees with that
> too.
>
> I'll fix it and change the header image too.
>
> > - The documentation of the VelocityLayoutServlet is very hidden at
> the
> > moment. Could this be made a little bit easier to find?
> Agreed. I'll pull this up into the top-level tools index.
>
> > - Regarding the section on Model 1 vs. Model 2 in the
> VelocityStruts
> > documentation: I would make this section part of the
> VelocityStruts
> > User Guide.
> Ok. The rationale you gave makes sense. I'll move it there.
>
>
> > aware of the fact that Velocity does not support model 1
> Heh heh..well, the VelocityViewServlet does make it possible, eh?
>
> Could build a Model 1 webapp using only *.vm files and a few tools
> added
> into the context via the toolbox. Example, a "SQL" tool, #set
> ($results
> = $SQL.select("foo, bar from tableFoo") ) )
>
>
> > his application was a mix of model 1 and model 2 design.
> I feel your pain. I'm now working on a similar project.
>
> > - Download: There is now a nightly snapshot available for
> > download. This should be mentioned in the doownload sections
> everywhere.
> Ok, where is that?
> I looked here without luck:
> http://jakarta.apache.org/builds/jakarta-velocity/
>
> > How do you want to proceed? I guess the easiest would be that you
> send
> > me all the documentation files (not diffs) and I check them
> > in from here.
> Hah. Nathan and Ted gave me grief for suggesting the same thing. :-)
> So either your being too nice, or that is honestly the way you'd
> prefer
> to do it.
>
> Either way, give me a chance to make the changes above first (and
> some
> fixes Tony and Nathan suggested.)
>
> Then I'll be happy to send in diffs, or a tarball. Also, the xdocs
> directories are published out on the crufty.happysearch.com server
> too.
>
>
> Whatever you prefer and is easiest for you - I'm flexible and happy
> to
> do whatever works.
>
> QUESTION: When we get the 'beta' docs up and available on
> jakarta.apache.org/velocity/xxxx so that we can point users at them
> to
> get more feedback? (both on the docs and presumably on the code,
> since
> the docs will I believe spur more developers to give it a try.)
>
> I don't want to put the cart before the horse, so if the answer to
> that
> question is, "Not until we release a 1.0" - I'd be ok with that.
>
> Cheers,
> Tim
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
__________________________________________________
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 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
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 Tim Colson <tc...@cisco.com>.
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 - proposed update
Posted by Ted Husted <hu...@apache.org>.
+1
Being a bloody-minded idiot, I tried using the formal syntax at first,
but there are places where it doesn't seem to work well (like inside the
directives), so I tend to use the informal notation now. Velocity != Java.
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.
>
> 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
>
>
--
Ted Husted,
Struts in Action <http://husted.com/struts/book.html>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - proposed update
Posted by Anthony Kay <aw...@yahoo.com>.
--- Nathan Bubna <na...@esha.com> wrote:
> Anthony said:
> ...
> > The documentation does look good. I did find one more thing.
> >
> > In the FormTools documentation in VelocityStruts, several of the
> > examples include parantheses when using the "attribute" method of
> > bean access; the parentheses should be dropped. For example, under
> > $form.getToken() and $form.getTokenName(), the alternative is
> > listed as $form.token() and $form.tokenName().
>
> 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.
Just to be sure I wasn't misunderstood, the items like $form.token() in
the examples should be $form.token. I was pointing out a typo (since
the parentheses are meant for method names, not bean property names).
On Nathan's comments. I agree.
__________________________________________________
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 - proposed update
Posted by Nathan Bubna <na...@esha.com>.
Anthony said:
...
> The documentation does look good. I did find one more thing.
>
> In the FormTools documentation in VelocityStruts, several of the
> examples include parantheses when using the "attribute" method of
> bean access; the parentheses should be dropped. For example, under
> $form.getToken() and $form.getTokenName(), the alternative is
> listed as $form.token() and $form.tokenName().
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.
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 - proposed update
Posted by Anthony Kay <aw...@yahoo.com>.
Hey Tim,
The documentation does look good. I did find one more thing.
In the FormTools documentation in VelocityStruts, several of the
examples include parantheses when using the "attribute" method of
bean access; the parentheses should be dropped. For example, under
$form.getToken() and $form.getTokenName(), the alternative is
listed as $form.token() and $form.tokenName().
- Tony
--- Tim Colson <tc...@cisco.com> wrote:
> Hey folks -
>
> I made some of the changes that Gabe and Nathan suggested
> (VelocityStruts lives again. :-)
>
> http://crufty.happysearch.com/velocity/tools/docs/
>
> Big change to the logo - it's now has a wrench. :-)
>
> All images are now PNG's and use the same font (Trebuchet) as the
> main
> Velocity project.
>
> Brought VelocityLayoutServlet way up to the front.
>
> I'm still waiting on the decision about the VelocityLibrary tree, but
> then I'll start sending diffs for consideration. Now the bulk of
> stuff
> has been setup, it should be easy to suggest small changes via
> sending
> in a diff from the begining.
>
> Cheers,
> Timo
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
__________________________________________________
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 - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Hey folks -
I made some of the changes that Gabe and Nathan suggested
(VelocityStruts lives again. :-)
http://crufty.happysearch.com/velocity/tools/docs/
Big change to the logo - it's now has a wrench. :-)
All images are now PNG's and use the same font (Trebuchet) as the main
Velocity project.
Brought VelocityLayoutServlet way up to the front.
I'm still waiting on the decision about the VelocityLibrary tree, but
then I'll start sending diffs for consideration. Now the bulk of stuff
has been setup, it should be easy to suggest small changes via sending
in a diff from the begining.
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 - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Hey there Gabe!
I was getting worried that you'd left us for FreeMarker. <grin>
> Finally I found some time to look at your documentation. It
> looks great! Thanks a lot for your contribution!
Thanks for the kind words. I'm happy to finally be able to bring
something to the table, however small.
> - You changed the name of the VelocityStruts subproject to StrutsView.
> I actually prefer the original name. I feel Struts view is too
generic
> and the connection to Velocity is lost.
Alrighty, I'll concede on this since both Nathan and you have the same
opinion, and have also noted that the list majority agrees with that
too.
I'll fix it and change the header image too.
> - The documentation of the VelocityLayoutServlet is very hidden at the
> moment. Could this be made a little bit easier to find?
Agreed. I'll pull this up into the top-level tools index.
> - Regarding the section on Model 1 vs. Model 2 in the VelocityStruts
> documentation: I would make this section part of the VelocityStruts
> User Guide.
Ok. The rationale you gave makes sense. I'll move it there.
> aware of the fact that Velocity does not support model 1
Heh heh..well, the VelocityViewServlet does make it possible, eh?
Could build a Model 1 webapp using only *.vm files and a few tools added
into the context via the toolbox. Example, a "SQL" tool, #set ($results
= $SQL.select("foo, bar from tableFoo") ) )
> his application was a mix of model 1 and model 2 design.
I feel your pain. I'm now working on a similar project.
> - Download: There is now a nightly snapshot available for
> download. This should be mentioned in the doownload sections
everywhere.
Ok, where is that?
I looked here without luck:
http://jakarta.apache.org/builds/jakarta-velocity/
> How do you want to proceed? I guess the easiest would be that you send
> me all the documentation files (not diffs) and I check them
> in from here.
Hah. Nathan and Ted gave me grief for suggesting the same thing. :-)
So either your being too nice, or that is honestly the way you'd prefer
to do it.
Either way, give me a chance to make the changes above first (and some
fixes Tony and Nathan suggested.)
Then I'll be happy to send in diffs, or a tarball. Also, the xdocs
directories are published out on the crufty.happysearch.com server too.
Whatever you prefer and is easiest for you - I'm flexible and happy to
do whatever works.
QUESTION: When we get the 'beta' docs up and available on
jakarta.apache.org/velocity/xxxx so that we can point users at them to
get more feedback? (both on the docs and presumably on the code, since
the docs will I believe spur more developers to give it a try.)
I don't want to put the cart before the horse, so if the answer to that
question is, "Not until we release a 1.0" - I'd be ok with that.
Cheers,
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: [VELTOOLS] Documentation - proposed update
Posted by Gabriel Sidler <si...@teamup.com>.
Tim,
Finally I found some time to look at your documentation. I looks great!
Thanks a lot for your contribution! I am glad that you were able to put
some time into this. I always felt that good documentation is half the
rent for a project...
A few remarks:
- You changed the name of the VelocityStruts subproject to StrutsView.
I actually prefer the original name. I feel Struts view is too generic
and the connection to Velocity is lost. I always try to look at this
from the point of view of a Struts developer who isn't much into the
Velocity community. For him, the new name does carry the right info.
Therefore, I propose we stick with the original name. BTW, the name
VelocityStruts was the result of much discussion on the list.
- The documentation of the VelocityLayoutServlet is very hidden at the
moment. Could this be made a little bit easier to find?
- Regarding the section on Model 1 vs. Model 2 in the VelocityStruts
documentation: I would make this section part of the VelocityStruts
User Guide. My original motivation for adding this section was NOT to
educate people about Modell 1/2 designs in general but to make them
aware of the fact that Velocity does not support model 1 designs. If
you are considering to port a Model 1 JSP application to Velocity
Struts you will be forced to redesign you application quite significantly.
At the time I wrote this, I was help a friend to port his JSP application
to Struts and Velocity. We ran into quite some redesign issues because
his application was a mix of model 1 and model 2 design.
- Download: There is now a nightly snapshot available for download. This
should be mentioned in the doownload sections everywhere.
How do you want to proceed? I guess the easiest would be that you send
me all the documentation files (not diffs) and I check them in from here.
Gabe
Tim Colson wrote:
> Updated the formatting on the VelocityLayoutServlet xdocs... much
> prettier now. ;-)
> http://crufty.happysearch.com/velocity/tools/view/docs/velocitylayoutser
> vlet.html
>
> FYI - the view/examples/simple/WEB-INF/lib/velocity-tools-view-0.8.jar
> needs to be updated to include the latest build which contains the VLS.
>
> Say - is there a better way to 'share' the libs between two examples
> besides just copying them? (one for the simple VVS, a second .war for
> the VLS)
>
> Tim
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] example lib sharing - answer
Posted by Tim Colson <tc...@cisco.com>.
Well...answering my own question. ;-)
> Say - is there a better way to 'share' the libs between two examples
> besides just copying them?
Looking at the build.xml for the view examples, I see plainly that the
libs for the example are copied from the main velocity repository during
builds.
(Then later noticed the README in the simple/WEB-INF/lib that mentions
that.)
I've completed a basic layout example webapp (including Nathan's neat
Error.vm).
I think this example along with the other doc updates I've made would be
helpful to folks, but haven't heard any feedback positive/negative.
> http://crufty.happysearch.com/velocity/tools/view/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 - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Updated the formatting on the VelocityLayoutServlet xdocs... much
prettier now. ;-)
http://crufty.happysearch.com/velocity/tools/view/docs/velocitylayoutser
vlet.html
FYI - the view/examples/simple/WEB-INF/lib/velocity-tools-view-0.8.jar
needs to be updated to include the latest build which contains the VLS.
Say - is there a better way to 'share' the libs between two examples
besides just copying them? (one for the simple VVS, a second .war for
the VLS)
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
RE: [VELTOOLS] Documentation - proposed update
Posted by Tim Colson <tc...@cisco.com>.
Updated the my version of the Struts View userguide:
http://crufty.happysearch.com/velocity/tools/struts/docs/userguide.html
1) fixed the table of contents
2) added step-by-step instructions for install with links to
VelocityViewServlet for more detailed setup instructions
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org