IDEA: allow editing the placeholder in-place (like GCP docs)

[thesuperzapper]

The Google Cloud docs have an interesting placeholder implementation.
Users can click on the placeholder instances to turn them into the corresponding input box, so they can be updated in-place.

EXAMPLE PAGE: https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#applications_in_other_environments

Step 1 - Default

• 

Step 2 - Click to edit

• 

Step 3 - Changes are reflected across page

• 

They also have real-time mutation, but that is not necessary.

[six-two]

Hi, thanks for the suggestion. I like the idea, since it is far more intuitive than the (sometimes pretty large) tables that are currently used to set placeholders.

I think it should be possible to implement, since the dynamic (default) placeholders already are replaced with a bit of HTML. Adding a onclick event to that, that would turn it into a textbox should thus be possible. Live-updating is also supported (without reloading the page), if only dynamic placeholders are in use.

I will see if I find some time this weekend to try to implement it (or at least a prototype to see if it would work as expected).

[thesuperzapper]

@six-two in a separate but related idea, it would be great to have the input boxes scale to the width of the current text (which will be critical for the in-place editing).

I messed around with it today and it's actually kind of painful to dynamically scale the width of <input> tags, so we might be better off using <span>.

[six-two]

Neat, I never knew you could make <span>s work similar to input fields with contentEditable. Thanks for the idea! Input elements have always been annoying, due to them looking differently across different MkDocs themes, browsers and operating systems. So it would have been a pain to make them behave like inline elements.

I hacked together a small prototype using the <span> approach. It is still missing a proper UI, validation, support for checkboxes/dropdowns, etc. But if you go to https://dev.mkdocs-placeholder-plugin.six-two.dev/demo, click on file_to_transfer.txt anywhere in the page, edit it and press Tab/Enter it should update the value everywhere on the page.

[thesuperzapper]

@six-two also, while I have you here, I see that you are often working on the actual string version of the rendered pages (when looking for the input tags to mutate with default values).

Rather than trying to build your own XML parser, it's actually possible to hook into the Python markdown library (which mkdocs uses) with a tree processor extension that can work on the XML tree object rather than as a string after it's rendered

For example, I made this hook/plugin which finds <a> tags, and makes them open in a new tab, if they are external to the website:

• https://github.com/deployKF/website/blob/main/hooks/external_links_md_extension.py

[six-two]

Thanks for the tip! That might also be useful some of my other extensions (like mkdocs-badges) where I remember implementing some custom markdown parsing to see whether I am in a table or code listing

[thesuperzapper]

The only thing to remember, is that when you use a markdown extension, it will only affect the actual content from .md files, not the Jinja theme templates.

But at least for the placeholder plug-in I think that's fine, because I don't know why you would want placeholders outside of the main content.

[thesuperzapper]

Three more ideas:

• have a "revert to default" button when you are clicking on an inline text entry field
• put some indication that the in-place placeholder is editable and clickable (like on the GCP page)
• consider adding autocomplete="off" if we still use tags like <input> (I don't think browsers will autofill <span>) so that changes are reverted when the user refreshes their page (or at least have an option on a per-placeholder basis)

[six-two]

Regarding the three ideas:

1. A button would be hard to inject (while keeping the layout simple). Maybe a small span with an revert arrow when editing the placeholder. The idea I had is to show a tooltip below the field being edited. It could contain the placeholder's description and the default value. A user could just retype the default value or use the (somewhat hidden) reset all placeholders function from a placeholder table's settings. Another option would be a key binding, but that is not easily discoverable.
2. UI for the function is still missing. I would add a special class to them, so that users can overwrite the style and some optional default styling when I have some time.
3. Does your browser try to autocomplete any of the inputs? Would be a bit strange, since I do not recall setting 'id' or 'name' for them and they are not in a ''. So my understanding is, that the browser likely will not offer autocomplete based on this page. Placeholder values being stored is an intentional feature, so that you can change them on one page and they will remain with that value and also have it on other pages. If you do not like it, you could include a small script that (selectively) clears the localStorage entries for placeholders when a page is (re)loaded.

[six-two]

@thesuperzapper I have implemented the UI features (tooltip, special styling, etc) and support for dropdown/checkbox placeholders. Is there anything (except a revert button) missing related to the inline placeholder editors or are there any obvious bugs? The only thing I noticed is tooltips not being shown on my smartphone, but that is more of a general issue with touch devices not having mouse pointers.

The latest version is deployed at https://dev.mkdocs-placeholder-plugin.six-two.dev/demo and pushed to the main branch. If there is nothing broken/missing, I would like to release v0.4.2 with this new feature in a couple days.

[thesuperzapper]

@six-two A few things:

• the input boxes in the table now glitchy resize (get smaller) when you first edit them
• there should be a minimum width for the in-line placeholder (otherwise it could be very difficult to input a new value)
• I quite like what GCP did to indicate the in-line editable fields:
  • they put a small fixed-width icon which swaps between a "pen" and an "x" depending on if the input is selected (a "revert" button is probably more useful than "x", and it gives us a good place to put it)
  • they put a dotted underline (to show the boundary of each input field, which is important if they're beside each other)
  • they italicized the editable text
  • https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#applications_in_other_environments
• in-line editable placeholders should be opt-in so that not all instances of placeholders become editable:
  • you already have the concept of dPLACEHOLDERd, perhaps something like ePLACEHOLDERe for editable ones
  • this also lets us do the underline (and put the edit icon), because it won't affect existing placeholders
• I don't think "toggling" is the best implementation for "drop-down" and "check box" placeholders:
  • it's possible to accidentally click, and not be able to revert it (which might be a problem if it's a command template)
  • having a drop down sector, even for the in-line, is important
  • and I'm not sure that we should have in-line editing for check boxes

[six-two]

@thesuperzapper Thanks for the feedback. Regarding the points you raised:

the input boxes in the table now glitchy resize (get smaller) when you first edit them

I do not see this behavior with Firefox on Linux on my test site. To help me reproduce and fix it: What browser/OS and URL did you encounter this on? Can you maybe send a screencapture?

there should be a minimum width for the in-line placeholder (otherwise it could be very difficult to input a new value)

Implemented: for now it is a pink square with the width of the letter m, but you can apply custom styles with a selector like .placeholder-value-editable:empty

I quite like what GCP did to indicate the in-line editable fields:

• they put a small fixed-width icon which swaps between a "pen" and an "x" depending on if the input is selected (a "revert" button is probably more useful than "x", and it gives us a good place to put it)
• they put a dotted underline (to show the boundary of each input field, which is important if they're beside each other)
• they italicized the editable text

• Adding an icon (image) inline will likely be hard. Different themes and contexts may have different font-sizes, etc. And if I use an Unicode character (which would get around the above issues), I am afraid that it may be included when the user presses the copy listing button.
• I do not want to go too aggressive on the styling by default, but I see the point. That is one of the reasons why I show an underline when you hover over the placeholder. This shows exactly where the placeholder is and what it's value is before you click it. Again, custom styling is possible.
• I also colored and italicized the text 😉

in-line editable placeholders should be opt-in so that not all instances of placeholders become editable:

• you already have the concept of dPLACEHOLDERd, perhaps something like ePLACEHOLDERe for editable ones
• this also lets us do the underline (and put the edit icon), because it won't affect existing placeholders

Good point, I will think about it. Although I would probably implement it as a opt-out by default (by mapping xPLACEHOLDERx to ePLACEHOLDERe and giving an option to revert to the old behavior).

I don't think "toggling" is the best implementation for "drop-down" and "check box" placeholders:

• it's possible to accidentally click, and not be able to revert it (which might be a problem if it's a command template)
• having a drop down sector, even for the in-line, is important
• and I'm not sure that we should have in-line editing for check boxes

I tried to implement it with an inline dropdown that shown up when the user hovers or clicks on the placeholder, but that was both very buggy. For example when selecting a value in the onmouseenter implementation the user would leave the placeholder and thus cancel the dropdown. Now with the "empty placeholders can not be edited anymore" issue fixed, I do not quite understand the "accidentally click, and not be able to revert it" reasoning. For a checkbox just click it again. For a dropdown just right click it once or left-click till it has the old value.

One of the advantages I see with inline editors is that we do not need to rely on placeholder tables anymore. While they work OK on small to medium sized pages, they become way to big on very large pages, where it is a real pain having to scroll to them, find the correct placeholder and scroll down to your place again. Thus I would like to have all placeholders support inline editors. And if a site owner really dislikes the behavior, they could selectively disable the inline editors for these placeholders (dCHECKBOX_PLACEHOLDERd).

[six-two]

This week I made some changes to the code:

1. I changed the styling a bit. It turns out that (at least with Firefox/Chromium on Linux) contents of pseudo elements are not copied. So I can show an Unicode icon after each inline editor without for example breaking the copy function in code listings. There are two styles with the developer (inline_editor_icons in placeholder YAML) being able to choose the default and the user (Use icons and other styling to highlight inline editors in settings) being able to overwrite it.
2. Inline editors for checkboxes and dropdowns can now be manipulated using the keyboard: Tab to select one and Enter to change its value.
3. I added the ePLACEHOLDERe syntax and mapped xPLACEHOLDERx to it by default.

@thesuperzapper Do you see any more glitches, bugs or problems with the code in the current state? Do you have details for reproducing the "the input boxes in the table now glitchy resize (get smaller) when you first edit them" bug?

[thesuperzapper]

@six-two I can't seem to reproduce the glitchy size error, so it might have been fixed with your other updates.

Based on your demo my main comments are now about styling:

High Priority

1. Currently, I can't select only part of a code block by dragging my mouse:
   • (This is especially bad when you drag from the right hand side)
   • It seems like my mouse passing over the input boxes makes it open the edit box.
   • It's critical that we only open the edit box when a user explicitly clicks on the editable section.
   • I am not sure if its necessary to fix this, but the GCP docs actually don't seem to use contenteditable, but they swap and open an <input> tag on click.
   • Maybe we need to do that, or just only set contenteditable on click?
2. Dont use emojis, they are not consistently represented across devices (and are really bad for accessibility):
   • I recommend we use material design SVG icons:
     • Edit can be: https://pictogrammers.com/library/mdi/icon/pencil/
     • Swap enum can be: https://pictogrammers.com/library/mdi/icon/swap-horizontal/
     • Boolean can be:
       • False: https://pictogrammers.com/library/mdi/icon/checkbox-blank-outline/
       • True: https://pictogrammers.com/library/mdi/icon/checkbox-outline/
3. I am not sure a background color is the best way to highlight the input boxes:
   • It disrupts the flow of the page and theme
   • I like how GCP does a color + dotted underline: , and only shows a background box when the editing box is open:
4. We should stop the browser from doing strange things and set:
   • spellcheck="false"
   • translate="no"

Medium Priority

1. For the currently active edit box:
   • We could swap the "edit" icon for a "revert to default" button:
     • Icon: https://pictogrammers.com/library/mdi/icon/undo-variant/
   • Or we could at least swap the "edit" icon for a "close" icon to indicate which ones is currently open:
     • Icon: https://pictogrammers.com/library/mdi/icon/close/
2. We should still update the other instances of a template (even if it fails validation):
   • Otherwise its hard to know which ones are connected

[six-two]

Hi, it ha been a while, but I had a lot of private stuff to do. In response to the issues you raised:

• High 1: Should be fixed. But if you start selecting text over a text input you will edit it instead (and can only select within its bounds). I think this is a reasonable restriction, since you just can start somewhere else and end over the text box. Unless your selection starts and ends in the middle of text fields, but that is an edge case I am willing to accept.
• High 2: Fair point, I will try to switch from Unicode to SVG. I am just not sure how easy or hard it is to implement.
• High 3: Working on it
• High 4: Should be fixed
• Medium 1: The problem is: I can add an onclick event listener and it checks that you clicked in the icon. But checking whether you had this element focused before was not trivial. I played with something like that and it never worked as expected. Swapping the icon for a close button would be easy, but if it should actually remove the focus from the element, we run into the same issue.
• Medium 2: I disagree. If something fails validation (an error, not a warning) it should not be inserted anywhere. It could produce issues. Imagine you enter a space into an element that is inserted (unquoted) into a bash command (like sudo rm -rf xPATHx). It would change the meaning of the command with potentially dangerous consequences (example: sudo rm -rf /home/someuser /bin instead of sudo rm -rf /home/someuser/bin). I only show the new, invalid value in the textbox (instead of reverting to the last valid one) to give the user the chance to fix their input without loosing all their progress and frustrating them

[six-two]

@thesuperzapper

• High 2: Thanks for the icon links, I have replaced the emojis with inline versions (data URLs) of the icons.
• High 3: I stopped using background color and just indicate the inline editor state with border styling (is editor -> dotted underline, is hovered over -> solid underline, is focused -> full border on all sites). The focused mode looks different on Chromium, but it should be fine.

I noticed that Should be fixed is ambiguous. I actually meant that High 1 + 4 are fixed, but I only tested them myself a little (so they might not be fixed "right"). Given the current state, do you think the feature is ready to release or are there still some things that need to be fixed?