See #202404: Put link to Forms API Reference in Form Generation.

Basically, in core we link to the Form API reference on api.drupal.org. It'd be nice if it could tell we were coming from form.inc/7 and automatically fix the link to form_reference.html/7.

Files: 
CommentFileSizeAuthor
#43 699604-forms-api-reference-link-d6-backport-43.patch617 bytescam8001
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#42 forms_api_reference_link-699604-42.patch626 bytesAlbert Volkman
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#36 699604-forms-api-reference-link-d6-backport.patch607 bytescam8001
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]
#32 69604-forms-api-reference-link-d7-backport.patch4.11 KBcam8001
PASSED: [[SimpleTest]]: [MySQL] 39,398 pass(es).
[ View ]
#18 forms_api_reference-D8-699604-15.patch3.54 KBnmudgal
PASSED: [[SimpleTest]]: [MySQL] 35,930 pass(es).
[ View ]
#12 forms_api_reference-D8-699604-11.patch3.53 KBnmudgal
PASSED: [[SimpleTest]]: [MySQL] 35,659 pass(es).
[ View ]
#10 forms_api_reference-D8-699604-6.patch3.48 KBnmudgal
PASSED: [[SimpleTest]]: [MySQL] 35,645 pass(es).
[ View ]
#7 forms_api_reference-D8-699604-5.patch836 bytesnmudgal
PASSED: [[SimpleTest]]: [MySQL] 35,661 pass(es).
[ View ]
#3 forms_api_reference-D7-699604-1.patch731 bytesnmudgal
PASSED: [[SimpleTest]]: [MySQL] 38,490 pass(es).
[ View ]
#2 forms_api_reference-D8-699604-1.patch751 bytesnmudgal
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch forms_api_reference-D8-699604-1.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

Comments

Title:Inspect referrer and automatically fix version number for linksUse file name rather than full URL for links to Form API Reference page
Project:API» Drupal core
Version:6.x-1.x-dev» 8.x-dev
Component:Code» documentation
Category:feature» task
Issue tags:+needs backport to D6, +Novice, +needs backport to D7

Actually, what we should be doing here is just using the bare file name for the link, instead of the full URL. That should turn into the proper link with the right version suffix. So, we have in includes/form.inc currently:

  * workflow, see the
  * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink

It should just say
* workflow, see forms_api_reference.html

(without the @link stuff). I realize that this will not be quite as friendly, since it won't have the link title... so I guess it could say:
  * workflow, see the Form API reference (forms_api_reference.html)

(may need some line re-wrapping after that).

Should be a good Novice task. Should be backported to D7 and 6 as well. If there is any other existing full URL link in the code to the same URL in the code, that should be fixed too. And I also noticed that on the Drupal 6/7/8 landing pages on api.drupal.org, the link to Form API reference is broken there, so that needs to be fixed too (but that is in the Documentation repository, so let's get this other stuff fixed first).

And as a note to self: When a patch is submitted here, I should test it out on my API test site and verify that the links work.

StatusFileSize
new751 bytes
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch forms_api_reference-D8-699604-1.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

Could not find any other link in file.
Patch is attached after removing @link & just putting filename as mentioned.

Thanks

Version:8.x-dev» 7.x-dev
StatusFileSize
new731 bytes
PASSED: [[SimpleTest]]: [MySQL] 38,490 pass(es).
[ View ]

For D7.

Status:Active» Needs review

Version:7.x-dev» 8.x-dev
Status:Needs review» Needs work

Please leave this at 8.x until we get a good patch for 8.x committed. Then we can worry about the D7 port. Thanks!

So regarding the patch in #2, aside from the fact that the testbot can't apply it (not sure why):

+ * workflow, see the Form API reference (forms_api_reference.html)
  * and the

Probably this "and the" can be moved up to the previous line?

Also, there are some other links. A quick grep found:

includes/ajax.inc: *   @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7 Form API Reference @endlink
includes/form.inc: * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink
includes/form.inc: *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
modules/field/field.api.php: * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API @endlink

StatusFileSize
new836 bytes
PASSED: [[SimpleTest]]: [MySQL] 35,661 pass(es).
[ View ]

yes that's what I was wondering why bot is checking against version-7.
Update patch.

Status:Needs work» Needs review

review.

Status:Needs review» Needs work

still needs to fix the other links in #6

Status:Needs work» Needs review
StatusFileSize
new3.48 KB
PASSED: [[SimpleTest]]: [MySQL] 35,645 pass(es).
[ View ]

Updated as in #6, please review.

Thanks

Status:Needs review» Needs work

Thanks!

This one needs some thought:

@@ -214,10 +212,9 @@ function drupal_get_form($form_id) {
  *     set.
  *   - values: An associative array of values submitted to the form. The
  *     validation functions and submit functions use this array for nearly all
- *     their decision making. (Note that
- *     @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
- *     determines whether the values are a flat array or an array whose
- *     structure parallels the $form array.)
+ *     their decision making. (Note that the Form API reference
+ *     (forms_api_reference.html) determines whether the values are a flat
+ *     array or an array whose structure parallels the $form array.)

The original reads "Note that #tree determines whether...". With your patch, it would now read "Note that the Form API reference () determines ...". That doesn't make much sense. Probably it needs to say:

Note that #tree determines whether the values are... See the Form API reference (filename) for more information.

This one also needs some similar attention:

@@ -667,11 +667,10 @@ function hook_field_is_empty($item, $field) {
  * which widget to use. Widget types are defined by implementing
  * hook_field_widget_info().
  *
- * Widgets are
- * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API @endlink
- * elements with additional processing capabilities. Widget hooks are typically
- * called by the Field Attach API during the creation of the field form
- * structure with field_attach_form().
+ * Widgets are, see the Form API reference (forms_api_reference.html) elements

StatusFileSize
new3.53 KB
PASSED: [[SimpleTest]]: [MySQL] 35,659 pass(es).
[ View ]

Updated according to #11.

Thanks.

Status:Needs work» Needs review

If that patch is good to go, I would be working on d7 one?

Thanks

Status:Needs review» Postponed

On D8/7 and when to work on the next patch - please see http://drupal.org/node/1488414#comment-5748422

Meanwhile... This patch is much closer, thanks! A few little items:

a) In the ajax.inc part of the patch, the new sentence needs a . at the end.
b) The form.inc section looks good.
c) In the field.api.php section, the original said "Widgets are Form API elements...". Let's keep that text.

Actually... I just tested this in my test version of the api.drupal.org site. Sigh. These links will not work anyway unless we do something different in the API module. Back to the drawing board... Sorry to send everyone on a wild chase to fix this.

API issue to support this:
#1489000: Need a way to make a reliable link to an HTML file
When that is resolved, we can come back here and fix the links. Until then, it's a bit pointless.

Status:Postponed» Needs work

That issue is now resolved, and the new code is on api.drupal.org. So it's time to go back and fix this. See comments in #15 (a-c).

Status:Needs work» Needs review
StatusFileSize
new3.54 KB
PASSED: [[SimpleTest]]: [MySQL] 35,930 pass(es).
[ View ]

Updated according to #15.

So... I actually just fixed up the API module so that we can do any of the following:
.... filename.html ...
.... (filename.html) ...
.... @link filename.html Link text @endlink
That software fix should be deployed on api.drupal.org in a day or two (actually maybe later today).

Do you think that @link would be better than what we're doing now in this patch (which is using () around the filename)? That is, we can take

@link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7 Form API Reference @endlink

and change it to
@link forms_api_reference.html Form API Reference @endlink

Thoughts?

What about using markdown link syntax? Something like

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Robin: Sorry, that is not going to happen. We are using @ tags. This is just a small refinement of what we already have, and we're not going to completely change it at this point.

+1 for this as this documentation is always meant to be for devs & it looks more decent rather than putting (see for more information ... thing)

@link forms_api_reference.html Form API Reference @endlink

But where to find forms_api_reference.html ??

@droplet
It would link to http://api.drupal.org/api/drupal/developer%21topics%21forms_api_referenc... as discussed in #15, #16, #19

@nmudgal,

API module will do this job but your IDE won't. so How to find it quickly? Google?

if no links, it maybe better..

@link API SITE: forms_api_reference.html Form API Reference @endlink

As I said in #22, it is intended for devs & they already know where to find FAPI reference, so think it is sufficient. But #26 sounds ok to me too.

I would rather see @link forms_api_reference.html Form API Reference @endlink as it stands out better.

#26 will not work with the API module.

Our choices are either #28 or the most recent patch.

Status:Needs review» Needs work

I see several votes (mine too) for #28. Let's get a new patch.

Version:8.x-dev» 7.x-dev
Status:Needs work» Patch (to be ported)

This looks like it was resolved with this issue-

http://drupal.org/node/1552412

Moving this back to 7.x.

Status:Patch (to be ported)» Needs review
StatusFileSize
new4.11 KB
PASSED: [[SimpleTest]]: [MySQL] 39,398 pass(es).
[ View ]

Here's a backport to D7. Note that I had to change the 'values' comment for drupal_get_form() to make sense in context - hope this is ok and not too much like scope creep.

Status:Needs review» Reviewed & tested by the community

Looks good, thanks! I'll get it committed shortly.

Status:Reviewed & tested by the community» Fixed

Committed to 7.x. Thanks!

Version:7.x-dev» 6.x-dev
Status:Fixed» Patch (to be ported)

No love for D6? :)

Assigned:Unassigned» cam8001
Status:Patch (to be ported)» Needs review
StatusFileSize
new607 bytes
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

One love, always :D

Status:Needs review» Needs work

- * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink
- * and the @link http://drupal.org/node/204270 Form API guide. @endlink
+ * @link forms_api_reference.html @endlink and the
+ * @link http://drupal.org/node/204270 Form API guide. @endlink

The first link is missing the link text (which in the original says "reference".

And is this really the only place in all of the D6 source where forms_api_reference.html appears?

Status:Needs review» Needs work

Ok. You're right too, I found another reference:

<?php
    $output
.= '<li>'. t('<code>register_globals</code> is <strong>turned off</strong>. If you need to use forms, understand and use the functions in <a href="@formapi">the Drupal Form API</a>.', array('@formapi' => url('http://api.drupal.org/api/group/form_api/6'))) .'</li>';
?>

No, that is a reference to http://api.drupal.org/api/group/form_api/6 -- which is a different page.

[6.x] $ grep -rI 'forms_api_reference' .
./includes/form.inc: * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink

That's all I found.

OK, good! Then let's get that one fixed correctly (see #37). :)

Status:Needs work» Needs review
StatusFileSize
new626 bytes
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

Done.

StatusFileSize
new617 bytes
PASSED: [[SimpleTest]]: [MySQL] 190 pass(es).
[ View ]

+++ b/includes/form.incundefined
@@ -41,8 +41,8 @@
- * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 reference @endlink
- * and the @link http://drupal.org/node/204270 Form API guide. @endlink
+ * @link forms_api_reference.html Form API Reference @endlink and the
+ * @link http://drupal.org/node/204270 Form API guide. @endlink

Should this be "reference" instead of "Form API Reference"? That's how it was previously.

Also, apologies for my sloppy comment above, I was interrupted on my way out the door and probably shouldn't have clicked "Save".

Status:Needs work» Needs review

Status:Needs review» Reviewed & tested by the community

Thanks -- the patch in #43 looks good.

Assigned:cam8001» Unassigned
Status:Reviewed & tested by the community» Fixed

Thanks! At long last, committed to 6.x.

Status:Fixed» Closed (fixed)
Issue tags:-needs backport to D6, -Novice, -needs backport to D7

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