Hierarchy Layout of App / Data / Content Pages Debate and Proposal

Last modified by Vincent Massol on 2024/11/19 16:14

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 nameStructureRationale and precisionsProsCons 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.

  • Easy to do bulk operations such as the removal of all pages.
ConProspective solution
Many top level spaces are reserved for application data, raising possible conflict issues for users who want to use the same space name for content.No easy way to work around that issue.
L2
/Applications/
 - MyApp/
   - WebHome
   - MyAppClass
 - Users/
   - XWikiUsers
   - XWikiUserSheet
/Data/
 - MyApp/
   - MyAppData1
 - /Groups/
   - AdminGroup
 - /Users/
   - jdoe
/MyProject/
 - MyContent
/Var/
 - Cache/
 - Logs/
  • Analogy of the spaces Applications, Data and Var with several operating systems structure such as Microsoft Windows (folders Program Files, Application Data, ...), Debian (/usr/, /var/, /home/) or MacOS.
  • Each reserved functional area should be configurable.
  • Each user page could be a space.
  • There are far less reserved top level spaces than with L1, hence lowering the risk of conflicts with user data, all the more as the reserved spaces could be configurable.
  • Content and data live in different spaces, but some users consider it's a downside.
ConProspective solution
Content and data live in different spacesSeveral users consider it's an advantage.
Content pages have URLs that include the "Data" prefix followed by the name of the application they relate to.Can be fixed by adding URL rewriting rules but this adds complexity.
Complex migration of existing applicationsSee use case below and solution approach.
What if a page is managed by several applications in the future? For instance a page that contains an XWiki Presentation that includes an XWiki Map and an XWiki Diagram?
L3
/Applications/
 - MyApp/
   - WebHome
   - MyAppClass
 - Users/
   - XWikiUsers
   - XWikiUserSheet
/Groups/
 - AdminGroup
/MyProject/
 - MyAppData1
 - MyContent
/Users/
 - jdoe
/Var/
 - Cache/
 - Logs/

Differences with L2:

  • No reserved Data space: data goes where the user wants to.
  • Top level spaces are introduced for Users and Groups.
  • There is no encouragement to separate data from content by default, but the users can remain free to do so if they wish to.
  • This non-separation is more in line with happens on a personal computer: files produced by applications such as LibreOffice or Gimp, while they consist of structure data just as an XWiki Diagram or XWiki Forum, are not stored in dedicated folders, they're simply stored where the user wants them to.
  • The URLs for accessing content created by users are shorter (they don't include the Data prefix).
  • There is a lack of namespace separation between application code files and content.
ConProspective solution
Data can get scatteredThis could be addressed by user interfaces that guide the users.
Data can end up in places the users did not want want because he did not pay attention at the location he was atUX could bring a solution.
Many users wish to clearly separate data managed by applications from other content. XWiki Standard includes some hacks to try to separate them (for example the Applications Panel and the Navigation Panels)To be investigated, to understand more precisely what hurts the users and if the issue can be solved by UX.
Conceptually, it would be more satisfying if the concept of /home/ folders were represented by a top level Content space, but this could annoy the users to have URLs with such as scheme Content (longer URLs + does not add contain relevant information)Using the action part of the URLs could be a workaround, but then the action becomes mandatory, hence again longer URLs.
Bulk actions become hard and requires scripting, in particular: remove all data, move it to somewhere else, put permissions on them, etc.Could be fixed by generic scripts for doing bulk operations across scattered data.
Complex migration of existing applications.
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:

  • Named according to the Unix layout: easy to understand for developers
  • Dedicated space for all application configurations: easy to undertand where the configuration should take place
  • Dedicated space for all content, should it be data created by applications or not, solving the namespace separation concern
  • To be detailed
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:

  • create a "standalone" Meeting Notes page in whatever location they want; the Meeting Notes application can suggest a (configurable) default location (say the top level "Meeting Notes" page) but the administrator can change that and can also move / rename the previously configured default location without breaking the application
  • or create a "Meeting Notes Collection" / "Meeting Notes Home" page that provides a live data view of existing child meeting notes
    • from this collection / home page the user can go to Create Page and create a child Meeting Notes page, that will then appear in the live data
  • Separation of code and data
  • Code editing is protected by default
  • Users can use whatever top level page name they want (except XWiki)
  • Users can move / rename the application data location without breaking the application (the code remains in the same place)
  • Users can have multiple "instances" of the application, i.e. multiple locations where to group application entries based on their needs (e.g. multiple meeting notes spaces, one per each project)
  • Deleting the (default) application entry space doesn't delete the code. The users should uninstall the application to remove it
  • The applications panel needs to be rethinked: it assumes there is only one space for the application entries; it could point to the (configurable) default application entry location, but it needs to be updated when the user changes the configuration.

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.

 

Get Connected