The Menu With Item Selection is a Joomla! module to show menus in the frontend. It is a modification of the Joomla! menu module that adds the option to select what menu items are shown by the module, instead of basing it in the depth of the items and so on.
As the Menu With Item Selection is a modification of the Joomla! menu module it is licensed under the GNU General Public License version 2, or (at your option) any later version.
Download and installation
The Menu With Item Selection is just a single module:
- For Joomla 1.7.x/2.5.x: mod_menuwithitemselection-1.0.zip
- For Joomla 3.x: mod_menuwithitemselection-1.0.1.zip
The module package can be installed like any other Joomla! extension. Download it to your system and then upload it in the Extension Manager, or just copy the link to the module package directly in the Extension Manager.
Details
The Menu With Item Selection is a modification of the Joomla! 3.x menu module or the Joomla! 1.7.x/2.5.x menu module, depending on the version. All the original basic options from the Joomla! menu module are preserved, and so is its behaviour, so it can be used like the original Joomla! menu module. But, besides the original mode, it offers an item selection mode that adds the option to select what menu items are shown by the module.
Original mode and item selection mode are mutually exclusive. To enable the item selection mode the option Ignore basic options must be set in the Items section of the configuration of the module. The Items section contains also a list with all the menu items, grouped by menus. Once Ignore basic options is enabled, only the menu items selected in the list will be shown in the module. Note that the items shown can belong to different menus, and that child items can be shown without showing their parents.
Also note that in the item selection mode all the selected items are always shown (well, unless the user access prevents it). In the original mode, if the option Show Sub-menu Items is set to No, items from levels deeper than the level specified in the option Start Level are shown only if the item itself, a descendant or its direct parent is the active menu item. The option Show Sub-menu Items, like the rest of the basic options, is ignored when the item selection mode is used, so no matter if it is set to No or to Yes, when the item selection mode is used all the selected menu items will be shown.
Tests
Note: if you do not intend to modify the code of the module you can safely skip this section ;)
There are unit tests available for the module. They use Joomla! test infrastructure, so it has to be available in your Joomla! installation (if you are using the git version you should have it already; if you are using a packaged release you should download the test infrastructure from git) and properly configured (not needed in Joomla! 3.x; tests/unit/config.php in Joomla! 1.7.x/2.5.x). PHPUnit >= 3.4 is needed. For further details about Joomla! test please see Joomla! documentation. Apart from the Joomla! test infrastructure, you will need the DOM and Tidy extensions of PHP, and a PHP version with support for reflection (PHP 5).
Unit tests
The unit tests are included in the package of the module, that is, mod_menuwithitemselection.zip, in the directory unit-tests.
Although the unit tests are included in the package, they are not installed when the package is installed. So, to install them, copy the contents from the directory unit-tests to the directory tests/unit/suites/modules/mod_menuwithitemselection/ of your Joomla! 3.x installation, or to the directory tests/unit/suite/modules/mod_menuwithitemselection/ of your Joomla! 1.7.x/2.5.x installation. You may need to create the directory modules, and you will need to create the directory mod_menuwithitemselection.
The *.csv files are used before each test to initialize the database with the necessary data. Since Joomla! 3.x, an in-memory database is used for the unit tests that depend on a database. The structure of the tables is initialized automatically before the tests are run, so there is nothing to configure or prepare manually before running the tests.
Things are a little more complicated in Joomla! 1.7.x/2.5.x, though. In those versions a real database is used, and the tables themselves and their structure must be created before the tests are run. create-test-tables.sql is provided for convenience; replace #_ with the proper prefix name and execute the SQL queries in the database. However, note that Joomla! unit tests do not restore the database to its previous state once all the tests end, so ensure that a test only database is set in your configuration. Also note that the *.csv files must be in tests/unit/suite/plugins/system/simplecustomrouter/ along with the unit test files, and not in tests/unit/stubs/ like other database initialisation files do.
There is only one unit test class, MenuWithItemSelectionTest, which checks that the HTML markup generated by the module is valid and that the HTML lists reflect the menu item hierarchies.
About
The Menu With Item Selection was developed by me, Daniel Calviño Sánchez.
I developed it to cover my own needs, and published it in the hope that it will be useful to someone :)