Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Update invalid block copy #9667
Based on feedback in #9473 this tries to improve the text for the content and buttons of an invalid block from:
It also changes the text for a single-use block to make it more active. From:
Finally it removes the duplicate invalid block button from:
How has this been tested?
This is a text only change.
referenced this pull request
Sep 6, 2018
I agree with @johngodley that Convert to HTML would be better.
Also, I think an Edit as HTML option (which does the same thing as the one in the ellipsis menu) should be added to the ellipsis menu and the ellipsis menu in the toolbar should be removed. It is kind of weird having 2 ellipsis menus shown, and you don't really want to expose other options like duplicating an invalid block.
@johngodley I really like the updated text
Perhaps there's a happy medium that could be achieved by adding descriptive tooltips to your shortened button text?
Some good suggestions, thanks!
I agree that 'Convert to HTML block' is appropriate and matches 'Convert to Classic Block'. The attempts at brevity are to try and keep everything on one line on desktop (for English and other languages of a similar text length). It's worth trying though.
I went with 'auto-convert' instead (alternative could be 'auto-fix') as it indicates that a conversion is going to happen, and Gutenberg is going to do whatever it can.
I think this is a great idea - a tooltip with a longer description could really help explain the finer details.
Also adding that #7995 will add a comparison diff for 'Convert to blocks' so you'll be able to see exactly what happens - this may help.
@johngodley (+ @talldan) that's an excellent point about already being a block -- that is confusing. Perhaps
I really like your proposal in #7995 -- giving a diff definitely helps increase confidence in the process.
Both the "modified externally" and "contains unexpected content" messages seems like that have insufficient information for the user. The block has been modified externally: so what? There's unexpected content: what does that mean? It's not unexpected to me; I put it there. Since there's not a lot of information, it's hard for the user to know what they're supposed to do -- we don't give them any guidance on which choice is the right/best choice. And if I'm seeing this message for the first time, will I know what auto-convert/keep mean?
Can we add more context to these messages? Especially since blocks are so new for everyone; that gives us even more reason to provide useful, actionable information in. It would be great to see a real explanation of what is happening and what the choices actually mean, and we can then edit down to a reasonable length.
@michelleweber to answer your question, the message appears when the current content of the block doesn't match what Gutenberg expects it to be.
Usually a block is visually edited, and the HTML output is known - Gutenberg generates the HTML based on the visually edited data.
However, we also allow people to directly edit the HTML (the 'edit as HTML' option). Gutenberg will compare what it thinks the HTML should be against the user changes, and flags an error if there is a difference.
Typically this difference is because the user introduced custom HTML into the block, and so we offer a 'Keep as HTML' option. This converts the block into a HTML block, allowing the user to carry on with their custom content. This is the default button as it results in no data loss. The main difference is they can no longer visually edit the block and must continue to use HTML.
The 'Convert to blocks' or 'Auto-convert' runs the block through Gutenberg's HTML parser in an attempt to determine what block(s) it best matches, and then converts it into valid block(s). This can cause a loss of information as Gutenberg will throw away data it doesn't understand, and it may convert to another kind of block, or even several blocks. An incoming feature in #7995 will visually show this conversion (although it is hidden behind a dropdown menu).
Another reason why the message is triggered is because the user could break the HTML in some way. For example, by removing an HTML tag.
There may be other ways in which the block's HTML is modified outside of the user directly changing it, which I think is the origin of the 'externally modified' text, but I can't think of a specific instance right now.
Hopefully that explains what the message is about. Essentially the user changes a block in such a way that they need to decide whether to move it out of the visual Gutenberg world into HTML, or whether to push it back inside - Gutenberg is very particular in this respect.
All super helpful, thanks y'all.
I like the direction of @0aveRyan 's last suggestion. I might tweak a little to try and go a little friendlier and add a smidge more info.
Question: in "it might be broken," what is "it"? Is this saying "it might be a broken block"?
It's referring to broken/invalid HTML. There's a separate warning, without buttons, that appears if the block's code breaks.
Here's some screenshots of the suggestions to see how they look:
I'll include @jasmussen in for thoughts about the effect on the design as I think it was originally designed for a single line (for English, at least)
I know Matías has a lot of thoughts on this.
There are a lot of things to balance — we hope for the user to not see this warning very often. And we also want for the warning to not be too warningy, because something bad has not necessarily happened, honestly.
Finally, because it already looks slightly jarring, I personally feel like the less text, the better. In that vein, I like "Keep as-is" as the 2nd option.
Perhaps we could keep the text ultra small and sort of friendly, like:
"This block wasn't recognized, or might be damaged."
If only there was a softer word for "damaged". Maybe "modified"?
Finally I thought it was an interesting suggestion, I think by @jorgefilipecosta on a different thread, to involve the new diffing tool in this.
So, summary, perhaps the warning could look like this:
Clicking [Compare] opens up the diffing modal which shows the most recent change that happened to the block.
This modal, in other words:
How about that?
Then we keep it to two buttons on the warning, we keep the warning simple, the "Compare" warning isn't very scary and the actual diff helps the confidence. And we save an ellipsis menu option!
The word "modified" sounds confusing to me, because aren't you supposed to be able to modify blocks? I think "damaged" is a better choice, though perhaps there is a word better than both.
I like this, except that I am not sure that "Keep as-is" is the right wording here. It implies that the block will be left unchanged, which is not entirely true. It does not inform the user that it will be converted into a different block entirely. I think "Keep as HTML" is better.
I still think it all still sounds a bit 'tech-speak', and that a user new to the concept of blocks and Gutenberg probably wouldn't have a clue what's happening when they see this. Especially if the situation is that another user has changed something in the post using the classic editor.
I think the diff screen is fantastic if the user has edited the HTML themselves, but maybe not so much if the error has come from elsewhere (although the visual diff is nice). The user might not be tech-savvy enough to understand the HTML, especially given one of the philosophies of Gutenberg is to keep them away from it .
For that reason, I do quite like a longer sentence, but understand that it looks wordy. I wonder if there's a way we can have a short description and a longer explanation that's initially hidden.
Or a link to an FAQ (e.g. 'Find out more about this warning').
I'd actually be interested to know more about this. Other than somebody else editing (and breaking) the post, are there other sources for this message?
It's worth remembering that this error message is probably the result of the user editing HTML. While they may not be very familiar with Gutenberg, we can maybe assume they are confident enough to pick 'edit as HTML' or 'code editor', and then confident enough to mess around with the HTML. As Joen describes, this message is hopefully never shown, but if it is it's likely to be shown to a more advanced user (or at the least, one who knowingly edited and could expect a warning).
There is other work to make this message less trigger-happy, so ideally it will only be seen by someone who can react confidently.
I think we agree the current text is confusing. In an effort to reduce the scope of this PR these ideas seem worth doing elsewhere:
With this in mind, the question remains about improving the current text. This may not be the final text, and we can iterate as other changes improve the experience. Note this is just my attempt at merging everyone's suggestion while trying to stay reasonably compact!
My thought here is that 'convert to HTML' more accurately describes the action, while 'keep' implies it stays the same.
I think this needs to indicate that Gutenberg is going to make a best attempt at 'fixing' it. The fact that it may change it into another block, or several blocks, is something that will be covered by (2).
I think this probably represents the cause of the warning, and mentioning HTML should remind people that's it's because they edited directly. We can add more descriptive text via (1)
Still very open to changes, and I'll update the code when it settles.
I am fine with either "Attempt recovery" or "Auto convert", but I think I would lean towards the former.
This implies that modifying HTML is not allowed at all for blocks, so I would change that to say "This block is unrecognized or contains invalid modified HTML" or something like that.
This was referenced
Sep 13, 2018
Ok, updated the PR with the latest, based on the assumption that the user has just edited their HTML and has a little context and knowledge:
It just fits in one line, in English, and is hopefully a little clearer than before. I suspect the text will continue to evolve and adapt to other changes we make.
I've created two related issues, discussed above, which should help further:
Minor consistency note:
In the top-level error boundary, we use the string "Attempt Recovery":
AFAICT, "Try" and "Attempt" would be considered synonyms. Any reason they shouldn't be the same, even if that means changing the error boundary to "Try" (which I have no qualms against).
Also a consideration for localization effort in maintaining two separate overlapping strings.
Nice conversation and thoughts. I have a few points to add:
I think this is a good iteration and I'm looking forward to:
However, I don't fully like the last text "This block is unrecognized or contains invalid HTML" because it's not true — the block is recognized, which is why we can show the message in the first place.
Something like "There appears to be an issue with the content of this block which we need you to make a call on" is what we are effectively telling the user.
It's common for other editors to modify the HTML without the user knowing. That is right now the source of most of these messages. I actually think the user modifying the source is the least common.
The case where the user switches to "Edit as HTML" and breaks the block is already handled separately as an exception, so that covers most direct edits.
The new 'Resolve' button now directly opens the comparison modal, as per #9862. The main text has been changed to
Wouldn't this trigger the invalid message for the editor?
I don't think anything else needs to be done here; I've removed the "needs copy editing" label because it's been through a few rounds and this seems in line with what was suggested.