Changes between Initial Version and Version 1 of DeveloperGuidelines/Menus

Timestamp:

06/23/12 15:45:57 (13 years ago)

Author:

Fran Boon

Comment:

--

DeveloperGuidelines/Menus

@@ +1 @@
+= Themes =
+[[TOC]]
+
+Sahana Eden supports custom Menus as part of it's overall [DeveloperGuidelines/Templates Templates] system.
+
+This allows customisation of:
+* Menu content
+* Menu layout
+
+NOTE: This is still a work-in-progress: not everything here is ready yet & 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.
+
+== See Also ==
+* [DeveloperGuidelines/Templates Templates]
+* [DeveloperGuidelines/Themes Themes]
+* [DeveloperGuidelines/CustomPages Custom Pages]
+