Help File Fixup: File module

What content do you think it needs?

It does need capitalization attention though...

Here's a patch with more content and fixed caps.

One minor capitalization change.

Let's get this one in...

Hm. This feels over-the-top on developer-speak for the target audience for this page, and also makes file out of sync with list, text, etc. modules.

I would just fix this myself, but unfortunately, this patch no longer applies. So could someone please re-roll it and remove the bit about "The File module defines a managed_file Form API field (for Drupal module developers)"?

Ok, I hate to interrupt the stream of green with one pink outlier, but in looking at this again prior to commit, I discovered that that the help text isn't overly helpful. :)

"The File module defines a File field type for the Field module"

Well.... yes. I could probably infer that by reading its title. ;) But what does it do?

There are a few interesting things about File module, esp. now that Upload module is obliterated:

1. It allows you to choose whether the files uploaded by the field go into the public or private file downloads folder (which might be a good place to explain that there is a public and private file downloads folder). It also allows you to specify a path within that folder to place all files uploaded with that field.

2. It allows you to add some basic validation: specify a list of allowed file extensions, as well as a maximum size.

3. You can choose whether files are listed directly on the page or not, and also give the user a choice on a per-file basis (for example, a PDF file might make sense to be listed at the bottom, where a thumbnail image linking to the PDF would not, since users wouldn't be downloading the thumbnail image, and you'd throw some HTML in the node body to format it the way you'd want).

Then there's also the question of how this fits with #645776: Help File Fixup: field. The trend there is for each field to basically have a sentence about it, and refer back to Field module for an explanation of how it works. So if this one goes bananas itemizing every last thing it can do, we should also do that for the others for completeness.

I initially tried to write a description for File module based on Number module in the other patch (since I really really didn't want to have to mark this down to code needs work on you...):

"The File module defines a file upload field for the Field module. File fields may be limited to a set of allowed file extensions, and configured to upload files to a specific location in either the private or public files directory."

Something like that might be sufficient, and it would match the rest of the fields. But if so, we should remove the "Uses" section here (or maybe remove it anyway, since it's describing generic stuff that's true of all fields).

So... Um... something needs to happen here. :) I'm not quite sure what. I kick it back to you, oh faithful docs team, for a decision.

I don't personally think it is a problem that some field modules can be explained in one or two sentences and some have more information. That is true of our module help in general: we document what we think is important to document, in the most concise manner possible, right? :) I'm not sure that the other field modules (except for image and taxonomy) are interesting enough to have more than one line about them. If they are, I agree we should put more in their help. Image and taxonomy already have more than one line, because they are interesting.

So here's a stab at a more complete explanation for the File module. Definitely could use a review.

Curious.. this hunk:

To do this, visit the <a href="@content-types">Content types administration</a> page, and click on the <em>manage fields</em> link for your content type. Add a field of type <em>File</em>, and set up your desired validation options (maximum file size and allowed extensions).', array('@content-types' => url('admin/structure/types'))) . '</dd>';
+      $output .= '<dt>' . t('Managing attachment display') . '</dt>';

Doesn't it seem like a generic version of that belongs in Field UI module (if it's not there already), rather than spelling it out here?

Other than that, this looks good to me! Though would love for Julia, Boris, or Lisa to take a look.

You are right, we probably don't need to explain how to use the Field UI module here. Will re-patch.

OK... I added a link from Field UI help to Field help (which will be much better if that patch ever goes in), and fixed a typo in the Field UI help file generation (one of the t() parameters was missing @ in its definition). I do think Field UI explains well enough how to attach fields, or at least points you to the screens.

And took that bit out of the File module help.

Still needs a review.

- I'm OK with "either".
- I'm OK with "anyone who knows the file URL..." [note: should be knows not know]
- Regarding overhead... what happens is that instead of the browser just sending a request for the file and getting it directly from Apache, a request is sent to a Drupal path, so Drupal has to load (with all its modules, includes, etc.), resolve the path, check permissions, read the file in, and then send it to Apache to send to the browser.

Besides adding to the server load, the request will be slower for the user.

We should probably change the status while this is debated. :)

OK, here's a new version of the patch, with above comments (hopefully) addressed. The section on managing files is now:

When you create a File field, you can specify a directory where the files will be stored, which can be within either the public or private files directory. Files in the public directory can be accessed directly through the web server; when public files are listed, direct links to the files are used, and anyone who knows a file's URL can download the file. Files in the private directory are not accessible directly through the web server; when private files are listed, the links are Drupal path requests. This adds to server load and download time, since Drupal must start up and resolve the path for each file download request, but allows for access restrictions.

Thoughts?

Typo: doc header should say "Implements hook_help()." not Implement.

Gracious. Try this one. Sigh.

Committed to HEAD! Thanks!