theme_get_registry() doc is confusing

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443

I would like to add that the api documentation for theme_get_registry() is also misleading...

Retrieve the stored theme registry. If the theme registry is already in memory it will be returned; otherwise it will attempt to load the registry from cache. If this fails, it will construct the registry and cache it.

This simply doesn't match the function...

function theme_get_registry($registry = NULL) {
  static $theme_registry = NULL;
  if (isset($registry)) {
    $theme_registry = $registry;
  }

  return $theme_registry;
}

There is no "construction" going on this function.

While developing a module, I called theme_get_registry() and received NULL in return (on a couple of Drupal 6.12 sites - but it returned the theme hooks just fine on another development site). I then thought that calling drupal_rebuild_theme_registry() was needed before calling theme_get_registry(), but that didn't change anything - it still returned null.

In fact, "to construct the registry and cache it" it seems you need to explicitly call _theme_load_registry($theme)...

Perhaps I am misunderstanding something, if so please correct me! Otherwise, it seems the documentation for these functions could be clarified.

Thanks.

Hmmm..

OK, here is what is going on.

It looks like the theme registry is normally built/loaded in _theme_load_registry(), which calls _theme_build_registry() if the registry does not exist in the cache. _theme_load_registry() is called (semi-silently -- there should be a See Also between these functions!!) by _init_theme(), which is called from init_theme(), which several functions [including theme() and drupal_render_form()] call just before theme_get_registry().

So I think that theme_get_registry() should say that you need to call init_theme() to build the theme registry, before using theme_get_registry(). That will address #3's comments.

Regarding the original issue reported here, it does look like the Drupal 5 -> Drupal 6 upgrade guide should have mentioned that theme_get_function() is gone in Drupal 6.

But... Just a note: I don't know why you would be calling theme_get_function() or theme_get_registry() in the first place. You should just be calling theme() to theme something, because as of Drupal 6, you can override theme functions by using a .tpl.php file or a theme function.

Note: The Drupal 7 doc for this function is correct, so this is only a Drupal 6 issue.

And maybe the coder module should tell a 5.x-6.x upgrade module that uses theme_get_function() to call theme() instead of pointing them to theme_get_registry()?

Anyway, meanwhile, here is a fix for the documentation of theme_get_registry() that will hopefully clear up the confusion.

I also filed an issue on the Coder module to consider changing the messages when a module uses theme_get_function():
#612896: theme_get_function() 5->6 upgrade suggestion to theme_get_registry() is confusing

Thanks for pointing out init_theme. That seems more appropriate than directly calling _theme_load_registry() and also works for my purposes. In this case I need to access the theme registry since I am collecting the theme hooks that use templates for later use in hook_preprocess.

The proposed fix is much better than the current documentation. I am not sure that the paragraph beginning "Most modules do not need direct access to the theme registry..." is really necessary for this function in particular, but the statement is correct.

A concise description of the structure of $theme_registry would be even more helpful. It turns out that this is available on the hook_theme page of the api reference. So it might also be good to throw in a reference to that page for the structure of the return variable.

Looks like the patch there could use some work based on #7.

Guess we can close this issue? :)