joomla 的 jdoc module 的正确用法

大家如果按照官方的解释：http://docs.joomla.org/Jdoc_statements 来使用jdoc的module功能，必然什么都没得到啊。我搜了一下E文的，原来是这个实在是改了， 现在实际上没什么用了 ，但不知道Joomla1.6有没有修复：

JDoc-tag of type "module"

Within Joomla! templates you can use so-called <jdoc>-tags to indicate where in your HTML-document dynamic content should be inserted. For instance there is a tag of type "modules" that inserts the output of one or more modules in the template. But there is also a <jdoc>-type "module" (not plural but singular) and little is explained on this type. This article reveals the bits.

Type "modules"

First have a better look at the most regular type "modules". You can display multiple modules that are configured for a specific module position. Take for example this code:

<jdoc:include type="modules" name="left" />

This will display all modules configured on position "left". The ordering they appear in on the webpage can be determined through the Module Manager.

Get the terminology right

Before you continue to read, it's wise to take note of the right terminology. A module position is not the same thing as a template position : The module position is an attribute of a single module instance, while the <jdoc>-tag itself can be seen as the template position, which can house many modules.

A Joomla! module is a set of files that offers certain functionality. But to do something useful with these files, we need to create a module instance , in which we can configure attributes like a title, parameters and a position.

Take for instance the menu-module. The module "mod_mainmenu" actually refers to PHP-scripts and the functionality within those scripts, while we can have many menus on our website - they are all module instances of mod_mainmenu.

Most of the time that we are talking about modules we actually mean module instances.

The history of type "module"

Now let's take a look at the type "module". The syntax is the same as type "modules", so the only difference on first sight is the difference between singular and plural (single and multiple).

<jdoc:include type="module" name="left" />

In the past it was exactly that. While type "modules" showed multiple modules on a position, the type "module" just displayed one single module. Which module? The module configured on position "left". And if there were more then one modules on that position, Joomla! would just take the first one in order.

This is NOT the case anymore, so before you read on, please note that this paragraph is not accurate any more. The <jdoc>-tag above will not display anything.

The right use of type "module"

Somewhere in the past the Joomla! team changed the behavior described above. I discovered myself that after an upgrade my single module on position "top" did not work anymore. I concluded that <jdoc:include type="module" /> just did not work anymore, and changed "module" into "modules".

But so now and then, I got word that type "module" did still work for some people. So to get rid of the confusion, I opened up the Joomla! framework to check what was really going on. This is it: Type "module" can still be used, but the "name" attribute does not refer to a position, it refers to the module name.

Take for instance the following example:

<jdoc:include type="module" name="breadcrumbs" />

Here "breadcrumbs" does not refer to the position "breadcrumbs", but it refers to the module "mod_breadcrumbs". The only condition here is that you need to have at least one module instance published on the site.

Because the "name" attribute refers to the actual technical name of the module, the following tags could also be used:

<jdoc:include type="module" name="mainmenu" />



<jdoc:include type="module" name="custom" />



<jdoc:include type="module" name="footer" />



<jdoc:include type="module" name="search" />

But the docs.joomla.org site also mentions the following tags:

<jdoc:include type="module" name="menu" />



<jdoc:include type="module" name="submenu" />

This would suggest the existence of the modules mod_menu and mod_submenu, but to my knowledge they don't exist (at least not in a default Joomla! installation). These tags do not work, and it seems a left over from old ideas.

That's silly

The silly thing about this behaviour is that you still need a module instance to put module-functionality on your site. The type "module" suggests the use of modules without using module instances, but it doesn't work that way. You have to configure module instances.

Even stranger: For every module instance you must fill in a module position. But because your module instance is already displayed through <jdoc:include type="module" name="x">, this module position is pointless and the best thing is to name it to "THIS_POSITION_IS_VIRTUAL" to avoid further confusion.

The only reason I can think of why the type=module behaviour changed, is to allow template-builders to build nice menus without having them to worry that the Joomla!-administrator configured the "Main Menu" module instance with a wrong module position. I think that goal is not reached: An administrator is still able to change a lot of things that might mess up the template, and the only thing to prevent this is to tell the administrator how to configure the template properly.

To me, the new behaviour of type "module" is not so useful and also suggests the wrong thing. Hopefully this will be cleared up in the future.

EDIT: This issue has already been reported to the tracker under ID 12206 , and qualified not as a bug but as an undocumented feature.

EDIT2: Added a new feature request (with patch) to the tracker under ID 15405 .