Changes between Version 33 and Version 34 of S3/S3Navigation

Timestamp:

03/05/12 20:37:50 (13 years ago)

Author:

Dominic König

Comment:

--

S3/S3Navigation

@@ -282 +282 @@
 This will call the layout method of the element, provided that the element is ''active'' (i.e. relevant for the current request).
 
+== Eden Navigation Layouts ==
+
+The trunk version of Sahana Eden currently defines 4 different layouts (S3NavigationItem subclasses):
+
+  - '''S3MainMenuLayout''' (Shortcut {{{MM}}}) for the application main menu (also called "modules" menu)
+  - '''S3OptionsMenuLayout''' (Shortcut {{{M}}}) for the options menu (also called "controller" menu)
+  - '''S3MenuSeparatorLayout''' (Shortcut {{{SEP}}}) for separators in pull-down menus
+  - '''S3BreadcrumbsLayout''' for breadcrumbs
+
+These layout classes (as well as additional layouts) are defined in {{{modules/eden/layouts.py}}} and can be customized there.
+
 == Eden Standard Menus ==
 
+For the trunk version of Sahana Eden, all menu definitions have been implemented as functions in two classes:
+
+  - '''S3MainMenu''' for the application main menu ("modules" menu)
+  - '''S3OptionsMenu''' for the options menus per module ("controller" menus)
+
+These classes can be found in {{{modules/eden/menus.py}}} and shall ''not'' be customized in place - instead, any custom menu definitions can happen in models/01_menu.py. The default version of 01_menu.py looks like:
+
+{{{
+    # =========================================================================
+    # Main menu
+    #
+    current.menu.main(
+
+        # Standard modules-menu
+        S3MainMenu.menu_modules(),
+
+        # Standard service menus
+        S3MainMenu.menu_help(right=True),
+        S3MainMenu.menu_auth(right=True),
+        S3MainMenu.menu_lang(right=True),
+        S3MainMenu.menu_admin(right=True),
+        S3MainMenu.menu_gis(right=True)
+    )
+
+    # =========================================================================
+    # Controller menus
+    #
+    s3_menu_dict = {
+
+        # Define custom controller menus here
+
+    }
+
+}}}
+
+The first section defines the application main menu ("modules" menu). In the trunk version, this invokes the respective definition methods of '''S3MainMenu'''. To customize the main menu, you can simply comment the standard option and replace it by a custom definition, e.g.:
+
+{{{
+    # =========================================================================
+    # Main menu
+    #
+    current.menu.main(
+
+        # Standard modules-menu, commented out
+        #S3MainMenu.menu_modules(),
+
+        # Custom menu:
+        homepage(), # no parameters -> links to default/index
+        homepage("gis"),
+        homepage("pr", restrict=[ADMIN])(
+            MM("Persons", f="person"),
+            MM("Groups", f="group")
+        ),
+        MM("more", link=False)(
+            homepage("dvi"),
+            homepage("irs")
+        ),
+
+        # Standard service menus
+        S3MainMenu.menu_help(right=True),
+        S3MainMenu.menu_auth(right=True),
+        S3MainMenu.menu_lang(right=True),
+        S3MainMenu.menu_admin(right=True),
+        S3MainMenu.menu_gis(right=True)
+    )
+}}}
+
+This example uses the {{{homepage}}} helper function to define a {{{MM}}} instance out of the module's nice name setting in 000_config.
+
+Mind the trailing commas! Note that you do not need to check for module activation - this happens automatically in check_active: items linked to deactivated controllers will automatically be deactivated.
+
+To customize a controller menu, you can override the standard menu in the s3_menu_dict, e.g.:
+
+{{{
+    # =========================================================================
+    # Controller menus
+    #
+    s3_menu_dict = {
+
+        # Custom menu for the PR controller
+        "pr": M(c="pr")(                        # <- the menu itself has no label, just the controller
+                  M("Persons", f="person")(     # <- Sub-item, inherits c from the parent item
+                       M("List"),               # <- Sub-item, inherits both c and f from the parent item
+                       M("New", m="create"),    # <- method m will be appended to args, if not the last arg
+                       M("Search", m="search"), # <- no need for T() of the label, happens automatically
+                  ),
+                  M("Groups", f="group")(
+                       M("List"),
+                       M("New", m="create"),
+                       M("Search", m="search"),
+                  ),
+               ),
+    }
+}}}
+
+All controller menus which are not defined in s3_menu_dict fall back to the standard definition in S3OptionsMenu in modules/eden/menus.py.
+
+Options menus which are to be shared by multiple controllers must ''not'' define the controller in the root item, but instead at the first sub-item level.
+
+Items which shall match multiple functions can take a list of function names for the parameter f, where the first function name is used to render the URL, i.e.:
+
+{{{
+   M("Persons", c="pr", f=["person", "index"])
+}}}
+
+is rendered as {{{/pr/person}}} but matches both {{{/pr/person}}} and {{{/pr/index}}}.
+
 == Customizing Menus ==