TopBar

Provides tabs for navigation and buttons for contextual actions.

Beware that this API will be replaced be the ts.ui.Header in a future release.

If you plan to make use of the TopBar, we suggest that you give it a descriptive title.

ts.ui.TopBar.title('My App');

— because even when the title is hidden by the tabs, like on this page, it will become visible when you resize to mobile breakpoint. The title also functions to show the TopBar on page load, so that it doesn't suddenly appear when you add buttons later.

TopBar.tabs

We can initialize the TopBar tabs with the the tabs method.

ts.ui.TopBar.tabs([
	{ label: 'Overview' },
	{ label: 'TopBar' },
	{ label: 'TabBar' },
	{ label: 'ToolBar' },
	{ label: 'StatusBar' }
]);

— but since the page already has tabs, we will instead append a new tab to the existing collection. If you omit the argument, you"ll get the current tabs (jQuery style).

var tabs = ts.ui.TopBar.tabs();
tabs.push({
	label: 'Bonus Tab',
	onselect: function() {
		var text = this.label + ' selected';
		ts.ui.Notification.success(text)
	}
});

You can use array methods like push, pop, shift, unshift, splice and so on to manage tabs, just note that the tabs length is a readonly property. Also note that tabs don"t do anything by default, so what happens at onselect is completely up to you.

Updating tabs

We can at any time change what happens when a tab gets selected. We can also change the tab label if we like, although maybe this would be confusing for the user.

var tabs = ts.ui.TopBar.tabs();
tabs[4].label = 'Choose Me!';
tabs[4].onselect = function() {
	this.label = 'Thanks!';
};

Selecting tabs

We can programatically select a tab using one of these approaches.

ts.ui.TopBar.tabs()[4].select();
ts.ui.TopBar.tabs().selectedIndex = 1;

Querying tabs

This will all become a lot easier if we give all the tabs an id and use tabs.get()

var tabs = ts.ui.TopBar.tabs();
tabs.splice(4, 0, {
	label: 'Example Tab',
	id: 'example-tab'
});
tabs.get('example-tab').select();

Tabs icons

You can add a tab with an icon if somehow that tab is special.

ts.ui.TopBar.tabs().push ({
	label: 'Icon Tab',
	icon: 'ts-icon-todo'
});

Tab counters

You can add a counter to the tabs for whatever reason you like.

ts.ui.TopBar.tabs().forEach(function(tab){
	tab.counter = Math.ceil(Math.random() * 10);
});

When the counter reaches zero, it disappears.

ts.ui.TopBar.tabs().forEach(function(tab){
	tab.counter --;
});

Closeable tabs

You can create closeable tabs, but note that the tab must be selected before it can be closed. You can return false in the onclose method to prevent the tab from closing (if this would otherwise cause data loss).

ts.ui.TopBar.tabs().push ({
	label: 'Closeable Tab',
	closeable: true,
	selected: true,
	onclose : function() {
		ts.ui.Notification.success(this.label + ' closed');
	},
});

New-Tab button

You can allow the user to create new tabs via a special button as seen in popular browsers. Note that the button just triggers a callback and that the new tab must be created manually. In the example below, the selected property also selects the tab.

var tabs = ts.ui.TopBar.tabs();
tabs.showNew(function onclick() {
	tabs.push({
		label: 'My New Tab',
		selected: true
	});
});

If you regret this later on, you can also hide the button.

ts.ui.TopBar.tabs().hideNew();

Here"s a summary of the tabs collection and tab model.

TopBar.buttons

Add buttons to the TopBar with the buttons method. This both sets and gets. If you omit the argument, you"ll get the current buttons (jQuery style).

ts.ui.TopBar.buttons([
	{label : 'Primary', type : 'ts-primary'},
	{label : 'Secondary', type : 'ts-secondary'},
	{label : 'Tertiary One'},
	{label : 'Tertiary Two'}
]);

You can use array methods like push, pop, shift, unshift, splice, reverse and so on to manage buttons. Just note that the buttons length is readonly.

  • The buttons type property works like the CSS class for a regular Button
  • The TopBar will automatically sort all buttons from primary to tertiary.
  • If there"s more than one tertiary button, these will be pushed to an Aside.
  • In the mobile breakpoint, all the buttons will be pushed to an Aside.

Buttons won"t actually do anything unless you define the onclick method.

ts.ui.TopBar.buttons().splice(0, 1, {
	label : 'Click me!',
	type : 'ts-primary',
	onclick: function() {
		this.label = 'Thanks';
	}
});

Fortunately, you can always change what happens when a button gets clicked.

ts.ui.TopBar.buttons().forEach(function(button, index) {
	button.label = "Button " + (index + 1);
	button.onclick = function() {
		ts.ui.Notification.success(this.label);
	};
});

Query buttons

You can locate buttons by index in the buttons collection. But since this isn"t likely to match the order in which they appear on screen, it"s easier to give the buttons an id and find them using buttons.get().

var buttons = ts.ui.TopBar.buttons();
buttons.push({ id: 'example-button' });
var button = buttons.get('example-button');
button.label = 'My Button';
button.type = 'ts-secondary';

Hide buttons

You can hide() and show() buttons. You can also toggle visible.

ts.ui.TopBar.buttons().forEach(function(button) {
	if(button.visible) {
		button.hide();
	} else {
		button.show();
	}
});

Disable buttons

You can disable() and enable() buttons. You can also toggle disabled.

ts.ui.TopBar.buttons().forEach(function(button) {
	if(button.disabled) {
		button.enable();
	} else {
		button.disable();
	}
});

Busy buttons

We can display a temporary progress indicator with the busy and done methods.

var button = ts.ui.TopBar.buttons()[0];
button.busy();
setTimeout(function() {
	button.done();
}, 1000);

The busy method supports an optional status message.

var button = ts.ui.TopBar.buttons()[0];
button.busy('Making progress');
setTimeout(function() {
	button.done();
}, 1000);

Button groups

You can also group buttons in arrays to create button groups that look like this:

ts.ui.TopBar.buttons([
	{ label: 'Normal'},
	{ label: 'Normal'},
	[
		{ label: 'Accept', type: 'ts-primary' },
		{ label: 'Reject', type: 'ts-danger' }
	]
]);

You can of course also create grouped buttons with icons instead of text.

var group = ts.ui.TopBar.buttons()[2];
group.push({
	icon: 'ts-icon-other',
	type: 'ts-secondary'
});

Here"s a summary of the buttons collection and button model.

TopBar Back & Forward

The TopBar features both Back and Forward buttons for use in "drill down" scenarios.

ts.ui.TopBar.showBack(function() {
		console.log('Back');
	}).showNext(function() {
		console.log('Next');
	});

You can also hide the Back and Forward buttons. Since the buttons obscure the tabs, you might actually like to do that now.

ts.ui.TopBar.hideBack().hideNext();

Note that tabbed navigation is not supposed to coexist with Back and Forward buttons.

Hide & show the TopBar

You can hide the TopBar — but not in mobile breakpoint, see below. Note that this operation will clear the contents of the TopBar.

ts.ui.TopBar.hide();

You can also show it again. Because the content was cleared, we'll also restore it.

ts.ui.TopBar.show();
restoreTopBar();

When you resize the window to mobile breakpoint, the hidden TopBar will be shown again automatically. That's because the TopBar is used to access the main navigation. Without the TopBar, you would be stuck in the app forever. But since you chose to hide the TopBar, we can assume that the content of the TopBar is not relevant. Therefore:

Since we don't want to show an outdated TopBar to mobile users, the content of the TopBar will be cleared when you hide it. To restore the old content, you will simply have to populate the TopBar again.

If you don't want your app to feature a TopBar under any circumstance, you can simply remove the whole <div data-ts="TopBar"> from the HTML.

TopBar summary

Here's a summary of the TopBar methods, including some bonus not yet discussed.

If you find a bug or need a feature…

  • Create GitHub Issue…