Re: [xwiki-devs] [proposal] Make EntityReferences easier to create.

On Tue, Jun 29, 2010 at 12:32, Caleb James DeLisle &lt;calebdelisle(a)lavabit.com&gt; wrote: > Thomas Mortagne wrote: >> On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle >> &lt;calebdelisle(a)lavabit.com&gt; wrote: >>> I believe that in order for a new api to be accepted by the community, it must be more useful and/or easier to use >>> than the api which it replaces. >>> >>> The old way of getting a document was this: >>> $xwiki.getDocument("xwiki:Main.WebHome") >>> >>> The current way to get a document is this: >>> $xwiki.getDocument($services.model.createDocumentReference($context.wiki, $space, "WebHome")) >>> >>> I am quite sure that the user community will choose the former even if it has escaping issues. >>> >>> Lest one think we can bully the community into choosing the latter by deprecation or removal of methods, recall >>> the dismal sales of Windows Vista even with the control afforded by the proprietary license and the awesome power >>> Microsoft wields over the market. The user is the boss, their word is law. >>> >>> My first proposal is that we move to an easier way to handle document names. >>> >>> >>> >>> My second proposal is a possible way to do it. >>> I would like velocity and groovy script authors to be able to give a command like this: >>> xwiki.getDocument(["Main", "WebHome"]); >>> or in velocity >>> $xwiki.getDocument(["Main", "WebHome"]) >>> >>> To make that possible I am proposing we change the reference model as follows: >>> EntityReference extends List<String> >>> Each reference has a name which is expressed as a string, it also has a reference to the next node and the last >>> node. This is a classic example of a LinkedList. The point is that any List<String> is a valid (although reletive) >>> reference. When a relative reference is passed, it is replaced with a complete reference which is completed using >>> the document in the context. >>> >>> As you prepare your -1's please recognize that the community will never go for the current model and almost >>> anything is better than a rift between the community and the development team. If there are any other ideas of >>> how to make it that easy, I would be glad to hear them. >> I don't see why making public script API to get a document easier >> imply to change EntityReferences. You can always have this >> xwiki.getDocument(["Main", "WebHome"]); without touching >> EntityReferences design, you just create a reference from this list in >> the getDocument implementation. > Then we will have > getDocument(Reference) > getDocument(String) > getDocument(List) > not to mention rename, copyDocument etc. > > If we must add new methods because we can't make references easy to create then I think sooner or later we are > going to have to change direction. Note that you forget one feature of Velocity: we can implements an uberspector that automatically convert give list to the corresponding EntityReference. So you would only have getDocument(DocumentReference) in the api but if someone calls getDocument(["Main", "WebHome"]); the uberspector will see that there is not direct match but there is a EntityReference based one so it will convert the List and calls getDocument(DocumentReference)

Groovy does not needs a service to create a document reference so it's not an issue for it IMO

>> Problem with your proposal is that it will introduce several >> limitations  since you have only strings: You have no idea what is >> what in this String list you can only rely on the index of the string >> in the list. >> - the current EntityReferences is that way because we wanted to make >> possible to have a reference with just the wiki and the page and give >> it to a resolver to get a full reference >> - how do you support multiple spaces since you can't know which of >> theses strings are spaces ? > The algorithm would work like this. If the current document is: > xwiki:one.two.three.space.doc > and you reference ["xwiki", "Main", "WebHome"] > it would count back 3 from the current document location and you would get > xwiki:one.two.xwiki.Main.WebHome > To make an explicit reference you could pass an entity which is illegal such as: > [0, "xwiki", "Main", "WebHome"] > or > [$xwiki, "xwiki", "Main", "WebHome"] > Since nested spaces are not implemented I don't see why we need to worry too much about > how easy it is to work around them as long as we know it won't be impossible to implement > when the time comes. Except that, as I said, it is impossible with the design you are proposing...

>>> Caleb >>> >>> _______________________________________________ >>> devs mailing list >>> devs(a)xwiki.org >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >> > _______________________________________________ > devs mailing list > devs(a)xwiki.org > http://lists.xwiki.org/mailman/listinfo/devs >