getNavItem Application Delegate Class Method

Return to Application Delegate Class

Synopsis

The getNavItem() method of the application delegate class can be used to override the items that appear in the navigation menu (i.e. the menu that allows users to select the table via either tabs along the top or items along the side). It should return an associative array with characteristics of the navigation item including the href (i.e. link), label, and selected status.

Using this method it is now possible to have non-table navigation items as well. You would just add these items to the \[_tables\] section of the conf.ini file then override the item using this method.

Since 1.3

How the Nav Menu Is Built

Xataface builds the navigation menu by looping through each item in the [_tables] section of the conf.ini file, passing it to the getNavItem() method, and adding the resulting navigation item to the menu. If getNavItem() returns null, then that item will be skipped. If getNavItem throws an exception, then the default rendering for the menu item will take place.

Signature

function mixed getNavItem( string $key, string $label ) throws Exception

Parameters

• $key - The key of the nav item. In the case of a table, this would be the table name.
• $label - The label of the nav item (may be overridden).

Returns

This method should return either:

1. An associative array with the properties of the nav item.
2. null to indicate that this nav item should be omitted altogether. (e.g. if the user shouldn't have permission for it).

If returning an associative array, it should contain the following keys:

• href - (String) The URL where this nav item should point.
• label - (String) The label of this nav item.
• selected - (Boolean) True if the nav item is currently selected. False otherwise.

Throws

If you want to signal Xataface to just use default rendering for the current navigation item you can just throw an exception. The default rendering will link to the table named $key, and the item's label will be the same as $label.

Examples

Given the following conf.ini file:

...
[_tables]
   people=People
   books=Books
   accounts=Accounts
   reports=Reports

...

Suppose we want the navigation menu to only show the people and books options for regular users. Admin users can see all options.

In addition, the 'reports' option doesn't correspond with a table of the database. Instead we are just going to link it to a custom action named 'reports'.

Our getNavItem() method will look something like this:

function getNavItem($key, $label){
    if (!isAdmin() ){
        switch ($key){
            case 'people':
            case 'books':
                // non-admin users can see these
                throw new Exception("Use default rendering");
        }
        // Non-admin users can't see any other table.
        return null;
 
    } else {

        //Admin users can see everything..
        $query =& Dataface_Application::getInstance()->getQuery();
        switch ($key){
            case 'reports':
                // reports is not a table so we need to return custom properties.
                return array(
                    'href' => DATAFACE_SITE_HREF.'?-action=reports',
                    'label' => $label,
                    'selected' => ($query['-action'] == 'reports')
                );
            
        }
        

        // For other actions we need to make sure that they aren't selected
        // if the current action is reports because we want the 'reports'
        // tab to be selected only in that case.
        return array(
            'selected' => ($query['-table'] == $key and $query['-action'] != 'reports')
        );
    }
}

See Also

• isNavItemSelected? - Overrides default behavior of whether a navigation item is currently selected.