Hierarchy Layout of App / Data / Content Pages Debate and Proposal
- XWiki
- Design
- Idea
- [forum.xwiki.org] thread - November 2019
- [xwiki-devs] Application pages layout best practices - Spring 2019
- [xwiki-devs] [Proposal] 2 new rules for Application Best Practices - 2015
Description
The current best practices for application pages layout raises some concerns. Their pros and cons are summarized in the table below, in comparison with alternative layouts. This page contains also a section describing several use cases and open questions, and solution attempts to meet these use cases (work in progress).
Layout comparison
Layout name | Structure | Rationale and precisions | Pros | Cons and prospective solutions | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
L1 (current) | /MyApp/ - Code/ - MyAppClass - MyAppSheet - WebHome - MyAppData1 /MyProject/ - MyContent /XWiki/ - XWikiUsers - XWikiUserSheet - XWikiGroups - XWikiAdminGroup - jdoe | Everything's related to one application is stored in a top level common area. |
|
| ||||||||||||||
L2 | /Applications/ - MyApp/ - WebHome - MyAppClass - Users/ - XWikiUsers - XWikiUserSheet /Data/ - MyApp/ - MyAppData1 - /Groups/ - AdminGroup - /Users/ - jdoe /MyProject/ - MyContent /Var/ - Cache/ - Logs/ |
|
|
| ||||||||||||||
L3 | /Applications/ - MyApp/ - WebHome - MyAppClass - Users/ - XWikiUsers - XWikiUserSheet /Groups/ - AdminGroup /MyProject/ - MyAppData1 - MyContent /Users/ - jdoe /Var/ - Cache/ - Logs/ | Differences with L2:
|
|
| ||||||||||||||
L4 | /etc/ - MyApp/ - configuration - XWikiPreferences - ... /sys/ - MyApp/ - WebHome - MyAppClass - Users/ - XWikiUsers - XWikiUserSheet /var/ - cache/ - logs/ /wiki/ - users/ - jdoe - groups/ - AdminGroup - MyProject/ | Differences with other layouts:
|
| To be detailed | ||||||||||||||
L5 | /My global meetings/ - Some meeting notes /MyProject/ - Project Meetings/ - First meeting - Second meeting - Project roadmaps/ - First roadmap - Second roadmap /XWiki/ - MeetingNotes/ - Class - Sheet - Template - TemplateProvider - Translations - ConfigurationClass - ConfigurationSheet - AdministrationSection - HomeTemplate/ - DemoMeeting - HomeTemplateProvider - Roadmap/ - ... - CKEditor/ - JSX / SSX / UIX - Lightbox/ - Notifications/ - XWikiUserSheet - XWikiGroups - XWikiAdminGroup - jdoe | Put the application code in a nested space inside the XWiki top level space, which should be the only top level space reserved by XWiki. The users should be allowed to use any other name for a top level space. Applications that can have entries (data) should not enforce a specific space where entries are created. The users should be allowed to create application entries in multiple places, and to be able to group them under multiple "home" / "collection" (live data) pages. Applications could provide a "Home page" template to help with that. Applications could also have a "default entry location" configuration that points to a page outside XWiki top level space, and the users should be able to move / rename that default location (besides being able to use other locations for storing application entries). To take the example of a hypothetical Meeting Notes application, after installing it there's no top level space created by default for holding meeting notes. The user goes to Create Page and has two options:
|
|
|
Questions and use cases
User interface homogeneity when creating data
Use case:
- I create a blog post from the blog application home page, or via the create button
- I want to go through a workflow that is similar in order to understand this is the same action
Solution:
- The user interface experience when creating any new entry in the wiki should be as unified as possible, so that the user understands that in all cases, he creates a page that lives in a hiearchy. Either the create action screen could be made generic enough to be the default in all cases, or if too complex, part of it could be reused to make it clear that the underlying action is the same.
Ability to keep data and content separate or grouped
Use case:
- As a user, I want to store in a specific folder data that gets created and managed by application A, that is distinct from pages that do not contain data
Solution:
- In L1 or L2: I can choose the target folder when creating data, however the space reserved by the application, e.g. "Diagram" or "Data/Diagram" remains present in the wiki, wherever I actually want to store my data, and even though for instance I never intend to use the "Data" folder.
- In L3 or L4: I can choose the target folder, none is reserved by default. I can also specify in the TemplateProviders which target space that I define should be used.
Use case:
- As a user, I want to store data that gets created and managed by application A in any folder
Solution:
- Doable in any layout, with the con in L1 and L2 that some spaces are reserved.
Multiple home pages for applications
Use case:
- I install the Blog application
- I create a blog for MyProject in space "MyProject.Blog"
- I want to view the home page of the blog application at "MyProject.Blog.WebHome", so that, in particular, I can see all blog posts this blog has, and I can easily create a new blog post directly from that page.
Solution:
- Make the application home pages generic enough to be includable from any other page.
Migration to the new hierarchy
Use case:
- I have an instance of XWiki with several applications organized in a previous layout
- Upon application upgrade, I want that the application code and instances get rearranged according to the new layout
Solution:
- Upon upgrade, fire Java code that performs the transition to the new class, and migrate the existing object instances, but leaving the documents in their original location, so that users can remain free to use the current structure or move to a different one.