Page MenuHomePhabricator

Allow top-level wiki doc to display entire document hierarchy instead of only 2 levels
Closed, DuplicatePublic

Description

As usual, please let me know if a quick'n dirty temporary patch can be applied to the code.

Event Timeline

swisspol created this task.Jun 3 2014, 3:37 PM
swisspol raised the priority of this task from to Needs Triage.
swisspol updated the task description. (Show Details)
swisspol added a subscriber: swisspol.
epriestley triaged this task as Wishlist priority.Jun 3 2014, 4:18 PM
epriestley added a project: Phriction.

Oh, sorry that's actually fixing a different issue (if you have more than 250 documents, only the first level will be shown). There's no easy workaround for showing unlimited levels.

In general, we need to have a cutoff somewhere. If you have a million documents total or 100 levels of documents, showing them all won't produce a meaningful result.

We currently show at most 250 documents from the first two levels, dropping deeper levels until the result set fits within the limit or we've discarded all documents not at top level.

We could adjust this approach slightly and attempt to show documents across more levels (say, 5 levels instead of 2), applying the same logic to discard results until we have reach a reasonable limit. This query needs to be rewritten for T4029 anyway.

Ah right that makes more sense. Can't I just fix the query to cut at say 4 instead of 2?

BTW there should be some UI feedback if not showing all results in either direction I.e. Clipping at 250 total or at depth 2 (for this one maybe adding ellipsis under the tasks at level 2 if level 3 ones are present)

i find the current display of documents a little lacking: it is a bit misleading (because there are effectively hidden documents), it gives a poor overview of the entire document landscape, and it forces a lot of extra clicking & reloading if i am trying to get to a deeply nested document.

i'd love to have some features to improve this:

  1. an indicator of how many documents are not being shown
  2. a global configuration to control how many levels to show by default
  3. client-side full-tree hierarchical navigation

i think #3 is the "right" way to go, i.e. send the entire document tree to the client and allow a typical client-side hierarchical navigation with and icons to collapse/expand branches.

for #1, i think an improvement would be:

* Top Level Doc 1
  * Sub Doc 1.1 (3 sub documents)    # inline style
  * Sub Doc 1.2
    * (3 documents not shown)        # indented style
* Top Level Doc 2
...

if you agree, i can work on a stop-gap implementation of #1 and #2 while someone implements #3.

send the entire document tree to the client

What if there are one million documents?

We don't want anything in the upstream which fails for installs with a million documents. All of your proposed solutions break down at that scale. Things in the upstream should work if the wiki content is, e.g., the entire contents of Wikipedia, or some team decides to automatically generate tens of thousands of wiki pages with the API, or whatever else.

good point. how about an ajax call? i.e. any time a level is expanded it returns a json array of the documents in that branch (a spinner is displayed while fetching).

the endpoint would support pagination in case any one level has an excessive number of documents, and the client would have a typical "see more" button.

for example (and depending on how phabricator standardizes paginated responses), requesting the third "page" of a branch with a million documents would return:

{
  "documents": [
    {"id": "34", "name": "doc-1"},               # this doc is a leaf node
    {"id": "53", "name": "doc-2", "leaves": 3}   # indicates this node has 3 child leaf nodes
  ],
  "pagination": {
    "size": 2,
    "offset": 4,
    "count": 1000000
  }
}
chad added a subscriber: chad.Feb 25 2015, 9:32 PM

How many documents / levels do you have @metagriffin?

I don't know how you'd build #1 if you have more than 250 documents, Performance is always going to be the main issue for any solution. #2 won't be considered either, we're fairly strict about "config options" and they need to truly be something most admins would consider setting / need to set.

The most correct current path is still likely T5254#62173. This task though isn't on any Roadmap, so we're unlikely to pursue it for some time.

case in point: to answer your question took *many* clicks... 5 levels (less than 100 docs).

I don't know how you'd build #1 if you have more than 250 documents

i don't know what the UI currently does, but for #1 i'd imagine something like this would be more useful than just truncating them:

* Doc 1
...
* Doc 250

(512 Documents not shown) [button "show more"]

Performance is always going to be the main issue for any solution.

that is the beauty of #3: it accomplishes it asynchronously, thus it would actually perform better than any of the other approaches including what is being done now.

The most correct current path is still likely T5254#62173.

that may help, but it does not solve the problems of:

  • it is misleading (because there are unintentionally hidden documents)
  • it gives a poor overview of, and ability to navigate through, the entire document tree

i think client-side traversal wins hands-down. #1 and #2 were my ideas on how to solve the problems in the interim.

chad added a comment.Feb 25 2015, 11:26 PM

The core issue is Phriction itself doesn't have the robustness to allow organizations to build structure in their documents (ie, be a real CMS). Some of these features are already roughly planned out. Relying on a tree of hundreds or thousands of links isn't the solution we intend to pursue, we'd rather solve the issue in other ways. We're not apt to accept stop gap solutions if it means they'll have to be removed down the road.

If you already have a local patch or fork, that's really going to be the best option for now.

ok... yet another solution:

  1. add a "Hierarchical" option to the "Order" drop down on the index page, which would cause it to render in tree mode.

would you accept a patch that does that?

and, while i'm there, would you be ok with adding an "Alphabetic" sort order too?

chad added a comment.Feb 26 2015, 4:46 AM

Hmmmmmmmmmmmm.

What about making the full list a dialog? If there are more than 250, then show a button on the hierarchy box to see the full list, which then just displays dialog. That way later we can add search or other things to the dialog if needed.

since my current problem is the nesting limit, not the doc count limit, can we make it "more than 250 OR more than 2 nested levels"?

thus, i propose:

  1. when generating a phriction document's "Document Hierarchy", a "See Full Hierarchy" button (SFH) shall appear if any child documents are not shown, which can currently happen if either:
    1. there are more than 250 documents
    2. documents are nested in more than 2 levels
  2. when clicking the SFH button:
    1. a dialogue is opened that displays a spinner
    2. an ajax request is dispatched to fetch the entire list (no limits) of children to the current document
    3. on ajax completion, the entire list is rendered into the dialogue, formatted identically to the current Document Hierarchy

how about anchoring the endpoint referenced in 2.2 at /phriction/children/{ID}/?

the endpoint shall accept the following options in preparation of a better client-side implementation (for SFH, depth and page.size will be set to infinite):

  • depth parameter controlling the nesting limit, 0 for infinite, default: 2
  • pagination options:
    • page.size parameter to control page size (in documents per response), 0 for infinite, default: 250
    • page.offset parameter to control starting response offset (in documents, not pages), default: 0
    • page.sort parameter to control sorting method (for now, restricted to hierarchical)

and shall respond with JSON, as in the following example:

{
  "documents": [
    {"phid": "PHID-WIKI-...", "uri": "...", "title": "...", "slug": "...", "status": "..."},
    {"phid": "PHID-WIKI-...", "uri": "...", "title": "...", "slug": "...", "status": "...", "children": 3}
  ],
  "page": {
    "size": 2,
    "offset": 4,
    "count": 1000000
  }
}
eadler added a subscriber: eadler.Apr 28 2015, 3:18 AM
epriestley moved this task from Backlog to Next on the Phriction board.Sep 10 2015, 12:46 AM
timor added a subscriber: timor.Sep 10 2015, 11:54 AM

2 is such a surprising limit, it misleads you. You look at your wiki and you think, "I was sure I wrote a page on X, but no, I guess I'll start a new one".

If the limit in the UI is going to be an arbitrary 2, it could be wise to make the actual limit 2 as well (disallowing any deeper nesting than that for documents). This would lead to a smaller amount of surprise in the wiki.

Any progress here? What about setting the hierachy limit in the wiki document itself? So you can say "show X levels in the document hierachy of this page" where X is inherited and has a default value of 2?

We don't have a secret internal Phabricator full of juicy status updates: if we make progress, we'll update this task. See Planning for details.

We're going to likely move the hierarchy and give you control over what it shows. Merging in favor or T8552