🇺🇸United States @Amber Himes Matz

Adding credit for marjose who reported the issue to Drupalize.Me originally.

amber himes matz → created an issue.

eojthebrave → credited amber himes matz → .

Thanks for the update, @eojthebrave! I've reviewed it again and just have some copy edit suggestions.

Also, I just used the GitLab WebIDE to search for links to the deleted file, install-manual, but I'm not sure I trust that 100%. So just wanted to make sure that you searched and removed links to the file you deleted.

Ship it!

I agree that the manual downloading instructions should be removed in favor of using Composer.

I reviewed the MR and caught some typos and commas. After these changes are made, I think this is good to go.

Opened a merge request here: https://git.drupalcode.org/project/user_guide/-/merge_requests/61

amber himes matz → created an issue.

Here's some additional feedback/questions we (Drupalize.Me) received about this tutorial:

Do you need to delete the content type's custom fields first before deleting
the content type? In D7, I think if the custom fields were not deleted first,
they still exist in the database. Not sure if this is taken care of in D8+,
but it would be nice to make that clear regardless.

Just a couple of things. (See comments in GL.) Otherwise looks good. Thanks!

Setting to needs work for the one possible issue. See inline comment in GitLab.

Removed the section at the top of the page about the broken api.drupal.org links, since that site has been updated, and the broken links to classes issue has been resolved. See https://www.drupal.org/project/api/issues/3342815 🐛 Classes missing from Drupal 10 Fixed

larowlan → credited Amber Himes Matz → .

Also, looks like the patch needs rerolling.

Looking at this issue again at DrupalCon at the Bug Smash table.

Looks like a possible intermittent test failure. Re-adding this to the queue.

Looking at this issue again from Bug Smash. There's been no activity for over 1 year since it was marked as Postponed (maintainer needs more info), and could be potentially be closed.

I am certainly no expert on this, but I did do some hunting for other issues related to YamlFileLoader and I learned that:

Portions of this file are a direct copy of
// \Symfony\Component\DependencyInjection\Loader\YamlFileLoader"

And, it seems, looking at other issues related to YamlFileLoader that the consensus is that Drupal's YamlFileLoader should really stay as close as possible to Symfony's. So I'm wondering if this issue should be closed a "won't fix"? Or possibly rolled in as a task with another feature request related to YamlFileLoader? Like ✨ Use native Symfony YamlLoader + Config Needs work maybe?

Adding tag, because it would be helpful to know how to verify this issue.

URLs where a specific version is present as the last path segment are redirecting to a page that appends (not replaces) `11.x` as the last path segment. Which results in a 404 because there are 2 versions in the path.

For example, this URL:

https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Component%21Util...

Redirects to an 11.x search page, with the following message:

Sorry, api/drupal/core%21lib%21Drupal%21Component%21Utility%21Unicode.php/function/Unicode%3A%3Astrlen/8.5.x/11.x cannot be found.

(Notice the “8.5.x/11.x” at the end of the url in the message.)

Keeping at “needs review” to invite other reviews.

This is great! Please create a change record that will help folks update docs and tutorials.

larowlan → credited Amber Himes Matz → .

Thanks all for your participation in the Bug Smash meeting.

Added info about The One to the section, What bugs we’re looking at.

Removed redundant mention of meta issue in Contributor Guide section.

Updated the section on Help Topics with current information on its status, issues, and how to help. Updated the section on the Contributor Guide with links and as current info as I could find. Skimmed the Previous Goals section and made some annotations with regard to status, as far as I know.

Looks like this is fixed. Thanks everyone!

Another missing class: https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!ContentEnt...

I went through all unresolved threads and double-checked that they were resolved, and resolved them.

Updated issue summary’s remaining tasks about adding the optional deriver argument, and crossed it off to show that we’ve completed it.

Updated remaining tasks in issue summary (all tasks done).

This is ready for review.

I've converted the 2 test plugins, EmptyHelpSection and TestHelpSection to use the HelpSection attribute.

And I removed a trailing comma from the last item in the attribute HelpTopicSection. I guess we're not doing trailing commas for last items in these arrays in attributes? Yet, anyway. I think that code standards for these are still pending (that's my current understanding). Regardless, this makes everything consistent and is consistent with the Action example as well.

Thanks @quietone for the reminder! I am working on this now.

Also, I updated the IS with remaining tasks (and those already done).

There was a missing use statement for the HelpSection attribute class in HelpSectionManager.php. Adding this fixed the error on installation (because it fixed the value of the HelpSection::class parameter passed in the parent constructor, which was meaningless without the use Drupal\help\Attribute\HelpSection; statement.

I tested this on a successfully-installed 11.x-dev site and verified that HelpSection plugins displayed as expected on admin/help. Screenshot attached with HelpSection plugins provided by Help module highlighted.

I'm working on this again. When I try to install Drupal 11.x-dev with this code running, the installation is failing with a typehint error in this new code.

TypeError: Drupal\Core\Plugin\Discovery\AnnotatedClassDiscovery::__construct(): Argument #4 ($annotation_namespaces) must be of type array, string given, called in /var/www/html/core/lib/Drupal/Core/Plugin/DefaultPluginManager.php on line 305 in Drupal\Core\Plugin\Discovery\AnnotatedClassDiscovery->__construct() (line 56 of core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php).

After fixing this, I will test the HelpSection in the UI to make sure it's working and upload a screenshot of that.

larowlan → credited Amber Himes Matz → .

Thanks for the review, @larowlan! I think I addressed everything, though there was 1 point of confusion about line 29 of core/modules/help/src/Plugin/HelpSection/HelpTopicSection.php, which I asked about in GitLab.

Looks like I missed some coding standards. I'll take a closer look tomorrow if I can. Happy to have help though.

I took a stab at this.

Amber Himes Matz → made their first commit to this issue’s fork.

Updated title to fix typo in "annotations" to ensure issue is discoverable in searches for "annotations".

lostcarpark → credited Amber Himes Matz → .

Adding tag per Gábor's request.

@fjgarlin Is there anything we can do to help hasten the launch of the new API site? Are there any project issues that are blocking it that we could help with? My colleagues and I would welcome opportunities to help, as we have so many API links on Drupalize.Me that are breaking, and we get weekly support messages from our members telling us about the broken URLs. It's a bit of a maintenance pain, as we try to keep the links up to date with the latest version of Drupal, and now I'm having to change some of them back to "9". It's confusing for folks.

We totally get the project priority thing, but if there is a way to help and get the new API site launched, we'd love to know about it.

Hiding patch files, as the MR contains the latest solution.

Amber Himes Matz → created an issue.

Thanks for the clarification, @andypost. This patch adds the patch from #2 (the changes to core/modules/help/tests/src/Kernel/HelpSearchPluginTest.php). Interdiff included.

Ok, I think this is ready for review!

Alright, here's a patch that adds to the one in #3, updating the URL and link text to the Help Topic Standards docs page (without the redirect).

Replaced "Drupal 8" with "Drupal" in several places.

Amber Himes Matz → created an issue.

Updated the IS. Per @andypost in #99 (and I, as co-maintainer, concur), moving some items in the IS that were in the section "Needs discussion" to "Not part of the roadmap".

1. Moved ✨ Do we need hierarchy/order for help topics? Active to the section "Not part of the roadmap".
2. Moved "
3. #3064854: Allow Twig templates to use front matter for metadata support → , and if that is done, #3085972: Replace Drupal\help_topics\FrontMatter with Drupal\Component\Utility\FrontMatter →

" to the section "Not part of the roadmap"

4. Moved 📌 Move testing of help topic rendering into child of GenericModuleTestBase Active to "Not part of the roadmap" as it's not a part of this roadmap, but a child of 🌱 Deprecate hook_help() and combine with Topics Active (per #111

Hopefully the IS now clearly reflects that there are no action items remaining.

A nice workaround could be if help topics could receive a context provided by some service, maybe defining injection in the frontmatter.

I imagine @fgm is not the only one to need this. Sounds like "Allow help topics to get context defined in frontmatter" should be opened as a child issue of this one? @fgm do you want to open the issue, or should I? In either case, I'm interested in more details as to what you are looking for, and if you could provide examples of your modules that use context in their hook_help() implementations. Thank you.

LGTM and credit has been added already, so closing as fixed. Thanks all!

Thank you @quietone for pointing out that this IS is a bit of a hard-to-understand mess. And to @xjm for pointing out the scoping problem. I have updated the title and issue summary as follows:

1. Removed statement about it being postponed, because it is not.
2. Updated title to "Fix up minor copy problems in help topics" since this issue is only focused on copy edits, not content or code errors (scope).
3. Updated issue summary. Moved the original summary down to "Original issue summary section". Organized the IS into template with clear action items and scope, and indicated what has been done.
4. Added referenced issues
5. Added Release notes snippet

Also, just to add additional context and clarification, this issue historically was a sort of meta issue to collect problems. Problems were fixed in other issues or new issues created. This issue is now scoped to minor copy edits related to word usage and consistent link text.

I hope this update makes it easier to review and commit. But feedback is always welcome on how it could be further clarified if clarification is required. Forgive us if we are a bit strained as getting help topics stable has been a long long road.

When I checked the MR just now, it said it was still blocked even after @andypost rebased earlier today, so I hit the rebase button again, and now it looks "able to merge" again.

I found this issue via #bugsmash, where catch requested reviews and testing, so adding the Bug Smash Initiative tag.

I validated the issue in Drupal 11.x in Firefox 114.0.2 and Chrome Version 114.0.5735.198 using DDEV by following the steps to reproduce in the IS, and found 2 JS assets' response headers included x-generator: Drupal 11 (https://www.drupal.org), as described in the issue summary problem. (Screenshots attached.)

To test the patch, I applied the patch, cleared the cache on the Performance page, and returned to the Add article page. I opened the devtools' Network tab, and refreshed the page 3 times. I inspected the response headers for each aggregated CSS and JS asset, and did NOT find x-generator: Drupal 11 (https://www.drupal.org) as before.

I navigated to other admin and front-facing pages on the Umami site, and inspected response headers for aggregated CSS and JS assets. Where I found x-generator: Drupal 11 (https://www.drupal.org), I refreshed the page, and noticed it was then gone. (With the patch applied.)

As far as I can tell, this patch in #23 addresses the problem. Setting to RTBC.

Looks good to me! Thanks @andypost for taking care of this.

Updated issue summary regarding opening 📌 Standardize how external links are wrapped with Twig trans/endtrans tags in help topics Active as separate issue and not addressed in this issue.

I've pushed new commits that "undo" changes to Twig trans tag wrapping and resolved the thread discussing this. Ready for review (assuming tests pass).

After discussing with @andypost in Slack, I'm going to "undo" changes in this MR where I moved the Twig {% trans %}{% endtrans %} wrapping (in Additional resources external links). I opened a new issue to discuss this 📌 Standardize how external links are wrapped with Twig trans/endtrans tags in help topics Active .

Amber Himes Matz → created an issue.

I've submitted a merge request which addressed all remaining "PATCH" items in the issue summary. These are mostly nits and standardizing on the User Guide links in the Additional resources.

I've opened separate issues where there a content update to a topic is needed.

This will be ready for review after the tests run (and hopefully pass).

I've updated the issue summary to denote where items have been fixed, outdated (no longer an issue), "won't fix", moved to separate issues, or in-scope ("PATCH") for this issue.

Also changed this issue back to "Task" as I have a patch/MR almost ready to fix the remaining in-scope issues here.

Amber Himes Matz → created an issue.

Amber Himes Matz → created an issue.

From this issue summary, I added the following item:

On #3150364: Add a description for the language toolbar button to the CKEditor help page → they also made a list of accessibility features and a section about making accessible text. I'm not sure we covered that well in our topic on Accessibility, so we should check. See this screenshot of the output of one of the patches:

to 📌 Create or update help topics that cover CKEditor 5's module overview text in hook_help() Active

See also this comment: https://www.drupal.org/project/drupal/issues/3358585#comment-15116862 📌 Create or update help topics that cover CKEditor 5's module overview text in hook_help() Active

Added another CKEditor help related item from 📌 Fix up minor copy problems in help topics Fixed to the issue summary.

On #3150364: Add a description for the language toolbar button to the CKEditor help page → they also made a list of accessibility features and a section about making accessible text. I'm not sure we covered that well in our topic on Accessibility, so we should check. See this screenshot of the output of one of the patches:

hestenet → credited Amber Himes Matz → .

volkswagenchick → credited Amber Himes Matz → .

Before you “reroll”: Please remember that the “Needs reroll” tag also applies to merge requests that need rebasing. I understand how this can be confusing. And, adding patches to an issue using merge requests can result in confusion and lost work. Please avoid doing that. Refer to the documentation on how to rebase a merge request:

https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-dr... →

Comparing the MR in #8 that was set to needs review and the patches that followed, it’s clear that all of the patches that followed were incomplete — missing files and changes that were included or requested in the MR. (This is why we don’t want to switch between MR and patch workflow if it can be helped.)

Hiding all of the files since they derailed the issue (except for the ones showing the CSS class name changes in the inspector since I’m not sure how helpful those are or not). The MR (link in #8) is where work needs to resume from:

1. The MR needs to be rebased. The target branch probably needs to be updated as well.
2. The MR needs review — hint: the @file docblock in wide-content.pcss.css needs to conform to https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... → with a summary and description with lines between.
3. When comments on the MR have been addressed, they should be marked as resolved. (The current unresolved comment was addressed, but the update doesn’t meet @file docblock coding standards.)

Please refrain from adding screenshots of terminal windows showing commands for applying a patch. The CI jobs and test runs will tell us if a code change cannot be merged. Screenshots are really only useful for showing a UI change or problem.

Removing credit where patches were added unnecessarily.

There appear to be a number of unresolved threads on the MR that will need to be resolved before this can be RTBC’d again. Thank you!

@Gauravvvv Thanks for your attention to the “Needs reroll” tag, but this issue appears to be using an MR-based workflow, not a patch workflow. I realize that the “Needs reroll” tag could be confusing, when what is needed is a rebase on the merge request, not a patch file. Please refer to the docs on rebasing a merge request: https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-dr... →

Also, it does look like there are a number of unresolved threads in the MR that should be marked as resolved if the feedback has been addressed.

@eojthebrave asked if I would take a look at the copy and check for spelling/grammar. This is kind of awkward to do because we’re not dealing with a file or patch. So here’s the whole blob with my edits included.

In the prereqs, does a module need to be installed if it contains a SDC? It just says the theme must be enabled (which I changed to the word, “installed”. We should include both cases, I think, if that’s the case.

A component is a piece of the user interface (UI) that has its own logic and appearance. A component can be as small as a button, or as large as an entire node. Drupal's Single Directory Components consist of metadata that describe the component, HTML markup, and, optionally, CSS and JavaScript, which are all located in the same directory. Hence, the name, Single Directory Components.

To demonstrate how Single Directory Components work, we're going to walk through creating an example 'chip' component and use it in a theme.

## Prerequisites to working with components

- You must be using Drupal 10.1 or greater
- You must have the Single Directory Components module enabled (at _admin/modules_)
- You must have a theme (or module) that you want to add components to. The theme must be installed (at _admin/appearance_)
- You must know where in the filesystem the theme's code is located. (We'll be using the Drupal core Olivero theme, located at _core/themes/olivero/_ in this example.)

## Define a component

Every component requires a single directory for its assets to reside in. This directory must exist in a _components/_ subdirectory of your theme (so that Drupal can find it). A _{NAME}.component.yml_ file with metadata about the component is required.

Pick a name for your component. We'll use "chip" for our example. It should be unique within the theme. Components are namespaced, so multiple different themes could declare a "chip" component.

Create the directory _core/themes/olivero/**components/chip/**_. Then, in that directory, create a file starting with your component name,  followed by _.components.yml_. For example, _chip.components.yml_.

Populate the _chip.components.yml_ file with metadata that describes the component:

```yaml
name: Chip
props:
  type: object
  required:
    - color
  properties:
    # Can the chip be dismissed by clicking on it?
    dismissable:
      type: boolean
    # One of 'primary', or 'secondary'.
    color:
      type: string
slots:
  # Content to display in the chip.
  chip_content: {}
```

The data in this file describes your component to Drupal and to anyone who wants to make use of it. This one includes a human-readable `name` for the component. Definitions of the component’s inputs in the form of **props** (for data whose type and structure is well defined) and **slots** (for data with an unknown structure, like nested components). These act as an API or contract for the component, and is like saying, "We promise to always accept and use these inputs."

[Learn about additional metadata values](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml#s-full-example).

## Add some markup

A component that doesn't output anything isn't that useful. So let’s add some markup via a Twig file. Within the component’s directory, create a _.twig_ file using the name of your component.

For example, in _components/chip/chip.twig_, add the following:

```html
{%
  set classes = [
  'chip',
  'chip--color-' ~ color|clean_class,
  dismissable ? 'chip--dismissable',
]
%}
<div class="{{ classes|join(" ") }}">
  {% block chip_content %}{% endblock %}
</div>
```

The above code contains some HTML markup and Twig expressions that make use of component inputs in order to output dynamic content. Note: the Twig variable names (and their values) map to the props and slots defined in your _{NAME}.component.yml_ metadata file.

## Use your component in a template file

In order to use the markup generated by your component, you'll need to embed it into a Twig template file in your theme. We're going to add ours to the node template file, because we're going to display the node type (bundle) as a chip.

Edit the _core/themes/olivero/templates/content/node.html.twig_ template file and add the following (where you want the chip to display):

```html
{% embed 'olivero:chip' with {
  color: 'primary',
  dismissable: true
} only %}

  {% block chip_content %}
    Type: <span>{{ node.bundle() }}</span>
  {% endblock %}

{% endembed %}
```

This Twig code embeds the chip component into the Twig template file and defines the values to pass to the component’s inputs. This uses standard Twig embed syntax. Some things to note: the namespacing of the component `olivero:chip` resolves to the 'chip' component in the _olivero_ theme. And, the definition of the input props (`color` and `dismissable`) and slots (`chip_content`) correspond to the props and slots you defined in your component’s metadata file (_{NAME}.component.yml_).

Clear the cache and view a node on your site. You should see the node type output as a `chip` on the page in the place you embedded the component in the node template file.

## Add some style

Let's add some CSS and make that chip look a little more attractive. This requires creating a CSS file with the name of your component in the component directory, and well, ...that's it!

Create the file, _core/themes/olivero/components/chip/chip.css_, with the following contents:

```css
.chip {
  display: inline-block;
  padding: 0.25rem;
}

.chip--color-primary {
  background-color: var(--color--primary-50);
  color: white;
}

.chip--color-secondary {
  background-color: var(--color--gray-100);
  color: var(--color-text-primary-medium);
}

.chip--dismissed {
  display: none;
}
```

If the component’s _{NAME}.css_ file exists, Drupal will automatically find it, and include it on the page. In the case of our chip component, since the _chip.css_ file exists, Drupal will use it whenever the chip component is used in a template file.

## Finally, add some interaction with JavaScript

Adding some JavaScript to our component isn't any harder. Let's add some JavaScript that will make it so the chip can be dismissed (hidden) when a user clicks on it. This requires creating a _{NAME}.js_ file with the component name in the component’s directory.

Create the file, _core/themes/olivero/components/chip/chip.js_, with the following JavaScript code:

```js
((Drupal) => {
  Drupal.behaviors.chip = {
    attach(context) {
      context.querySelectorAll('.chip--dismissable').forEach((chip) => {
        chip.addEventListener('click', () => {
          chip.classList.toggle('chip--dismissed');
        })
      });
    },
  };
})(Drupal);
```

Refresh the page and Drupal should automatically locate this new JavaScript file and include it whenever the chip component is used. You can test that it's working by setting the `dismissable` prop of your component to `true`, and then clicking on the chip element. (It should disappear.) Now set it to `false`, and clicking should have no impact.

Note: this ties together code in CSS where we have classes to show/hide the chip and the Twig file where we dynamically decide whether or not to add the `.chip--dismissable` class depending on the `dismissable` prop's value.

## Take it further

Components can do a lot more. Now that you understand this brief example, check out the [complete annotated example](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/annotated-example-componentyml#s-full-example) to learn more. Here are a few things to experiment with:

- You can include other assets in the directory, too, like images, but they won't be automatically loaded. You'll need to reference them via your Twig, CSS, or JavaScript files. Can you add an icon to your chip component?
- Use the `libraryOverrides` in your _{NAME}.component.yml_ file to require additional JavaScript libraries like _drupal/once_ or jQuery. Can you rewrite the JavaScript so that it uses the _drupal/once_ library?

1.

+++ b/core/lib/Drupal/Component/FileSecurity/FileSecurity.php
@@ -157,7 +157,7 @@ protected static function writeFile($directory, $filename, $contents, $force) {
+    if (@file_put_contents($file_path, $contents ."\n")) {

Coding standards nit. Should be a space after the concatenation dot.

2. And, it needs another reroll.

3. @mstrelan -- Can you give reviewers a clue on how to manually test your patches? Looks like there's some confusion there.

4. I'll add a Drupal 10 test run for the other patch (1915772-34-generated-htaccess-new-line.patch) in #34.

5. Hiding some files. It's confusing because we're dealing with 2 files. (I'm not entirely clear on why that is -- maybe because one is dynamically generated.)

Hiding old patches, as it looks like the patch from #52 is the one!

1. Looks like there is 1 unresolved comment (that got addressed but was never marked as resolved): https://git.drupalcode.org/project/drupal/-/merge_requests/3075#note_137045)

2. The merge request is currently blocked and needs a rebase.

Thank you!

The MR is currently blocked and needs to be rebased. Also, the version on the issue is 11.x-dev but the target branch on the MR is 10.1.x, so maybe the target branch on the MR needs to be updated as well? Just a bit of git-related cleanup required before this can be reviewed by a committer. Thank you!

Hiding the patch file because it looks like the workflow was switched to MR.

The MR is currently blocked according to GitLab and needs to be rebased.

Looks like the MR was updated after the last RTBC and needs another review. Thank you!

Looks like this MR needs to be rebased onto 9.5.x, as the merge is currently blocked according to the MR in GitLab. (Clicking the Rebase button didn't work for me.)

It's really unclear if this issue is using a patch or a merge request, and which one contains the fix. Please clarify where the work is being done on this issue. (And contributors, please follow that guidance.)

Whether patch or MR is chosen, the current ones don't apply. So after a path is chosen (patch or MR), reroll/rebase.

Also, posting screenshots of a terminal window applying the patch is not helpful. I've hidden the screenshot file showing terminal window. Screenshots are helpful if a patch affects a change in the UI itself. Please review https://www.drupal.org/community/contributor-guide/task/add-screenshots-... → -- especially the "Goal".

Thank you!

Looks like this MR needs a rebase, as the merge is blocked. It might work to just click the Rebase button in the MR link.

larowlan → credited Amber Himes Matz → .

We triaged this as part of Bug Smash Initiative. This needs more info, especially an issue summary update. It would be great if someone could go to #1818574: Support config entities in typed data EntityAdapter → , and starting with comment #73, figure out what needs to be done in this issue. Also, changed to a task.

Thank you for catching the typos, @rgladden!

volkswagenchick → credited Amber Himes Matz → .

@webchick Thank you so much. I’ll never forget how the “webchick” tour Lullabot workshop for Drupal 7 happened at exactly the time when I was trying to get back on my feet and back into Drupal development after a major life setback. That’s when I first met you in person. You were such an inspiration to me and I proudly wore my webchick tour t-shirt until it was full of holes and falling apart at the seams.

Your mentorship, guidance, and encouragement during the development of Help Topics as an experimental module was so vital and helpful to me as I was struggling to learn how to become a maintainer myself.

But more than that, you are just such a terrific human being. I miss your presence in the community and I wish you the very best in all your future endeavors.

:hugs:

The link is now fixed. Thank you @apaderno! There’s nothing to commit here since it was a documentation page edit.

Thanks for the broken link report! Technically, I think an issue for documentation pages like this one go in the https://www.drupal.org/project/issues/search/documentation → queue, but that queue isn't being actively managed it looks like, so we can leave it in here for now.

I'll see about pinging an admin of that page to get it updated.

And, I'm setting the status to Active since there's no patch or work in progress on it.

larowlan → credited Amber Himes Matz → .