Problem/Motivation
The README explains how the module is built, but not enough of how to set it
up or use it. Working through it as a first-time user turns up four gaps, one of
which makes the module look broken.
1. Permissions are not mentioned at all
Entity Browser generates a permission per browser. Without Access
Paragraph items pages
(access paragraph_items entity browser pages), clicking the toolbar
button opens the dialog on an Access denied page instead of the
Paragraph type selector.
Nothing in the README mentions it, and the permission is named after the
entity browser rather than after this module, so there is no obvious connection
to follow. This was found while writing the FunctionalJavascript tests in
#3040507
— the test failed on it before anything else.
2. The allowed HTML step points at a config file
Step 4 currently links to line 16 of the example module's
filter.format YAML and asks the reader to work it out. The tag and
its attributes should be in the README, since getting this wrong silently strips
embedded paragraphs when the text is filtered.
3. There is no description of the editing experience
The README covers configuration and then stops. It never says what an editor
actually does — press the toolbar button, choose a type, fill the form, use
Edit paragraph or Embed — or what a successful
result looks like. That makes it hard to tell whether the configuration worked.
4. A known console error is undocumented
Selecting an embedded entity logs a JavaScript error from Entity Embed
(Cannot read properties of undefined (reading 'pencil'), see
#3619182).
Embedding still works, but a user who opens the console will reasonably conclude
the module is broken and file a duplicate.
Proposed resolution
- Split Installation into numbered steps and add a Grant the
permissions step naming both the UI label and the machine name. - Write the required
<drupal-entity>tag and its
attributes out in full, with the narrower variant the example module
uses. - Add a How editors use it section describing the flow from
toolbar button through to the saved, rendered paragraph. - Add a Troubleshooting section covering: access denied,
embeds disappearing when filtered, the toolbar button doing nothing, and the
console error above. - Correct the embed button configuration step: the bundles field is labelled
Paragraph type, because Entity Embed uses the entity type's
own bundle label, not "Allowed Entity Bundles". - Move the Drupal 12 status into its own section and link the tracking
issue.
Remaining tasks
- Review the wording.
- Consider mirroring the same changes onto the project page, which currently
repeats the README.
Comments
Comment #4
marcelovaniMerged as MR !21.
Two parts.
The README was reworked after going through it as a first-time user. The gap that mattered was permissions: they were not mentioned at all, and without
access paragraph_items entity browser pagesthe toolbar button opens the dialog on an access denied page, which reads as the module being broken. The permission is named after the entity browser rather than after this module, so there was nothing to lead a reader to it. Installation is now five numbered steps with that as its own step.Also: the allowed HTML step pointed at line 16 of the example module's config and left the reader to work it out, so the
<drupal-entity>tag is now written out; there was no description of what an editor actually does, so there is now a "How editors use it" section; and there is a troubleshooting section for the four ways this goes wrong in practice. One correction along the way — the embed button's bundles field is labelled "Paragraph type", not "Allowed Entity Bundles", because Entity Embed uses the entity type's own bundle label.Second,
hook_help()now renders the README at/admin/help/paragraphs_inline_entity_form, the same way config_pr and the other modules do it, so the instructions reach the person configuring the site rather than only the person reading the repository.One deliberate difference from that pattern: the contents are escaped before
nl2br(). This README documents the<drupal-entity>tag, and unescaped the browser treats it as unknown markup and drops it, so the most important line of step 4 disappears from the page with no sign it was ever there. The test asserts that line survives.Comment #5
marcelovani