JDK-8274625: Search field placeholder behavior #5825

hns · 2021-10-05T16:09:30Z

Please review a change to use the HTML placeholder attribute in the javadoc search input instead of an actual input value. This revives the fix I originally created for JDK-8221366 but forwent back then because of insufficient support by the Microsoft IE and Edge browsers. MS Edge has since been updated and supports the placeholder attribute well now.

Example pages generated with this change can be viewed here (top level pages only):
http://cr.openjdk.java.net/~hannesw/8274625/api.00/

I changed the color of the placeholder to a lighter grey than we used for our own solution because the placeholder attribute works in a slightly different way. While we removed the placeholder text when the user clicked on the input field, the standard placeholder is still visible right until the user starts entering text. Because of this, using a darker color for the placeholder is confusing because it can easily be mistaken for actual input. The lighter grey is also closer to the default value for most browsers and web frameworks such as bootstrap.

I also changed the HTML for the search input to not have an initial value of "search" which had then to be cleared by the search script. Furthermore, the disabled attributes now come in HTML5 value-less boolean format, i.e. disabled instead of disabled="disabled".

In addition to most significant desktop browsers I tested the generated docs on various mobile browsers on Android and iOS devices.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8274625: Search field placeholder behavior

Reviewers

Pavel Rappo (@pavelrappo - Reviewer) ⚠️ Review applies to dffd411

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/5825/head:pull/5825
$ git checkout pull/5825

Update a local copy of the PR:
$ git checkout pull/5825
$ git pull https://git.openjdk.java.net/jdk pull/5825/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 5825

View PR using the GUI difftool:
$ git pr show -t 5825

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/5825.diff

bridgekeeper · 2021-10-05T16:09:38Z

👋 Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-10-05T16:12:24Z

@hns The following label will be automatically applied to this pull request:

javadoc

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.

mlbridge · 2021-10-05T16:17:18Z

Webrevs

pavelrappo · 2021-10-05T16:41:03Z

The example documentation looks nice. I wonder if we could eventually use input type="search" instead of our custom search field.

pavelrappo

We should use standard tools for standard tasks where possible. In this case using a "placeholder" instead of the custom "watermark" workaround fixes the problem, simplifies the code and looks better.

Update the copyright years before integrating.

pavelrappo · 2021-10-05T17:04:56Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java

                .setId(id)
-                .put(HtmlAttr.VALUE, value)
-                .put(HtmlAttr.DISABLED, "disabled");
+                .put(HtmlAttr.DISABLED, "");


I'm curious: if such a call to put translates to a boolean HTML attribute, what call to put translates to an HTML attribute with an empty value?

pavelrappo · 2021-10-05T17:11:30Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java

+        HtmlTree inputReset = HtmlTree.INPUT(reset, HtmlIds.RESET_BUTTON)
+                .put(HtmlAttr.VALUE, reset);


Isn't it a mere coincidence that "reset" is both an input type and the value of the "value" attribute:

<input type="reset" id="reset-button" disabled value="reset">

Why do we need this "value" attribute?

pavelrappo · 2021-10-05T17:22:34Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

 doclet.Modifier_and_Type=Modifier and Type
 doclet.Implementation=Implementation(s):
 doclet.search=SEARCH:
+doclet.search_placeholder=Search


Later we should consider a better placeholder, such as an example input. We already have the adjacent "SEARCH" text label and the magnifying glass icon. Something tells me that the user has a pretty good idea what this field is for and that they don't need yet another "Search".

openjdk · 2021-10-05T17:32:10Z

@hns 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:

8274625: Search field placeholder behavior

Reviewed-by: prappo

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 15 new commits pushed to the master branch:

df125f6: 8273410: IR verification framework fails with "Should find method name in validIrRulesMap"
c74726d: 8274730: AArch64: AES/GCM acceleration is broken by the fix for JDK-8273297
2faced0: 8274738: ZGC: Use relaxed atomic load when reading bits in the live map
8a4d2b4: 8274680: Remove unnecessary conversion to String in java.desktop
986ee5d: 8274670: Improve version string handling in SA
df7b0c7: 8274715: Implement forEach in Collections.CopiesList
d4e8712: 8274797: ProblemList resourcehogs/serviceability/sa/TestHeapDumpForLargeArray.java on macosx-x64
4726267: 8274642: jdk/jshell/CommandCompletionTest.java fails with NoSuchElementException after JDK-8271287
83b2219: 8273612: Fix for JDK-8272873 causes timeout in running some tests with -Xcomp
d34ec6c: 8274793: Suppress warnings on non-serializable non-transient instance fields in sun.net
... and 5 more: https://git.openjdk.java.net/jdk/compare/e1f0df0de3b205cecdb1aa1d74562536c06097dd...master

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 master branch, type /integrate in a new comment.

mlbridge · 2021-10-06T08:58:39Z

Mailing list message from Hannes Wallnoefer on javadoc-dev:

Thanks for the review, Pavel.

Am 05.10.2021 um 19:34 schrieb Pavel Rappo <prappo at openjdk.java.net>:

We should use standard tools for standard tasks where possible. In this case using a "placeholder" instead of the custom "watermark" workaround fixes the problem, simplifies the code and looks better.

Update the copyright years before integrating.

Done.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java line 604:

602: .put(HtmlAttr.PLACEHOLDER, searchPlaceholder);
603: HtmlTree inputReset = HtmlTree.INPUT(reset, HtmlIds.RESET_BUTTON)
604: .put(HtmlAttr.VALUE, reset);

Isn't it a mere coincidence that "reset" is both an input type and the value of the "value" attribute:

<input type="reset" id="reset-button" disabled value="reset">

Why do we need this "value" attribute?

I don?t think we need it, but I left it in as I?m not totally sure it is safe to remove and it isn?t shown anyway. By contrast the search input value caused some flickering during loading when the value was cleared by the search.js script and replaced by the placeholder.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java line 534:

532: .put(HtmlAttr.TYPE, type)
533: .setId(id)
534: .put(HtmlAttr.DISABLED, "");

I'm curious: if such a call to `put` translates to a boolean HTML attribute, what call to `put` translates to an HTML attribute with an empty value?

Good question, I think there is currently no way to create an attribute with an empty string as value.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 226:

224: doclet.Implementation=Implementation(s):
225: doclet.search=SEARCH:
226: doclet.search_placeholder=Search

Later we should consider a better placeholder, such as an example input. We already have the adjacent "SEARCH" text label and the magnifying glass icon. Something tells me that the user has a pretty good idea what this field is for and that they don't need yet another "Search".

Yes, displaying example input may be a useful enhancement.

hns · 2021-10-06T09:26:53Z

/integrate

openjdk · 2021-10-06T09:28:50Z

Going to push as commit cdf8930.
Since your change was applied there have been 15 commits pushed to the master branch:

df125f6: 8273410: IR verification framework fails with "Should find method name in validIrRulesMap"
c74726d: 8274730: AArch64: AES/GCM acceleration is broken by the fix for JDK-8273297
2faced0: 8274738: ZGC: Use relaxed atomic load when reading bits in the live map
8a4d2b4: 8274680: Remove unnecessary conversion to String in java.desktop
986ee5d: 8274670: Improve version string handling in SA
df7b0c7: 8274715: Implement forEach in Collections.CopiesList
d4e8712: 8274797: ProblemList resourcehogs/serviceability/sa/TestHeapDumpForLargeArray.java on macosx-x64
4726267: 8274642: jdk/jshell/CommandCompletionTest.java fails with NoSuchElementException after JDK-8271287
83b2219: 8273612: Fix for JDK-8272873 causes timeout in running some tests with -Xcomp
d34ec6c: 8274793: Suppress warnings on non-serializable non-transient instance fields in sun.net
... and 5 more: https://git.openjdk.java.net/jdk/compare/e1f0df0de3b205cecdb1aa1d74562536c06097dd...master

Your commit was automatically rebased without conflicts.

openjdk · 2021-10-06T09:29:06Z

@hns Pushed as commit cdf8930.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

hns added 2 commits October 5, 2021 16:22

JDK-8274625: Search field placeholder behavior

ab9cf90

JDK-8274625: Do not set initial value attribute on search input

dffd411

openjdk bot added the rfr Pull request is ready for review label Oct 5, 2021

openjdk bot added the javadoc javadoc-dev@openjdk.org label Oct 5, 2021

Merge branch 'master' into JDK-8274625

291ec2c

pavelrappo approved these changes Oct 5, 2021

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Oct 5, 2021

JDK-8274625: Update copyright years

c74b0f6

openjdk bot closed this Oct 6, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 6, 2021

		HtmlTree inputReset = HtmlTree.INPUT(reset, HtmlIds.RESET_BUTTON)
		.put(HtmlAttr.VALUE, reset);

JDK-8274625: Search field placeholder behavior #5825

JDK-8274625: Search field placeholder behavior #5825

Uh oh!

Conversation

hns commented Oct 5, 2021 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Oct 5, 2021

Uh oh!

openjdk bot commented Oct 5, 2021

Uh oh!

mlbridge bot commented Oct 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

pavelrappo commented Oct 5, 2021

Uh oh!

pavelrappo left a comment

Choose a reason for hiding this comment

Uh oh!

pavelrappo Oct 5, 2021

Choose a reason for hiding this comment

Uh oh!

pavelrappo Oct 5, 2021

Choose a reason for hiding this comment

Uh oh!

pavelrappo Oct 5, 2021

Choose a reason for hiding this comment

Uh oh!

openjdk bot commented Oct 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Oct 6, 2021

Uh oh!

hns commented Oct 6, 2021

Uh oh!

openjdk bot commented Oct 6, 2021

Uh oh!

openjdk bot commented Oct 6, 2021

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

hns commented Oct 5, 2021 •

edited by openjdk bot

Loading

mlbridge bot commented Oct 5, 2021 •

edited

Loading

openjdk bot commented Oct 5, 2021 •

edited

Loading