PxNav

Basic

For the proper positioning, place the .px-navs before .px-navbar and .px-content elements.

Add .px-nav-left or .px-nav-right to the .px-nav element to place it left or right.

Page content.

Dropdowns

Labels

Nav-box

Use .px-nav-box elements to add custom content.

Page content.

Collapsed by default

If you want make the .px-nav element collapsed by default, just add the .px-nav-collapse class to the .px-nav.

Page content.
Note: Even if you set the .px-nav-collapse class, it will have effect only if the nav state is not stored before, because the PxNav plugin restores the previous nav state by default. To prevent this behaviour, you need to turn off the storeState option.
Page content.

Off canvas

Add the .px-nav-off-canvas class to hide the .px-nav when collapsed. If you want hide the nav only on large and extra large screen sizes, use the .px-nav-off-canvas-desktops class instead of .px-nav-off-canvas.

Page content.
Page content.

Static

Add the .px-nav-static class to the .px-nav to make all .px-nav-dropdowns permanently expanded.

Disabled accordion behaviour

Disabled tooltips

Page content.

Disabled animations

Fixed

To make the nav fixed, add the .px-nav-fixed class.

You also need to make the navbar fixed.

<body class="px-navbar-fixed">
  <nav class="px-nav px-nav-fixed">
    ...
  </nav>

  <nav class="navbar px-navbar">
    ...
  </nav>

  <div class="px-content">
    ...
  </div>
</body>
        

Initializing

PxNav plugin is initialized on pre-existing markup.

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, for example: <nav class="px-nav px-nav-left" data-accordion="false" data-store-state="false">...</nav>.

$('.px-nav').pxNav(options);
        

Option Default Description
accordion true Enable accordion behaviour.
transitionDuration 300 Transition duration (milliseconds) - used for the transition fallback. Must be equal to SCSS's variable $px-nav-transition-duration.
dropdownCloseDelay 400 Delay in milliseconds before closing a dropdown menu (after mouseleave event triggered).
enableTooltips true Enable tooltips.
animate true Enable animations.
storeState true Store/restore the nav state.
storagePrefix 'px-nav.' Storage key prefix.
modes {
  phone: ['xs'],
  tablet: ['sm', 'md'],
  desktop: ['lg', 'xl'],
}
The nav mode breakpoints. See more info below.

Usage


require(['jquery', 'px/plugins/px-nav'], function($) {
  ...
});
        

Explanation of modes

The PxNav plugin works in three modes:

The nav modes are activated according to the current viewport breakpoint. Look at the modes config option:

For example, to activate desktop mode (instead of tablet mode) on medium screen sizes:

  1. Edit the _variables.scss file and assign a lower breakpoint value to the $px-nav-tablets-breakpoint/$px-nav-desktops-breakpoint variable (according to the mode which you want to change):

    
    // Default:
    //   $px-nav-desktops-breakpoint: $screen-lg-min;
    
    $px-nav-desktops-breakpoint: $screen-md-min;
                
  2. Recompile SCSS.
  3. Init the PxNav plugin with updated config:

    
    // Default:
    //   tablet: [ 'sm', 'md' ]
    //   desktop: [ 'lg', 'xl' ]
    
    $('.px-nav').pxNav({
      modes: {
        tablet:  [ 'sm' ],
        desktop: [ 'md', 'lg', 'xl' ],
      },
    });
                

Methods

You can call a public method of PxNav instance using the syntax:


$('.px-nav').pxNav('methodName');
        

[1] The parameter can be a string, jQuery object or DOM element. For example the next calls are equivalent:


$('.px-nav').pxNav('activateItem', '#some-nav-item');
$('.px-nav').pxNav('activateItem', $('#some-nav-item'));
$('.px-nav').pxNav('activateItem', document.getElementById('some-nav-item'));
          

[2] Root dropdown - a dropdown which is a direct child of the .px-nav-content element:


<nav class="px-nav">
  <ul class="px-nav-content">
    <li class="px-nav-item px-nav-dropdown"> <!-- Root dropdown -->
      <a href="#">...</a>
      <ul class="px-nav-dropdown-menu">
        <li class="px-nav-item px-nav-dropdown">...</li>
        <li class="px-nav-item px-nav-dropdown">...</li>
      </ul>
    </li>
    <li class="px-nav-item px-nav-dropdown"> <!-- Root dropdown -->
      <a href="#">...</a>
      <ul class="px-nav-dropdown-menu">
        <li class="px-nav-item px-nav-dropdown">...</li>
        <li class="px-nav-item px-nav-dropdown">...</li>
      </ul>
    </li>
  </ul>
</nav>
          

Method name Description
toggle Toggle the nav state.
expand Expand the nav.
collapse Collapse the nav.
isFixed Returns true if the nav is fixed, otherwise returns false.
isStatic Returns true if the nav has the .px-nav-static class, otherwise returns false.
isCollapsed Returns true if the nav is collapsed, otherwise returns false.
activateItem(el[1])

Make the el active and expand all parent dropdowns. All other active nav items will be deactivated.

Note: The el must have the .px-nav-item class. Dropdowns cannot be activated.
openDropdown(el[1], showDropdown = true)

Show/expand the el and show/expand all parent dropdowns.

If the el is a root dropdown[2] and the nav is collapsed and showDropdown=false then nothing will happen.

If the el is not a root dropdown[2] and the nav is collapsed and showDropdown=false then all parent non-root dropdowns will be expanded, but the parent root dropdown will not be shown.

Note: The el must have the .px-nav-dropdown class.
closeDropdown(el[1])

Hide/collapse the el.

Note: The el must have the .px-nav-dropdown class.
toggleDropdown(el[1])

Open/hide the el (see the openDropdown and closeDropdown methods).

Note: The el must have the .px-nav-dropdown class.
closeAllDropdowns(parent[1] = $('.px-nav-content'))

Close all opened dropdowns inside the parent. If the method is called without parameters then all opened nav dropdowns will be closed.

Note: The parent must have the .px-nav-dropdown class.
freezeDropdown(el[1])

Freeze the el. When the nav is collapsed and the mouse pointer leaves an opened root dropdown[2], the "normal" (non-frozen) dropdown will be closed on a timer. The frozen dropdown prevents this behaviour.

Note: The el must have the .px-nav-dropdown class.
unfreezeDropdown(el[1])

Unfreeze the el.

Note: The el must have the .px-nav-dropdown class.
isFloatingDropdown(el[1])

Returns true if the nav is collapsed and the el is a root dropdown[2], otherwise returns false.

Note: The el must have the .px-nav-dropdown class.
getDropdownContainer(el[1])

Returns the dropdown container. If the el is a floating dropdown and shown then returns the .px-nav-dropdown-menu-wrapper element, otherwise returns the .px-nav-dropdown-menu element.

Note: The el must have the .px-nav-dropdown class.
isDropdownOpened(el[1])

Returns true if the el is opened, otherwise returns false.

Note: The el must have the .px-nav-dropdown class.
isDropdownFrozen(el[1])

Returns true if the el is frozen, otherwise returns false.

Note: The el must have the .px-nav-dropdown class.
append(item, parent[1] = $('.px-nav-content')) Insert the item to the end of the parent element. See the insert method.
prepend(item, parent[1] = $('.px-nav-content')) Insert the item to the beginning of the parent element. See the insert method.
insert(item, position, parent[1] = $('.px-nav-content')))

Insert the item at the position in the parent element.

The item can be an HTML string, jQuery object or DOM element.

The position is a number. The index of the first item is 0, and the index of the last item is numberOfItems - 1. If the position paremeter is not passed or equals to null then the item will be inserted to the end of the parent element, else the item will be inserted before the given position.

The parent must have the .px-nav-dropdown class. If the parent paremeter is not passed then the item will be inserted into the .px-nav-content element (root).

Examples:


// Insert an item to the beginning of the root (use prepend instead)
$('.px-nav').pxNav('insert', '
  • Some item
  • ', 0); // Insert an item to the end of the root (use append instead) $('.px-nav').pxNav('insert', $('
  • Some item
  • ')); // Insert an item before the third item in the root $('.px-nav').pxNav('insert', '#item-to-insert', 2); // Insert an item to the beginning of the specified dropdown (use prepend instead) $('.px-nav').pxNav('insert', '
  • Some item
  • ', 0, '#targeted-dropdown'); // Insert an item to the end of the specified dropdown (use append instead) $('.px-nav').pxNav('insert', $('
  • Some item
  • ', $('#targeted-dropdown'))); // Insert an item before the third item in the specified dropdown $('.px-nav').pxNav('insert', '#item-to-insert', 2, document.getElementById('targeted-dropdown')); // Insert an item before the specified item var indexToInsertBefore = $('#targeted-item').parent().find('> .px-nav-item').index($('#targeted-item')); $('.px-nav').pxNav('insert', '#item-to-insert', indexToInsertBefore); // Insert an item after the specified item var indexToInsertAfter = $('#targeted-item').parent().find('> .px-nav-item').index($('#targeted-item')) + 1; $('.px-nav').pxNav('insert', '#item-to-insert', indexToInsertAfter); // Insert a dropdown $('.px-nav').pxNav('insert', '
  • Some dropdown
    • '); // Insert several items $('.px-nav').pxNav('insert', '
    • Some item
    • Some item
    • Some item
    • '); $('.px-nav').pxNav('insert', $('
    • Some item
    • Some item
    • Some item
    • '));
      remove(item[1])

      Remove the item.

      Note: The item must have the .px-nav-item class.
      destroy Destroy the PxNav instance.

      Events

      You can subscribe on PxNav events using the syntax:

      
      $('.px-nav').on('event.px.nav', function(e) {
        // ...
      
        // Preventable events can be prevented:
        // e.preventDefault();
      });
              

      Events marked with * are preventable.
      Event Description
      expand*

      This event is fired immediately when the expand() method is called.

      expanded

      This event is fired when the nav has expanded.

      collapse*

      This event is fired immediately when the collapse() method is called.

      collapsed

      This event is fired when the nav has collapsed.

      destroy*

      This event is fired immediately when the destroy() method is called.

      dropdown-open*

      This event is fired immediately when the openDropdown() method is called.

      dropdown-opened

      This event is fired when the dropdown has opened.

      dropdown-close*

      This event is fired immediately when the closeDropdown() method is called.

      dropdown-closed

      This event is fired when the dropdown has closed.

      dropdown-frozen

      This event is fired when the dropdown has frozen.

      dropdown-unfrozen

      This event is fired when the dropdown has unfrozen.

      In addition, you can subscribe on initialized event, which is fired when a nav is initialized:

      
      $('.px-nav').on('initialized', function() {
        // ...
      });
              

      Control Examples

        DOM Manipulation Examples

        Page content.

        Usage

        To use PxNav plugin, you need to include the next scripts:

        
        <script src="path/to/js/pixeladmin/plugins/px-nav.js"></script>
        <script src="path/to/js/pixeladmin/directives/angular-px-nav.js"></script>
                

        Then inject the plugin into your angular application:

        angular.module('yourApp', ['px-nav']);

        Alternatively, you can include PxNav plugin using ocLazyLoad plugin:

        
        $ocLazyLoad.load([
          {
            name: 'px-nav',
            files: [
              'path/to/js/pixeladmin/plugins/px-nav.js',
              'path/to/js/pixeladmin/directives/angular-px-nav.js',
            ],
          },
        ]);
                

        px-nav directive

        Specify template-url attribute on the element to load nav content from a template.

        NOTE: The template-url attribute expects an angular expression instead of a literal string.

        
        <px-nav>...content...</px-nav>
        <px-nav template-url="'path/to/nav/template.html'"></px-nav>
                  

        You can use px-nav directive where you want. And when the scope is destroyed the directive will be destroyed.

        Page content.

        Instance

        You can define instance attribute to get a pointer to PxNav element:

        
        <px-nav instance="ctrl.$nav">...</px-nav>
                
        
        function SomeController() {
          // Pointer
          this.$nav = null;
        
          // ...
        
          // Then, after the initialization, you can call plugin methods:
          this.$nav('expand');
          this.$nav('isFixed');
          this.$nav('append', $item);
        });
                

        Options

        PxNav's options can be specified as attributes. All options expect an angular expression instead of a literal string.

        • accordion
        • animate
        • dropdown-close-delay
        • enable-tooltips
        • modes
        • storage-prefix
        • store-state
        • transition-duration
        
        <px-nav accordion="false"
                enable-tooltips="false"
                storage-prefix="'main-nav.'">...</px-nav>
                

        Events

        Event handlers can be bound using attributes:

        • on-collapse
        • on-collapsed
        • on-destroy
        • on-dropdown-close
        • on-dropdown-closed
        • on-dropdown-frozen
        • on-dropdown-open
        • on-dropdown-opened
        • on-dropdown-unfrozen
        • on-expand
        • on-expanded
        
        <px-nav on-collapse="ctrl.collapse"
                on-dropdown-open="ctrl.dropdownOpen">...</px-nav>
                
        
        function SomeController() {
          this.collapse = function(e) { ... }
          this.dropdownOpen = function(e) { ... }
        });