Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: pass (herse.apache.org: domain of ross.gardler@googlemail.com
 designates 209.85.146.179 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=googlemail.com; s=beta;
        h=received:message-id:date:from:sender:to:subject:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references:x-google-sender-auth;
        b=ghrqpl59qtzZvI2QhF3gddlQpB43qS9mf3zOPvCKbkViibVRdB7MOwqq7oajFh1sJULaPC9RKGNpOx2lBf/3zYs8Ajyef8uL9Kf+XSZmY3Lc8ODrU76SsTqMwZUTr3E8ssv9Y6ijG+YFVVq1IKr6QPRD4uI1p2w4c/c8IILf1Lg=
Message-ID: <61c9bc470706060642j58ce8896g5b74482ddc074813@mail.gmail.com>
Date: Wed, 6 Jun 2007 14:42:49 +0100
From: "Ross Gardler" <rgardler@apache.org>
Sender: ross.gardler@googlemail.com
To: dev@forrest.apache.org
Subject: Re: Outline FOAF plugin
In-Reply-To: <a477174c0706052321r5b432e0v9a732681d3e1a974@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
References: <a477174c0706052321r5b432e0v9a732681d3e1a974@mail.gmail.com>

On 06/06/07, Oshani Seneviratne <oshani@apache.org> wrote:
> I have created an outline FOAF plugin and attached the patch to a JIRA issue
> FOR-1002 [1] . I would really appreciate if my mentor/co-mentor or any one
> of the Forrest developers could take a look at it and comment.

Fantastic, well done Oshani. I will have time to look over this later
today if Gav or someone else does not beat me to it.

> As the first step, I simply wrote an xsl to extract the plain XML data out
> of a FOAF document. The idea was to read through a *single* FOAF document
> and generate all the person details and index those in a single page.
> There's nothing fancy in this yet: in fact, I didn't consider much of the
> semantics of FOAF. Only used just the basic terms such as foaf:person,
> foaf:knows, etc.

This is exactly what we need to get us started. In open source release
early, release often is very important. Early feedback means that
improvements can be made quickly and easily. Don't be afraid of
committing things that may not be perfect, or even things with known
issues. As long as the known issues are documented that is fine.

> For the next development step, I believe we could create multiple pages with
> multiple FOAF files which could be either related (with a foaf:knows
> relationship) or unrelated, and possibly enhance the number of
> transformations of the FOAF semantics in the xsl. Anyway, I would like to
> hear your comments on this and any other possible enhancements that we could
> do.

I think your proposal is a good one with respect to progression.

Thinking about your plugins wider use, the DOAP standard uses FOAF to
record maintainer, translator and developer information. It would be
interesting to see how your FOAF and the DOAP plugin would play
together. That is have the DOAP plugin use your FOAF plugin to render
the FOAF info in DOAP files.

One caveat here, Forrest does not support dependencies between
plugins. For now we need not worry about this, as we are planning to
switch to an IVY build management system for plugins and that will
address the issue. However, if you move forward to this step you
should add an entry in the issue tracker to remind us of this
dependency.

A second caveat is that since we have not done any dependencies
between plugins before there is no documentation on how to do it. So
you'll probably want to float the idea here before tackling it.

> While developing this initial version of the plugin, I came across few
> forrest specific problems.I apologize if these have been answered before (I
> did go through much of Forrest's code, checked almost all of Forrest's
> documentation and the mail archives but was not able to find the answers.)
> They are not major problems, however I would like to get them clarified:
>
> For instance,
>
> 1. After seeding the plugin and after doing all the configurations as
> advised in [2], I did 'forrest run'... only to find that it failed because
> the plugin descriptor was not to be found.
>
> So, as a workaround, I did the following:
>   Copied a plugins.xml file to the foaf plugin dir
> (FORREST_HOME/whiteboard/plugins/o.a.f.p.i.foaf)
>   Added a new plugin entry there for the FOAF plugin
>   Added '
> forrest.plugins.descriptors=file:///${project.home}/plugins.xml'
> in to the forrest.properties file.
>
> After this, it did not complain about any missing plugin descriptors.
> So, my question is, is this the expected way of letting the forrest build
> know about a new plugin (at least until the plugin is registered in the
> official plugin descriptor files)?

That is an oversight in the documentation, it would be good if you
could provide a patch to the docs.

In this case you can add your entry directly to the whiteboard
plugins.xml file as we will certainly be accepting your plugin into
the whiteboard.

If you were not donating this to the project then you would need to
create a local plugins.xml file and reference it in the
forrest.properties file as you have done. However, you would need to
ensure existing plugins.xml files were also referenced.

> 2. When I ran the 'ant test' target against the plugin, it failed saying
> that there are broken links in the site. I found the culprit to be a couple
> of @rdf:ID and  @rdf:resource elements I embedded in the xsl.
>
>  For example,  there's the following line in the foaf-to-document.xsl
>  <a href="{foaf:homepage/@rdf:resource}"><xsl:value-of
> select="foaf:homepage/@rdf:resource"/></a>
>
>  When Forrest renders this link it leads to a relative path like
> "http://localhost:8888/homepage_url_given_in_foaf:homepage/@rdf:resource".
>  How can we make it absolute, so that it will be linked to
> "homepage_url_given_in_foaf:homepage/@rdf:resource" and not
> the relative url as in above?

I'll need to look at this in the code to see exactly what is
happening, I understand the question, but not the context at present.
perhaps you should raise an issue about this. I just added a new
"Plugin: input.FOAF" component to JIRA for you.

> 3.I was able to see the transformation I intended with the xsl at
> http://localhost:8888/personDetails.xml (in one of these
> forrest's internal doc forms I believe). However, when I point my browser to
> http://localhost:8888/personDetails.html, I could only see
> a blank page with the default forrest skin applied. The content was missing!
> Now, how is this page generated? Is the
> FORREST_HOME/main/webapp/sitemap.xmap responsible for
> generating this html page?

Yes. The document at [3] should help understand the process, in
particular see the section "Understanding the HTML-Pipeline"

> More importantly, what changes should I make to get those content from the
> transformed FOAF into that html?

This depends on why it is not being rendered. The fact you see a
result from the *.xml request is good. I'm guessing that there is a
problem with the doctype or something like that. Again, it will
probably be easier to answer your question when I look at the code.
Create an issue for this please.

>  4. This could be a very silly question, but thought I'd ask anyway... Would
> you advice against making changes to the plugin source within the build dir,
> once it is locally deployed in the FORREST_HOME/build/plugins? I ask
> because, I found it much more convenient to make changes from the build dir,
> rather than from
> FORREST_HOME/whiteboard/plugins/o.a.f.p.i.foaf, do 'ant
> local-deploy' and then do 'forrest run' after each and every change. :)

I would advise against it, there is a potential to forget to copy the
changes back. I've lost many hours this way in the past.

What I do is have a shell window open that I use for deploying the
plugin, thus the deploy process is just "CTRL-TAB -> up arrow ->
return"

Pretty soon it becomes second nature.

Alternatively, if you use an IDE you could add it as a build step, so
that whenever you save a file it gets deployed.

> Also, I think I should mention that, although I looked in to the possibility
> of using dispatcher with this initial outline plugin, I am afraid I did not
> make much progress with that. Hopefully, in the coming weeks I would be able
> to understand how to use it. Until then I am going to experiment a bit and
> learn more. Any hints on how to get up to speed with dispatcher with this
> plugin will be appreciated!

I'd say ignore the dispatcher for now. It is not a simple beast, but
you can do many things with it that you can't do with plain skins.
When you hit that problem then we'll look at the dispatcher.

Ross

>  [1] https://issues.apache.org/jira/browse/FOR-1002
> [2]
> http://forrest.apache.org/docs_0_90/howto/howto-buildPlugin.html
>

[3] http://forrest.apache.org/docs_0_90/howto/howto-custom-html-source.html#Understanding%20the%20HTML-Pipeline