4 Apr
2007
4 Apr
'07
6:59 p.m.
I am very sympathetic to Uwe's plight, as even with the Javadoc I was
all but lost until I actually started running it under Eclipse, where I
could follow references through all of the indirections and blind
interfaces.
An idea that I had some time ago got some discussion, but no action
(including from me): have XWiki pages that import the Javadoc through a
filter that decorates parts of it with comment blocks for people to
scribble on, so that our collective understanding can accumulate bit by
bit and the real Javadoc comments can be improved.
I think the reason that it never went anywhere was that, in addition to
not having a lot of time (despite knowing that it would save a lot more
time than it cost us), we're all such a lot of incurable GEEKS that we
had to architect a perfect, scalable, future-proof solution before
beginning to work. Ironic enough since the whole wiki concept is about
creating an environment where ideas can be developed together starting
with just the barest seed and proving ideas as they are put forward,
scrapping them and starting over when it gets too hard to continue in
one direction.
Now that I think of it, one reason that I didn't get anywhere in trying
something like that was that I was unable to locate an HTML DOM library
that I could read the pages into, decorate and display.
I think I'm going to start another Idea page...
brain[sic]
-----Original Message-----
From: Vincent Massol [mailto:vincent@massol.net]
Sent: Wednesday, April 04, 2007 11:31 AM
To: xwiki-users(a)objectweb.org
Subject: Re: [xwiki-users] Xwiki.com API stability and
Class/Object model
On Apr 4, 2007, at 5:04 PM, Oova wrote:
Hi Vincent, Thanks for the prompt response, Please see my answers
below. I took out the pieces, which are answered.
[snip]
>> - How is the visibility of references
across
spaces/pages? I assume
>> references created locally on a page
(e.g., $mydoc) stay local,
>> means if you want for example work with one document on
the menu and
>> the toolbar and the main page, you have
to create a kind of
>> administrator object, which can be used across the xwiki
or space.
>> What is the recommended practice here?
>
> Have you tried it? I don't have the time right now but I'd say the
> scope is global.
>
> I tried, and the vairables were not global.
Mistake?Design?Problem I
> had?
Cool then, I was worried the scope was global :)
I can think of 2 ways to share data:
1) Use the Servlet scopes: Application scope, Session scope
or Request scope. You can get access to the request using
$request. The session can be obtained with $request.getSession(), etc.
2) Use the XWiki Context:
$context.put("mykey", someObject);
and
$context.get("mykey")
>> - I would volunteer to create a docu
about how to use the
API, if I
>> understood the inner guts of it. When is
a documentation planned
>> with some examples, who is in charge of it and could help?
>
> Have you checked the documentation on http://xwiki.org? What is
> missing? Everyone is in charge... It's a wiki. You see
something that
> is required, you volunteer, you ask on the
list first and explain
> what you want to do and when you get agreement, you edit pages on
> xwiki.org and implement it.
>
> I do look after xwiki.org to ensure it stays consistent,
has a good
> quality, etc.
>
> Vincent, I spent hours trying to understand the meaning of the
> methods and their parameters in the API docu. After I
thought I had a
> hunch, I tried them and failed in approx. 60%
of the cases (which
> just means I didn't understand).
40% is quite good seen the low level of comments... :)
> The docu is generated automatically and only
if somebody added a
> comment to the method, you have additional information.
> Example:
> getAttachmentURL(java.lang.String filename, java.lang.String
> action) ,
> what is "action"? I have no clue, other parameters I am clueless
> about is 'key'. What does the $context really mean and how
do I use
> it correctly?
> What does the method getProtectedContext() do, the notion of
> protectedContext is new to me, etc. etc. Did I miss a whole
> documentation, which explains such things? I hope I was more clear
> what I meant.
Yes, and all your points are very valid. We're missing a
developer's guide. We discussed this with Jean-Vincent the
other day and we came up with the following ideas:
http://www.nabble.com/Developer%27s-Guide-improvements-ideas-
tf3455730.html#a9641200
Right now, I think the easiest way for someone to develop on
top of XWiki is by looking at examples:
- by looking at existing pages sources
- by looking in the Code zone on xwiki.org
Now of course, once you figure out what something is doing,
help is welcome to improve the doco.
> And I
> understand it is a wiki and everybody is invited to
contribute, but I
> need to understand the architecture and
concept first,
before I start
> documenting it. Maybe it is just me.
No it's not you... Documentation isn't too good on the
development side.
>
>> - How to I archive the code I created? Any export/import
mechanism
>> available?
>
> Have you checked the documentation on xwiki.org? :-)
>
> I'm not giving you the answer as I want to ensure this is
something
> easy to find out. If you don't find it
easily please let us know
> where you were expecting it so that we can improve the
documentation!
>
> I was looking for import/export with search function and found one
> relevant document from you
> http://www.xwiki.org/xwiki/bin/view/AdminGuide/ImportExport which
> doesn't apply to users of the farm. What did I miss?
ok so you found the page, cool. Why do you say it doesn't
apply to users of the farm?
Thanks
-Vincent