kotti_navigation 0.5

Add a configurable navigation to your Kotti site

# kotti_navigation

[](https://pypi.python.org/pypi/kotti_navigation/) [](https://pypi.python.org/pypi/kotti_navigation/) [](http://www.repoze.org/LICENSE.txt) [](https://travis-ci.org/Kotti/kotti_navigation)


This is an extension to [Kotti][1] that renders navigation displays in a choice of available locations for a Kotti website (top nav, left slot, right slot).

## Hint

Starting with version ``0.5`` ``kotti_navigation`` uses [kotti_settings][2] for configuration of the navigation widget. The previously used configuration in the ini file is not supported anymore. The configuration is now done via the settings interface where you can adjust the navigation widget to your needs at run time. If your site depends on the old configuration make sure you pin ``kotti_navigation`` to version ``0.3.1`` and read the relevant [documentation][3].

## Set up kotti_navigation

To activate kotti_navigation add the following entry, as with any add-on, to kotti.configurators of your .ini config file. ``kotti_navigation`` depends on [kotti_settings][2], so you have to add also an entry for this add-on. So the kotti.configurators part of your your ini file should include the following lines.

```ini
kotti.configurators =
kotti_settings.kotti_configure
kotti_navigation.kotti_configure
...
```

## How to use it?

You have different settings to adjust ``kotti_navigation`` to your needs. You can view the settings page at http://yourkottidomain.tld/@@settings and you can find a link to `Settings` in the `Administrator` dropdown of the editor bar. By default, no special navigation is activated and the default navigation bar from Kotti will be used.


### Slots

The navigation widget can be displayed in all slot of ``Kotti``, see the [API documentation](http://kotti.readthedocs.org/en/latest/api/kotti.views/kotti.views.slots.html) of Kotti for more information about slots.

There are six slots or locations are available to include the navigation widget::

* top (within and beneath the default nav toolbar)
* left (slot)
* right (slot)
* abovecontent (slot)
* belowcontent (slot)
* beforebodyend (slot)

Here are the slot choices in a layout diagram:

+------------------------------------------------------+
| nav (the nav in the Kotti toolbar -- configurable) |
|------------------------------------------------------|
| editor_bar |
|+----------------------------------------------------+|
|| breadcrumbs ||
|+-------------++---------------------++--------------+|
|| SLOT "left" || SLOT "abovecontent" || SLOT "right" ||
|| |+---------------------+| ||
|| || Content || ||
|| |+---------------------+| ||
|| || SLOT "belowcontent" || ||
|+-------------++---------------------++--------------+|
| footer |
|------------------------------------------------------|
| SLOT "beforebodyend" |
+------------------------------------------------------+

For every location you have an own tab in the settings. There you can choose if the navigation is enabled for the location and how it will be displayed.
The following options are available.

### Display Types

With the display type you choose how your navigation will be rendered.

1. Not enabled
- As expected the widget will not be shown in the slot.
2. Tree
- The full tree is used for the navigation.
3. Items
- Only the the children of the current context are included.
4. Menu
- The navigation will be rendered as a dropdown menu.
5. Breadcrumbs
- Here the real breadcrumbs will be rendered, useful when you need it in another slot than usual.

For a typical website that has a tree navigation display in the left slot, you would configure for only the left location, and omit configuration for any other. But you are encouraged to play around with the possibilities.

### Display Manner

With the display manner you can choose how the menu items will be displayed. The options `Pills` and `Tabs` are possible. The setting only affects the display types `Items` and `Tree`.

### Options

The options are a multi selection box, so you can enable how much you want, however it will not always make sense to mix all of the options together.

- List
- Pills
- Tabs
- These define the bootstrap classes that are used to render the navigation. It is recommended to only use one of them.
- Stacked
- This makes your navigation stackable. Refer to the [bootstrap documentation](http://getbootstrap.com/components/#nav) for more information.
- Open all
- This will be open all of your menu points no matter where your context is. This is useful if you plan to set up a menu via css or javascript, because all items in the site hierarchy are always included.
- With Dropdowns
- Add a dropdown to tree or items display type. *experimental*
- Show Menu
- Add a menu item listing. *experimental*
- Include Root
- Indicate if the root object will be included on the top of the navigation and so an item showing the title of the root of the site is inserted as the first item for the display choices.
- Show hidden while logged in
- With this option enabled items that are not included in the navigation for the user of the website are shown to the editor or admin.

### Label

The label is optional, but can provide clarification in some nav display cases.
It is positioned within the display in different ways, depending on display type. In a tree-type display (one of the "stacked" display choices), it is at the top of the display. The label is optional, but can provide clarification in some nav display cases. It is positioned within the display in different ways, depending on display type.

The current context will be indicated by the highlighting of the context menu item in the indented 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. To do this, include the actual word ``context`` in the label text, so `<context>` would become ${'<' + context.title '>'} in the template code.

### Include Content Types

Here you find a list of the content type names that are to be allowed in a given navigation display. Use this, for example, to have a nav tabs display in the top location, along with an images-only display in the right slot. The images-only nav display could be given a label such as "Images:" for clarity.

### Exclude Content Types

This is a list of the names of content types that are to be ignored in the navigation display. It is the opposite of the ``Include Content Types`` setting described above. It is commonly used to exclude the Image content type from a normal nav display, to avoid the "clutter" with listing images, which can be numerous. The same could be true for other content items, such as for a site that allows the Event content type of kotti_calendar to be stored in various places in the site, and where events are wished to be shown only on calendar or event list displays.

## Development

Development happens on [GitHub](https://github.com/Kotti/kotti_navigation), please report any [Issues](https://github.com/Kotti/kotti_navigation/issues) there.

[1]: http://pypi.python.org/pypi/Kotti
[2]: http://pypi.python.org/pypi/kotti_settings
[3]: https://github.com/Kotti/kotti_navigation/tree/0.3.1

Contributors
============

Thanks to the following people for support, code, patches etc:

- Andreas Kaiser (disko)
- Jeffrey Gill Pittman (geojeff)
- Marc Abramowitz (msabramo)
- Ghiță Bizău (GhitaB)

Changelog
=========

0.5 (2016-02-26)
----------------

* Use kotti_settings for configuration of the navigation widget.

The previously used configuration in the ini file is not supported
anymore. The configuration is now done via the settings interface
where you can adjust the navigation widget to your needs at run time.


0.4a2 (2013-04-18)
------------------

* Clarified descriptions and improved wording in the readme. [geojeff]


0.4a1 (2013-04-18)
------------------

* Warning: the changes for this release do wholesale renaming, so existing
deployments will require adjustment.
* Moved to a configuration approach that allows multiple navigation displays,
in different locations, where the new concept of location encompasses both
slots and the top, which is the area of Kotti's default navbar. [geojeff]
* Added an include_content_types param, as a counterpart to the existing
exclude_content_types. This way a display type can be set to only include
specific content types, as with an images-only display. [geojeff]
* Devised new display type names that are more specific and descriptive, and
are representative of the options available with Bootstrap. [geojeff]
* Changed the handling of the top location to remove the default Kotti nav
altogether, and replace it with optional specific placement of the menu
display type, restricted to the area between brand and search in the Kotti
navbar, and allowing any display type underneath the navbar. [geojeff]
* Added a breadcrumbs display type that is the same as the default Kotti one,
but with a configurable label. [geojeff]
* Added a treatment for the menu display type for root, so that it is always
shown (previously, the menu simply did not show for root). [geojeff]


0.3 (2013-04-17)
----------------

- No changes.


0.3b1 (2013-03-11)
------------------

* Made the context menu highlight context as the active li item. [geojeff]
* Added logic for better home label in context menu. [geojeff]


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]


0.1
---

* Initial release [j23d]