On Feb 17, 2010, at 4:11 PM, Jerome Velociter 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
yes but that's covered by adding new reference-based APIs: List<DocumentReference> searchDocuments(...) To summarize the goal is to remove the need to manipulate any reference as Strings. Manipulating strings representing wiki name, space name or document name is ok. Thanks -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
