GHOP #125: Document D6 menu placeholders

The Drupal menu system was totally rewritten for Drupal 6.x. One of the new features is menu placeholders/wildcards. These are important because they allow Drupal to automatically load one or more objects for the page callback based on the hook_menu definition.

This task involves documenting these new D6 menu placeholders. They look like %user, %node, %current_user, etc. Such documentation will be an important reference for those writing Drupal 6.x modules.

For this task you do not need a complete understanding of how the Drupal 6.x menu system works - however, you will need to acquire a basic familiarity.

The requirements of the task are to:

1) Read this page and its sub-pages: http://drupal.org/node/102338
2) Create a new documentation page as a child of this page: http://drupal.org/node/102338
3) Explain how a module developer would use an existing placeholder, and how they would define their own (e.g. how they define a load function, and what types of error checking the load function should do).
4) Examine all the hook_menu functions in core to find every placeholder and corresponding load function
5) Document each placeholder and which core modules use it
6) Include a link to each load function's api.drupal.org page
7) Paste a code block showing for each placeholder one use in a core hook_menu implementation (include a note about which module it's from)

Regarding step 2:
I assume the person who does the task would need to join the documentation group in order to create the page. How would they go about this? I'm also not sure if a new page is required, as the information could be put into the existing children "Wildcard, ancestors and fitness" and "Dynamic arguments replacement".

@corsix - unless the permissions have changed, any registered user can create a page in the handbook. However, it would probably be worth developing the page in the Documentation queue before actually posting it.

submitted as a GHOP task: http://code.google.com/p/google-highly-open-participation-drupal/issues/...

Whoever claims the task should follow up to this Drupal issue.

Initial draft of the page: http://drupal.org/node/209056
Codefilter is currently turned off for d.o though, so the code blocks are not nice.

It's a good start, bu looks like you are missing this piece: "Explain how a module developer would use an existing placeholder"

As part of this, it would be good to have a very brief overview of the whole scheme.

I would also move the part on how to define your own placeholder/wildcard to closer to the top of the page and also the bu on error checking needs to be more thorough. Cross reference this page or others in that section as appropriate: http://drupal.org/node/101495

And also repeat some of the general guidelines: know what type of input you expect, validate it, and escape it in any queries.

Updated the page with a brief overview of wildcards and using them, extended the example of defining your own to reinforce the error checking part, and replaced the php blocks with plain HTML code tags so that the code is at least monospaced until codefilter is turned back on.

It's almost done, but a few minor content/style suggestions:

1. Page title something more like "Wildcard usage and available wildcards from core"
2. At the beginning, the first sentence sounds a little awkward:

   "Under Drupal 5, if you wanted to define a menu wildcard "

   maybe something like:

   "With Drupal 5, if you wanted to define a dynamic menu path (...) then you would have to check the $no_cache flag in your hook_menu implementation and then check the each piece of the path using arg()"

3. There are some minor punctuation problems - check for periods, etc.
4. I think the lists of modules using each would be clearer if changed from a style like:

   "poll, comment, translation, statistics, node, book from D6 core"

   to something like:

   Poll, Comment, Translation, Statistics, Node, and Book modules from D6 core

5. this sentence should be expanded a little:

   "Even though part 3 of the path is not a wildcard, it can still be inserted into the arguments array"

   to something like:

   Even though part 3 of the path is not a wildcard, it can still be inserted into the arguments array, and will result in the string 'edit' being passed as a parameter to the callback function.

Made aforementioned changes. Also attached is the script which mines the modules folder looking for wildcards.

Changed http://drupal.org/node/209056 to use php blocks again, now that codefilter is turned back on.

There is already http://drupal.org/node/109153 which , I believe needs to be married somehow with this page. At least link ? And / or remove duplicated information ...?

I've gone with the link option, as the duplicated information was added for "3) Explain how a module developer would use an existing placeholder" (unless there is content in the other two sections which you feel is repeated?).

@chx - I should have looked a bit more at that other page, but I think the two are complementary for the most part.

Perhaps they should be retitled - something like:

Dynamic arguments - overview and theory
http://drupal.org/node/109153

Wildcard: intro to usage and core load functions
http://drupal.org/node/209056

@Corsix - aside from these, chx pointed out to me some terminology to be cleaned up

%your_wildcard_name <= the only wildcard here is the percent sign.

So % is the wildcard (it can be on its own, as in the taxonomy module), while the rest specifies the load function

mention why we use %user_current and not %user

not a full explanation, just mention it and link to the other page using this (new) anchor: http://drupal.org/node/109153#to_arg

$map is not documented at all

mention additional possible load function arguments (map, index) and link to them using this (new) anchor: http://drupal.org/node/109153#index-map

I've tried to make the distinction between the wildcard and the loader.

Added a note on the loader arguments to %user_category (Note the use of load arguments, which must be present (as shown) in order to use %user_category. See the documentation on load arguments for more information.) and in the writing a loader section (You can specify additional arguments for the load function with the load arguments entry of a menu item. See %user_category for an example of these in use, along with the documentation on load arguments.).

Added a note to %user_current (%user_current behaves identically to %user (user_current_load directly calls user_load), however, %user_current creates a menu link as well. Hence there is a "My recent posts" link in the Drupal 6 menu which leads to tracker/(your user id), but you can also go to tracker/(any user id) to see recent posts from other people. See _to_arg for more information on this.) and to the writing a loader section (Furthermore, the function loader_name_to_arg can be implemented to cause a link to be made in the menu when the loader is specified in a menu path. See %user_current for a practical example of this, or the _to_arg documentation.).

might need a few minor edits, but I think all the requirements of the task have been met.

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