Page MenuHomePhabricator

Update Phriction UI structural behaviors
Open, NormalPublic

Assigned To
Authored By
Sep 9 2019, 3:57 PM
Referenced Files
F6857238: Screen Shot 2019-09-12 at 7.56.20 PM.png
Sep 13 2019, 2:57 AM
F6849521: Screen Shot 2019-09-09 at 8.49.31 AM.png
Sep 9 2019, 3:57 PM
F6849510: Screen Shot 2019-09-09 at 8.39.13 AM.png
Sep 9 2019, 3:57 PM
F6849508: Screen Shot 2019-09-09 at 8.38.51 AM.png
Sep 9 2019, 3:57 PM
"Love" token, awarded by mcorteel.


Currently, Phriction pages list child pages in a "Document Hierarchy" section at the bottom of the page. This listing is hard-coded as 2-ply with a fallback to 1-ply if there are too many direct children.

Screen Shot 2019-09-09 at 8.38.51 AM.png (441×907 px, 41 KB)

The "Table of Contents" is available in a popout menu:

Screen Shot 2019-09-09 at 8.39.13 AM.png (217×372 px, 20 KB)

The page actions are in a standard curtain UI, embedded into the document:

Screen Shot 2019-09-09 at 8.49.31 AM.png (495×337 px, 31 KB)

These behaviors are okay but not great. I'd like to make these changes:

  • On Wide Screens, Put Navigation and Actions at the Edges: On normal desktop-sized screens, a lot of real-estate is unused. The actions take up space in the document and the navigation tree isn't visible on screen. The UI would be improved by moving navigation to a persistent left-side menu and actions to a right-side menu.
  • Anticipate Comments: Visual comments are some ways away, but this design should leave room for inline comments.
  • Provide More Control: (T8552) Users should have more control over document hierarchy display.
  • Offer Display Customization: Provide at least basic support for header colors, backgrounds, images, etc. The primary goal is to let user make different sections of the wiki look visually different.
  • Support Locking Pages: See PHI1366. The existing lock behavior can likely extend easily to Phriction pages.

These adjacent changes are also desirable:

  • Improve Anchor Behavior: (T4280) We currently auto-generate very clumsy anchor names and don't support custom anchors. Better anchor generation and more control over anchors would be nice.
  • Apply These Changes to Diviner: Diviner could benefit from the same navigation treatment. Some of this could probably go to Phame eventually, too.
  • Support {index ...} (or similar) as a Remarkup Element: (PHI1412) Roughly, provide a remarkup element for embedding the hierarchy of some page in another page. This hadn't occurred to me but I think it's quite clever.
  • Fix Subtree Moves: (PHI987 / T6004). Moving a document currently does not provide an option to move the whole subtree; it should.
  • Figure out UI customization inheritance: If pages can play custom background music, the UI needs to provide reasonable ways to say "this page should follow the rules of <the parent / some other page / the grandparent>".
  • Remove "Moved From..." Banner?: (PHI1431) Phriction currently shows a "this document was moved from X" banner until the document is edited. This is probably not really that useful and should perhaps just be removed.
  • PHI2072 discusses a "Book View", where some page/x/ and all descendants are rendered on a single page.

Event Timeline

epriestley triaged this task as Normal priority.Sep 9 2019, 3:57 PM
epriestley created this task.

Left Nav

I'd like to at least experiment with some parts of this structure:

Root Page
n-parent Page
Grandparent Page
Parent Page
Sibling Page A
Sibling Page B
Current Page

    • Header A
    • Header B
    • Current Header
    • Header D
  • Subpage A
  • Subpage B
  • Subpage C

Sibling Page D

That is:

  • Consider putting all parents at the top, duplicating or replacing the breadcrumbs? I'm not really tied to this; the breadcrumbs are fine. But this might be attractive to improve non-desktop behaviors, or if pages get special navigation display behavior (like icons or colors which can't be shown in crumbs).
  • List all the siblings as primary navigation. This will make varying amounts of sense depending on document structure, but is probably often good?
  • List the table of contents as on-page navigation in the menu.
  • List subpages under the table of contents.

This structure may make less sense on mobile, but it's probably not awful. Meaningful customizations here would be:

  • Subpage ordering, particularly "by alphabet ascending / descending". Reverse-ordering is useful for "changelog"-style pages. Unclear if other orderings make sense. Ordering should be numeral-aware so numerals sort "9, 10, 11", not "1, 10, 11, 2".
  • Letting pages have an icon or image, and maybe coloring.
  • Subpage child/grandchild behavior. Perhaps this is not necessary if an {index ...} or {tree ...} element with some options is introduced.

This needs a lot more work, but here's very roughly where I'm trying to go with this:

Screen Shot 2019-09-12 at 7.56.20 PM.png (1×1 px, 539 KB)

This feels pretty promising so far.

At the lowest levels:

Remarkup currently can not export a structured representation of document headers, just a blob of HTML. It should support structured export instead. We need this to be able to render page headers into the left nav. This is not very difficult.

I'd like to figure out what's going on with Remarkup headers and anchors first. We currently generate very clumsy anchors, like #termination-for-nonpayme (this is not a typo; we truncate in the middle). At a minimum, I'd like to allow generation of longer anchors and try much harder not to truncate in the middle of words. For example, #termination-for-nonpayment is a better anchor here. As a compatibility step, we could also add Javascript to try to scroll #asdf to any anchor on the page which has asdf as a prefix, so #termination would scroll to the first anchor beginning with #termination. This would keep the legacy anchors working and let savvy users tidy up weird anchors if they want without having to actually edit the document.

I'm tentatively inclined to introduce {anchor ...} and {header ...}, which would have similar behavior. Something like {anchor #name [options]} and {header [#name] [options]} <text to end of line>, possibly?

So things like these would work:

{header #sizes icon=paw} Choosing the Right Size
{anchor #weights-and-measures} <table> ... </table>
{header} Dark Omens!
{header size=6} Ominous Darkness!

This seems generally reasonable. Headers which specify an anchor would also generate a default-named anchor, but the specified anchor would become preferred.

The {anchor} element would just generate an invisible document anchor for now. In the future, maybe it could generate a hint that the anchor exists in the left margin or something like that, or have a "name" option to make it appear in the table of contents. I think all of this stuff is relatively advanced, but at least some use cases involve auto-generating documents or compiling "presentation" documents where it makes more sense to put effort in upfront.

So my plan is:

  • Add {anchor} and {header}.
  • Fix anchor generation.
  • Possibly deal with anchor jump behavior.
  • Support getting a structured table of contents out of the Remarkup engine.
  • Then, probably try to adopt this layout in Diviner first, since this is less disruptive than doing it in Phriction.