Introducing ToolbarJS - A HTML5 JavaScript Library to Implement the Windows Phone AppBar Functionality

Back in February I released deeptissuejs, a HTML5, JavaScript touch gesture library. In January I release panoramajs a HTML5, JavaScript library to implement the basic Windows Phone panorama control experience. This month I am excited to release another new HTML5 modern web application library, toolbarjs.

Toolbarjs is a JavaScript library to add the Windows Phone appBar functionality to modern HTML5 web applications. It is composed of a framework agnostic JavaScript library, example CSS and markup to help developers get started.

Adding toolbarjs to a web application is very simple. First I recommend you grab the source code from GitHub. There is a minimized version already included in the project's js folder. If you want to develop against the debug version (unminimzed) version feel free, it is located in the debug folder. In the css folder there is a toolbar.css file. It contains a reference set of CSS classes to style the toolbar in the Metro IU feel. There are three example pages to demonstrate how to use the toolbarjs library. They all contain a base HTML snippet to apply the library.

There are a simple set of instructions also included in the source code, readme.md. You can read those before reviewing the example pages.

Implementing the toolbarjs library is extremely simple. Make sure you have a target element with a pair of child elements to hold the menu items.

<

footer

class

="toolbar"

>


<

nav

class

="toolbar-top-menu"

></

nav

>


<

nav

class

="toolbar-sub-menu"

></

nav

>


</

footer

>



Creating the toolbar requires nothing more than passing the target node to the library and the menu items for the top and sub menus. If you want to simply pass the toolbar element's selector you can do that and the library will take care of the node selection for you.


var

tb = toolbar(

".toolbar"

,
{
menuItems: {
topMenu: [],
subMenu: []
}
});

Each menu item is a JavaScript object with the following structure:

{
title:

"Sports"

,

//text displayed below the icon or in the sub menu, its what the user will read.


iconClass:

"sports-icon"

,

//used to apply CSS background image and hook for callback


callback:

function

(e) {
console.log(

"Sports"

);
}

//gets executed when the item is selected


}

The 'title' is the caption displayed below the menu item's icon or the text rendered in the sub menu. The iconClass is the CSS class containing the styling for the actual icon. The library assumes you are using a background image, typically with a CSS sprite or data URI.

The callback method is a function that is executed when the user either clicks or touches the menu item. The demos will echo a message to the console, but in practice these choices would trigger an action like opening a new view. If you do not change the items in the toolbar you will want to call the expandToolbar passing true to collapse the toolbar.

tb.expandToolbar(

true

);

While developing the library I found too many situations where collapsing when the toolbar when a menu item was selected just did not work. So I made the decision to make this a manual trigger. If the menu items are changed the menu will force a collapse. This is common when a user navigates between views. The following shows how to change the menu items.

tb.setToolbarMenu(menuItems);

Like all my libraries there are many custom settings that can be adjusted when creating a new instance. Toolbarjs is no different. The following is the default settings object.

settings: {
minHeight: 35,
minWidth: 42,
expandWidth: 200,
mainSelector:

".toolbar"

,
topMenuSelector:

".toolbar-top-menu"

,
subMenuSelector:

".toolbar-sub-menu"

,
expandTargetSelector:

".expand-toolbar"

,
topMenuItemSelector:

".toolbar-item"

,
menuItems: {
topMenu: [],
subMenu: []
},
toolbarItemTemplate:

"<div class='toolbar-item'><div class='toolbar-item-icon {{iconClass}}'></div><figcaption>{{title}}</figcaption></div>"

,
subMenuItemTemplate:

"<div class='toolbar-sub-menu-nav-item {{iconClass}}'>{{title}}</div>"

,
topLevelItems: [],
secondLevelItems: [],
expandSpeed: 1000,

//ms


that: undefined,
easing:

"ease-in-out"


}

These values can be overwritten when the library is created. You could also change any property during run-time by referencing the settings object like this: tb.settings.minWidth = 45;. To customize a setting when the object is created just add it to the second parameter with the menu items. In this example the default expand speed is changed from 1 second to 700 milliseconds.

var

tb = toolbar(document.querySelector(

".toolbar"

),
{
menuItems: {
topMenu: [...],
subMenu: [...]
},
expandSpeed: 700
});

At this time I am aware the library is not working 100% correctly in the default Android WebKit browser. I am working on this and hope to post and update soon. There are also several other features I want to support. So look for updates over the coming weeks.

Like the previous libraries I am using toolbarjs on my own projects. I created it out of personal demand and am glad I can share it with you. I hope you enjoy using it. Please provide feedback and report any issues or bugs you find. I can't promise I will fix them immediately but will get to them as I have time. Unlike toolbarjs I remembered to add the license to the library this time. I think I added MIT, but basically assume you can use the code, but I offer no warranties at all.

Share This Article With Your Friends!

Googles Ads Facebook Pixel Bing Pixel LinkedIn Pixel