wiki:DeveloperGuidelines/Menus

Version 3 (modified by Fran Boon, 9 years ago) ( diff )

--

Themes

Sahana Eden supports custom Menus as part of it's overall Templates system.

This allows customisation of:

  • Menu content
  • Menu layout

NOTE: This is still a work-in-progress: the details may change...

Default Menus

By default these files are used:

  • /modules/eden/menus.py
  • /modules/eden/layouts.py

These both build on the core functionality in:

  • /modules/s3/s3navigation.py

This core functionality ensures that menu items only appear of the appropriate moduels are enaled & if the user has the relevant permissions to access the resource.

There are 2 menus by default:

  • S3MainMenu
    • defaults to a link to the homepage of each enabled module, plus a section for Logging-in & selection of Language
    • defaults to being rendered horizontally across the top of the page
  • S3OptionsMenu
    • a separate menu for each application
    • defaults to being rendered vertically on the left of the page

Custom Menu Content

In order to customise the content of the menus, you should create a template folder, if you don't already have one, and ensure there is an empty init.py file inside:

/private/templates/<template>/__init__.py

You should then copy the example file from the 'default' template folder to:

/private/templates/<template>/menus.py

You can modify the labels (which are automatically translated unless you specifically set translate=False on an item), which items show, and in what order, and under which conditions.

Note: For high performance, all conditional checks should be constructed as lambdas so they are called only when that menu is rendered not on every request.

Custom Menu Layouts

If you wish to go further than simply customising the content, but rather change the look & feel or add more different sorts of menu, then you need to also copy one of the example layouts.py files to:

/private/templates/<template>/layouts.py

This allows you to subclass the normal layouts, S3MainMenuLayout and S3OptionsMenuLayout, so that you can alter their HTML structure, add custom classes, etc

You can also add completely new classes & make use of these for menus in your menus.py.

Note: You need to restart web2py to see changes in layouts.py (including switching between alternate themes).

See Also

Note: See TracWiki for help on using the wiki.