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

marcelovani created an issue. See original summary.

  • marcelovani committed 97c4d371 on 3619188-readme-instructions
    Issue #3619188: Show the README on the module's help page
    
    The...

  • marcelovani committed 341ae0e0 on 8.x-1.x
    Issue #3619188: Make the setup instructions complete
    
marcelovani’s picture

Merged 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 pages the 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.

marcelovani’s picture

Status: Active » Fixed

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.