8294158: HTML formatting for PassFailJFrame instructions #15660
Conversation
Instructions for FileChooserSymLinkTest are rendered in HTML.
Each text component (JTextArea or JEditorPane) are configured in its own dedicated method. This avoids unnecessary type casts.
|
👋 Welcome back aivanov! A progress list of the required criteria for merging this PR into |
|
@aivanov-jdk The following label will be automatically applied to this pull request:
When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command. |
It reverts the accidental change where I unwrapped call to createUI
| instructionsText.setEditable(false); | ||
| instructionsText.setLineWrap(true); | ||
|
|
||
| JTextComponent text = instructions.startsWith("<html>") |
There was a problem hiding this comment.
Probably trim() and toLowerCase() could be useful here.
Do we consider adding adding one more builder method to force enable html rendering?
(e.g. when we just want to highlight only few words/sentences with <b> without adding <html> tag)
There was a problem hiding this comment.
Probably
trim()andtoLowerCase()could be useful here.
Could be… On the other hand, in post XHTML era, the elements are usually in lower-case. Thus we should stick with it and use lowercase HTML elements anyway.
I think startsWith("<html>") covers the scenario well.
Although neither <html> nor <body> are required, I prefer to always add them. These two elements don't add much overhead, do they?
Do we consider adding adding one more builder method to force enable html rendering? (e.g. when we just want to highlight only few words/sentences with
<b>without adding<html>tag)
I don't think it's needed. If you want the instructions rendered as HTML, you'll have to format them as HTML.
Forcing HTML rendering on plain text which highlights a couple of words with <b> will render the text unreadable: line ends are ignored by HTML, so you'll have to use <br> element to force line breaks. (A similar thing often happens in javadoc where a blank line is added as if to start a new paragraph, but without the explicit <p> element the text continues on the same line / paragraph.)
It is possible to wrap such instructions into <html><body><pre> but what stops you from doing it explicitly if it's what you want? (Note, however, the <pre> element disables line wrapping.)
I'd rather keep it simple.
There was a problem hiding this comment.
Could be… On the other hand, in post XHTML era, the elements are usually in lower-case. Thus we should stick with it and use lowercase HTML elements anyway.
https://www.w3schools.com/html/html_elements.asp
HTML is Not Case Sensitive
HTML tags are not case sensitive:
<P>means the same as<p>.The HTML standard does not require lowercase tags, but W3C recommends lowercase in HTML, and demands lowercase for stricter document types like XHTML.
At W3Schools we always use lowercase tag names.
So this is still a recommendation, not a requirement (we don't use XHTML).
But I agree that this can be helpful for a certain amount of consistency across tests(they can still use other tags in uppercase).
Although neither nor are required, I prefer to always add them. These two elements don't add much overhead, do they?
It is a matter of personal taste.
Normally, I prefer to indent a content of such tags by extra spaces, andThis can create additional formatting difficulties under the 80(120) character limit per line.
In those cases, I would prefer to omit those tags.
There was a problem hiding this comment.
I know HTML is not case sensitive. It's just HTML tags are always in lower case in recent years.
But I agree that this can be helpful for a certain amount of consistency across tests(they can still use other tags in uppercase).
Yep! In a way, this will enforce <html> in lower case, and I hope all other tags in the instructions.
Although neither nor are required, I prefer to always add them. These two elements don't add much overhead, do they?
It is a matter of personal taste.
Yes, it is… which could create inconsistencies.
Normally, I prefer to indent a content of such tags by extra spaces, and
This can create additional formatting difficulties under the 80(120) character limit per line.
In those cases, I would prefer to omit those tags.
I don't expect too many nesting levels in instructions. However, I agree it could be problematic…
In the sample in #15661, I keep <html><body> and the content on the same level.
Now that I looked at it again, I realised that I didn't follow the indentation consistently: first-level <li> aren't indented but third-level <li> are. I should correct this.
Because <pre> is used to format pieces of code, I decided not to indent the first-level <li> elements to avoid indentation of the code inside.
There was a problem hiding this comment.
I don't have a problem with keeping it simple. If some one writing a test doesn't see the HTML interpreted, they'll quickly be able to figure out why.
One thing about these and the other enhancements I see is that there's an (increasing) need for a nice bit of documentation in PassFailJFrame itself about all its features.
Easiest to do this as you are adding them, so a doc comment block can be started with this one.
Probably as a class comment.
Suggested text
/**
- PassFailJFrame documentation
- Instructions for the user can be either plain text or HTML as supported by Swing.
- Text beginning with <html> is presumed to be HTML.
*/
There was a problem hiding this comment.
One thing about these and the other enhancements I see is that there's an (increasing) need for a nice bit of documentation in PassFailJFrame itself about all its features.
Easiest to do this as you are adding them, so a doc comment block can be started with this one.
Probably as a class comment.
Yes, I absolutely agree, the class requires adding docs. It's what I wrote in PR #15665: the entire class requires a bit of TLC for documentation.
Yet I'd rather do it for PR #15665, it is easier to handle in one place rather than writing docs for one feature just to modify them right away for another feature.
|
@aivanov-jdk This change now passes all automated pre-integration checks. ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details. After integration, the commit message for the final commit will be: You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed. At the time when this comment was updated there had been 616 new commits pushed to the
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details. ➡️ To integrate this PR with the above commit message to the |
|
/integrate |
|
Going to push as commit 14090ef.
Your commit was automatically rebased without conflicts. |
openjdk
bot
removed
ready
|
@aivanov-jdk Pushed as commit 14090ef. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
This enhancement provides HTML formatting for instructions in the manual test framework,
PassFailJFrame.Some tests could benefit from rich-formatted instructions, especially when the instructions are long.
See a sample usage in #15661.
Progress
Issue
Reviewers
Reviewing
Using
gitCheckout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/15660/head:pull/15660$ git checkout pull/15660Update a local copy of the PR:
$ git checkout pull/15660$ git pull https://git.openjdk.org/jdk.git pull/15660/headUsing Skara CLI tools
Checkout this PR locally:
$ git pr checkout 15660View PR using the GUI difftool:
$ git pr show -t 15660Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/15660.diff
Webrev
Link to Webrev Comment