Problem/Motivation
This is a portion of #2900409: [Meta] Improve UI of Reference field settings form, separated out after comment #133.
When you are setting up an entity reference field, you usually only select 1 bundle or maybe a couple of similar bundles to be referenced. It is then somewhat jarring when you go to choose the sort options in the settings dialog, and you are shown all kinds of fields that are not present on these bundles, or have labels on the chosen bundles that are different from the labels that are shown.
Testing notes
Add an entity reference field to a content type, or edit an existing one. For example, using the Standard profile,
- Visit
/admin/structure/types/manage/article/fields - Click the "Add field" button.
- Select Content under the Reference group.
- Enter a label, then "Save and continue".
- On the next screen, click the "Save field settings" button.
- In the "Reference type" section, select at least one content type. This will expose the "Sort by" select list.
If the only selected content type is Basic page, then the current behavior is to include options related to the Image field (field_image), even though that field is only attached to the Article content type.
Proposed resolution
Limit the field choices in the Sort By select list to fields that are on the selected bundles. Also, display one of the field labels that is actually in use on those bundles.
Remaining tasks
Commit the merge request (the patch is the same).
User interface changes
Sort options will correspond to the selected bundles in entity reference field settings.
Before: this screenshot shows the title field with the label "Recipe name" even though only the Vendor content type is selected:
After: with a little help from browser tools to show both widgets at the same time, the Vendor content type is selected and the title field is displayed as "Vendor name":

Here's another test case description: Using the Article and Page content types from the standard profile, I changed the title of the Article content type to "Article title" and page to "Page title". I also added a field "Article type" to Article, and "Page thing" to Page. I verified that if only Article is selected, the choices include "Article title" and "Article thing" but not "Page thing" or "Page title". Here are screenshots of the A-C and I-S sections of the choices list, so you can see the two A choices appearing and not the two P choices:


I verified manually that it works fine for page content too, and for both types, but I didn't really think we needed that many screenshots.
API changes
None.
Data model changes
None.
Release notes snippet
Probably not necessary.
| Comment | File | Size | Author |
|---|---|---|---|
| #59 | article-choices-bottom.png | 19.87 KB | jhodgdon |
| #59 | articlechoices.png | 14.3 KB | jhodgdon |
| #50 | after patch no addition fields .png | 884.58 KB | janmejaig |
| #50 | before patch additional fileds .png | 1.45 MB | janmejaig |
Issue fork drupal-3089525
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
- 3089525-sort-options-should
changes, plain diff MR !34
Comments
Comment #2
benjifisherI think the attached patch should do it. I am adding tags for screenshots (a novice task) and tests.
In both manual and automated testing, we should consider references to nodes, where the options should depend on the selected bundles, and users, where there are no bundles to select.
Comment #4
benjifisherHere is an updated patch, with a test based on the patch from #2900409-128: [Meta] Improve UI of Reference field settings form. The test in that patch just made sure to select some bundles before checking for sort-by fields. (In other words, it fixed the test failure from the patch in #2 on this issue.)
I added one more line, checking that "_none" is the only available sort-by option before any bundles have been selected. I noticed that there is already a helper method in the test class that makes this easy to test.
If we want a more comprehensive test, I could add a second bundle (content type), with different fields. Then I could test that a particular field is available as a sort-by option depending on which bundle is selected.
I have attached a test-only patch, which should fail, as well as a patch that (I hope) will pass. I did not attach an interdiff, since it would be the same as the test-only patch.
Comment #6
jhodgdonI do think that a test that actually verifies the behavior we want (that only the fields from one bundle are shown) would be good. So setting to needs work / needs test for that.
Other than that, this looks quite reasonable. Still needs manual test / screenshots.
Comment #7
jhodgdonThanks for working on all of these issues by the way!!
Comment #8
benjifisherHere is a patch that adds a second content type in the test so that we can check that the available sort-by options change depending on which content type(s) we target.
It would be simpler and more complete to list exactly the expected options, using the helper function
assertFieldSelectOptions(), but that would also be more fragile/brittle. (See the discussion on the related issue #3089521: Sort options for entity reference field are unsorted.) I welcome advice on testing best practices. (Related: I see that the test classes have a helper functiondrupalCreateContentType()for creating content types. Is there something similar for creating fields?)The test-only patch is basically an interdiff with the patch in #2. I do not think an interdiff with the patch in #4 would be helpful.
Comment #9
dev.patrick commentedAdded patch and it applies clean. Further tested patch pre and post and adding supporting screenshot.
All further functionality is working as expected.
Comment #12
benjifisher@dev.patrick:
Thanks for the screenshots!
The two screenshots (with and without the patch) where the Select list is collapsed show nothing selected under "Content type". Once the patch is applied, you have to select at least one content type before anything is added to the Select list. Can you add a screenshot that shows this? Since the expanded Select list shows "Vendor name", I think the "Vendor" content type must be selected.
I was not sure whether the test code was adding a plain or formatted text field, and I guessed wrong. The attached patch should fix that: expect
field_text.valueinstead of justfield_text.Again, the test-only patch is basically an interdiff with the patch in #2. I am also attaching an interdiff with the patch in $8.
Comment #14
dev.patrick commented@benjifisher yes Vendor content type is referenced, attaching supporting screenshot,. I have added inline CSS to show selected option and corresponding selected list.
Comment #15
benjifisherIn #2, I wrote,
Here is a patch that adds a couple of lines to the test, when the entity type is set to
user, to check thatuidis an available sort option and thatnidis not.I am updating the issue summary with some of the screenshots from #9 and #14. Thanks again, @dev.patrick!
Comment #16
jhodgdon#15 says "Here's a patch" but there is no patch... so I will wait to review until the new patch is added.
Comment #17
benjifisherOops, thanks for the nudge. I hope it will not be confusing if I leave the file names with "15" in them.
Comment #19
jhodgdonI tested this manually today and it works correctly:
- If you have no bundles selected, no sort options are available.
- If you have only 1 bundle selected, the fields/labels from that bundle are shown.
- If you have 2 bundles selected, the fields from both bundles are shown.
I have also looked over the code and tests, and they look fine.
I also looked at the test results. The test-only-fail patch fails as expected, and the test-plus-code patch passes, with no coding standards problems.
So... RTBC! This will really improve the usability of the entity reference field setup UI. Let's get it in ASAP, along with #3089521: Sort options for entity reference field are unsorted. Then we can woodshed on the other related issues, but these two are the big ones.
Comment #20
jhodgdonSetting this back to Needs Review because @benjifisher reminded me we need to test this with other ref fields like User that has no bundles and make sure it works there too.
Given that... would it make sense to add a test for a user ref field? Manual tests are good, but if we think we should manually test something that isn't in the automated tests, that is most likely a hole in our automated tests.
Comment #21
jhodgdonI tested this for user references, and it is fine: you don't have to select a (nonexistent) bundle in order for the sort options to appear. I looked at the patched test file again, and there is a test for it. So, User Reference is OK and tested.
However, it looks like there is a problem with taxonomy term references. The sort options are not available, no matter whether I select a bundle or not.
Hm. That is not caused by this patch. I'm not seeing sort options for taxonomy terms even without the patch. Oh, OK. Taxonomy uses its own subclass of the entity reference form, and it has
So, all of this seems to be OK, with more careful checks. Back to RTBC.
Comment #22
jhodgdonHah! Just as I was setting this to RTBC, #3089521: Sort options for entity reference field are unsorted came through, so the test portion of this patch needs a reroll. This should do it. Setting to needs review so @benjifisher can give it a quick look...
Comment #23
jhodgdonBy the way I tested manually with this new rerolled patch and we probably don't need the reroll tag.
Comment #24
benjifisherThe reroll looks good. The only differences in the patches from #17 and #22 are the context lines.
I reviewed the test to make sure that it still makes sense when combined with the changes from #3089521: Sort options for entity reference field are unsorted, and I do not see any problems. If we commit this change first, then we will have to look again when we get to #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected.
In manual testing, I noticed something new. Using Umami, I selected both Article and Recipe, so the
titlefield gets the label "Recipe Name". (We will revisit that in #3089528: Sort options for entity reference fields can be ambiguous if a field has different labels across bundles.) I chose to sort by this field. Then I de-selected Recipe, and the sort option automatically changed to "Title". Behind the scenes, the value has not changed, only the label. I think this behavior is a feature, not a bug.Back to RTBC!
Comment #25
benjifisherI guess we will have to change the order, since #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected was just fixed.
This will not be a routine reroll. We will have to check that the tests actually make sense when we combine the changes.
Comment #26
benjifisherI am working on the reroll.
Comment #27
benjifisherThe reroll was not too bad. This issue and #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected both added assertions in the same location, and that was the only conflict. I just had to decide which one to put first:
The last two lines are from this issue, and the previous line is from #3089523.
I looked over the test with the combined changes, and I think it still makes sense. I hope the testbot agrees!
Comment #28
jhodgdonI tested this again using User, Taxonomy, and Content reference fields. Just about everything is working as expected: taxonomy ref fields don't have sorting, and User fields always show the sort field (no bundles).
There is one quirk, however. To reproduce:
1. Set up a content reference field.
2. Check at least one bundle. The sort field appears (good).
3. Select a sort option. The sort direction field appears (good).
4. Uncheck all bundles. The sort field disappears (good), but sort direction field is still shown (bad).
This is maybe due to #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected (insufficient manual testing, probably my bad!) or could be a product of this patch... let's see.
Well, the behavior is a bit different with and without this patch, so I think we can probably fix it here?
With the current Core and with this patch, if I then (after 1-4 above):
5. Check a bundle. The sort field appears and sort direction disappears (good). Don't choose a sort option.
6. Uncheck all bundles. The sort and sort direction fields both disappear (good).
With the current Core and without this patch, if I do 5 and 6, the sort direction field persists on being shown (bad).
So... can this be fixed? And tested?
Comment #29
benjifisherI should have been more careful in reviewing the combined changes to the test. The failure in #27 comes from these lines:
We added the first comment and the last two line in the loop as part of #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected. The last two lines (a comment and the assertion that failed in #27) are part of the patch in #27. I will remove the three lines added as part of #3089523, which should fix this problem.
I confirmed the behavior described in #28. I will start by adding a test for that, so the new patch should still fail, but in the newly added part of the test.
Comment #30
benjifisherThe test failed to fail. Try again.
Comment #31
benjifisherI am not really happy with this, but it seems to fix the problems pointed out in #28. I am not sure why I need to make changes in two places, but it seems that neither one alone will do. I am not sure where it happens, but data from
$form_stateis sent to the constructor as$configuration, except when it isn't. :-(Comment #34
jhodgdonThis doesn't seem like the right fix to me (plus, the test doesn't pass)...
On the sort-by field, we have:
And then for direction, we have:
It seems like putting a 'states' on this, with the same conditions as the one on the sort field, would take care of the problem easier?
Comment #35
benjifisherI did say in #31 that I had some reservations about that attempt, so let's try the suggestion in #34.
Forgetting about #31, the attached patch goes back to the one in #30 and applies the suggestion from #34, adding a
#stateskey to the "Sort direction" element. The interdiff compares the attached patch to the one in #30.The only thing I do not like about this approach is that I prefer to get the markup right when the form is built rather than show/hide things with Javascript. The form is rebuilt (with an AJAX call, if Javascript is enabled) whenever the "Sort by" element changes, so it should be possible to get the form at that point.
I tested this manually using both a node reference and a user reference. It seems to avoid the problem pointed out in #28.
Comment #37
benjifisherOops, I uploaded the wrong patch. Try again.
Comment #39
benjifisherBoth patches are failing at the same point, before getting to the step that I thought would be different. I think I am missing an
assertWaitOnAjaxRequest().Comment #41
benjifisherAfter following the suggestion in #34, I have to update the test to check visibility of the "Sort direction" field. The current patch does that.
The test-only patch in #39 fails at the expected point for this issue. In order to test the problem noted in #28, the "-fail" patch attached here is test-only and comments out that line in the test, so (I hope) we will finally get to test assertions I added in #30.
Comment #44
jhodgdonLooks like the test still needs another wait in it...
Comment #46
abhijeet.kumar2107 commentedComment #47
benjifisher@abhijeet.kumar2107, I am un-assigning you. Have you made any progress on this issue?
I am now set up to run functional Javascript tests locally, so I hope to be able to finish this issue soon.
I am also updating the Remaining tasks in the issue summary.
Comment #48
benjifisherFrom #44:
That is a reasonable guess, but I think what is actually going on is that the tests I added in #41 (and maybe earlier patches) were more thorough than the manual testing we did. The current patch removes three lines that test whether the sort direction is hidden. You can test this manually, with or without the patch for this issue:
I believe this has been a problem for a while, but is more obvious since #3089523: Use progressive disclosure to hide Sort options on entity reference fields until bundles are selected, where we hid the "Sort by" option in (4).
I now have functional javascript tests running locally for Drupal 8.9.x, and the attached patch passes. I hope it will also pass when applied to 9.1.x.
Comment #50
janmejaig commentedI have verified the above issue , found that after applying the patch #48 , it is working fine as mentioned in the summary. Please find the attachment & below i have mentioned the steps to verify the issue.
Steps :
Comment #52
benjifisherAfter Comment #48, I added #3158651: Sort direction is not hidden when no sort field is selected for the problem I pointed out there. (That issue references this one.) Now that that issue has been fixed, the patch in #48 no longer applies.
Comment #53
benjifisherIt looks as though the patch in #48 also conflicts with #3139406: Replace usages of AssertLegacyTrait::assert(No)FieldByName, that is deprecated. I will start with a reroll, including the deprecated assertions, and then update them.
Comment #55
benjifisherThe reroll was a little tricky because there was so much overlap with the patch committed for #3158651: Sort direction is not hidden when no sort field is selected. For the non-test portion of the patch, one hunk from the patch in #48 was applied as part of that issue. The test portion was more complicated.
As for replacing deprecated assertion messages, #3139429: Replace usages of AssertLegacyTrait::assert(No)FieldByXPath, that is deprecated was more relevant than the related issue I mentioned in #53.
I am un-assigning myself and updating the issue summary. Unless I introduced new test failures, that task was done in #48. I think we still need to update the screenshots in the issue summary, but I am not going to set the status to NW for that. Perhaps we can still use the screenshots from #9.
Comment #56
benjifisherThe test failure looks unrelated. Maybe it is a glitch in the new GitLab integration.
The patch here should be the same as the one tested above, and I am also attaching a test-only patch.
Comment #58
jhodgdonThe MR on #54 failed in ComposerIntegrationTest. That is a random test fail for patches that I've seen over the past few months occasionally.
Anyway, thanks for the test-only patch, which fails in what looks like an appropriate manner. I'll give the MR/patch a review probably tomorrow. Thanks for getting this going again!
Comment #59
jhodgdonThis is looking good! I tested it manually, and everything is working fine according to what the issue summary says it should do. I've updated the screenshots in the summary (the ones referenced in the issue summary that are in comment 9 are outdated).
I also reviewed the code and the test. The code changes look good to me.
The test changes that are there also look good. The modified test is doing a good job of testing this part of the Proposed Resolution in the issue summary:
However, as far as I can tell, the other part of the proposed resolution is not in the test [setting to Needs Work for that]:
What I would suggest for testing that: Change the Title labels for the two content types in EntityReferenceAdminTest. With only one of the bundles selected, verify that the correct Title label is shown and the other one is not on the page.
Since built-in fields like Title might not behave the same as Field UI fields, it might also make sense to add a second text field to both content types, using different labels for each version of it, and verify the correct label is shown for that field when each bundle is selected.
Comment #60
benjifisherGood idea: more tests! I confess that I am relieved you did not suggest testing the "majority wins" scenario. In fact, I am not sure we have implemented that. Perhaps we should move that bit of the Proposed Resolution to #3089528: Sort options for entity reference fields can be ambiguous if a field has different labels across bundles.
I was not sure how to change the label of the title field, so I checked how it is done in Drupal\node\NodeTypeForm. It feels odd to call
\Drupal::service('entity_field.manager')instead of using DI, but I think that is the right thing to do in functional tests. Besides, there is already\Drupal::entityTypeManager()->getDefinitions()in the same test.I have to resolve a merge conflict because of #3145005: [November 9, 2020] Remove uses of t() in drupalPostForm() calls. I do not have to reroll a patch!
I hope I used the correct assertions. I do not see any other examples of testing option labels, but maybe I should look harder. Luckily, I am pretty comfortable working with XPath expressions.
If the tests pass, then I will finish replying to #59. I still have to add a test of another field with different labels.
Comment #61
jhodgdonLooks good to me! Updated the summary to say we require that a field label in use on that particular bundle is shown.
Comment #62
jhodgdonOne note: The MR page says:
The source branch is 7 commits behind the target branch
...
Fast-forward merge is not possible. Rebase the source branch onto 9.2.x to allow this merge request to be merged.
Are patch/MR providers supposed to keep rebasing as commits happen? That seems like a large burden, since it could be months before a RTBC patch/MR is committed (in my recent experience anyway).
Comment #63
jhodgdonHiding obsolete patch files.
Comment #64
benjifisher@jhodgdon:
In #59, you wrote,
I was planning to add that to the test. But I am flexible.
I tried clicking the Rebase button, and it failed. Locally, I merged with the current HEAD of 9.2.x and pushed that. Now, instead of a green Rebase button there is a gray Merge button.
I also tried rebasing locally. That also failed: as I said in #60, I had to resolve a merge conflict when updating the MR.
As long as merging is possible, I guess the core committer will do a squash merge. If merging is not possible, the corresponding patch would require a reroll.
Comment #65
jhodgdonI got some clarification/action from drumm/mixologic on this:
a) The tests were previously being re-run on an old patch file instead of the new MR. That has been fixed, so now the auto-run tests every 2 days for RTBC issue are being run on the MR. Hooray!
b) If you click through to the MR and it says "Fast-forward merge is not possible", that's kind of a lie. We don't need to rebase all the time until the tests fail with "Not currently mergeable" or if the MR links on the issue show up in red with a merge error.
So in summary: the tests should now run against the MR every 2 days, and like with a patch, if they continue to pass we don't need to do anything like keep rebasing. The committers can do the final merge unless there is a merge conflict.
Comment #66
jhodgdonI think at least having the title field label check in the test is probably fine. If you want to add the other one, that is fine too, and I will review it. :)
Comment #67
benjifisherThanks, but I think I will move on to other things.
Comment #68
benjifisherI moved on to other things. I reviewed another issue ... and was reminded that I forgot to look up assertEquals(). I got it backwards: the arguments should be expected, actual. It makes a difference when the assertion fails, since the message identifies the actual and expected.
Comment #69
jhodgdonGood catch! The changes look correct to me, and I checked and the MR doesn't contain any other assertEquals calls that are reversed.
Comment #70
alexpottThe merge request no longer merges in HEAD. In fact it never has since it was made rtbc - see #3187193: RTBC retests and merge requests
Comment #71
benjifisherI updated the MR. It looks to me as though the conflict is with #3168375: Convert calls to drupalPostForm(NULL, ...) to submitForm. The MR for this issue adds two lines before a line that is changed in that commit
Comment #72
jhodgdonThe merge looks good to me. Assuming the bot agrees, this is back to RTBC.
Comment #73
alexpottCommitted and pushed ad1cbe9b99 to 9.2.x and de4d6358df to 9.1.x. Thanks!
Comment #80
quietone commentedClosed #2707321: Entityreference field settings have irrelevant fields in "Sort by" select options as a duplicate, adding credit.