Modules are essentially the building blocks of a page in Mambo site. Mambo comes with several built-in modules such as Main Menu (mod_mainmenu), Login Form (mod_login), Who's Online (mod_whosonline), and Polls (mod_poll). If you take a look at Site Module Manager in administration page (Modules -> Site Modules), each module is assigned a position (left, right, top, etc) and more than one modules can have the same position. Mambo uses position name to group modules into blocks.

Fig 3. Site Module Manager

Back to our layout file. The function used to display a group of modules is mosLoadModules() which is defined in installdir/includes/frontend.php.

<?php 
  // Display all modules whose position is set to 'left'
  mosLoadModules('left'); 
?>

The input argument for mosLoadModules() is NOT the module name but rather the position name. The function above will display all published modules whose position is set to 'left'. There is another column in Module Manager called 'Reorder' where you can arrange the order of which the modules appear within its group.

mosLoadModules() can accept a second input argument, $style, to set the display style. There are 4 possible values for $style: '0' (default), '1', '-1', or '-2'.

Values '0' and '1' define if modules in this block should be displayed vertically (one stacked on top of the other) or horizontally. In horizontal layout, modules are put in a 1-row container table where each module occupies a table cell. Each individual module is wrapped inside <table class="moduletable"></table> tag. There is no CSS class assigned to the container table.

To change styling for each individual module, set $style to '-1' or '-2'. If set to '-1', a module will be displayed without any wrapper (no 'moduletable' table) and its title is not shown. If set to '-2' a module will be displayed inside <div class="moduletable"></div> tag and its title inside <h3></h3> tag within the DIV. This is considered as standard-compliant style and follows xMambo style.

You can define a suffix for each module which will be appended to the default class name, 'moduletable'. For example, setting the suffix to '_mymodule' will result in class name 'moduletable_mymodule'.

Fig 4. Define module class name suffix

It is important to note that value '-1', or '-2' is applicable only for modules whose type begins with 'mod_' (see column 'Type' in Site Module Manager). Basically these are built-in modules that come with Mambo and all installed modules. New module created by clicking 'New' button in Site Module Manager will have its type automatically set to 'User' and setting $style to '-1' or '-2' will have no effect on this module.

Below are examples of mosLoadModules() usage:

<?php 
  // Input argument $style will be set to 0 and
  // modules are displayed vertically. Each module is
  // wrapped in <table class="moduletable"></table> tag
  mosLoadModules('left'); 

  // Modules are displayed horizontally, each module
  // wrapped in <table class="moduletable"></table> tag
  mosLoadModules('left', 1);

  // Only the content of each module is shown
  // (no title) and each module is not wrapped
  // inside any table/div 
  mosLoadModules('left', -1);

  // Each module is wrapped in 
  // <div class="moduletable"></div> tag. It is
  // up to you to style the DIV (floating, etc)
  mosLoadModules('left', -2);
?>


New in 4.5.2: mosLoadModules() supports '-3' style. When set to this value, modules are displayed using <dl class="module"></dl> tags:

<dl class="module">
    <dt><p>Module title</p></dt>
    <dd><p>Module content</p></dd>
</dl>


When module class suffix is defined, it will be appended to the default class name 'module'.

You can add your own position name through Module Position page in administration area (Site -> Template Manager -> Module Positions for Mambo 4.5.1a). Some of the default names like 'user1', 'user2' are not very descriptive so you can change it here. Renaming an existing position requires you to manually update each modules that belong to this position in Site Module Manager. Don't forget to check your template's layout file to make sure you enter the correct name there or your modules will not show up.

Fig 5. Module positions

If you want to find out if a position has any published module in it, use mosCountModules() function which returns the number of modules found in that position. Here is an example how you can hide a block if there is no module in it:

<?php
  // Only show 'right' block if there is
  // at least 1 module
  if (mosCountModules('right')) {
      modLoadModules('right');
  }
?>


To summarize this section, here is a rough guide to design a layout for your site. Decide what modules you want to show on the page (e.g. Main Menu, Top Menu, Search, Poll, Who's Online, etc) and then group them into position blocks. For example, Main Menu and Polls should be on the left (hint: set the type of these module to 'left'), Who's Online should be on the right, and so on. Write the HTML codes inside the layout page and decide where you want to display each position block. Then insert mosLoadModules() functions in each block with the appropriate position name.