Convert action module hook_help() to topic(s), including views bulk operations

Blocker commited #3047723: Convert views, views_ui module hook_help() to topic(s)

I am working on this.

The plan is to have 2 topics:
- Actions overview: what are actions
- Using actions: create an action and use it in a view

This patch adds the 2 help topics according to plan #6.

I have uploaded the patch with minor changes, except the points below as I am not sure about the changes

e) Task topic -- the links to permissions in the "Who can create actions" section link back to the topic page. I'm not sure where they should link or even if they should be links?

j) Task topic -- Since we're talking about views, we should link to the views overview topic in the Goal section, like "See ____ for more information about views" and also add the views overview topic and views editing/creating topics as Related.

m) I think somewhere (in the overview topic?) we need more clarification about action types, and how they might be connected to views base tables... although that said, I am not sure how to determine the base table for a view. It doesn't seem to be visible at admin/structure/views (I thought it used to be???). Hm, if you click through to a particular view, it does show you the base table as part of the page title, but I don't see it on admin/structure/views. I wonder when/why that change was made, seems very lame to me!!!

Please review for the points I have implemented.
Thank you !

I have uploaded the patch as per the suggestions in #11

For points
m) I have added it in overview topic in 'where are actions used?' section

3. Removed the explanation and placed it in point m (I have added it in overview topic in 'where are actions used?' section)

Please review
Thank you !

Test is failing because views.overview code is committed in the Drupal code repository for 9.1.x and not in 8.9.x

Issue in which patch added for views.overview https://www.drupal.org/project/drupal/issues/3047723

I have made the changes as suggested in #17 except the below point

b) Question about action.overview topic here:

So node actions will be available in views that list content
Are the actions actually called "node" actions in the user interface? I kind of doubt it -- we have had the policy for years of not using the word "node" in UI text except as the name of the module.

I tried searching for some better wordings (Actions page in the UI) but I could not find any, so leaving the word "node" as it is in help.

Applied the recommended minor fix.

Known random test fail

+++ b/core/modules/help_topics/help_topics/action.creating.html.twig
@@ -0,0 +1,30 @@
+<h2>{% trans %}Goal{% endtrans %}</h2>
+<p>{% trans %}Create an advanced action, and add it as an additional <em>bulk operation</em> to a <em>view</em> that already supports bulk operations. You can, for example, create an action to change the author of multiple content items. See <a href="{{ view_overview }}">Managing content listings (views)</a> for more information about views and <a href="{{ action_overview }}">Configuring actions</a> for more about actions.{% endtrans %}</p>
+<h2>{% trans %}Who can create actions?{% endtrans %}</h2>
+<p>{% trans %}Users with the <em><a href="{{ action_permissions }}">Administer actions</a></em> permission (typically administrators) can create actions. You will need <em><a href="{{ views_permissions }}">Administer views</a></em> permission to add it to a view.{% endtrans %}</p>
+<h2>{% trans %}Steps{% endtrans %}</h2>
+<ol>

I think this has been discussed in another ticket but not sure where - I think we need to check access to these links and vary the text based on access - so that we're not linking people to a 403.

Condition to render parts of topic been discussed somewhere else, but it must be covered in twig issue - which is now various url generation
#3090659: Make a way for help topics to generate links only if they work and are accessible

Links issue has moved on a lot which is good. If that lands first we should update things here, but otherwise fine to commit and then use the new API once it's in.

Some comments on the text:

1. +++ b/core/modules/help_topics/help_topics/action.creating.html.twig
   @@ -0,0 +1,29 @@
   +<h2>{% trans %}Who can create actions?{% endtrans %}</h2>
   +<p>{% trans %}Users with the <em><a href="{{ action_permissions }}">Administer actions</a></em> permission (typically administrators) can create actions. You will need <em><a href="{{ views_permissions }}">Administer views</a></em> permission to add it to a view.{% endtrans %}</p>
   +<h2>{% trans %}Steps{% endtrans %}</h2>
   

   'to add it to a view' can this be 'to add actions to a view'?

2. +++ b/core/modules/help_topics/help_topics/action.creating.html.twig
   @@ -0,0 +1,29 @@
   +<h2>{% trans %}Steps{% endtrans %}</h2>
   +<ol>
   +  <li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Configuration</em> &gt; <em>System</em> &gt; <em><a href="{{ actions }}">Actions</a></em>. A list of all actions is shown.{% endtrans %}</li>
   +  <li>{% trans %}Choose an advanced action from the dropdown and click <em>Create</em>.{% endtrans %}</li>
   +  <li>{% trans %}Enter a name for the action in the <em>Label</em> field. This label will be visible for the user.{% endtrans %}</li>
   +  <li>{% trans %}Configure any of the other available options. These will depend on the kind of action that you have chosen.{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Save</em>. You will be returned to the list of actions, with your new action added to the list.{% endtrans %}</li>
   +  <li>{% trans %}In the <em>Manage</em> administrative menu, navigate to <em>Structure</em> &gt; <em><a href="{{ views }}">Views</a></em>. A list of all views is shown.{% endtrans %}</li>
   +  <li>{% trans %}Find the view that you would like to edit, and click <em>Edit</em> from the the dropdown button.{% endtrans %}</li>
   +  <li>{% trans %}Click on the <em>Operations bulk form</em> in the <em>Fields</em> list. The exact name of the bulk form field depends on the action type.{% endtrans %}</li>
   +  <li>{% trans %}Check the action in the <em>Selected actions</em> list and click <em>Apply (all displays)</em>.{% endtrans %}</li>
   +  <li>{% trans %}Click <em>Save</em>. The action will be available as a <em>bulk operation</em> in the view.{% endtrans %}</li>
   +</ol>
   

   Wonder if the howto would be better as a tour, although I don't think we have any low-level tours at all.

3. +++ b/core/modules/help_topics/help_topics/action.overview.html.twig
   @@ -0,0 +1,21 @@
   +<h2>{% trans %}What are actions?{% endtrans %}</h2>
   +<p>{% trans %}Actions are tasks that can be executed by the site such as unpublishing content, sending email messages, or blocking a user. Other modules can trigger these actions when specific system events happen; for example, when new content is posted or when a user logs in. Modules can also provide additional actions.{% endtrans %}</p>
   +<h2>{% trans %}What are simple actions?{% endtrans %}</h2>
   

   I'm not sure 'other modules' is the best thing here, especially when administrators can trigger actions via views. This reads like a description of the hook system. Could we possibly drop the last two sentences - modules being able to provide actions is developer information really. The 'how are actions used' section describes how you use them. The other way would be via Rules - but as contrib-only I don't think it needs to be explicitly mentioned.

Updated patch in #28 addressing #30.1. Thanks!

Changed to use help_route_link according to https://www.drupal.org/node/3192582

+++ b/core/modules/help_topics/help_topics/action.creating.html.twig
@@ -0,0 +1,21 @@
+{% set action_permissions = render_var(url('user.admin_permissions', {},{'fragment': 'module-action'})) %}

+++ b/core/modules/help_topics/help_topics/action.views.html.twig
@@ -0,0 +1,23 @@
+{% set views_permissions = render_var(url('user.admin_permissions', {},{'fragment': 'module-views_ui'})) %}

also fixed indent before {'fragment'

First off, thanks to everyone who's been working on this issue!

I've gone ahead and created a new patch with the changes I think should happen.

1. The topic which was titled "Adding bulk actions to a view" describes the process for adding a bulk operations form to a view, so I updated the title to that. Also, the Actions module does not need to be installed to add a bulk operations form to a view, so I renamed the file to views.bulk_operations.html.twig, and I added it as a related topic to views.overview.html.twig. I think it makes more sense as a Views help topic, even though it uses actions behind the scenes.

Also, I moved info and links to related topics from the "Goal" section and added an "Additional resources" paragraph about installing Actions module to see related topics. This was partially due to the fact that the help_topic_link() function returns the text "Missing help topic" if the module providing the topic is not installed. This isn't really ideal for links to help topics belonging to another that may not be installed. (Luckily our Related Help Topics feature takes care of that nicely and only displays links to topics of modules that are installed.)

2. For action.overview.html.twig, I updated some text with intention of clarifying the text, and I also added information about configuring the bulk operations form and taking care with permissions. I ran into some particularly gnarly white screens when testing bulk operations in views which had conflicting permissions -- it was not pretty and so this text was added to guide the user to best practices and to avoid gnarly gotchas when adding a bulk form element to an administrative view.

I also added some info about how bulk operations forms are labeled and distinguishing them from "operations links". I found this aspect particularly confusing and wanted to give the user some tips on how to successfully add the correct and appropriate bulk operation form to their view. We are trying to help folks with these topics after all.

3. For action.creating.html.twig, I added steps to edit configuration of an action you've created in the Actions UI and also how to delete an action you've created.

Interdiff and new patch attached.

Forgot some trans/endtrans tags for new text I added (yay, tests caught that!). Interdiff (from my last patch in #35) and new patch attached.

Thanks @jhodgdon for your review, suggestions, and new patch. I agree with your feedback and have reviewed and tested the patch in #40 on a local Drupal 9.2.x development branch with an administrative user and an authenticated user with permissions to view help topics to verify links. It looks good to me!

Past contributors to this issue, could 1 or 2 of you take a look at the latest patch and review?

If you use https://simplytest.me/ to review, select project name "drupal" and from the next drop-down, select branch 9.2.x (it's near the bottom of the list of options). Expand the Advanced options and under Apply patches, enter https://www.drupal.org/files/issues/2021-04-21/3094482-40.patch. Then select the "Launch sandbox" button. Wait for the environment to be prepared (this will take a little while).

Steps to test (see also "Review the patch" instructions from the issue summary at the top of the page. The steps below are specific to the files in the patch in comment #40.

0. Login with username: admin, password: admin (if you used simplytest.me to launch a sandbox site).
1. Install Help Topics and Actions modules (Manage > Extend, under Core check "Action", under Experimental core, check Help Topics, then select Install at the bottom of the page.
2. From the Manage menu, select Help (admin/help). Verify that the Topics section appears and various topics are listed. Verify that the "Configuring actions" topic appears in this list.
3. Select "Configuring actions". Read through the topic and verify the links. Does the topic conform to the "Parts of a section topic" standards?
4. From Related topics, select "Creating an advanced topic". Read through the topic. Does it conform to the "Parts of a Task topic" standards? Can you follow the steps? Do they make sense?
5. From Related topics, select "Adding a bulk operations form to a view". Read through the topic. Does it conform to the "Parts of a Task topic" standards? Can you follow the steps? Do they make sense?
6. From Related topics, select "Managing content listings (views)". Read the section "What are bulk operations?". Is the language clear and understandable?
7. For all topics, are there any spelling or grammar issues or errors? Do the topics adhere to the Help Topic Standards?

I followed the review process as described in the IS.
I all looks good to me.
For me it is RTBC.

The failed test has to do a with a page crash when running Layout_builder.Drupal\Tests\layout_builder\FunctionalJavascript\LayoutBuilderDisableInteractionsTest and not our patch, I think.

Testbot is happy again.
Back to RTBC.

+++ b/core/modules/help_topics/help_topics/action.overview.html.twig
@@ -0,0 +1,25 @@
+<p>{% trans %}In the core software, actions can be executed through a <em>bulk operations form</em> added to a view; if you have the core Views module installed, see the related topic "Managing content listings (views)" for more information about views and bulk operations.{% endtrans %}</p>

Discussed with @jhodgdon as to why this isn't linked.

Now that the new help topics url feature is in, this can be a link.

@jhodgdon proposed to add that to #3121340: Fix up minor copy problems in help topics which is doing that in bulk

That's fine with me

Saving issue credits

Committed f29f4a3 and pushed to 9.3.x. Thanks!

Because help topics is experimental, backported to 9.2.x