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")
Thanks
-Vincent
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
