Thomas Mortagne wrote: > On Tue, Jun 29, 2010 at 12:32, Caleb James DeLisle > <[email protected]> wrote: >> >> Thomas Mortagne wrote: >>> On Tue, Jun 29, 2010 at 11:42, Caleb James DeLisle >>> <[email protected]> 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)
So you advocate for adding API which is not explicit in the code, not listed in javadoc, and might create a collision that is undetected on compile? That sounds to me like a hack. > > Groovy does not needs a service to create a document reference so it's > not an issue for it IMO So in groovy/python/ruby/etc. users will not be able to get documents or will they be given the choice of the buggy method and the one nobody is likely to adopt? > >>> 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... Please explain why that is, I see no problem with taking a List as a relative Reference and completing it using the document in the context. The biggest challenge I see is signaling what the "current node" is since each reference is a node as well as a list containing that node and I'm sure there is a way to sneak that information out through a method in the list interface. A hack it would be but I don't see that it would have any major user affecting consequences as would some other ideas. > >> >>>> Caleb >>>> >>>> _______________________________________________ >>>> 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
