These are the configuration settings we will be discussing here for the
navigation widget::
# general navigation widget settings, showing defaults
kotti_navigation.navigation_widget.display_type = tree
kotti_navigation.navigation_widget.show_context_menu = false
kotti_navigation.navigation_widget.label = none
kotti_navigation.navigation_widget.slot = left
kotti_navigation.navigation_widget.open_all = false
kotti_navigation.navigation_widget.show_hidden_while_logged_in = true
kotti_navigation.navigation_widget.exclude_content_types = (e.g., Image)
kotti_navigation.navigation_widget.include_root = true
# specific to list display
kotti_navigation.navigation_widget.show_dropdown_menus = true
To set up the navigation widget to display on every page in Kotti in the
default left slot as a tree display, add an entry to kotti.configurators
in the .ini config file for your project::
You see the top nav position in the diagram above (it is not a slot), where
default Kotti puts the nav.pt template. kotti_navigation provides a nav.pt
that can replace Kotti’s nav.pt::
This will tell Kotti that you are selecting any templates that are defined
within kotti_navigation:kotti-overrides and which match Kotti’s directory
structure for templates.
This top position is not a slot, so make sure to omit the slot setting or to
set it as::
kotti_navigation.navigation_widget.slot = none
For this top position, you will probably want to configure these nav settings
as::
kotti_navigation.navigation_widget.display_type = list
kotti_navigation.navigation_widget.show_context_menu = true
and you probably want to omit the label setting. The breadrumbs may in this
usage be deemed redundant. If so, override Kotti’s master template to omit it
(See below, under discussion of display_type).
Excluding the Root
To exclude the root of the site from the navigation, in either the tree
display or the context menu of the list display, set this::
You can exclude specific content types from the whole navigation
structure. If you not want to show images in the navigation at all,
set the kotti_navigation.navigation_widget.exclude_content_types
variable to the following::
Control the type of display with the display_type setting, which can be either
list (default) or tree::
kotti_navigation.navigation_widget.display_type = list
Configuring the tree display is straightforward; you have the choice of
including the root, or not. The navigation tree shows the full site content in
an indented vertical list. When an item with children is clicked, it is
exploded, and with another item is clicked, it is collapsed. The tree display
is most appropriate for the left and right slots, but can be used in any other
slot, probably accompanied by customization through CSS.
The list display does not show the full site content; Only the
immediate children for the context are shown as a simple list of
navpills wrapped within the available space. This navigation menu can be used
in two ways, regarding the breadcrumbs display in default Kotti:
Turn off the context menu for the list display with show_context_menu
set to false, and use Kotti’s breadcrumbs display for providing essential
navigation back up the site hierarchy
Turn on the context menu fo the list display, and turn off Kotti’s
breadcrumbs display by overriding via templates. The context menu will
provide an active link to go up one level from the current context, and will
provide links to the root and top-level content items.
The list style of display is different for “horizontal” vs. “vertical”
aspect slots, as follows:
In the abovecontent, belowcontent, and belowbodyend slots (“horizontal”
aspect), the list display is akin to the display of tags as nav pills
wrapping horizontally within a container filling the slot, plus a label
and/or context menu item button if they are configured to be present.
In the left and right slots, the list display is the nav-list style from
Bootstrap, which shows items in a more traditional “vertical aspect” list
format.
Configuring a Label
There is an optional label for the top of the tree display, underneath the
context menu if it is enabled, or for the first item in the list display.
For the following discussion about the optional label, the context is assumed
to be a document titled Animals, and there are two children titled Dogs and
Cats.
A label for a tree display
The optional label at the top of the tree dislay would usually be set to
none, because the nature of the indentation should make the context
obvious. In some situations, however, a simple label such as “Site Navigation”
or “Site Menu” could be desired. To set such a label, do::
kotti_navigation.label = Site Menu
The current context will be indicated by the highlighting of the context menu
item in the tree display. This is normally adequate. However, for extra
clarity, or for some special reason, you may want to include the current
context in the label, in a phrase such as “Current item: context”, where the
word context would be replaced by the actual context.title, e.g. “Current
item: Cats”. So, include the actual word context in the label text::
kotti_navigation.label = <context>
(the label would become ${‘<’ + context.title ‘>’} in the template code, which
would become <Animals> in the rendered label.)
Or, if the site’s breadcrumbs display is not shown, by overriding
templates, and you want to have a simple replacement in concert with the tree
display, do::
kotti_navigation.label = You are here: context
(You are here: Animals).
A label for a list display
If using a list display for navigation, the default will list children of the
current context in a list of nav pills that wrap, if necessary. Along with the
default Kotti nav toolbar and and breadcrumbs, this may provide a perfectly
good nav display. When the abovecontent slot is used, however, the title for
the context is _underneath_ the nav list, so it may not be clear enough that
that the nav pill items are children within the context. Perhaps this would
be true for the left slot, as well, but a bare nav pill list in the right and
belowcontent slots might work well.
If label is not set, the default value of none will result in two nav pill li
items for the example Animals context::
<Dogs> <Cats>
(< > notation used here to denote nav pill li items).
Using a custom string, punctuated with a colon::
kotti_navigation.label = Contained Items:
would result in a nav-header styled label with two nav pill li items, as::
Contained items: <Dogs> <Cats>
or, perhaps with some other punctuation::
kotti_navigation.label = Contents >>
etc.
As described above, set label to a string using the word context anywhere
in the string as a placeholder for context.title.
kotti_navigation.label = context
The result would be a label for Animals and two nav pill li items, as::
Animals <Dogs> <Cats>
With any punctuation or additional text of any sort along with context in the
label, as with::
label = context:
becomes::
Animals: <Dogs> <Cats>
If a phrase is used, take care to word appropriately, perhaps aided by use of
quotes or another indicator for context, such as (), [], etc.::
kotti_navigation.label = Items in [context] are:::
would result in::
Items in [Animals] are: <Dogs> <Cats>
and::
kotti_navigation.label = "context" contains:
would result in::
"Animals" contains: <Dogs> <Cats>
etc.
Configuring for Use with a Menu System
To open the whole navigation all the time, set the open_all variable. This
is useful if you plan to set up a popup menu via css or javascript::
You will want to set display_type to tree, because the list
shows, by design, only the children of the current context. The tree
display, when open_all is true, will produce items for each node in the full
tree.
Contributors
Thanks to the following people for support, code, patches etc:
Andreas Kaiser (disko)
Jeffrey Gill Pittman (geojeff)
Changelog
0.3a2 (2013-02-01)
Added slots and options. [geojeff]
* Added possible slot positions where the navigation can be shown.
* Added new display type list.
* Added option to set a label for the navigation.
* See README.rst for more informations.
0.3a1 (2012-12-04)
Changes for compatibility with Kotti>=0.8. These changes
are not backward compatibel. If you want to use kotti_navigation
with Kotti<=0.7.x then pin kotti_navigation to 0.2.
* Use new children_with_permission function on context.
Use view_config decoration for views.
0.2 (2012-08-15)
Use assign_slot for slots instead of depricated register slot. [j23d]
0.2a3 (2012-07-02)
Move border from bottom to top for submenu. [j23d]
0.2a2 (2012-06-18)
Fix structure of navigation list. [j23d]
0.2a1 (2012-06-16)
Move to fanstatic for static resource inclusion. [disko]
Added option to exclude content types from the navigation. [j23d]
