On 17/02/10 16:41, Thomas Mortagne wrote:
On Wed, Feb 17, 2010 at 16:11, Jerome Velociter<jerome@xwiki.com> wrote:
On Feb 17, 2010, at 2:41 PM, Jerome Velociter wrote:
On Feb 17, 2010, at 11:42 AM, Vincent Massol wrote:
On Feb 17, 2010, at 11:35 AM, Jerome Velociter wrote:
>> On Wed, Feb 17, 2010 at 10:45, Jerome Velociter<jerome@xwiki.com> >> wrote: >> >>>> Hi, >>>> >>>> I'd like to suggest the following strategy for now: >>>> >>>> * We modify all our vm files to use references (by using the >>>> ModelScriptService, see below) >>>> * We introduce APIs taking References in api.* (ex: api.Document, >>>> api.XWiki) >>>> * We _don't_ deprecate existing APIs in api.*. This means we allow >>>> users >>>> to use the older string APIs for ease of use >>>> >>> Hello Vincent, >>> >>> Before I can make up my mind, I would like to know: >>> >>> * What will be the strategy for velocity code in wiki pages (here >>> you >>> mention only .vm pages - will the strategy be voted again for wiki >>> pages?) >>> >>> * Considering we use the same strategy for wiki pages, and since we >>> do >>> not >>> deprecate the old APIs that manipulate strings, what will be the >>> 'recommanded' way of say getting a document ? (the one we would >>> advertise >>> on xwiki.org code examples for example) >>> >> To summarize: >> * String based methods: helper methods for users >> * EntityReference based methods: what we are supposed to use or >> anyone >> that want to write proper code >> > OK, that's what I wanted to know :) > > I share this vision, and would be -1 to deprecate string based APIs > (unless of course replaced with new string based helpers). I think > it's > important that we keep (velocity) simple scripting accessible to > non-developers and that was my concern. You don't want to force users > to > know/understand what a reference resolver is for instance. > ... and you'll get lots of complaints on the list telling us our software don't work because they'll have "forgotten" (or simply don't know about it) to escape special chars... ;)
> As for what we do for velocity code in our own wiki pages (not .vms), > I > would tend to think we should keep it simple to read for users (so > with > string based APIs) but I'm a bit undecided. > It's not a question of choice. There's simply no choice jerome.
If you don't use the reference-based apis then you have to manually perform parsing/serialization, i.e. manually recode the reference API.
Except of course for the cases where you know the full reference specifically and you can guarantee there's no special chars in it.
That's what I am talking about.
For example : $xwiki.getDocument('XWiki.Ratings') or $xwiki.ssx.use('XWiki.Ratings')
vs $xwiki.getDocument($services.model.createReference("XWiki", "Ratings"))
Actually in this case I'd be for adding a new method instead: $xwiki.getDocument("XWiki", "Ratings")
Yes that would be good.
We also need a helper for old "full names" (Space.Name), i.e. the ones returned by #searchDocuments APIs
I would not like to see/write :
#foreach($docName in $xwiki.searchDocuments("where doc.author<>'XWiki.Admin'")) #set($myDoc = $xwiki.getDocument($services.model.resolveDocument($docName, "current"))) ## ... do something with myDoc #end
Sure but you will be supposed to use #searchDocumentReferences method, etc. The only issue is that not all APIs have the new reference based version yet but it will.
OK, thanks for the explanations. I'm +1 for the strategy expressed by Vincent, especially +1 _not to_ deprecate old String APIs Jerome.
Thanks, Jerome.
Thanks -Vincent
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs