Creating dynamic tree structure menu systems

• Introduction
• A basic example
• The constructor function properties
• Node properties
• The short form of node configuration
• Customising the appearance with CSS

Introduction

The RGraph Tree object that was bundled with version 7.01 has a very useful capability that allows you to produce dynamic (or static) tree menu structures like the one shown here on the right. These have many uses - one of which could be showing the various options that are available to users of your online management system (instead of using a flat list of links.

The menu system is easy to configure and can be customised to fit your requirements. The code for a basic menu is shown below.

A basic example

<script src="RGraph.common.core.js" ></script>

<div id="myTree"></div>

<script>
    //
    // Create the tree structure object. The text that's
    // provided here becomes the root node.
    //
    structure = new RGraph.Tree('My treemenu');
    
    //
    // Add three first level nodes. Objects are used as
    // the arguments to the add function which contain
    // both the text label and the link that's used by
    // the node.
    //
    structure.add({text: 'Option one',link:'/option1/index.html'});
    structure.add({text: 'Option two',link:'/option2/index.html'});
    structure.add({text: 'Option three',link:'/option3/index.html'});
    
    //
    // Add another node but assign the result to a
    // variable. This is so that sub-nodes can then
    // be added to it.
    //
    option4 = structure.add('Option four');
    
    //
    // Now add the sub-nodes to the "Option 4" node.
    //
    option4.add({text: 'Sub-option1',link:'/option4/suboption1/index.html'});
    option4.add({text: 'Sub-option2',link:'/option4/suboption2/index.html'});
    option4.add({text: 'Sub-option3',link:'/option4/suboption3/index.html'});
        
    
    //
    // Now create the object that converts the menu
    // to a dynamic tree menu. The options shown below
    // can be used with this object in the options block.
    //
    new RGraph.Treemenu({
        id: 'myTree',
        data: structure,
        options: {
        }
    }).draw();
</script>

Pretty easy to configure as you can see and there's more options, detailed below, that are available to both the constructor function and also the tree nodes when you create them.

The constructor function options

These properties can be used in the constructor function and apply to the whole tree.

Name: id

Description: 

This is the ID of the DIV tag that you want the treemenu to be added to.

Default: [must be provided]

Name: dynamic

Description: 

If you don't want your tree to be dynamic (ie the branch expand/contract icons have no effect) then you can set this option to false.

Default: true

Name: persistent

Description: 

By default, the expanded and contracted state of the branches is persistent. This is done by using the localStorage variable in the browser (not cookies). By setting this option to false you can change this so that the expanded and contracted state is not remembered. The tree will still be dynamic (unless you've set the option above to false) but when the page is refreshed the state of the tree will return to what it was when it was initially defined.

Default: true

Name: images

Description: 

This can be an object of custom image paths (as shown below) that you want to use as the branch images. By default the image paths are data: URLs of 20x20 images so no external images are required. Your images should be 20x20 too or you'll need to force them to 20x20 using the CSS width and height properties. An example of using this property is:

new RGraph.Treemenu ({
    id: 'myTree',
    data: structure,
    options: {
       // These can be paths to images on your server or data: URLs
        images: {
            folder:       '...',
            folderexp:    '...',
            page:         '...',
            line:         '...',
            branch:       '...',
            branchtop:    '...',
            branchbottom: '...',
            plus:         '...',
            plusbottom:   '...',
            plustop:      '...',
            minus:        '...',
            minusbottom:  '...',
            minustop:     '...' 
        }
    }
}).draw();

Any of these images can also be set to none if you didn't want an image so you could do this:

<script>
    new RGraph.Treemenu ({
        id: 'myTree',
        data: structure,
        options: {
            images: {
                branchtop:    'none',
                branchbottom: 'none',
                branch:       'none',
                line:         'none',
                plustop:      'none',
                plusbottom:   'none',
                plus:         'none',
                minustop:     'none',
                minusbottom:  'none',
                minus:        'none'
            }
        }
    }).draw();
</script>

Name: style

Description: 

With this property you can add custom styles to the menu if you want. "div#XXX" where XXX is the ID of the containing DIV tag (that you give to the constructor function) is added to the start of the string if it's not there already to constrain the style to this menu. Read more about this property at the section below.

Default: null

Node properties

These properties can be used with the add() function when you add nodes to the tree and apply to that individual node.

Name: text

Description: 

This is the text that you see on your screen for the menu item.

Default: null

Name: dynamic

Description: 

As well as being able to give the dynamic option to the constructor function and control wether the whole menu is dynamic or not you can also give the dynamic option to a specific node and control whether that particular node is dynamic or not - not affecting the rest of the menu.

Default: null

Name: cssClass

Description: 

This allows you to give a CSS class that's added to the containing DIV tag for this node. This can help you to pin down a particular image in your CSS that you might want to change. For example if you set this to myNode for a particular node then you could then do this:

// ...
style: [
    'div.myNode img:last-of-type {opacity: 0.5;}'
]
// ...

Default: [none]

Name: image

Description: 

If you want this menu item to have a different icon to the default page icon you can use this option to specify a path for it. It can be a path to an image file on your server (for example /images/myImage.png) or it could be a data: URL. If you need to specify dimensions for the image you can do so with the CSS width and height properties - optionally using the style property in the constuctor function. The default image for a node with no children is a page icon: and the default image for a node with children is a folder:

Default: null

Name: expanded

Description: 

You can use this option to stipulate that a node is always expanded (or contracted), but this does not override whatever may be stored in the browsers localStorage area. So, initially, this option dictates whether a node is expanded or contracted but when the user changes it, the users choice is then remembered. You can change this behaviour with the prioritiseConfig option below.

Default: null

Name: prioritiseConfig

Description: 

By default, when you specify the expanded option for a node, when the user changes the state of the node (ie expanded or contracted) then that's what is remembered (the users choice). But by specifying this option you can overide that so that the users choice is ignored and your configuration is what's used to determine whether a node is contracted or expanded.

Default: null

The short form of node configuration

If your needs just consist of specifying the link and the text for a node then instead of just the text you can give both the text and a link separated by a colon instead of a whole object. This looks like this:

<script>
    structure = new RGraph.Tree('People');
    structure.add('Richard:https://www.richard.com');
    structure.add('Gabriel:https://www.gabriel.com');
    structure.add('Charles:https://www.charles.com');
    structure.add('Tommy:https://www.tommy.com');
    
    new RGraph.Treemenu({
        id: 'myTree',
        data: structure,
        options: {
        }
    }).draw();
</script>

Customising the appearance with CSS

In a similar way to the datagrid component, the tree menu visualisation can be customised by using the style property. This is an easy way of adding CSS that's applied to the tree menu instead of having it in a separate CSS file or in a separate style block in the page. An example of using it is:

<script>
    new RGraph.Treemenu({
        id: 'myTree',
        data: structure,
        options: {
            style: [
                /* Set the dimensions of the icon that we've provided */
                'div#myTree div img:last-of-type {width: 20px; height: 20px;}',
                
                /* Set the size of the text (that ISN'T a link) */
                'div#myTree div span.rgraph-tree-branch-label {font-size: 20pt;}',
                
                /* Set the size of the text (that IS a link) */
                'div#myTree div span.rgraph-tree-branch-label a {font-size: 20pt;}'
            ]
        }
    }).draw();
</script>

The div#myTree bit at the start of each rule isn't strictly necessary as if it's not there it will be added to restrict the CSS rule to this tree menu. This means that to apply something to the whole tree menu you can do this:

<script>
    new RGraph.Treemenu({
        id: 'myTree',
        data: structure,
        options: {
            style: [
                '{font-size: 20pt;}'
            ]
        }
    }).draw();
</script>

Or this (they're the same)

<script>
    new RGraph.Treemenu({
        id: 'myTree',
        data: structure,
        options: {
            style: [
                'div#myTree {font-size: 20pt;}'
            ]
        }
    }).draw();
</script>