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 <[email protected]> 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 Thanks, Jerome.
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs