In-place Real-time Editing

Last modified by Vincent Massol on 2024/02/26 17:57

 XWiki
 Feature
 Active
 

Description

The Problem

The users are not motivated to contribute to the wiki, particularly because:

  1. there are too many steps required to make a change or to add new content (e.g. you need to scroll up, click the Edit button, scroll down, click the Save button)
  2. it takes too much time to make a change or to add new content (e.g. you need to wait a few seconds for the edit mode to load and then another few seconds to get back to the view mode)
  3. the users don't know:
    • where to make the change (e.g. the content you look at is coming from another wiki page)
    • or how to make the change (e.g. you have to know the wiki syntax)
    • or event that they can make the change (e.g. the configuration you need to change is hidden somewhere in the administration)
  4. collaborating with other users on the same page can lead to complex merge conflicts that have to be resolved manually
  5. the content can become outdated without the user being aware of it (e.g. you view a page that someone else is editing)
  6. there's only very little reward for making a change or for adding new content: you don't know if someone noticed your change, or how many people viewed the content you added and if they liked it, or how much you contributed compared to the other users.

Note that the first 2 items are related but not the same. You can have a single step for which you need to wait 10s. So we need to fix box problems. The last item, about user engagement, deserves a separate investigation so it won't be covered here.

The Goals

Making changes and adding new content should:

  1. require fewer steps
  2. take less time
  3. preserve the context
  4. be straightforward
  5. propagate in real-time

Use Cases

Plain wiki pages

UC1: Modify the title of a plain wiki page

You're looking at a wiki page and you decide to modify its title. Currently you have to take the following steps:

  • locate the Edit button, move the mouse over it and click
  • wait for the edit mode to load (3s)
  • move the mouse over the title text input and click on it to have the focus
  • make the change
  • locate the Save button at the bottom of the page, move the mouse over it and click
  • wait for the view mode to load (2s)
  • verify that the title was updated

This requires 7 steps and takes at least 10 seconds to complete.

The current implementation has the following problems:

  • switching from view mode to edit mode and back takes too much time and is perceived by the user as a context switch because the layout is very different
  • the title input should be focused automatically, being the first input of the edit form

UC2: Modify the content of a plain wiki page

You're looking at a long wiki page (e.g. the Sandbox home page) and you notice a typo somewhere at the end. If you want to fix it then you need to:

  • Without section editing (either because there's no section or because you don't notice the section editing icon):
    • scroll the page to the top
    • locate the Edit button, move the mouse over it and click
    • wait for the edit mode to load (3s)
    • move the mouse over the content text area
    • scroll down and scan the content until you find the typo
    • place the caret over the typo and fix it
    • [optional] locate the Preview button, move the mouse over it and click
    • [optional] wait for the preview mode to load (2s)
    • [optional] scroll down and scan the content until you find the place you modified, in order to verify the typo is properly fixed
    • locate the Save button, move the mouse over it and click
    • wait for the view mode to load (2s)
    • scroll down and scan the content until you find the place you modified, in order to verify the typo is indeed fixed

  • With section editing
    • [optional] depending on the length of the section, you may have to scroll the page up to locate the section heading
    • locate the section edit icon on the right, move the mouse over it and click
    • wait for the edit mode to load (2s)
    • [optional] depending on the length of the section, you may have to scroll down to find the typo
    • place the caret over the typo and fix it
    • [optional] locate the Preview button, move the mouse over it and click
    • [optional] wait for the preview mode to load (2s)
    • [optional] depending on the length of the section, you may have to scroll down to find the place you modified, in order to verify the typo is properly fixed
    • locate the Save button, move the mouse over it and click
    • wait for the view mode to load (2s)
    • scroll down and scan the content until you find the place you modified, in order to verify the typo is indeed fixed

This requires 6 to 12 steps to complete and takes at least 8 to 16 seconds. The current implementation has the following problems:

  • you need to scroll to the top of the page to find the Edit button
  • you may need to scroll to find the section editing icon
  • you loose the context:
    • you need to find the place you want to modify after the edit mode is loaded
    • if you edit a section, you don't see the other sections anymore
  • the lack of a real WYSIWYG edit mode (same layout as in view mode) makes the user repeat the Preview - Back To Edit loop which is time consuming
  • after editing a section the page should be scrolled automatically to that section in view mode in order to verify the changes

UC2.1: Move around content blocks

You are editing the content of a plain wiki page and you have the need to move around blocks of content (e.g. sections, lists, tables). The current status is this:

  • paragraphs, headings, lists can be moved with drag & drop but:
    • you need to select their entire text, which makes this feature hard to discover and use
    • there is no visual clue visible while dragging to indicate where the content will be inserted (although there is a visual clue indicating that you are dragging some block of text)
    • it's very easy to drop the block in-line (e.g. inside of a paragraph) while you would expect to be allowed to drop only between blocks.
  • tables can't be moved at all
  • images and macros have a drag handler
    • which makes it easy to discover that they can be dragged, and simplifies the drag operation
    • there is a visual clue (dotted horizontal line) visible while dragging, indicating where the block will be inserted
    • you can drop the block only between blocks

FTR, CKEditor5 doesn't have support for real content drag & drop ATM.

UC3: Modify the content of an included wiki page

You're reading a wiki page and you notice a typo. You decide it's worth fixing it so you:

  • [optional] scroll the page up to the nearest section editing icon or to the top
  • locate the section edit icon or the Edit button on the right, move the mouse over it and click
  • wait for the edit mode to load (3s)
  • [optional] move the mouse over the content text area
  • [optional] scroll down to find the typo
  • place the caret over the typo to fix it
  • realize it can't be fixed directly because that is the output of a macro that can't be edited in-line
  • double click to edit the macro
  • realize it's the include macro so the typo is in a different page
  • notice the name of the included page and, hopefully, notice that the same page is listed in the Page Information panel on the right side
  • close the macro edit modal
  • move the mouse over the Page Information panel and click on the link to open the included page
  • wait for the included page to load (2s)
  • locate the Edit button or the nearest section editing icon, move the mouse over it and click
  • wait for the edit mode to load (3s)
  • [optional] move the mouse over the content text area
  • [optional] scroll down to find the typo
  • place the caret over the typo and fix it
  • locate the Save button, move the mouse over it and click
  • wait for the view mode to load (2s)
  • find a way to get back to the original page
    • if you didn't open the included page in a separate tab then you're blocked..
    • otherwise you need to get back to the previous tab and:
      • cancel the edit mode
      • wait for the view mode to load (2s)
      • scroll down and scan the content until you find the place you modified, in order to verify the typo is indeed fixed

This requires 20 to 25 steps and takes at least 35 seconds for a knowledgeable user to complete.

The current implementation has the following problems:

  • the include macro is not editable in-line with the WYSIWYG editor
  • it's not easy to open the included page (in a separate tab) in order to edit it (there's no clear link on the Edit Macro dialog)
  • there's no easy way to get back from the included page to the page that includes it

UC4: Translate an existing plain wiki page

You're browsing the wiki with the language set to French and you notice a page that is in English (while the UI is still in French). You decide to translate it to French. Currently you have to do this:

  • locate the Edit button, move the mouse over it and click
  • wait for the edit mode to load (3s)
  • notice that the UI language has switched to English; fortunately you know a bit of English, but it could have been worse (Russian)
  • scan the page and notice the Page Translations panel
  • understand that you're editing the original English version of the page
  • move the mouse over the "fr" link and click
  • wait for the edit mode to load (3s)
  • do the translation
  • locate the Save button, move the mouse over it and click
  • wait for the view mode to load (2s)
  • review the page

This requires 11 steps and takes at least 16 seconds to complete, without counting the time to do the translation.

The current implementation has the following problems:

  • the UI language is changed when you try to edit a page that doesn't have a translation in your current language
  • it's easy to miss that you're editing the default translation
  • the link to create the new translation is also easy to miss

Structured wiki pages

UC5: Modify the value of a field from a structured page

You're looking at a structured page and you notice that the value of a field is wrong. You decide to fix it so you:

  • locate the edit button, move the mouse over it and click
  • wait for the edit mode to load (3s)
  • scan the page for the field you want to change
  • move the mouse over that field and click to change its value
  • make the change
  • locate the Save button, move the mouse over it and click
  • wait for the view mode to load (2s)
  • scan the page for the field you modified
  • verify that the value is fixed

This requires 9 steps and takes at least 12 seconds to complete.

The current implementation has the following problems:

  • the Inline Form edit layout is closer to the view layout but still different; the following items are missing: the author and the creator, the page tags and the page extra tabs. So this is still perceived by the user as a context switch
  • you need to wait for all the fields to be loaded in edit mode even if you just want to edit a single field

Panels

UC6: Add or remove panels

While looking at a wiki page you realize that one of the panels doesn't make sense in this context and you would prefer to replace it with another panel.

UC7: Change panel layout

While looking at a wiki page you realize that the right panels take too much space and don't bring enough value so you decide to change the panel layout to remove the left column.

UC8: Configure a panel

UC8.1: Remove an application from the Applications panel

After installing an extension you notice that there's a new entry on the Application panel. You decide to remove it.

UC8.2: Hide a page from the Navigation panel

You created an application without using AppWithinMinutes and you want to exclude its home page from the Navigation panel because you added an entry to the Applications panel.

UC9: Hide page extra tabs

You want to hide the comments tab but you still want to show the list of attachments.

You want to change the wiki logo, either for the entire wiki or just for a specific page and its children.

Constraints

Plain wiki pages

Wiki pages have editable metadata that is currently not displayed in view mode and thus it cannot be edited in-place as is. We either find a place for this metadata in view mode or we keep a dedicated edit mode for it.

  • default language, syntax, hidden: we have good defaults for these and they are rarely modified by simple users
  • comment, minor edit
    • the users rarely set them
    • they can be hidden from the administration
    • setting these while editing in-place is inconvenient so we'll have to drop them; but this means they will become less and less relevant as the users start using the in-place editing more and more
    • there is a setting to make the version summary (comment) mandatory; we'll have to disable in-place editing when this is on; we'll also have to keep the classic edit mode because of this

The edit mode provides tools that are obviously not present in view mode and thus would be missing while editing in-place:

  • auto save: this is useful mainly when you edit the page content for a long period of time, thus it's probably not needed when editing in-place, but we should keep it for the classic edit mode
  • link to XWiki syntax help (only for Wiki edit mode)
  • link to configure more syntaxes
  • included pages: this information is shown in the "Information" tab but it's going to be easy to miss it while editing in-place because this tab is not active by default
  • translations:
    • the current language
    • links to existing translations
    • link to create a new translation

Structured wiki pages

  • structured wiki pages have custom sheets and often custom displayers for their fields
    • the way the fields are arranged or grouped in view and edit mode can vary a lot
    • the amount of space taken by each field in view and edit mode varies also
  • structured wiki pages can have custom validation rules and relations between the fields
    • this makes in-place single field editing very complicated

Solutions

Real WYSIWYG edit mode

There are 2 approaches:

  1. Modify the WYSIWYG edit mode to look similar to the view mode (show the same panels, show the page extra tabs, show the page tags, author and creator information). When switching to WYSIWYG edit mode the browser will reload the entire page but since the edit mode will look very similar to the view mode the browser will render the edit mode faster and thus the transition from view to edit will be smoother.
  2. Modify the view mode to support activating the WYSIWYG edit mode without reloading the page.

For both approaches we'll have to move fields and tools from the edit panels to someplace visible in view mode:

  • Display the default language, syntax and hidden page metadata inside the "Information" page extra tab and make them editable in-place from there. Otherwise we need to keep a dedicated edit mode. Note that all the other page extra tabs have actions that modify the current page (comment, attach, revert), so being able to modify the current page from the "Information" tab shouldn't come as a surprise. At most we may consider changing the title of the tab, but I don't think it's necessary.
    • We'll have to move the link to configure more syntaxes also. An idea is to have this as an option in the syntax drop down (i.e. you select from the available syntaxes or you add more syntaxes).
  • Add a tool bar button for the Wiki editor and for the WYSIWYG editor (when in Source mode) to open the XWiki Syntax help (depending on the page syntax)
  • Display the language, the list of translations and the link to create a new translation (for the current UI language) inside the "Information". There's no reason to limit this to edit mode. Note that the list of existing translations is availalbe also in the drawer menu, but this has created confusion in the past because the users often ask "why can't I switch to XX language?" and the answer is "Because the current page is not translated in that language". I'd rather keep the drawer for changing the UI language (i.e. list all supported languages) and use the "Information" tab to list available page translations.

Also, for both approaches we'll have to adjust the title input and the WYSIWYG editor text area:

  • hide the title label (screen reader only) and set the placeholder attribute of the title input
  • style the title text input so that it appears as in view mode (keep the border but use a bigger font size to match the level 1 heading styles)
  • since the title can be computed we might have to show the computed title when the title input is not focused, and show the raw value (e.g. the Velocity code) when the title input is focused; one thing to consider is that the rendered title can be influenced by the page content, so in order to preview the title we'll have to submit also the edited page content
  • run CKEditor in inline mode rather than using an iframe so that there's no scroll bar on the text area; we'll use the page scroll bar and the toolbar will float on top of the edited content; note that the inline CKEditor doesn't support some features:
    • Source text area: but there is a Source dialog that can be used instead
    • full screen mode: we need to decide if it's still useful and if we think it is then we'll have to find a workaround

Changes required for the first approach (modify the WYSIWYG edit mode):

  • show the author and last modification date (should we update these once the user makes modifications in order to match what the user will see in view mode?)
  • show the tags, creator and creation date
  • show the same panels as in view mode and the page extra tabs

Changes required for the second approach (activate WYSIWYG edit mode on top of view mode):

  • load on every view of a plain wiki page (no view sheet applied) the JavaScript code that can activate the WYSIWYG edit mode; this can be a light JavaScript code that:
    • catches the click on the WYSIWYG edit menu
    • loads more JavaScript code on demand (using RequireJS)
  • in order to be able to edit we need to have the data (e.g. the raw page title and the annotated XHTML of the page content); we can either:
    • modify the view mode to include this data:
      • pass the raw page title as an attribute of the title heading
      • use the annotated XHTML in view mode to display the page content
      • pass some hidden information like the CSRF token, page version and language (to know which page translation we're viewing and editing)
    • or fetch the data using JavaScript; the advantage of this is that:
      • it could be packaged as an extension more easily
      • we can fetch the data as JSON and start a real-time session with it
  • the JavaScript should also modify the current URL (using the History JavaScript API) so that the real WYSIWYG edit mode can be loaded directly with a dedicated URL

In-place section editing

Instead of taking the user to a separate edit mode where they see only the content of that section, we could keep the user in view mode and activate the in-line CKEditor for that section.

Quick WYSIWYG edit mode activation

In order to overcome the issue of scrolling the page and moving the mouse over the page Edit button or the section edit button, we should find a way to activate the edit mode faster. One idea is to show a balloon with the invitation to edit when the user selects a piece of text. A similar behavior can be seen in Medium (context toolbar) and Discourse (quote balloon). The flow would be like this:

  • the user selects a piece of text
  • we show a balloon with the " Edit" action, placed at the start of the text selection
  • upon clicking on the Edit link we activate the real WYSIWYG edit mode (described in the previous section), preserving the selection
  • there should be little to no UI flicker, and the user can start editing right away

There's of course a big issue with this solution: discoverability. But once you learn the behavior it can be very powerful. Moreover, this could eliminate the need to edit a section of a page. Note also that the balloon toolbar could be extended later with actions for annotations and comments.

Quick Inline Form activation

Much like in the previous section, we need to find a way to overcome the need to scroll the page and move the mouse over the page Edit button (because it may be far away from the field you're looking at and that you wish to modify). Using the selection is less intuitive in this case and we should avoid interfering with the logic of the sheet. An alternative is to automatically inject an edit icon after each field label (in view mode). Showing the edit icons all the time clutters the UI so we could show them only when the label is hovered. This eliminates the clutter but makes the feature less discoverable and makes it unusable on touch devices. But since we're keeping the Edit page button, there should be no issue.

The difficulty is in loading the edit mode smoothly and in preserving the target field (label) under the current mouse position. Of course, the target field (that triggered the edit mode) should be focused.


 


Tags:
    

Get Connected