= S3HierarchyWidget =
[[TOC]]

== Introduction ==

The '''S3HierarchyWidget''' class provides a drop-down options widget with a folder-tree style menu for hierarchical lookup fields.

  [[Image(hierarchywidget.png)]]

It is used for both CRUD form widgets (both directly and inline link), as well as a filter widget (S3HierarchyFilter).
== Python Widget Class ==

The S3HierarchyWidget (modules/s3/s3widgets.py) uses the '''S3Hierarchy''' toolkit to extract hierarchy information for the lookup table and to render it as a nested unsorted list (<ul>), then instantiates an '''s3.hierarchicalopts''' widget (static/scripts/s3/s3.jquery.ui.hierarchicalopts.js).

It is currently used in 3 different use-cases:

  - S3HierarchyWidget (directly as CRUD widget)
  - S3HierarchyFilter (filter widget)
  - S3SQLInlineLink (inline-widget to create link table entries to a hierarchical lookup table)

See [wiki:S3/S3Hierarchy#Configuration] how to configure the hierarchy for the lookup table.

Currently, the S3HierarchyWidget does not yet support custom hierarchy data.
== JQuery UI Widget ==

'''s3.hierarchicalopts''' (in static/scripts/S3/s3.jquery.ui.hierarchicalopts.js) is a JQuery UI widget that implements the drop-down button, the folder-tree style appearance of the menu and all interactions with the hierarchical selector.
== Styling ==

The hierarchy widget consists of two parts: the button and the hierarchical menu. 

The style of the button is controlled by the global jQuery UI theme (ui-widget and related CSS classes).

The hierarchical menu has its own CSS theme, the default theme is located in static/styles/jstree/default. Custom themes can be derived from this, and then configured via a deployment setting:

{{{#!python
# Set a theme relative to the static/styles/jstree folder
settings.ui.hierarchy_theme = "default"
}}}

To hold the hierarchy theme e.g. in a template, specify a pathname relative to the application folder instead:

{{{#!python
# Set a theme relative to the application folder
settings.ui.hierarchy_theme = "modules/templates/TEMPLATE/theme/hierarchy"
}}}

== See Also ==

  - [wiki:S3/S3Hierarchy Hierarchy Toolkit]
  - [wiki:S3/FilterForms#S3HierarchyFilter S3HierarchyFilter]
  - [wiki:S3/S3HierarchyCRUD S3HierarchyCRUD]

----
- [wiki:S3 S3 API Guide]
- DeveloperGuidelines