UIZE JavaScript Framework

MODULES Uize.Dom.Tree

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Dom.Tree package provides convenience methods for generating a tree data object by analyzing HTML on a page.

DEVELOPERS: Chris van Rensburg

1.1. Examples

The following example pages are good showcases for the Uize.Dom.Tree module...

Get Tree from List - See how a tree data object can be generated by analyzing the structure and contents of a nested list defined by an HTML ul (unordered list) tag.
Get Tree from Page - See how a tree data object can be created by analyzing the occurrence of different CSS classes for section headings at different depths of a document.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Dom.Tree module...

SEARCH

1.2. Implementation Info

The Uize.Dom.Tree module defines the Uize.Dom.Tree package under the Uize.Dom namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Dom.Tree.getTreeFromList | Uize.Dom.Tree.getTreeFromPage

STATIC PROPERTIES

Uize.Dom.Tree.moduleName | Uize.Dom.Tree.pathToResources

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Dom.Tree module.

2. In a Nutshell

The Uize.Dom.Tree module provides convenient ways to derive a tree data object from HTML on a page.

2.1. Tree Data Object

A tree data object is an array, where each element of the array is a tree item.

Because a tree item may itself contain a child tree data object, specified by its items property, a tree data object can be used to represent an arbitrarily complex, hierarchical structure for information.

2.2. Using a Tree Data Object

A tree data object can be used in any number of ways, but is commonly used for building tree-based user interface elements such as contents lists, structured dropdown menus, etc.

A number of widget class support data in the tree data object format, such as the Uize.Widget.Tree.List, Uize.Widget.Tree.Menu, and Uize.Widget.Tree.Select classes. Outside of widgets, tree data objects can be used to drive the generation of HTML, in build scripts or Web applications, using JavaScript Templates. To see tree data objects in action, see the Tree List From JSON and Tree Menu From JSON examples.

2.3. Tree Item

A tree item is a single item in an array of items that make up a tree data object.

Any tree item may contain a subtree, which is itself a tree data object, specified by the items property. A tree item has the following structure...

ITEM STRUCTURE

{
  title       : titleSTR,         // required
  link        : linkUrlSTR,       // optional
  description : descriptionSTR,   // optional
  items       : childItemsARRAY,  // optional
  expanded    : expandedBOOL      // optional, defaults to true
}

2.3.1. title

A string, specifying the display title for the item.

2.3.2. link

An optional string, specifying the URL that the item should link to.

For items that should execute JavaScript code, a link with the javascript: protocol can be used.

2.3.3. description

An optional string, specifying description text for the item.

2.3.4. items

An optional array, specifying the tree data object for a subtree, where each element in the array is an item.

An empty array value for this property is equivalent to the values null or undefined, and indicates that the item does not have a subtree.

2.3.5. expanded

An optional boolean, specifying whether or not a subtree specified by the items property is expanded.

When this property is omitted, its value is defaulted to true. Therefore, for a subtree to be collapsed, the expanded property must be explicitly set to false.

2.4. Getting a Tree From a List Element

To generate a tree data object from a hierarchical list defined by an HTML ul (unordered list) or ol (ordered list) tag, the Uize.Dom.Tree module provides the Uize.Dom.Tree.getTreeFromList static method.

This method is able to scan through the structure and contents of a list element and build a data structure that reflects the structure of the list. All the method needs in order to work its magic is a reference to

(or id for) either a list node or the immediate parent node of a list node. The method can handle unordered lists as well as ordered lists. From the list HTML that it analyzes, the method is able to build a tree data object where each item will have a title property, and may also have link, description, items, and expanded properties.

2.4.1. An Example

The following sample code blocks show the source HTML, JavaScript code, and output tree data object for the Get Tree from List example.

HTML

JAVASCRIPT

Uize.Dom.Tree.getTreeFromList (page.getNode ('list'));

OUTPUT

[
  {
    title:'Dogs',
    items:[
      {
        title:'Small Breeds',
        items:[
          {
            title:'West Highland White',
            link:'http://en.wikipedia.org/wiki/West_Highland_White_Terrier'
          },
          {
            title:'Mexican Hairless',
            link:'http://en.wikipedia.org/wiki/Mexican_Hairless_Dog'
          },
          {
            title:'Miniature Chihuahua',
            link:'http://en.wikipedia.org/wiki/Chihuahua_%28dog%29'
          },
          {
            title:'Teacup Poodle',
            link:'http://en.wikipedia.org/wiki/Teacup_Poodle#Poodle_sizes'
          }
        ]
      },
      {
        title:'Large Breeds',
        items:[
          {
            title:'Afghan',
            link:'http://en.wikipedia.org/wiki/Afghan_Hound'
          },
          {
            title:'Great Dane',
            link:'http://en.wikipedia.org/wiki/Great_Dane'
          },
          {
            title:'Irish Wolfhound',
            link:'http://en.wikipedia.org/wiki/Irish_Wolfhound'
          },
          {
            title:'St. Bernard',
            link:'http://en.wikipedia.org/wiki/St._Bernard_%28dog%29'
          }
        ]
      }
    ]
  },
  {
    title:'Cats',
    items:[
      {
        title:'Persian',
        link:'http://en.wikipedia.org/wiki/Persian_%28cat%29'
      },
      {
        title:'Siamese',
        link:'http://en.wikipedia.org/wiki/Siamese_%28cat%29'
      },
      {
        title:'Hairless',
        link:'http://en.wikipedia.org/wiki/Hairless_cat'
      }
    ]
  },
  {
    title:'Other',
    items:[
      {
        title:'Bunny',
        link:'http://en.wikipedia.org/wiki/Bunny'
      },
      {
        title:'Hamster',
        link:'http://en.wikipedia.org/wiki/Hamster'
      },
      {
        title:'Mouse',
        link:'http://en.wikipedia.org/wiki/Mouse'
      },
      {
        title:'Rat',
        link:'http://en.wikipedia.org/wiki/Rat'
      }
    ]
  }
]

2.4.2. Deriving Item Property Values

Values for item properties are derived in a number of different ways, depending on the property.

2.4.2.1. Deriving the title Property's Value

The value of the title item property is derived by getting the cumulative text contained inside an item node, without regard to HTML elements used in formatting the item node, and excluding the text contained inside nested lists.

EXAMPLE

  • This is the item title
  
      
    
    • This is nested item 1
      • 
    
    • This is nested item 2
      • 
  
    

    •

    If the above HTML were the HTML for a tree item, then the value derived for the title property of the item would be "This is the item title". For one thing, the span and b tags would be stripped out, and only the unformatted / unmarked up text would be retained. And, secondly, the text contents of the nested ul tag would be ignored and would not contribute to the tree item's derived title.

    2.4.2.2. Deriving the link Property's Value

    The value of the link property is derived from the href property of an item's node, if this node is a link tag.

    EXAMPLE

  • HOME
  

    •

    If the above HTML were the HTML for a tree item, then the value derived for the link property of the item would be "http://uize.com". It doesn't matter that there are multiple link tags in the HTML, since the two other link tags belong to a nested ul tag - only the first link tag will be used when deriving the value for the item's link property. Note that not all items need to be linked - for item nodes that are not link tags, the value of the link property will not be set and the link property will not be present in the tree item.

    2.4.2.3. Deriving the description Property's Value

    The value of the description property is derived from the "title" attribute of an item's node, if this node is a link tag.

    EXAMPLE

  • HOME
  

    •

    If the above HTML were the HTML for a tree item, then the value derived for the description property of the item would be "UIZE JavaScript Framework". It doesn't matter that there are multiple link tags in the HTML, since the two other link tags belong to a nested ul tag - only the first link tag will be used when deriving the value for the item's description property.

    Note that not all items need to be linked - for item nodes that are not link tags, the value of the description property will not be set and the description property will not be present in the tree item. Similarly, for item nodes that are link tags, but that do not have a "title" attribute specified, or that have an empty string specified for the "title" attribute, the description property will not be present in the tree item.

    2.4.2.4. Deriving the items Property's Value

    The value of the items property is derived from the first ul (unordered list) or ol (ordered list) tag encountered in an item's node.

    EXAMPLE

  • HOME
  

    •

    If the above HTML were the HTML for a tree item, then the value derived for the items property of the item would be an array with the following structure...

    [
  {
    title:'Download',
    link:'http://uize.com/download.html'
  },
  {
    title:'Site Map',
    link:'http://uize.com/directory.html'
  }
]

    It doesn't matter that there is HTML content ahead of the nested ul tag - that content will be ignored when deriving the value for the items property, but it will be used when deriving values for the title, link, and description properties of the tree item object. Note that not every item needs to have a subtree - in most cases, the majority will not. For item nodes that do not contain nested list tags, the value of the items property will not be set and the items property will not be present in the tree item.

    2.4.2.5. Deriving the expanded Property's Value

    The value of the expanded property is derived from the value of the display CSS property of the first ul (unordered list) or ol (ordered list) tag encountered in an item's node.

    EXAMPLE

  • HOME
  

    •

    If the above HTML were the HTML for a tree item, then the value derived for the expanded property of the item would be false. The rule is simple: if the list tag that represents the items in the subtree for an item is set to display:none, either through inline CSS in a style attribute, or in a style rule in an external style sheet, then the value of the expanded property will be false. Note that not every item needs to have a subtree - in most cases, the majority will not. For item nodes that do not contain nested list tags, the expanded property will not be present in the tree item. Also, for any item that does have a subtree and where the subtree is expanded, the value of the expanded property will be true and the property will not be present in the tree item, since true is the default value for this property.

    2.5. Getting a Tree From a Page's Section Headings

    To generate a tree data object from the section headings contained inside a document, the Uize.Dom.Tree module provides the Uize.Dom.Tree.getTreeFromPage static method.

    This method is able to scan through all the nodes inside a document, building a data structure that reflects the structure of the document by analyzing the occurrence of different CSS classes for section headings at different depths of a document. All this method needs in order to work its magic is an array specifying the names of CSS classes that identify section headings at different depths (section heading nodes may be of any type, including div, span, p, etc.). From the document HTML that it analyzes, the method is able to build a tree data object where each item will have title and link properties, and may also have description and items properties.

    2.5.1. An Example

    The following sample code blocks show the source HTML, JavaScript code, and output tree data object for the Get Tree from Page example.

    HTML

    
  1. Renewable Energy

    
  
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    1.1. Solar Power
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    1.2. Wind Power
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    1.3. Biofuels
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    

    
  2. Fossil Fuels

    
  
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    2.1. Peak Oil
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    2.2. Types of Fossil Fuel
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
    
    
      2.2.1. Oil
    
    
      
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
    
    
      2.2.2. Natural Gas
    
    
      
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    2.3. Climate Change
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW
    
  
    
    2.4. Energy Security
  
    
    
    WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW WWW

    JAVASCRIPT

    Uize.Dom.Tree.getTreeFromPage (['level1Header','level2Header','level3Header'],Infinity);

    OUTPUT

    [
  {
    title:'Contents',
    items:[
      {
        title:'1. Renewable Energy',
        link:'http://uize.com/examples/get-tree-from-page.html#sect1',
        description:'All about renewable energy technologies',
        items:[
          {
            title:'1.1. Solar Power',
            link:'http://uize.com/examples/get-tree-from-page.html#sect1_1',
            description:'An introduction to solar power'
          },
          {
            title:'1.2. Wind Power',
            link:'http://uize.com/examples/get-tree-from-page.html#sect1_2',
            description:'An introduction to wind power'
          },
          {
            title:'1.3. Biofuels',
            link:'http://uize.com/examples/get-tree-from-page.html#sect1_3',
            description:'An introduction to biofuels'
          }
        ]
      },
      {
        title:'2. Fossil Fuels',
        link:'http://uize.com/examples/get-tree-from-page.html#sect2',
        description:'All about fossil fuel technologies',
        items:[
          {
            title:'2.1. Peak Oil',
            link:'http://uize.com/examples/get-tree-from-page.html#sect2_1',
            description:'An introduction to the concept of peak oil'
          },
          {
            title:'2.2. Types of Fossil Fuel',
            link:'http://uize.com/examples/get-tree-from-page.html#sect2_2',
            description:'A look at different types of fossil fuels',
            items:[
              {
                title:'2.2.1. Oil',
                link:'http://uize.com/examples/get-tree-from-page.html#sect2_2_1',
                description:'A look at the history and future of oil'
              },
              {
                title:'2.2.2. Natural Gas',
                link:'http://uize.com/examples/get-tree-from-page.html#sect2_2_2',
                description:'An introduction to natural gas'
              }
            ]
          },
          {
            title:'2.3. Climate Change',
            link:'http://uize.com/examples/get-tree-from-page.html#sect2_3',
            description:'Climate change and fossil fuels'
          },
          {
            title:'2.4. Energy Security',
            link:'http://uize.com/examples/get-tree-from-page.html#sect2_4',
            description:'Fossil fuels and energy security'
          }
        ]
      }
    ]
  }
]

    2.5.2. Deriving Item Property Values

    2.5.2.1. Deriving the title Property's Value

    The value of the title item property is derived by getting the cumulative text contained inside an item's heading node, without regard to HTML elements used in formatting the heading text, and then stripping leading and trailing whitespace.

    EXAMPLE

    
  
    2.
   Static Methods

    If the above HTML were the HTML for a tree item heading node, then the value derived for the title property of the item would be "2.1. Tree Data Object" - the span and a tags would be stripped out, and only the unformatted / unmarked up text would be retained. Note also that the leading and trailing whitespace resulting from the indentation of the HTML tags would be stripped as well.

    2.5.2.2. Deriving the link Property's Value

    The value of the link property is derived from the id attribute of an item's heading node, by concatenating the value of the id attribute at the end of the value of the location object's href property, with the two parts separated by a "#" (pound / hash) character.

    EXAMPLE 1

    
  
    2.
   Static Methods

    If the above HTML were the HTML for a tree item heading node, and if the value of the location object's href property was "http://uize.com", then the value derived for the link property of the item would be "http://uize.com#sect2".

    For heading nodes that do not have an id specified, an ID will be dynamically generated and assigned to the node. The generated ID will be constructed by combining the prefix "Uize_Node_Tree_" with a suffix that indicates the "path" of the section or subsection in the overal hierarchical structure of the document. The format for the suffix is [sectionNo]_[subsectionNo]_[subSubsectionNo]..., where the numbering for sections at any level in the tree structure is one-based (not zero-based). In order words, the generated suffix for the third subsection of the second section of a document would "2_3", where "2" represents the second section, and "3" represents the third subsection.

    Consider the following example...

    EXAMPLE 2

    
  2. Static Methods

    In the above example, assuming that the heading was for the second section of the document, then the value derived for the link property of the item would be "http://uize.com#Uize_Node_Tree_2".

    2.5.2.3. Deriving the description Property's Value

    The value of the description property is derived from the "title" attribute of an item's heading node.

    EXAMPLE

    
  
    2.
   Static Methods

    If the above HTML were the HTML for a tree item heading node, then the value derived for the description property of the item would be "2. Static Methods". For item heading nodes that do not have a "title" attribute specified, or that have an empty string specified for the "title" attribute, the value of the description property will not be set and the description property will not be present in the tree item.

    2.5.2.4. Deriving the items Property's Value

    The value of the items property is derived from all tree item heading nodes following the current item's heading node, that are at the immediately deeper level in the document structure, and up until the very next heading node that is at the same level as or at a shallower level than the current item.

    So, for example, if an item is a section, then the items in that section will be derived by finding all heading nodes following the section heading node that are subsection heading nodes, up until the next section heading node. Consider the following example...

    EXAMPLE

    
  
    2.
   Static Methods

    


    
  
    
    
      2.
      1.
     Uize.callOn
  
    

  
    
    ...
  
    

  
    
    
      2.
      2.
     Uize.capFirstChar
  
    

  
    
    ...

    If the above HTML were the HTML for a tree item, then the value derived for the items property of the item would be an array with the following structure...

    [
  {
    title:'2.1. Uize.callOn',
    link:'http://uize.com/reference/Uize.html#sect2_1',
    description:'2. Static Methods -> 2.1. Uize.callOn'
  },
  {
    title:'2.2. Uize.capFirstChar',
    link:'http://uize.com/reference/Uize.html#sect2_2',
    description:'2. Static Methods -> 2.2. Uize.capFirstChar'
  }
]

    Note that not every item needs to have a subtree - in most cases, the majority will not. For items that do not, the value of the items property will not be set and the items property will not be present in the tree item. In our above example, this is the case for the items for sections 2.1 and 2.2.

    2.5.2.5. Deriving the expanded Property's Value

    When using the Uize.Dom.Tree.getTreeFromPage method, the value of the expanded property is derived from the value of the method's initialExpandedDepthINT parameter and the level of the current item.

    The initialExpandedDepthINT parameter specifies the depth to which the generated tree data object should be expanded, so the value of the expanded property for any tree item will be true if the depth level of that item is less than or equal to the value of the initialExpandedDepthINT parameter. Put another way, a value of 1 for the initialExpandedDepthINT parameter will result in the generated tree data object being expanded to only one level deep, while the value 2 will result in the tree data object being expanded to two levels deep.

    So, for example, if sections of a document are considered to be at level 1, and subsections of a document are considered to be at level 2, then the value 2 for the initialExpandedDepthINT parameter will result in all section and subsection items in the generated tree data object being expanded, the value 1 will result in only section items being expanded, and the value 0 will result in all items being collapsed. If you wish all levels of the tree to be expanded, then you can specify the value Infinity for the initialExpandedDepthINT parameter. If you wish all levels to be collapsed, then you can specify any value less than 1.

    NOTE

    Note that for any item that is expanded, the value of the expanded property will be true and the property will not be present in the tree item, since true is the default value for this property.

    3. Static Methods

    3.1. Uize.Dom.Tree.getTreeFromList

    Returns a tree data object, generated by analyzing the structure and contents of a hierarchical list defined by an HTML ul (unordered list) or ol (ordered list) tag.

    SYNTAX

    treeOBJ = Uize.Dom.Tree.getTreeFromList (nodeSTRorOBJ);

    The nodeSTRorOBJ parameter should specify either a list node (i.e. a ul or ol tag) or the immediate parent node of a list node. List type (unordered or ordered) does not affect the data in the tree data object returned by this method, and a hierarchical list can mix different types of lists.

    EXAMPLE

    For an example showing how this method is used, consult the section Getting a Tree From a List Element.

    NOTES

    compare to the Uize.Dom.Tree.getTreeFromPage static method

    IMPLEMENTATION INFO

    this feature was introduced in this module

    3.2. Uize.Dom.Tree.getTreeFromPage

    Returns a tree data object, generated by analyzing the occurrence of different CSS classes for section headings at different depths of a document.

    SYNTAX

    treeOBJ = Uize.Dom.Tree.getTreeFromPage (levelClassesARRAY,initialExpandedDepthINT);

    Provided that unique CSS classes are used for styling section headings differently at different levels in a document's structure, then the Uize.Dom.Tree.getTreeFromPage method can be used to glean a contents tree for a document by scanning through the elements of the document and watching for the CSS classes that denote section headings.

    VARIATION

    treeOBJ = Uize.Dom.Tree.getTreeFromPage (levelClassesARRAY);

    When the initialExpandedDepthINT parameter is not specified, then the value 1 will be used as the default for this parameter.

    EXAMPLE

    For an example showing how this method is used, consult the section Getting a Tree From a Page's Section Headings.

    3.2.1. Parameters

    The Uize.Dom.Tree.getTreeFromPage method supports the following parameters...

    3.2.1.1. levelClassesARRAY

    An array of string type elements, representing the CSS class names that identify section headings for different levels of a document.

    The first element in this array specifies the CSS class name for top level section headings, the second element specifies the CSS class name for subsection headings, the third element specifies the CSS class name for sub-subsection headings, and so on. The Uize.Dom.Tree.getTreeFromPage method supports documents with an arbitrary number of section levels.

    3.2.1.2. initialExpandedDepthINT

    An integer, specifying the depth to which the generated tree data object should be expanded.

    If you wish all levels of the tree to be expanded, then you can specify the value Infinity for the initialExpandedDepthINT parameter. If you wish all levels to be collapsed, then you can specify any value less than 1.

    NOTES

    compare to the Uize.Dom.Tree.getTreeFromList static method

    IMPLEMENTATION INFO

    this feature was introduced in this module

    4. Static Properties

    4.1. Uize.Dom.Tree.moduleName

    IMPLEMENTATION INFO

    this feature was introduced in this module

    4.2. Uize.Dom.Tree.pathToResources

    IMPLEMENTATION INFO

    this feature was introduced in this module