Background:
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- review / write the hook_help text according to help guidelines

Comments

ifrik’s picture

See #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI
and the help text for Link module #2028799: Improve help for link module, for the default wording of modules that provide fields for fieldable entities.

About
The Foo module allows you to create fields that contain [something]. See the <a href="!field">Field module help</a> and the <a href="!field_ui">Field UI help</a> pages for general information on fields and how to create and manage them.
thijsvdanker’s picture

StatusFileSize
new4.75 KB
PASSED: [[SimpleTest]]: [MySQL] 58,926 pass(es).
[ View ]

Using https://drupal.org/node/2028799#comment-7894195 as a starting point, the patch:

  • updates urls to use the Drupal 8 url replacement
  • Changes the field description to match the link field (pointing to field and field_ui documentation).
thijsvdanker’s picture

Status:Active» Needs review
jhodgdon’s picture

Status:Needs review» Needs work

The copy/paste from the Link module needs to not say "link" in it. :)

Also, you might look at what is being done for the File module. I think the Image module help needs to say more specifics about the Image field settings and formatter settings than what is here?
#2031177: Improve help for file module

thijsvdanker’s picture

The copy/paste from the Link module needs to not say "link" in it. :)

You think? ;)
I'll go over it again tomorrow if no one beats me to it.

thijsvdanker’s picture

Status:Needs work» Needs review
StatusFileSize
new8.38 KB
PASSED: [[SimpleTest]]: [MySQL] 58,712 pass(es).
[ View ]

Update gives extensive information about the different settings and options for the image field.
I wanted to discuss if this is the right amount of information or too much? (some of the info comes from the description of the form item).

There is also an inconsistency with these form item descriptions, or is there a good reason why:

Enable Alt field
The alt attribute may be used by search engines..

Alt has a capital A in the first line, but not in the second?

Last but not least, this patch assumes that the system module will describe the file system, as discussed here: https://drupal.org/node/2031177#comment-7893741

Status:Needs review» Needs work

The last submitted patch, image-help-text-2091337-6.patch, failed testing.

thijsvdanker’s picture

Status:Needs work» Needs review

#6: image-help-text-2091337-6.patch queued for re-testing.

ifrik’s picture

Thanks @thijsvdanker for the patch.

You are right, the updated version gives too much detail. We had come across the problem of needing to explain all the field and display settings before, and came up with the solution of refering to the Field and Field UI help for all those issues that are the same for all modules that provide fields.
That's mainly what the two sentences are for that you've already included in your updated text: The one in the About section linking to Field and Field UI, and the second item under Uses. If you move that one up as first item, then you can concentrate on those options that are specific to the image module.

See the link module #2028799: Improve help for link module for comparison. That's committed to core, and should work as a template for other modules that provide fields.

And yes, the information about the file storage should go into the system help. However, while writing this comment, I noticed that I forgot to mention to link to the system module in the help text of the file module. I will just update that patch now with a wording that then could be used for the image module as well. https://drupal.org/node/2031177

ifrik’s picture

Status:Needs review» Needs work
ifrik’s picture

Issue summary:View changes
Status:Needs work» Needs review
StatusFileSize
new8.02 KB
PASSED: [[SimpleTest]]: [MySQL] 59,114 pass(es).
[ View ]
new12.01 KB

I've removed those uses that should be covered by the Field and Field UI help pages, and grouped the rest.

I've also filled a bug, because if the use of a Default image is chosen, there is no indication for users what's happening and where that image suddenly appears from. #2143653: Show default image on image field
The documentation for "Default image" is currently correct, but needs to changed, in case the functionality gets changed.

ifrik’s picture

I've just discovered that the image field has two settings for default image - one in the Field settings tab, and on in the instance settings "edit".
That looks rather confusing - and certainly needs changing in the documentation.

jhodgdon’s picture

RE #12 - that is just how field settings work in general. All of the settings in the Field Settings tab are also shown on the Edit tab, for fields -- or at least, that is how it has been in Drupal 7. In any case, it is not specific to the Image module. They are the same setting.

ifrik’s picture

I'm not quite sure whether this is a bug or a new functionality.

In D7, if I add an default image on the "Field settings" tab then that same image is also listed on the "Edit" tab in the "Field settings" section. If I re-use that field then it shows the same image in both places as well.

However, in my current D8 installation, I can add a default image on the "Field settings" tab - and it does not show up on the "Edit" tab. Instead I can either leave the default image on the edit tab blank (then it displays the one from the field settings tab with new content) - or I can add a second default image that is then displayed.
If I re-use the image field then it takes default image on the Field settings page, but not the one on the Edit page.

Any idea? If it's a bug then I'll file it - but if it's a new functionality then I re-write the help text

jhodgdon’s picture

Ugh. That is at least a usability bug. Yes, please file an issue and explain just what you did in comment #14 -- that is very very confusing.

ifrik’s picture

There is an issue for it... looks like there is unclarity what the functionality should be.
So we need to wait for that to be solved.

jhodgdon’s picture

Component:documentation» image.module
Status:Needs review» Postponed

I'm postponing this issue until the UI issue is resolved. If you can find that issue, can you link it here as "related"? Also moving this to the image module component since it seems like we need the maintainers to weigh in on what the intended UI behavior is so we can document it in the help.

ifrik’s picture

jhodgdon’s picture

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.

amitgoyal’s picture

StatusFileSize
new8 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 75,687 pass(es).
[ View ]

@jhodgdon - The hook_help was already as per #2183113: Update hook_help signature to use route_name instead of path.

But it was not getting applied in current core code so I have made the required changes in the patch. Please review attached patch.

jhodgdon’s picture

Status:Postponed» Active

This issue probably needs to get back to "active" status. Can someone check and see if the UI problem with default images (see comment #12 and #14) has been resolved? Can we write coherent help for this module now?

ifrik’s picture

There is a patch for this module. Once that's committed I can finish this help text.

ifrik’s picture

Status:Active» Reviewed & tested by the community

Sorry, I commented on the wrong issue.

ifrik’s picture

Status:Reviewed & tested by the community» Needs work
batigolix’s picture

Issue tags:+documentation, +sprint
jhodgdon’s picture

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

I don't think that this issue is critical or major, so leaving it as Normal. But we still need to do this.

Looking at the latest patch it seems to have replaced mentions of the Image module with the File module. That wasn't right... so I think we need to start over with the current Image module hook_help, and review that with the current Image module functionality and go from there.

jhodgdon’s picture

Status:Needs work» Needs review
StatusFileSize
new9.09 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 83,937 pass(es).
[ View ]

So... The latest patch here didn't apply any more, and anyway it seems to be changing the Image module help to be File module help. So we definitely do not want that patch. The patch on #11 looks much the same.

So I went back to the starting point of the help currently in the Image module, and sort of applied the patch by hand, keeping some existing sections of help that had been added on other issues. Then I made additional edits to clarify, make more concise, copy edit, and organize the page.

A few notes:

a) I looked into the problem discussed above about default images. That is #1999232: Default image upload on edit and field settings tab is confusing and while I don't think the UI is great, I think that can be pretty easily fixed on the other issue so I don't think we should hold this up.

b) In help you have to be careful about making links to pages that depend on other modules. Image depends on File, which depends on Field, but they don't depend on Field UI. So that link has to be done a bit carefully.

c) I was going to make sure we talked about image toolkits, since that was part of the help at some point for this module. However, I realized that this is part of the System module, so I added a note to #2091363: Update hook_help for System module about this instead.

Anyway... here's a patch!

ifrik’s picture

Status:Needs review» Needs work

Thanks, just some small changes.

In the about section: should it be "create fields that contain image files" instead of "create entity fields"?

Some small language changes:
in Defining image styles
Making it even clearer that you only need to upload one image
"The concept of image styles is that you can upload a single image but display it in several ways. Each display variation ..."

in Configuring image field file storage
".... shown on the File system settings page." This should be "shown on the File system page." as that's the title of the page.

----------------------

I've checked the default image again, and both images can be changed later.

Providing default images
You can provide a default image that will be displayed if no other image is upload (for example if a user does not upload a profile picture). You can provide a default image for all instances of this image field in the field storage settings when you create a field. You can also add a default image for an entity sub-type which will override the one set in the field settings. Both images can be removed or changed later.

jhodgdon’s picture

Status:Needs work» Needs review
StatusFileSize
new8.85 KB
new8.93 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 83,989 pass(es).
[ View ]

Thanks for the great review! Here's a new patch. I pretty much adopted what you suggested, hopefully making it even a little clearer and more concise. In the last bit, I don't really even think we need to mention whether/when it can be changed. Thoughts?

ifrik’s picture

Looks good to me. Should I RTBC it, or do we wait for somebody else to do that?

jhodgdon’s picture

Please do! Two people agreeing that the Help page looks good should be enough. ;)

theMusician’s picture

Status:Needs review» Needs work
StatusFileSize
new125.5 KB

This is so much better. New users might actually be able to make sense of image styles.

I noticed within a section of the definition list paragraph tags are being used within the dt tag causing inconsistent formatting. I'll roll an updated patch with multiple dd tags in place of the p tags. I know p tags can be used within dt tags, this is one reference, http://reference.sitepoint.com/html/dd, but multiple dd tags are also allowed and will keep everything looking the same.

theMusician’s picture

Status:Needs work» Needs review
StatusFileSize
new8.93 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 83,999 pass(es).
[ View ]

Here is the updated patch.

genjohnson’s picture

StatusFileSize
new7.95 KB
new8.92 KB
FAILED: [[SimpleTest]]: [PHP 5.4 MySQL] Unable to apply patch 2091337-36.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

The spacing changes in #35 look good to me. I've removed a few unnecessary commas.

Status:Needs review» Needs work

The last submitted patch, 36: 2091337-36.patch, failed testing.

genjohnson’s picture

Status:Needs work» Needs review
StatusFileSize
new8.92 KB
FAILED: [[SimpleTest]]: [PHP 5.4 MySQL] Unable to apply patch 2091337-37.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

Let's try this again.

Status:Needs review» Needs work

The last submitted patch, 38: 2091337-37.patch, failed testing.

genjohnson’s picture

Status:Needs work» Needs review
StatusFileSize
new8.92 KB
FAILED: [[SimpleTest]]: [PHP 5.4 MySQL] Unable to apply patch 2091337-38.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

One last try.

ifrik’s picture

Status:Needs review» Needs work

genjohnson, could you make an interdiff so that we can see which changes you made?

See https://www.drupal.org/node/1488712 and https://www.drupal.org/patch on more information on how to do that.

genjohnson’s picture

Status:Needs work» Needs review
StatusFileSize
new7.95 KB

I was having end-of-file whitespace issues with those patch attempts because I had some cruft that didn't belong in the patches I was trying to remove by hand, but the interdiff from comment #36 should still be good for the changes between the patch in #35 and the patch in #40.

To be clear, here's an interdiff between the patch in #35 and the patch in #40.

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Great! I think several people have now agreed that the text in this help is good, and I like the cosmetic and comma changes since my last patch, so I'll go ahead and mark this RTBC. Thanks everyone!

Status:Reviewed & tested by the community» Needs work

The last submitted patch, 40: 2091337-38.patch, failed testing.

jhodgdon’s picture

Whoops, guess we need a rerolle here.

genjohnson’s picture

StatusFileSize
new8.94 KB
FAILED: [[SimpleTest]]: [PHP 5.4 MySQL] 84,512 pass(es), 45 fail(s), and 0 exception(s).
[ View ]

Reroll of #40.

genjohnson’s picture

Status:Needs work» Needs review

Status:Needs review» Needs work

The last submitted patch, 46: 2091337-46.patch, failed testing.

genjohnson’s picture

Status:Needs work» Needs review
StatusFileSize
new8.97 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 85,215 pass(es).
[ View ]
new4.55 KB

I don't understand enough about the tests for the test logs to make much sense, so I asked about the test failures in IRC and mikeker pointed out that the route image.style_list was recently changed to entity.image_style.collection in commit 3d14a7d25ac370a4616d095ade2f2d87de40b3b2.

This patch attempt is the same as the patch in #46 with image.style_list changed to entity.image_style.collection.

genjohnson’s picture

Finally a patch that passes tests :)

jhodgdon’s picture

Status:Needs review» Reviewed & tested by the community

Thanks! The reroll and URL route fix look good to me. Back to RTBC.

alexpott’s picture

Here is a paste of the text as it actually appears for simpler review:

About

The Image module allows you to create fields that contain image files and to configure Image styles that can be used to manipulate the display of images. See the Field module help and the Field UI help pages for terminology and general information on entities, fields, and how to create and manage fields. For more information, see the online documentation for the Image module.

Uses

Defining image styles
The concept of image styles is that you can upload a single image but display it in several ways; each display variation, or image style, is the result of applying one or more effects to the original image. As an example, you might upload a high-resolution image with a 4:3 aspect ratio, and display it scaled down, square cropped, or black-and-white (or any combination of these effects). The Image module provides a way to do this efficiently: you configure an image style with the desired effects on the Image styles page, and the first time a particular image is requested in that style, the effects are applied. The resulting image is saved, and the next time that same style is requested, the saved image is retrieved without the need to recalculate the effects. Drupal core provides several effects that you can use to define styles; others may be provided by contributed modules.
Naming image styles
When you define an image style, you will need to choose a displayed name and a machine name. The displayed name is shown in administrative pages, and the machine name is used to generate the URL for accessing an image processed in that style. There are two common approaches to naming image styles: either based on the effects being applied (for example, Square 85x85), or based on where you plan to use it (for example, Profile picture).
Configuring image fields
A few of the settings for image fields are defined once when you create the field and cannot be changed later; these include the choice of public or private file storage and the number of images that can be stored in the field. The rest of the settings can be edited later; these settings include the field label, help text, allowed file extensions, image resolution restrictions, and the subdirectory with the public or private file storage where the images will be stored. The editable settings can also have different values for different entity sub-types; for instance, if your image field is used on both Page and Article content types, you can store the files in a different subdirectory for the two content types.
Configuring image fields for accessibility
For accessibility and search engine optimization, all images that convey meaning on web sites should have alternate text. Drupal also allows entry of title text for images, but it can lead to confusion for screen reader users and its use is not recommended. Image fields can be configured so that alternate and title text fields are enabled or disabled; if enabled, the fields can be set to be required. The recommended setting is to enable and require alternate text and disable title text.
Configuring image field file storage
When you create an image field, you will need to choose whether the uploaded images will be stored in the public or private file directory defined in your settings.php file and shown on the File system page. This choice cannot be changed later. You can also configure your field to store files in a subdirectory of the public or private directory; this setting can be changed later and can be different for each entity sub-type using the field. For more information on file storage, see the System module help page.
The maximum file size that can be uploaded is limited by PHP settings of the server, but you can restrict it further by configuring a Maximum upload size in the field settings (this setting can be changed later). The maximum file size, either from PHP server settings or field configuration, is automatically displayed to users in the help text of the image field.
You can also configure a minimum and/or maximum resolution for uploaded images. Images that are too small will be rejected. Images that are to large will be resized. During the resizing the EXIF data in the image will be lost.
Configuring default images for image fields
You can configure a default image that will be used if no image is uploaded in an image field. This default can be defined for all instances of the field in the field storage settings when you create a field, and the setting can be overridden for each entity sub-type that uses the field.
Configuring image field behavior
On the Manage display page, you can choose the image style used to display the image in each display mode and whether or not to display the image as a link. On the Manage form display page, you can choose the preview image style shown on the entity edit form.
alexpott’s picture

Status:Reviewed & tested by the community» Needs work

It seems to me that the "Configuring image fields" and "Configuring image field file storage" should be merged - since the user can not do one without the other through the UI. Also "Configuring image fields for accessibility", "Configuring default images for image fields" and "Configuring image field behavior" are to me all subsets of configuring image fields.

and the subdirectory with the public or private file storage - I think this should be subdirectory in the

jhodgdon’s picture

Status:Needs work» Needs review
StatusFileSize
new8.9 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 86,897 pass(es).
[ View ]
new6.22 KB

Thanks, good suggestions!

In other hook_help text, we've separated out the field settings from the display/form display settings (they're on a different page, after all), so I went ahead and left that "Behavior" section as a separate section. But I did retitle it to be more consistent with the other pages, and use the terms formatter and widget as we do in the other help.

I also took out all the headers for the other "configure" sections, so basically we have one header and a bunch of paragraphs (technically DD sections) within it. I added an "also" here and there, nad fixed the "with" to "in" the subdirectory problem.

So, here's a new patch and an interdiff. Can someone please review? Thanks!

no_angel queued 54: 2091337-54.patch for re-testing.

no_angel’s picture

I tested the "admin>help>image on simpletest

+ tested all links on page [no problems encountered]

+ added new image style with long title name
+ added new image style with short title name

jhodgdon’s picture

OK. I'm not sure why you tested those pages on this issue, but fine. So can someone please review the help and mark this RTBC if it's OK, or Needs Work (with a comment) if not? Thanks!

no_angel’s picture

StatusFileSize
new147 KB

Confirmed Update hook_help for Image module.

Changing to RTBC

no_angel’s picture

Issue summary:View changes
Status:Needs review» Reviewed & tested by the community
alexpott’s picture

Status:Reviewed & tested by the community» Fixed

Documentation is not frozen in beta. Committed 61eae01 and pushed to 8.0.x. Thanks!

  • alexpott committed 61eae01 on 8.0.x
    Issue #2091337 by genjohnson, no_angel, jhodgdon, ifrik, thijsvdanker,...

Status:Fixed» Closed (fixed)

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