You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@myfaces.apache.org by Sean Schofield <se...@gmail.com> on 2005/02/21 19:49:06 UTC
Examples Suggestions
I have a few suggestions on how we might be able to improve our
documentation and examples.
1.) Stop putting examples into the tabbed panel and menu. While this
is nice to have in order to show off the tabbed panel, menu, etc. it
adds a lot of code to the example page that is not relevant to the
component in question. There are issues with subview, verbatim, etc.
that just confuse the issue. I suggest that we rework the individual
component examples so that they can stand on their own.
2.) Make the examples available in the documentation of the
components. It would be nice if you were interested in the date
control to click a link and read about it and then see an example of
the component on the same page.
3.) Include the JSF source of the examples on the example page. It
would be nice to see the actual JSF that produces the component when
reading the documentation and looking at the example. Of course, the
source code can be downloaded and examined, but for the casual user
investigating myfaces, it would be nice to just see the JSF right
there. We could probably do some interesting tricks with ANT scripts
and <f:verbatim escape="true"> to auto-generate this source.
4.) Develop a standard template for component documentation and
examples. This really just means standardizing on items 1-3 (or some
other set of standards.) Each component's web documentation should
have the same look and feel to it with roughly the same layout.
I am bringing these issues up now because I think it might be
something we want to address as MyFaces leaves the incubator. I will
be happy to help with whatever the group can agree on.
sean
Re: Examples Suggestions
Posted by Heath Borders <he...@gmail.com>.
Yeah.
Ideally, the documentation for every component would have its own
minimalist page, and a link to the jsp source for that page.
Including raw jsp source is pretty easy with the a UIOutput with
escape="true".
On Mon, 21 Feb 2005 14:39:34 -0500, Sean Schofield
<se...@gmail.com> wrote:
> > Obviously, its still good to have something like the cardemo to show
> > everything working together.
>
> Agreed. But there isn't much point in showing a bunch of variations
> of tree component and having to embed all of the trees inside of
> subview. The menu example, etc. can just have relatively simple pages
> (like the info, copyright pages, etc.) without the extra custom
> components.
>
> > -Heath Borders-Wing
>
> sean
>
--
-Heath Borders-Wing
hborders@mail.win.org
Re: Examples Suggestions
Posted by Sean Schofield <se...@gmail.com>.
> Obviously, its still good to have something like the cardemo to show
> everything working together.
Agreed. But there isn't much point in showing a bunch of variations
of tree component and having to embed all of the trees inside of
subview. The menu example, etc. can just have relatively simple pages
(like the info, copyright pages, etc.) without the extra custom
components.
> -Heath Borders-Wing
sean
Re: Examples Suggestions
Posted by Heath Borders <he...@gmail.com>.
I like the idea of making minimalist example pages. Like, nothing
more than the view, form, and whatever is necessary to demonstrate the
component.
Obviously, its still good to have something like the cardemo to show
everything working together.
On Mon, 21 Feb 2005 13:49:06 -0500, Sean Schofield
<se...@gmail.com> wrote:
> I have a few suggestions on how we might be able to improve our
> documentation and examples.
>
> 1.) Stop putting examples into the tabbed panel and menu. While this
> is nice to have in order to show off the tabbed panel, menu, etc. it
> adds a lot of code to the example page that is not relevant to the
> component in question. There are issues with subview, verbatim, etc.
> that just confuse the issue. I suggest that we rework the individual
> component examples so that they can stand on their own.
>
> 2.) Make the examples available in the documentation of the
> components. It would be nice if you were interested in the date
> control to click a link and read about it and then see an example of
> the component on the same page.
>
> 3.) Include the JSF source of the examples on the example page. It
> would be nice to see the actual JSF that produces the component when
> reading the documentation and looking at the example. Of course, the
> source code can be downloaded and examined, but for the casual user
> investigating myfaces, it would be nice to just see the JSF right
> there. We could probably do some interesting tricks with ANT scripts
> and <f:verbatim escape="true"> to auto-generate this source.
>
> 4.) Develop a standard template for component documentation and
> examples. This really just means standardizing on items 1-3 (or some
> other set of standards.) Each component's web documentation should
> have the same look and feel to it with roughly the same layout.
>
> I am bringing these issues up now because I think it might be
> something we want to address as MyFaces leaves the incubator. I will
> be happy to help with whatever the group can agree on.
>
> sean
>
--
-Heath Borders-Wing
hborders@mail.win.org
Re: Examples Suggestions
Posted by Sean Schofield <se...@gmail.com>.
Yeah something like that.
sean
On Tue, 22 Feb 2005 16:56:03 +0100, Matthias Wessendorf
<ma...@matthias-wessendorf.de> wrote:
> I guess you mean something like you could
> see on attached png file?
>
> -Matthias
>
> Sean Schofield wrote:
> >>Not sure I follow. Do you mean adding the JSP goop that you should use
> >>in the java doc? If so I agree.
> >
> >
> > What I mean is that its nice to look at the actual JSF code used to
> > generate the example without having to download the source code and
> > open the JSP page yourself. So at a glance, you can see how the tags
> > work, etc.
> >
> > Its probably not as important as simplifying the examples but it would
> > be a nice extra. Maybe we could have a filter or something so if you
> > type hello-world.jsf-source the '.jsf-source' extension means to just
> > encode the file and return without actually processing the JSP.
> > Something like that maybe.
> >
> >
> >>-bd-
> >
> >
> > sean
> >
>
> --
> Matthias Weßendorf
> Aechterhoek 18
> DE-48282 Emsdetten
> Germany
> phone: +49-2572-9170275
> cell phone: +49-179-1118979
> email: matzew AT apache DOT org
> url: http://www.wessendorf.net
> callto://mwessendorf (Skype)
> icq: 47016183
>
>
>
Re: Examples Suggestions
Posted by Matthias Wessendorf <ma...@matthias-wessendorf.de>.
I guess you mean something like you could
see on attached png file?
-Matthias
Sean Schofield wrote:
>>Not sure I follow. Do you mean adding the JSP goop that you should use
>>in the java doc? If so I agree.
>
>
> What I mean is that its nice to look at the actual JSF code used to
> generate the example without having to download the source code and
> open the JSP page yourself. So at a glance, you can see how the tags
> work, etc.
>
> Its probably not as important as simplifying the examples but it would
> be a nice extra. Maybe we could have a filter or something so if you
> type hello-world.jsf-source the '.jsf-source' extension means to just
> encode the file and return without actually processing the JSP.
> Something like that maybe.
>
>
>>-bd-
>
>
> sean
>
--
Matthias Weßendorf
Aechterhoek 18
DE-48282 Emsdetten
Germany
phone: +49-2572-9170275
cell phone: +49-179-1118979
email: matzew AT apache DOT org
url: http://www.wessendorf.net
callto://mwessendorf (Skype)
icq: 47016183
Re: Examples Suggestions
Posted by Sean Schofield <se...@gmail.com>.
> Not sure I follow. Do you mean adding the JSP goop that you should use
> in the java doc? If so I agree.
What I mean is that its nice to look at the actual JSF code used to
generate the example without having to download the source code and
open the JSP page yourself. So at a glance, you can see how the tags
work, etc.
Its probably not as important as simplifying the examples but it would
be a nice extra. Maybe we could have a filter or something so if you
type hello-world.jsf-source the '.jsf-source' extension means to just
encode the file and return without actually processing the JSP.
Something like that maybe.
> -bd-
sean
Re: Examples Suggestions
Posted by Bill Dudney <bd...@mac.com>.
On Feb 21, 2005, at 11:49 AM, Sean Schofield wrote:
> I have a few suggestions on how we might be able to improve our
> documentation and examples.
>
> 1.) Stop putting examples into the tabbed panel and menu. While this
> is nice to have in order to show off the tabbed panel, menu, etc. it
> adds a lot of code to the example page that is not relevant to the
> component in question. There are issues with subview, verbatim, etc.
> that just confuse the issue. I suggest that we rework the individual
> component examples so that they can stand on their own.
>
I agree. Simple is much better as we move out of the incubator and more
people that are unfamiliar with JSF start to join the flock good docs
will save us tons of work.
> 2.) Make the examples available in the documentation of the
> components. It would be nice if you were interested in the date
> control to click a link and read about it and then see an example of
> the component on the same page.
>
Not sure I follow. Do you mean adding the JSP goop that you should use
in the java doc? If so I agree.
> 3.) Include the JSF source of the examples on the example page. It
> would be nice to see the actual JSF that produces the component when
> reading the documentation and looking at the example. Of course, the
> source code can be downloaded and examined, but for the casual user
> investigating myfaces, it would be nice to just see the JSF right
> there. We could probably do some interesting tricks with ANT scripts
> and <f:verbatim escape="true"> to auto-generate this source.
Same question as above.
>
> 4.) Develop a standard template for component documentation and
> examples. This really just means standardizing on items 1-3 (or some
> other set of standards.) Each component's web documentation should
> have the same look and feel to it with roughly the same layout.
>
Agreed, then we can auto generate all the docs...
> I am bringing these issues up now because I think it might be
> something we want to address as MyFaces leaves the incubator. I will
> be happy to help with whatever the group can agree on.
>
> sean
>
>
Thanks Sean!
-bd-