Re: [xwiki-devs] [Proposal] Introduce the notion of Nested Documents

On Fri, Jun 12, 2015 at 6:22 PM, vincent(a)massol.net &lt;vincent(a)massol.net&gt; wrote: +1, I'm currently working on http://jira.xwiki.org/browse/XWIKI-12173 and I've added a parameter "showSpaceAsDocument" to the document tree. Thanks, Marius > > Thanks > -Vincent > > > On 11 Jun 2015 at 17:28:11, Eduard Moraru (enygma2002@gmail.com(mailto:enygma2002@gmail.com)) wrote: > >> +1, with the same opinion on long URLs. >> >> So we need a way to have a document hierarchy without impacting the URL >> scheme, unless the admins of the wiki explicitly want to configure it that >> way. This means, as Caty suggested in an offline discussion, not doing the >> proposed item: >> "- Remove the current parent/child mechanism which is outdated (and >> confusing) compared to the new hierarchy." >> >> We still need the parent/child mechanism, but we could disable it by >> default and allow admins that create a new wiki or that migrate from a >> previous XWiki version that does not have ND to preserve their hierarchy >> and not change their URLs. The direction would obviously be to encourage >> the creation of Nested Documents, while still keeping the option of having >> shorter URLs (using parent-child). >> >> Note: If we keep both relationships (space-page and parent-child) the >> create/move/etc UIs will need to check if the parent-child relationship is >> enabled and provide a field to set/alter that too. >> >> Thanks, >> Eduard >> >> On Thu, Jun 11, 2015 at 12:54 PM, Marius Dumitru Florea < >> mariusdumitru.florea(a)xwiki.com&gt; wrote: >> >> > On Wed, Jun 10, 2015 at 6:36 PM, Ecaterina Moraru (Valica) >> > wrote: >> > > Hi, >> > > >> > > Since we discussed so many things lately and there are many technical >> > > constrain that we are facing, I'm going to try to get some conclusions >> > from >> > > the UI perspective: >> > > >> > > First of all there was the discussion about the usability tests. It's >> > true >> > > that users are confused that we provide 2 levels of hierarchy >> > > (wiki/space/page and parent/child). If we can switch to just one it would >> > > be great since it will simplify the user's mental model. Another problem >> > > they had was with the naming, since wiki/space/page does not ring any >> > > folder/page bell, even with the icon usage. That's why I like the concept >> > > of nodes and only one type of entities that can have children. Since we >> > are >> > > on the Web, I think the most likely entity name we could use is 'page', >> > > similar to content-page, web-page, wiki-page (even if technically is a >> > > space or a document). >> > > >> > > Having only one type of entity, I agree to the fact that we should remove >> > > the space notion. We still have complexity, since we will have main-wiki, >> > > wikis*, pages* (child-pages). >> > > >> > > I also agree to remove the notion of 'WebHome' from UI. We can still use >> > it >> > > technically to differentiate old spaces from pages, but for the user >> > > doesn't mean anything, except looking technical. >> > > >> > > Regarding the global-menu, we need to remove the wiki>space>page+actions >> > > display since it is not scalable. This means that the current breadcrumb >> > > zone will display the hierarchy. This is perfectly normal with the >> > current >> > > navigation patterns used all over the Web. Note that classical breadcrumb >> > > do not display entity-type or actions. We shouldn't either. This means >> > (as >> > > stated on >> > http://design.xwiki.org/xwiki/bin/view/Proposal/ExtendedBreadcrumb) >> > > that we need to provide a Drawer + Move actions inside the content-menu. >> > > >> > > Regarding actions, since we will have just one entity-type (not sure what >> > > we do with the wikis) we will need to standardize the entity actions. >> > > Currently we provide just 'Delete' for spaces, but if we don't display >> > > Spaces differently and they are just nodes, this means that we will need >> > to >> > > implement or normalize the available actions. No matter what type it is >> > > technically, the user should be able to: Add (child), Edit, Delete, View, >> > > Administer, Copy, Rename, Move, Export, Watch, View History, View >> > > Informations, View Attachments, View Comments, View Rights, View Objects, >> > > etc. >> > > >> > >> > > Now, what I really don't like are the long URL. For me this is the most >> > bad >> > > decision we can make. Nobody uses long URL on the web. I really like the >> > > way our current parent/child works, it provides the hierarchy in the UI, >> > > invisible in the URL (keeping it relevant to the current page). Hierarchy >> > > anyway should we displayed in Trees, not linear in URLs, since it's hard >> > to >> > > read. People like short URL. They are easier to share, easier to scan, >> > > easier to understand what the content is about. We have the breadcrumbs >> > for >> > > navigation, the URL is for identification. >> > >> > +1, I don't like long URLs either. >> > >> > Thanks, >> > Marius >> > >> > > >> > > Thanks, >> > > Caty >> > > >> > > >> > > >> > > On Mon, Jun 8, 2015 at 11:40 AM, Eduard Moraru >> > wrote: >> > > >> > >> Hi, >> > >> >> > >> Going on the "node" architecture, where we have only documents and child >> > >> documents, here's something interesting that pops up as "the way to go" >> > >> when storing a tree structure in SQL [1]: Closure Table [2]. It seems to >> > >> cover pretty much all use cases, as solution 1 (Path Enumeration - what >> > we >> > >> are doing with the "space" document field) is limited [3] when it comes >> > to >> > >> changes in the tree structure (i.e. renaming/moving a document). >> > >> >> > >> Note: There is also the extension [4] that includes a depth column which >> > >> would be most useful as well. Basically, getting the list of parents of >> > a >> > >> document would cost only 1 query, sorting by depth to preserve >> > hierarchy. >> > >> >> > >> Of course, all this requires an extra table in the database for storing >> > the >> > >> hierarchy relationship. >> > >> >> > >>> > >> >> > >> Thanks, >> > >> Eduard >> > >> >> > >> ---------- >> > >> [1] >> > http://www.slideshare.net/billkarwin/sql-antipatterns-strike-back/48 >> > >> [2] >> > http://www.slideshare.net/billkarwin/sql-antipatterns-strike-back/68 >> > >> [3] >> > http://www.slideshare.net/billkarwin/sql-antipatterns-strike-back/77 >> > >> [4] >> > http://www.slideshare.net/billkarwin/sql-antipatterns-strike-back/76 >> > >> >> > >> On Sat, Jun 6, 2015 at 3:38 PM, vincent(a)massol.net >> > >> wrote: >> > >> >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > On 6 Jun 2015 at 14:20:46, vincent(a)massol.net (vincent(a)massol.net >> > >> (mailto: >> > >> > vincent(a)massol.net)) wrote: >> > >> > >> > >> > > Hi Marius, >> > >> > > >> > >> > > On 4 Jun 2015 at 18:16:03, Marius Dumitru Florea ( >> > >> > mariusdumitru.florea@xwiki.com(mailto:mariusdumitru.florea@xwiki.com >> > )) >> > >> > wrote: >> > >> > > >> > >> > > > On Wed, Jun 3, 2015 at 5:10 PM, Guillaume "Louis-Marie" Delhumeau >> > >> > > > wrote: >> > >> > > > > Hello XWiki committers. >> > >> > > > > >> > >> > > > > >> > >> > > > > Vincent have proposed the development of nested spaces for 7.2 >> > and >> > >> > some of >> > >> > > > > us have already agreed. But the concept of nested spaces >> > >> introduces a >> > >> > > > > problem that Denis have mentioned during some internal >> > discussions >> > >> > at XWiki >> > >> > > > > SAS, and that I am going to report here. >> > >> > > > > >> > >> > > > > >> > >> > > > > From a UI perspective, differentiating pages `A.B.C.WebHome` and >> > >> > `A.B.C` >> > >> > > > > could become very difficult. >> > >> > > > > >> > >> > > > > >> > >> > > > >> > >> > > > > Moreover, we know that a lot of users do not understand the >> > notion >> > >> of >> > >> > > > > spaces, and they are lost when you look at them during usability >> > >> > sessions. >> > >> > > > >> > >> > > > I'm not sure about this statement. My feeling is that many users >> > >> > > > understand spaces as "folders" (they make the analogy with the >> > file >> > >> > > > system). Moreover, whenever we display a space in the XWiki UI we >> > use >> > >> > > > the folder icon, so we encourage the users to make this analogy. >> > >> > > >> > >> > > I agree with Guillaume here. We’ve seen it on this list but more >> > >> > importantly Caty has done some recorded usability sessions and if I >> > >> > remember correctly it was clearly showing the problem. And users don’t >> > >> > understand that Spaces are like Folders which is why we also had this >> > >> > discussion on the list at one point about renaming them as Folder. >> > >> > > >> > >> > > In any case, removing one concept can only be simpler IMO. I find it >> > >> > simpler to have 2 concepts (Wiki, Pages: A wiki is a set of pages) >> > >> instead >> > >> > of 3 (Wiki, Spaces, Pages: a wiki is a set of spaces, which each one >> > >> > containing pages). >> > >> > > >> > >> > > > > The situation is even worse if you consider the notion of >> > >> > parent/child >> > >> > > > > documents, which is completely unrelated to the actual >> > hierarchy. >> > >> It >> > >> > > > > creates confusion! >> > >> > > > > >> > >> > > > > >> > >> > > > >> > >> > > > > To fix these problems, we propose to introduce the notion of >> > >> "nested >> > >> > > > > documents", i.e. the ability to create documents inside >> > documents. >> > >> > > > >> > >> > > > What's the difference at a *conceptual* level between the notion >> > of >> > >> > > > parent/child we have right now and the notion of nested documents >> > you >> > >> > > > propose? I don't see it. >> > >> > > >> > >> > > Yes it’s the same thing from a User POV. One difference is that we >> > want >> > >> > a reference to contain the full path of a doc. Right now you’d need to >> > >> > transport the (Doc Reference + the full Breadcrumb) to represent the >> > same >> > >> > thing. >> > >> > > >> > >> > > But I agree that it’s the same concept, it’s just a different >> > >> > implementation. That’s why I’m proposing to drop the parent/child >> > fields >> > >> as >> > >> > we have them now since it’s just duplicating the concepts (and it’s >> > >> > confusing for users), and to reimplement the Breadcrumb UI using Doc >> > >> > References. >> > >> > > >> > >> > > Note that having the full location in the reference also allows to >> > have >> > >> > URLs containing the full path which is interesting (for knowing where >> > you >> > >> > are by looking at the URL: http://.../view/Space.Page1, http:// >> > >> .../view/Space.Page2 >> > >> > doesn’t indicate anything about the relationship between Page1 and >> > Page2 >> > >> > when Page1 could the parent of Page2). It’s also interesting for SEO. >> > >> > > >> > >> > > > You even use "parent" and "child" words below >> > >> > > > to explain the "nested" notion. The word "nested" sounds very >> > >> > > > technical to me. I don't know about French, but in my native >> > language >> > >> > > > the translation for "nested" is not a commonly used word, unlike >> > >> > > > parent and child. It seems easier to me to explan to a user that a >> > >> > > > document can have a parent document and some child documents (the >> > >> > > > parent / child relationship) then to explain them that a document >> > can >> > >> > > > be "nested" inside another document and can "nest" other documents >> > >> > > > too. >> > >> > > >> > >> > > I don’t think GL has suggested to use the word Nested anywhere in >> > the >> > >> > UI… It’s just a word we use internally to describe the feature. I’m >> > fine >> > >> to >> > >> > continue using the terminology Parent and Children. >> > >> > > >> > >> > > > > Say differently, if a page `A.B.C` exists, nothing should stop >> > the >> > >> > user to >> > >> > > > > create the document `A.B.C.D`. >> > >> > > > >> > >> > > > You mentioned JCR on the next paragraph. Are JCR nodes identified >> > by >> > >> > > > the position (path) in the tree? >> > >> > > >> > >> > > Yes. They call it Path (we call it a Document Reference). >> > >> > > >> > >> > > > I think we should make a distinction >> > >> > > > between the way we identify a document and the way we access that >> > >> > > > document. >> > >> > > >> > >> > > This means using unique ids for identifying docs (and this is what >> > we >> > >> > already have in the DB except the Id is based on its path in the DB >> > but >> > >> > this could be changed and this is our problem). Of course in the UI we >> > >> > should never display these ids. >> > >> > > >> > >> > > > I like the fact that currently when you change the parent of >> > >> > > > a document the document identifier (reference) stays the same. >> > >> > > >> > >> > > It’s not fully true. When we rename a doc the doc id is modified. >> > >> > > >> > >> > > What would be interesting would be the ability to have several >> > Document >> > >> > References for a given doc (with one being the default probably). >> > This is >> > >> > something I’ve been interested in implementing for a long time but it >> > >> would >> > >> > probably require some model changes and it’s not for XWiki 7.x IMO. We >> > >> > could discuss it when we talk about XWiki 8.x and the new model in >> > >> general. >> > >> > See also http://design.xwiki.org/xwiki/bin/view/Design/XWikiModel20 >> > (on >> > >> > that page I had put: “Ability to have multiple references pointing to >> > the >> > >> > same entity” and yes this is also supported by the JCR API). >> > >> > >> > >> > Also note the idea of "An Entity can be a pointer to another Entity >> > (e.g >> > >> > of use case: rename, aliases)” from that doc. This should be not to >> > hard >> > >> to >> > >> > implement using our current model by adding a Type field in the DB. >> > But >> > >> > it’s a breaking change that would require 8.x (because current apps >> > doing >> > >> > queries on the doc table would get the “pointer” Types which should be >> > >> > excluded, unless we add a filter to search*() APIs + the Query API). >> > >> > >> > >> > Thanks >> > >> > -Vincent >> > >> > >> > >> > > > > In JCR[1], there is only one concept: the "node". A node can >> > have a >> > >> > > > > content, and a list of child nodes. In XWiki, documents could >> > >> become >> > >> > a kind >> > >> > > > > of nodes, and we do not need spaces anymore. >> > >> > > > > >> > >> > > > > >> > >> > > > > If we don't have space anymore, we could ask ourselves: "How the >> > >> > rights >> > >> > > > > will be propagated to the children documents? How do we >> > distinguish >> > >> > rights >> > >> > > > > applied to the documents and the rights applied to the >> > children?" >> > >> > > > > >> > >> > > > > >> > >> > > > > I think the easiest solution is to inherit the rights from the >> > >> > parent to >> > >> > > > > the children, unless an object prevent it. We already have this >> > >> kind >> > >> > of >> > >> > > > > mechanism with XWikiRights and XWikiGlobalRights. XWikiRights >> > would >> > >> > be >> > >> > > > > applied for the current document, and XWikiGlobalRights for the >> > >> > document and >> > >> > > > > its children. >> > >> > > > > >> > >> > > > > >> > >> > > > > But changing the XWiki model is a lot of work, that we don't >> > have >> > >> > time to >> > >> > > > > achieve for 7.2. So we propose to make it step by step. >> > >> > > > > >> > >> > > > > >> > >> > > > > The first step is to change the UI to hide the notion of space >> > to >> > >> the >> > >> > > > > users. Concretely, each time a user wants to create a page >> > called >> > >> > `A`, we >> > >> > > > > actually create the document `A.WebHome`. So any child of this >> > page >> > >> > would >> > >> > > > > be created in the `A` space, like `A.Child`. But this child >> > would >> > >> be >> > >> > in a >> > >> > > > > space too, so it would be `A.Child.WebHome` actually. >> > >> > > > >> > >> > > > I find this 'A.WebHome' thing too complex. Look at the document >> > >> > > > hierarchy tree >> > >> > >> > >> >> > http://extensions.xwiki.org/xwiki/bin/view/Extension/Document+Tree+Macro#HD… >> > >> > > > . We can hide the spaces already by relying on the parent / child >> > >> > > > relationship. >> > >> > > >> > >> > > A.WebHome is too complex which is exactly why Guillaume is sending >> > this >> > >> > proposal about Nested Documents. The idea is that the doc will be >> > seen as >> > >> > “A" for the user (and implemented technically as A.WebHome till we >> > update >> > >> > the DB to remove the “space” field, which would make the impl much >> > >> simpler). >> > >> > > >> > >> > > > > Then, when we display the `A.WebHome` page, we remove all >> > mentions >> > >> > to the >> > >> > > > > `WebHome` name. In the UI, it will just be presented as the >> > >> document >> > >> > `A`. >> > >> > > > > This is a good point, knowing the fact that the term `WebHome` >> > have >> > >> > no >> > >> > > > > sense for the user, neither in English or in other languages. >> > >> > > > > >> > >> > > > > >> > >> > > > > Again, these changes are only for the UI. For the applications, >> > it >> > >> > is the >> > >> > > > > developer's job to decide if the app will create documents like >> > >> > > > > `Document.WebHome` or basic documents just as before. >> > >> > > > > >> > >> > > > > >> > >> > > > > The question of what to do with AWM comes up. When a user >> > creates >> > >> an >> > >> > entry, >> > >> > > > > should it be a new-kind-of-document (`AppSpace.Entry.WebHome`) >> > or >> > >> an >> > >> > > > > old-kind-of-document (`AppSpace.Entry`)? The first option is >> > good >> > >> for >> > >> > > > > consistency and for the new possibilities it offers, but the >> > second >> > >> > is >> > >> > > > > better for retro-compatibility. And the question will be the >> > same >> > >> > for all >> > >> > > > > existing applications that create pages. I believe we should >> > answer >> > >> > these >> > >> > > > > questions on a case-by-case basis and deserve their own mail >> > >> threads. >> > >> > > > > >> > >> > > > > >> > >> > > > > This proposal also implies to change some macros, like the >> > >> {{space}} >> > >> > one, >> > >> > > > > and some panels. But I believe there is no blocking-point there. >> > >> > > > > >> > >> > > > > >> > >> > > > > Finally, after these steps are accomplished in 7.2 and polished >> > >> > until the >> > >> > > > > end of the 7.x cycle, we will refactor the XWiki model >> > (something >> > >> we >> > >> > dream >> > >> > > > > about for years). >> > >> > > > > >> > >> > > > > >> > >> > > > > To sum up, the idea we propose is: >> > >> > > > > >> > >> > > > > >> > >> > > > > On the short run: >> > >> > > > > >> > >> > > > > - Hide the notion of space in the UI. >> > >> > > > > >> > >> > > > > - Hide the `WebHome` name in the UI. >> > >> > > > > >> > >> > > > > - When a user creates a page from the UI, it actually creates a >> > >> > space with >> > >> > > > > a WebHome. >> > >> > > > > >> > >> > > > > - Remove the current parent/child mechanism which is outdated >> > (and >> > >> > > > > confusing) compared to the new hierarchy. >> > >> > > > > >> > >> > > > > >> > >> > > > > On the long run: >> > >> > > > > >> > >> > > > > - Remove the notion of space in the model, and replace it by >> > >> "nested >> > >> > > > > documents". >> > >> > > > > >> > >> > > > > - Tune the rights system to inherit rights from parents to >> > >> children. >> > >> > > > > >> > >> > > > > >> > >> > > > > Of course, we can discuss the technical details and the >> > >> > implementation >> > >> > > > > strategies. But for now, we need to know if you accept the >> > general >> > >> > idea >> > >> > > > > (nested documents). >> > >> > > > > >> > >> > > > > >> > >> > > > >> > >> > > > > So, I hope you will like this proposal, and here is my +1. >> > >> > > > >> > >> > > > I'm not convinced. I don't see why we should drop the parent/child >> > >> > > > relationship in order to introduce something similar but more >> > >> complex. >> > >> > > >> > >> > > I’d say mostly because we need to transport the full location in the >> > >> Doc >> > >> > Reference, which allows us to do lots of things: >> > >> > > - display it in the URL >> > >> > > - no need to recompute the breadcrumb every time we need to display >> > the >> > >> > hierarchy (which is the case now and it doesn’t scale) >> > >> > > - ability in the future to have several references for a single doc >> > >> > > - consistency: there’s no reason that the space would be in the >> > >> > reference but not the parent… ATM we have two concurrent concepts >> > which >> > >> > makes it impossible for users to understand the difference between >> > Spaces >> > >> > and child/parent relationships. >> > >> > > >> > >> > > Thanks >> > >> > > -Vincent >> > >> > > >> > >> > > > Thanks, >> > >> > > > Marius >> > >> > > > >> > >> > > > > >> > >> > > > > >> > >> > > > > Thanks, >> > >> > > > > >> > >> > > > > Guillaume D. >> > >> > > > > >> > >> > > > > >> > >> > > > > >> > >> > > > > [1] JCR: >> > >> > https://en.wikipedia.org/wiki/Content_repository_API_for_Java >> > >> > > > > >> > >> > > > > >> > >> > > > > >> > >> > > > > >> > >> > > > > -- >> > >> > > > > Guillaume Delhumeau (gdelhumeau(a)xwiki.com) >> > >> > > >> > >> > >> > >> > _______________________________________________ >> > >> > 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 >> > >> >> > > _______________________________________________ >> > > 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 >> > >> _______________________________________________ >> 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