Building Blocks

The menu is built using a combination of the following 4 types of building blocks:


Section

A section is a grouping of other related navigational elements. Technically, a section is simply a Python dictionary, with a specific set of expected values.

A section will consist of section text and any nodes that make up the remaining parts of the section. Neither the text nor the nodes are required.

For Example:

  • You can have no text and no nodes if you just want some extra space in the sidebar between other sections.

  • You can have text with no nodes if you only want a header.

  • You can have nodes without text if you want a blank header.

Generally speaking, the most common implementation will consist of defining both text and nodes.


Section Keys

The following are accepted keys used when defining a section menu block.

text

A string that represents the section text that a user will see.

Key

text

Type

string

Required

False

nodes

A list of node dictionaries that will render out each sidebar link, and/or a tree definition that contains additional nodes to render links.

Key

nodes

Type

list

Required

False

Section Example

{
    'text': 'Home',
    'nodes': []
}

Separator

A separator is a physical line separating one section from the next.

Technically, this is a section block with very specific properties. It has no text or node keys, and instead has a key called separator that is set to True.


Separator Keys

The following are required keys used when defining a separator menu block.

text

A blank string.

Key

text

Type

string

Required

True

nodes

An empty list.

Key

nodes

Type

list

Required

True

separator

Defined as True.

Key

separator

Type

bool

Required

True

Separator Example

{
    'text': '',
    'nodes': [],
    'separator': True,
}

Node

A node is a python dictionary that will create a clickable sidebar link. This includes a name and an icon in the sidebar.


Node Keys

The following are accepted keys used when defining a node menu block.

route

A valid Django route. If you are scaffolding your menu out and do not have a valid route yet, just enter a # as a placeholder.

Key

route

Type

string

Required

True

route_args

Any required args needed to be able to reverse the route.

Key

route_args

Type

list

Required

False

route_kwargs

Any required kwargs needed to be able to reverse the route.

Key

route_kwargs

Type

dict

Required

False

text

A string that represents what will be rendered for the user to see.

Key

text

Type

string

Required

False

icon

Either a Font-Awesome 4 or Font-Awesome 5 set of CSS classes. All required classes needed to make the icon show up must be listed.

Key

icon

Type

string

Required

False

hook

An optional string that represents the name of a fully qualified function. This function will be called to return the text to render for the node. This allows the ability to dynamically create the node’s text.

Key

hook

Type

string

Required

False

Note

Django-AdminLTE2-PDQ will try to import the value for this key as a function and then invoke the function and use its results as the text for the node.

The function should return either a string that will be used for both the text and the title text of the node, or a 2-tuple with string values for both text and title separately.

Tip

This hook is best used for making a few nodes in an otherwise static menu dynamic. If you need a lot of dynamic nodes, the information in the Advanced section might be more useful.

url

An optional string representing the URL for the link. If provided, it will take precedence over the URL generated from the required route key.

Key

url

Type

string

Required

False

Warning

This key is generally reserved for providing external URLs.

When defining internal URLs, it is strongly recommended that you avoid this key and instead, use the node’s route key.

Note

If you decide to use the url key, you must still provide the route key with a value of "#" as well since the sidebar is expecting that every node will have a route key.

Additionally, if this key is used, it will take precedence over the route key.

Tip

This url key is useful if you need to link to an external website rather then an internal link. External links must define any permissions directly on the node as there is no associated view to be able to pull permissions from. See the Authentication and Authorization Policy page for more information.

permissions

An optional list of permissions as strings. The user must have all listed permissions to see the node.

Key

url

Type

list

Required

False

Warning

In general, you should use the functionality defined on the Authorization pages to add permissions to a view rather than directly to a node. Defining the permissions directly on the view will handle both:

  • Hiding a node in the sidebar.

  • Preventing direct URL navigation, without the need to additionally set the permissions on this node key.

This key will NOT fully protect the link that the node is associated with.

Tip

This key may be useful when you have an external link that needs to also be shown or hidden based on a list of permissions.

one_of_permissions

An optional list of permissions as strings. The user must have at least one of these order to see the node.

Key

url

Type

list

Required

False

Warning

In general, you should use the functionality defined on the Authorization pages to add permissions to a view rather than directly to a node. Defining the permissions directly on the view will handle both:

  • Hiding a node in the sidebar.

  • Preventing direct URL navigation, without the need to additionally set the permissions on this node key.

This key will NOT fully protect the link that the node is associated with.

Tip

This key may be useful when you have an external link that needs to also be shown or hidden based on a list of permissions.

login_required

An optional key on the node specifying whether a user must be logged in to the system to see the node.

Key

url

Type

bool

Required

False

Warning

In general, you should use the functionality defined on the Authorization pages to add a login required criteria to a view, rather than directly to a node. Defining login_required on the view will handle both:

  • Hiding a node in the sidebar.

  • Preventing direct URL navigation without the need to additionally define that login is required on this node.

This key will NOT fully protect the link that the node is associated with.

Tip

This key may be useful when you have an external link that needs to also be shown or hidden based on the user being logged in.

Node Example

{
    'route': 'adminlte2_pdq:home',
    'text': 'Home',
    'icon': 'fa fa-dashboard',
}

Complex Node Example

Node

{
    'route': '#',
    'text': 'Github',
    'icon': 'fa fa-github',
    'url': 'https://github.com',
    'hook': 'core.utils.home_link_text',
    'permissions': ['is_developer'],
}

core/utils.py

def home_link_text(context):
    "Custom home link text"
    text = 'Home'
    if user.is_staff:
        text = 'Home!!!!!'
    return text

Tree

A tree is a python dictionary that will create an expandable entry with text and an icon in the sidebar. In addition, the tree will contain other nodes and/or trees as the children of the tree.

Trees can make a very large menu fit into a smaller space by utilizing the ability to expand and collapse each tree section.


Tree Keys

text

A string that represents what will be rendered for the user to see.

Key

text

Type

string

Required

False

icon

Either a Font-Awesome 4 or Font-Awesome 5 set of CSS classes. All required classes needed to make the icon show up must be listed.

Key

icon

Type

string

Required

False

nodes

A list of node dictionaries that will render out each sidebar link, or a tree that will contain more nodes.

Key

nodes

Type

list

Required

False

Tree Example

{
    'text': 'Sample Tree',
    'icon': 'fa fa-leaf',
    'nodes': [],
},

Tree Example with a Node

{
    'text': 'Sample Tree',
    'icon': 'fa fa-leaf',
    'nodes': [
        {
            'route': 'adminlte2_pdq:sample2',
            'text': 'Sample2',
            'icon': 'fa fa-building',
        },
    ],
},

Tree Example with sub-tree and a Node

{
    'text': 'Sample Tree',
    'icon': 'fa fa-leaf',
    'nodes': [
        {
            'text': 'Sub Tree',
            'icon': 'fa fa-box',
            'nodes': [
                {
                    'route': 'adminlte2_pdq:sample2',
                    'text': 'Sample2',
                    'icon': 'fa fa-building',
                },
            ],
        },
    ],
},