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.