Provide documentation on making menu tabs

If you want this added to docs for hook_menu(), then it is an API doc issue, and needs to be in the proper queue.

Also, the procedure for API doc issues is to patch in 7.x, and then if appropriate, back-port to 6.x.

I'll patch this, but I want to wait until #382834: hook_menu API docs missing some elements gets committed (it's in RTBC status now). Reason for waiting is that the patch there is on the hook_menu() doc as well, and it's an extensive update.

That above issue's patch got committed to Drupal 7, so OK to work on this one now. I'll get to it next week. If someone wants to do it before then, just assign this issue to yourself and have fun. :)

Here's a Drupal 7 patch. If committed, should probably also be ported to Drupal 6.

Committed to CVS HEAD. Thanks.

Needs port to D6. Possibly combine with port of #382834: hook_menu API docs missing some elements, which is another recent hook_menu() doc update.

+ * $items['admin/config/foo/global'] = array(
+ * 'title' => 'Global settings',
+ * 'type' => MENU_DEFAULT_LOCAL_TASK,
+ * // page callback, etc. need to be added here
+ * );

For default local tasks, they *don't* have to provide all the callback and access details. They're automatically inherited from the parent admin/config/foo in this example. They could be provided, but not necessary.

Is *everything* inherited, so all you need to provide is the title and type?

Correct. For example see admin/appearance/settings/global in system_menu()

Looked in the code to answer question in #9... It looks like the following are inherited from the parent if not specified, only for default local tasks, in _menu_router_build():

access callback
access arguments
page callback
page arguments
file *
file path *
theme callback
theme argument

* Note that file and file path are only checked if page callback is being inherited... Actually, looking at the code, it looks like the file and file path components of menu router items are only loaded after access is checked, path args are auto-loaded, etc. So we should probably document that file/file path only apply to page callback.

Is that correct, or did I miss something? The doc currently implies that file and file path apply to other callbacks (though it specifically mentions now that it doesn't apply to the access callback)... maybe they would work with theme and block callbacks, but I'm not sure?

OK, I did some more research.

Here is a list of everything that might be called a "callback" on the menu router item:

title callback
page callback
access callback
theme callback
block callback
loader functions

The only one that the file / file path is actually used for, as far as I can tell, is page callback.

Reasoning:

- The include file defined by file/file path is loaded in menu_execute_active_handler(), after menu_get_item() is complete, and just before the page callback function is called.
- The following callbacks are used in _menu_translate (or functions it calls). Note that _menu_translate() is called from menu_get_item (i.e. before the include file is loaded): access, loader functions, title
- The block callback is used in system_main_admin_page() and system_admin_config_page() - does not load the include file as far as I can see.

Theme callback - a bit more complex, let's see. It is used in menu_set_custom_theme(), which is called from _drupal_bootstrap_full(), right before module_invoke_all('init') is called. And menu_execute_active_handler() is called from Drupal's main index.php file, after bootstrap. So I gather that theme callback is also before the include file is included.

So we need to patch the doc for hook_menu() to reflect:

a) file/file path only apply to page callback
b) inheritance as in comment #8 above

I'll make a patch in a couple of hours.

subscribing

Here's a cleanup patch for hook_menu() to reflect:

a) file/file path only apply to page callback
b) inheritance as in comment #8 above

Plus some other cleanup, clarifications, etc.

If this patch is accepted (and it should be reviewed before committing!), then I propose taking this as the D6 doc for hook_menu(). Though any references to the theme callback and theme arguments need to be removed from the D6 version (those were added in D7).

We should not document this before #296693: Restrict access to empty top level administration pages is not fixed.

Damn, I meant the patch in #5, which was already committed. :(

Any comments on this cleanup patch?

I'm going to incorporate this cleanup patch into #617424: Error in hook_menu documentation for load arguments, so marking this now as fixed, since the original patch was applied.