Re: [xwiki-devs] [Proposal] strategy for string vs Reference usage in vm files

> 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(a)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')