On 02/17/2010 02:51 PM, Vincent Massol 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<[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")
Which actually exists already. -- Sergiu Dumitriu http://purl.org/net/sergiu/ _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
