Navbar Review

[cgack]

Navbar Review

Description

A jQuery Mobile Widget that creates a row (bar) of buttons. The buttons are created from an unordered list of links wrapped in a container element with data-role=”navbar”. The buttons can contain text, icons, or text + icon.

Functional Specification

Navbar should extend the full available width of the viewport with a maximum number of buttons which, once reached, will:

• "smart" stack the buttons. Not just in n rows of 2 columns, but in n rows of the maxbutton columns and then evenly distribute the remainder
• if the morebutton option is set to true - trigger display of a "viewmore" button to indicate there are more buttons available. When "viewmore" is selected the remaining buttons will become visible in a popup. This morebutton functionality will be an extension to the navbar widget

Responsive Design Considerations

• Ensure that the navbar adapts to various viewport sizes
• possibly ensure that the default max number of buttons responds to relative screen size (i.e. 5 buttons for small/medium , 8 for larger layouts)
• demo to highlight the ability to alter maxbuttons on throttledresize

Performance Considerations

Accessibility Considerations

Ensure that the navbar receives the role="navigation" attribute - spec

Navigation Considerations

Options

• iconpos
  • sets the position of the icons
  • default: top
• maxbuttons
  • sets the maximum number of buttons for the screen, i.e. 8 means each button takes 1/8th of the width
  • default: 5

morebutton extension

• morebutton
  • tells the widget to use the view more extension functionality and button
  • default: false
• morebuttontext
  • sets the text of the more button
  • default: "..."
• morebuttoniconpos
  • sets the location of the optional icon on the more button
  • default: "top"
• morebuttonicon
  • sets the icon to be used for the more button
  • default: null

Events

• create triggered when a navbar is created

  
  $( ".selector" ).on("navbarcreate", function(event, ui) {});
  
  $( ".selector" ).navbar({
    create: function(event, ui) { }
  });
  

Methods

• destroy removes navbar enhancements from the element

  $( ".selector" ).navbar( "destroy" );
  

• refresh refreshes the navbar

$( ".selector" ).navbar( "refresh" );

Markup & Style

Initial Markup

<div class="selector" data-role="navbar" >
  <ul>
    <li><a href="#" class="ui-btn-active">Item 1</a></li>
      <li><a href="#">Item 2</a></li>
  </ul>
</div>

Enhanced Markup

<div role="navigation" class="selector ui-navbar" data-role="navbar">
  <ul class="ui-navbar-bar">
    <li class="ui-navbar-baritem"><a class="ui-link ui-btn ui-btn-active" href="#">Item 1</a></li>
    <li class="ui-navbar-baritem"><a class="ui-link ui-btn" href="#">Item 2</a></li>
  </ul>
</div>

CSS

.ui-navbar {
 max-width: 100%
}

.ui-navbar ul {
  padding: 0;
  display: table; 
  table-layout:fixed; 
  width: 100%;  
}

.ui-navbar li{
  display: table-cell;
  width: 100%;
}

Checklist

• Widget avoids using document and window directly - uses this.document and this.window
• Demos page
• Demos page added to menu
• Api PR #
• update /js/index.php
• update /js/jquery.mobile.js
• check with download builder
• Full test coverage
• Device Testing
• Screen reader testing
• Full accessibility review by expert
• add instructions to the upgrade guide

[arschmitz]

At first glance i notice classes like ui-navbar__baritem using a bem style naming system we are not ready for this type of system until we move to the in progress css framework and something for a css processor so for now we should use traditional classes

[arschmitz]

also i think ... is a bit more standard for a view more button icon

[arschmitz]

create event does not create the navbar its triggered by the navbar is created. saying it creates a navbar on the selector makes it sound like you could do $( "#foo" ).trigger("navbarcreate") and it would initialize the widget.

[jaspermdegroot]

Things to look into:

• Can we do something other than simply fall back to two columns when there are more than 5 buttons
• What do we do with the grid function that is only used by the navbar widget and not a documented feature (related feature request Smart and accessible navbars for tablets and phones #5436)
• Enhancing a navbar that doesn't have list items yet shouldn't cause an error (Syntax error, unrecognized expression: :nth-child #5141)
• Dynamically adding items should work, so we need to add a refresh method (.trigger('create') on navbar fails #4990).
• Use buttonMarkup() for adding classes to the anchors. Enhanced option so you can add them in the markup yourself.
• Fire a change event (Navbar does not have a change event #5865)
• Better handling of adding/removing the active state. This is handled in navigation but caused a conflict (navbar link stays active when using changePage() #1181). Also, currently you need to add two classes to give a navbar button the active state and make sure that it isn't removed after navigating away from the page. (See also Active state gets removed from persistent navbar after page transition #7583)
• Navbar buttons same font-size (and padding) as all other buttons, class ui-mini can be used for smaller size
• Support different icon position for each button (Better handling of iconpos on navbars #5374)
• Iconpos notext currently doesn't work: http://jsbin.com/ofuhaw/1383/edit
• Support combination buttons with top/bottom icon and buttons without icon (Navbar: Mixed buttons don't extend to bottom #7395)

Note: We should test icon related things with navbars inside and outside toolbars, because the CSS to make buttons inside toolbars default to mini and inline might affect the navbar buttons.

[gabrielschulhof]

• Use buttonMarkup() for adding classes to the anchors. Enhanced option so you can add them in the markup yourself.

Ummm, we're getting rid of buttonMarkup(), right?

[jaspermdegroot]

@gabrielschulhof - Ah, good point! I missed that when I copied this over from the old ticket.

[cgack]

since we talked about removing the idea of "persists" altogether I assume functionality like this:
"Navbars will have the ability to be persistent like a tab bar." - will be deprecated with this rewrite?

@arschmitz where you thinking an explicit morebuttonenabled: false/true option or something more like morebutton: null is the default and when it is not null then the morebutton extension becomes enabled?

[arschmitz]

I was thinking moreButton: true to enable false by default. null I don't think makes sense here as it would in it self have no meaning. We tend to have null have an actual meaning. For example null for disabled means to check the dom for the disabled attribute.

[arschmitz]

As far as persists goes. this all originally centered around the idea of persistent tool bars this used to be an extension to the fixedToolbar widget. However this was deprecated in 1.5. This behavior is however still available by means of a true persistent toolbar which is outside the page. The idea of persistence of things that are in the page I don't think makes sense.

[jaspermdegroot]

I added a bullet "add instructions to the upgrade guide" to the checklist. There is a 1.5 update branch in the jquerymobile.com repo which contains the 1.5 upgrade guide.

[cgack]

new PR created to track progress on the new branch.

[cgack]

I realized I have created a dependency on listview by the way I'm generating the items in the popup when we have the morebutton. @arschmitz I assume we want to limit the amount of dependencies and I should refactor and use some CSS to make it pretty, eh?

[cgack]

tracking #7909 here to make sure that a navbar without links either works or throws an proper error

[caoliuxue]

I'm using navbar widget under JQM 1.4.5, but I get the error
"no such method 'refresh' for navbar widget instance"
when I tried to refresh the icon of my navbar, is this an already known bug?

[arschmitz]

@caoliuxue the nav bar widget does not have a refresh method please see http://api.jquerymobile.com/navbar/ this issue is an in-progress re-write for 1.5.0