Changes between Version 5 and Version 6 of S3/S3Hierarchy


Ignore:
Timestamp:
05/21/14 21:26:31 (8 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3Hierarchy

    v5 v6  
    5555}}}
    5656
    57 == Connecting to the Hierarchy ==
    58 
    59   - ''tbw''
     57== Subset Definition ==
     58
     59To perform lookups in the hierarchy, you need to define a subset, which is an S3Hierarchy instance.
     60
     61With the tablename as only parameter, the subset would include all records in the hierarchical table (...which are accessible for the user):
     62
     63{{{#!python
     64subset = S3Hierarchy("hierarchical_type_table")
     65}}}
     66
     67To filter the records, a filter query can be specified as keyword parameter:
     68
     69{{{#!python
     70query = (FS("filter_field") == 5)
     71subset = S3Hierarchy("hierarchical_type_table, filter=query)
     72}}}
     73
     74== Performing Lookups ==
     75
     76All lookup attributes or methods of the subset use node IDs.
     77
     78The node IDs are either the record IDs (for simple self-reference) or the super-IDs (for super-entity self-reference) of the records in the subset.
     79
     80All lookup attributes and methods return either a single node ID (long), or a '''set''' of node IDs. The only exception is path() which returns an ordered list of node IDs.
     81
     82=== Root Nodes ===
     83
     84To get all root nodes of the subset, use:
     85
     86{{{#!python
     87# Returns a set of node IDs
     88root_nodes = subset.roots
     89}}}
     90
     91To get the root node for a particular node, use:
     92
     93{{{#!python
     94# Returns the root node ID for node_id (or node_id if it is a root node itself)
     95root = subset.root(node_id)
     96}}}
     97
     98=== Child Nodes ===
     99
     100To get all child nodes of a node, use:
     101
     102{{{#!python
     103# Returns the first generation of child nodes for node_id
     104children = subset.children(node_id)
     105}}}
     106
     107To get all descendants of a node, use:
     108
     109{{{#!python
     110# Returns all descendant nodes (any generation) for node_id
     111children = subset.findall(node_id)
     112}}}
     113
     114It is possible to use findall to get a union set of descendants for multiple parent nodes:
     115{{{#!python
     116# Returns all descendants in all specified nodes
     117children = subset.findall((node_id_1, node_id_2, node_id_3))
     118}}}
     119
     120=== Parent Nodes ===
     121
     122To get the parent node ID for a node, use:
     123
     124{{{#!python
     125# Returns the parent node ID for node_id (or None if node_id is a root node)
     126parent = subset.parent(node_id)
     127}}}
     128
     129=== Sibling Nodes ===
     130
     131To get all sibling node IDs for a node, use:
     132
     133{{{#!python
     134# Returns all sibling node IDs for node_id
     135siblings = subset.siblings(node_id)
     136}}}
     137
     138This does not normally return node_id itself, unless you specify inclusive=True:
     139
     140{{{#!python
     141# Returns all sibling node IDs for node_id - including node_id itself
     142siblings = subset.siblings(node_id, inclusive=True)
     143}}}
     144
     145=== Path ===
     146
     147The path of a node is an ordered list of all generations of parent node IDs from the root node down to the node itself. It can be requested by:
     148
     149{{{#!python
     150# Returns the path of a node (root node first) as ordered list
     151path = subset.path(node_id)
     152}}}
     153
     154== Using categories ==
     155
     156Categories can be used to classify nodes "horizontally", e.g. to indicate a hierarchy "level". To use them with the hierarchy toolkit, an additional category-field must be defined in the hierarchy configuration:
     157
     158{{{#!python
     159    self.configure(tablename, hierarchy=(parent_field, category_field))
     160}}}
     161
     162Categories are neither managed nor inferred by the hierarchy toolkit, but they can be used to filter the lookup axis.
     163
     164=== Filtering the Lookup Axis ===
     165
     166This is useful e.g. to find all descendants of a node of a specific category:
     167
     168{{{#!python
     169# Define a hierarchy of locations with "parent" as parent-reference and "level" as category
     170subset = S3Hierarchy("gis_location", hierarchy=("parent", "level"))
     171
     172# Lookup all descendants of location #3 with category "L3"
     173communes = subset.findall(3, category="L3", inclusive=True)
     174}}}
     175
     176When performing a root lookup, we may be interested in the closest parent of a particular category rather than the absolute root:
     177
     178{{{#!python
     179# Lookup the closest "L1" parent of location #454
     180state = subset.root(454, category="L1")
     181}}}
     182
     183This does also work with path lookups:
     184
     185{{{#!python
     186# Lookup the path of location #378 down from the closest "L1" parent
     187path = subset.path(378, category="L1")
     188}}}
     189
     190The category parameter can be used analogously with the children() and siblings() methods.
     191
     192=== Looking up the Category of a Node ===
     193
     194To lookup the category of a node, use:
     195
     196{{{#!python
     197# Returns the category for node_id (e.g. "L1")
     198category = subset.category(node_id)
     199}}}
     200
     201To get the category of each node in the result of the parent(), root(), path(), children(), findall(), or siblings() methods, use the classify-flag like:
     202
     203{{{#!python
     204# Returns the children of location #328 as set of tuples like: set([(367, "L3"), (368, "L3")])
     205children = subset.children(328, classify=True)
     206}}}
     207