[Summary view] [Print] [Text view]

   1  // $Id: README.txt,v 1.14 2010/03/22 19:19:36 johnalbin Exp $
   2  
   3  ADDING MENU BLOCKS
   4  ------------------
   5  
   6  To add new menu blocks, use the "Add menu block" tab (or button) on the
   7  administer blocks page, admin/build/block. You will then be able to configure
   8  your menu block before adding it.
   9  
  10  
  11  CONFIGURING MENU BLOCKS
  12  -----------------------
  13  
  14  When adding or configuring a menu block, several configuration options are
  15  available:
  16  
  17  Block title
  18    For menu trees that start with the 1st level, the default block title will be
  19    the menu name. For menu trees that start with the 2nd level or deeper, the
  20    default block title will be the title for the parent menu item of the
  21    specified level.
  22  
  23    For example, if the active menu trail for the Navigation menu is: Administer >
  24    Site building > Menus > Primary links, then a menu block configured to start
  25    with the 1st level of the Navigation will display a block title of
  26    "Navigation". And a menu block configured to start with the 3rd level of the
  27    Navigation menu will display a block title of "Site building".
  28  
  29  Block title as link
  30    For menu trees that start with the 2nd level or deeper, the default block
  31    title will be the title for the parent menu item of the specified level. If
  32    this option is checked, the block title will be a link to that menu item.
  33  
  34  Administrative title
  35    To help identify the block on the administer blocks page, you can specify a
  36    unique title to be used on that page. If blank, the regular title will be
  37    used.
  38  
  39  Parent item
  40    First select the menu. Then select the parent item from that menu. The tree of
  41    links will only contain children of the selected parent item.
  42  
  43  Starting level
  44    Blocks that start with the 1st level will always be visible. Blocks that start
  45    with the 2nd level or deeper will only be visible when the trail to the active
  46    menu item is in the block's tree.
  47  
  48  Make the starting level follow the active menu item
  49    If the active menu item is deeper than the level specified above, the starting
  50    level will follow the active menu item. Otherwise, the starting level of the
  51    tree will remain fixed.
  52  
  53  Maximum depth
  54    From the starting level, specify the maximum depth of the tree. Blocks with a
  55    maximum depth of 1 will just be a single un-nested list of links with none of
  56    those links' children displayed.
  57  
  58  Expand
  59    All children of this menu will be expanded.
  60  
  61  Sort
  62    Sort each item in the active trail to the top of its level. When used on a
  63    deep or wide menu tree, the active menu item's children will be easier to see
  64    when the page is reloaded.
  65  
  66  
  67  STYLING MENU BLOCKS
  68  -------------------
  69  
  70  Classes:
  71  
  72  Themers should look at the myriad of classes added to the <div>, <li> and <a>
  73  elements.
  74  
  75  <div>
  76    The <div> wrapped around the menu tree has a class for several of the
  77    configurable options of the block: menu-block-[block id number]
  78    menu-name-[menu name] parent-mlid-[menu link ID] menu-level-[level number]
  79  
  80  <li>
  81    The <li> elements of the menu tree can have an extended list of classes
  82    (compared to standard menu trees): first last menu-mlid-[menu link ID]
  83    has-children active active-trail
  84  
  85  <a>
  86    The <a> elements of the menu tree can have: active active-trail
  87  
  88  Templates:
  89  
  90  In addition, the wrapper <div> for the block is generated using the
  91  menu-block-wrapper.tpl.php template. And Menu block provides several theme hook
  92  suggestions for that template:
  93  - menu-block-wrapper--[block id number].tpl.php
  94  - menu-block-wrapper--[menu name].tpl.php
  95  
  96  For example, a file in your theme called
  97  menu-block-wrapper--primary-links.tpl.php can be used to override the <div> for
  98  just the "Primary links" menu blocks.
  99  
 100  Theme functions:
 101  
 102  Menu block uses Drupal core's menu theme functions. However, it also provides
 103  theme hook suggestions that can be used to override any of the theme functions
 104  called by it.
 105  
 106  - theme_menu_tree() can be overridden by creating one of:
 107    - [theme]_menu_tree__menu_block()
 108    - [theme]_menu_tree__menu_block__[menu name]()
 109    - [theme]_menu_tree__menu_block__[block id number]()
 110  
 111  - theme_menu_item() can be overridden by creating one of:
 112    - [theme]_menu_item__menu_block()
 113    - [theme]_menu_item__menu_block__[menu name]()
 114    - [theme]_menu_item__menu_block__[block id number]()
 115  
 116  - theme_menu_item_link() can be overridden by creating one of:
 117    - [theme]_menu_item_link__menu_block()
 118    - [theme]_menu_item_link__menu_block__[menu name]()
 119    - [theme]_menu_item_link__menu_block__[block id number]()
 120  
 121  For example, if you created a garland_menu_tree__menu_block() function, it would
 122  override theme_menu_block() any time it was used by this module, but not when
 123  used by any other module. Similarly, a garland_menu_item__menu_block__1()
 124  function would override theme_menu_item(), but only for the first menu block in
 125  your system (the menu block with an ID of 1).
 126  
 127  
 128  MENU BLOCK API
 129  --------------
 130  
 131  Developers can use the API of this module to create their own menu trees outside
 132  the confines of blocks. All of the publicly available API functions are
 133  documented in the menu_block.module file.
 134  
 135  In addition, Menu block implements HOOK_get_menus() and
 136  HOOK_menu_block_tree_alter(). See menu_block.api.php for documentation.