= S3Hierarchy =
[[TOC]]

== Purpose ==

The S3Hierarchy toolkit can be used to perform lookups in hierarchical taxonomies. It analyses the parent-relationships of the records, and provides methods to access and search through the parent-, child- and sibling-axes of each record.

== Example ==

Facility type as an example for a hierarchical taxonomy:

  - Arts and Recreation
    - Recreation Centers
  - Community Groups
    - Volunteer Opportunities
  - Education
    - Adult Education
    - Guidance and Tutoring Programs
  - Health and Mental Health
    - Dental Care
    - Health Centers
    - Health Clinics
    - Health Screening and Testing
    - Hospitals and Medical Centers
    - Mental Health Counseling
    - Mental Health Programs
    - Public Health Programs
    - Substance Abuse Programs
  - Social Services
    - Children and Family Services
    - Public Information Services
    - Senior Services
    - Support Groups

== Data Model ==

To store a hierarchical taxonomy, the database table must include a parent reference (self-reference). This can either be a foreign key to the table, or - if the table is a super-entity instance - a (second) reference to the super-entity. 

The diagrams explain the two models:

[[Image(hierarchy_data_model.png)]]

== Configuration ==

The hierarchy is configured in the model as the field name of the parent reference:

{{{#!python
    self.configure(tablename, hierarchy="parent")
}}}

If categories (e.g. level) are to be used, the hierarchy is configured as tuple of parent reference and category field:

{{{#!python
    self.configure(tablename, hierarchy=("parent", "level"))
}}}

== Connecting to the Hierarchy ==

  - ''tbw''