On 17/02/10 16:41, Thomas Mortagne wrote: > On Wed, Feb 17, 2010 at 16:11, Jerome Velociter<[email protected]> 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") >>> >> 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 >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >>> >> >> _______________________________________________ >> devs mailing list >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs >> >> > > > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
