Update hook_help for Contact module

Taking it - Drupalcon Prague

Text seems OK here - only link style was changed according to https://drupal.org/node/632280#url-note

Thanks! The changes look correct to me.

We need someone to give this a bit of manual testing:

a) Install the patch.
b) Enable the Contact module.
c) Navigate to admin/help/contact.
d) Read through the page and make sure it makes sense and is formatted in a reasonable way.
e) Test each link to make sure it goes to where it should go.
f) Try doing the actions listed in the help and make sure they work as described, and if the text says "click on ..." or "navigate to ..." or "the ... field", the help text matches what you see on the screen.
g) Navigate to admin/structure/contact.
h) With the help at the top of the page, repeat steps d-f above. I'm especially interested to know if it's true that the Contact page is added to the Footer menu (for instance, is it also true if you used the "minimal" install profile?).

Thanks!

Patch applies and links are good, but ...

... (un)fortunately the contact form has become an entity that can have custom fields. It now has its proper config screens at admin/structure/contact which are new in D8 with view mode and form mode management options.
So there are quite a few UI changes that need to be reflected in the help text. It also needs refernces to field and field_ui

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

@jhodgdon - Please review attached patch which will work with current code and has more additions as suggested in #4.

Thanks for the new patch! It's a good start... but I think it needs some more work.

For one thing, I don't think we should say "Contact form has become an entity that can have custom fields...." -- we need to document what the contact module currently does, not compare it to its past history, so "has become" is not good here. Also, people will not know what an "entity" is unless you explain it.

I also think that it will be confusing to talk about fields here, so we probably cannot just use the standard language...

The fields on most entities are used by content editors to set up things to display on the content pages, so when you create an entity item, you enter data in the fields, and that is what someone sees when they go to a page that displays the entity item.

The fields on most contact form modules (like contrib Webform) work differently: they are presented in a form that someone sees when they go to the Contact page.

I'm not sure which is the case for the new core Contact module. If it's "like other entities", then that will go against the expectation of people who want to build a custom contact form. If it's "like webform" then that will go against the expectation of how fields on other Core entities work. Whichever is correct, this help needs to explain it.

Also, another detail: check out the help guidelines -- the link to the online docs in About is not following our standard text/format.

@jhodgdon - Thanks for the feedback! The link to the online docs in About section is corrected.

After going through existing "Site-wide contact forms" section and newly introduced "Configuring contact forms" section by me, I felt that "Configuring contact forms" is more of repetition of "Site-wide contact forms" section. So I have removed this new "Configuring contact forms" help section.

Please suggest if you think differently.

Thanks, looking better!

A few things to fix:

a) Links to drupal.org should be https

b) All Uses points should start with a verb, like "Contacting users", not "User contact forms".

c) I think the help is missing a few things... I tested out the module to see how it is currently working, and I found the following:

1. We need to mention permissions:
- To see the tab for a user-contact form, a user needs "Use users' personal contact forms" and "View user profiles" permission (also the user has to have the personal contact form setting turned on). Although if they know the URL, and have permission, users can use the contact form without being able to view the user profile.
- There is also a permission for using the site-wide contact form.

2. I think the part about hiding email addresses in user contact forms is misleading. If user A is contacting user B, then user A does not see user B's email address, but user B will see user A's email address (at least, that is how it has always worked before; I didn't specifically test in D8).

3. I don't see any mention of how to customize the fields and form display for the personal or site-wide contact forms in the new help? There should be. And as I stated before, I think we want to stress that this is very different from how fields work on other entities. Here, if you add a field and make it visible in the Manage Form Display, this field will be displayed to people using the contact form -- it's not like adding fields to other entities. I have no idea what the Manage Display page does, but maybe it allows you to customize which fields are actually sent in the message? I really don't know, but we should figure that out and document it in the help.

d) In the page-specific help... that needs an update too, because when you go to that page, really what you are getting is the ability to configure both the personal and site-wide contact forms. And it needs to say what "categories" really are, because this is not obvious... also I added a category but I didn't see it appear in the contact form, so I really don't know how this works. We need to figure that out and document it. I'm pretty sure in 7 and previous versions, you got a drop-down list that let you select who you were contacting, but that isn't happening in 8, and since each category can have its own fields... I really don't know what it is supposed to do? I can apparently only select one to be the "default category", and then as far as I can tell, the other ones just go away. ?????

Maybe this is a separate bug? I really don't know.

One other thing. I believe that the Contact link in the Footer menu is only enabled automatically if you install with the Standard profile, so we should say something like "may be created by your installation profile" rather than saying it is "automatic".

PaBoden and I are taking a look at this while at DCon Austin sprints.
Kt

So looks like the missing category selection on the contact form is a bug - https://drupal.org/node/1997692

Ah, thanks for finding that!

Let's postpone this issue until that one is either fixed or abandoned, because someone may decide not to support categories at all? Who knows.

Sounds good. I'm adding the patch I made to address the other issues you had in #9 so we at least have those worked on and done.

tagging

The patch in #15 no longer applies since the text has been significantly modified by changes related to another issue (Issue #2285083). Somebody better informed than me may want to review the text and see if it's now satisfactory or still needs changes.

Here's the commit that made the change:

commit 093ea794426f426be0650a9a2c498ff63267e1ad
Author: Alex Pott <alex.a.pott@googlemail.com>
Date:   Sat Aug 16 12:57:44 2014 +0100

    Issue #2285083 by crowdcg, andypost, larowlan: Rename contact category to contact form.

We need to un-postpone this issue and get it done.

Instead of having one critical parent issue I have been asked to change the status of each child issue.

This one doesn't feel critical or major to me, because since the previous patches, the help has been updated quite a bit. But I think we need to start over and review the help and make a completely new patch at this point.

I have just reviewed the existing help for the Contact module and updated it in this patch. The previous patch was pretty old... I did not make an interdiff, because every line of the hook_help() function except the About and Uses headers has changed, so it's kind of pointless to make an interdiff file.

This patch fixes up the main Contact help at admin/help/contact as well as the top-of-page help on the admin/structure/contact page. If you apply the patch to a running install of Drupal 8, you'll need to clear the cache to see the change to the admin/structure/contact page help, because that will be in a cached block.

One other note: You have to be careful about making links from the Contact module help to pages provided by other modules -- you need to check that they're enabled. This patch takes care of that. It also changes all @url references in the help to !url.

Patch no longer applies.

Reroll.

Whoops. Some route names have changed. Reroll for that. Just the top three lines in contact_help() changed.

Thanks for the careful review -- and good idea. How about this change?

Docs are not frozen in beta. Committed 532ff0e and pushed to 8.0.x. Thanks!