Page Control

The Page Control component provides a tabbed interface for organizing content into separate tabs. It supports tab creation, activation, closing, and renaming, with features like overflow handling, context menus, and reference control.

Dependencies

• Metro UI Core
• DOM library

Usage

Basic Usage

<ul data-role="page-control">
    <li class="active">Home</li>
    <li>Profile</li>
    <li>Settings</li>
</ul>

With Icons and Close Buttons

<ul data-role="page-control">
    <li class="active" data-icon="mif-home">Home</li>
    <li data-icon="mif-user">Profile</li>
    <li data-icon="mif-cog" data-close="false">Settings</li>
</ul>

With Reference Control

<ul data-role="page-control" data-ref-control="true">
    <li class="active" data-ref="#home-content">Home</li>
    <li data-ref="#profile-content">Profile</li>
    <li data-ref="#settings-content">Settings</li>
</ul>

<div id="home-content">Home content here</div>
<div id="profile-content" style="display: none;">Profile content here</div>
<div id="settings-content" style="display: none;">Settings content here</div>

JavaScript Creation

// Create a page control programmatically
const pageControl = Metro.makePlugin("#container", "page-control", {
    tabsPosition: "center",
    appendButton: true,
    defaultNewTabTitle: "New Tab"
});

// Add tabs
pageControl.addTab({
    caption: "Home",
    icon: "mif-home",
    canClose: false
});

Plugin Parameters

The Page Control component accepts the following configuration options:

Parameter	Type	Default	Description
appendButton	boolean	true	Show button to add new tabs
tabsPosition	string	"left"	Position of tabs (“left”, “center”, “right”)
customButtons	array	null	Custom buttons for the control
activateNewTab	boolean	true	Activate newly created tabs
defaultNewTabTitle	string	"New File"	Default title for new tabs
defaultNewCanClose	boolean	true	Whether new tabs can be closed by default
defaultNewTabIcon	string	""	Default icon class for new tabs
defaultNewTabImage	string	""	Default image URL for new tabs
defaultNewTabPosition	string	"before"	Where to add new tabs (“before”, “after”)
appendActions	function	null	Function that returns an array of actions for the append button menu
tabsActions	function	null	Function that returns an array of actions for the tabs menu
tabActions	function	null	Function that returns an array of actions for individual tab menus
refControl	boolean	false	Control visibility of referenced elements based on active tab

Events

Event	Description
onAppendButtonClick	Triggered when the append button is clicked
onTabCreate	Triggered when a tab is created
onTabActivate	Triggered when a tab is activated
onTabDeactivate	Triggered when a tab is deactivated
onTabBeforeClose	Triggered before a tab is closed (return false to prevent closing)
onTabClose	Triggered when a tab is closed
onTabRename	Triggered when a tab is renamed
onTabPropChange	Triggered when a tab property is changed
onTabOrganized	Triggered when tabs are reorganized

API Methods

The Page Control component provides the following methods:

Method	Parameters	Description
createTab(options)	options: object	Creates a new tab with the specified options
addTab(options, insert)	options: object, insert: string	Adds a new tab with the specified options and position
activateTab(tab)	tab: element	Activates the specified tab
closeTab(tab, reorg)	tab: element, reorg: boolean	Closes the specified tab
closeAll()	-	Closes all tabs
closeInactiveTabs()	-	Closes all inactive tabs
closeOtherTabs(tab)	tab: element	Closes all tabs except the specified one
closeTabsOnTheLeft(tab)	tab: element	Closes all tabs to the left of the specified tab
closeTabsOnTheRight(tab)	tab: element	Closes all tabs to the right of the specified tab
getActiveTab()	-	Gets the currently active tab
getActiveTabIndex()	-	Gets the index of the active tab
getTabByIndex(index)	index: number	Gets a tab by its index
getTabByTitle(caption)	caption: string	Gets a tab by its caption/title
setupTab(tab, prop, val)	tab: element, prop: string, val: any	Updates a tab’s property
renameTab(tab)	tab: element	Opens a dialog to rename the specified tab
organizeTabs()	-	Reorganizes tabs to fit the available space

Tab Creation Options

When using the createTab() or addTab() methods, you can pass the following options:

Option	Type	Description
caption	string	Tab title/caption
icon	string	CSS class for the tab icon
image	string	URL for the tab image
canClose	boolean	Whether the tab can be closed
hasMenu	boolean	Whether the tab has a context menu
data	any	Custom data associated with the tab
ref	string	Reference to an element controlled by the tab

Example of API Usage

// Get the page control instance
const pageControl = Metro.getPlugin("#myPageControl", "page-control");

// Add a new tab
const newTab = pageControl.addTab({
    caption: "New Tab",
    icon: "mif-file",
    canClose: true
});

// Activate a tab
pageControl.activateTab(newTab);

// Close all inactive tabs
pageControl.closeInactiveTabs();

Styling with CSS Variables

The Page Control component can be styled using the following CSS variables:

Variable	Default (Light)	Dark Mode	Description
--page-control-background	#ffffff	#222222	Background color of the page control
--page-control-background-hover	rgba(137, 137, 137, .1)	rgba(137, 137, 137, .1)	Background color on hover
--page-control-closer-hover-background	#e1e1e1	#444444	Background color of the close button on hover
--page-control-border-color	#e0e0e0	#444444	Border color of the page control
--page-control-border-radius	6px	6px	Border radius of the page control

Example of Custom Styling

/* Custom styling for page control */
.custom-page-control {
    --page-control-background: #f5f5f5;
    --page-control-background-hover: rgba(0, 123, 255, 0.1);
    --page-control-closer-hover-background: #d0d0d0;
    --page-control-border-color: #cccccc;
    --page-control-border-radius: 8px;
}

Available CSS Classes

Container Classes

• .page-control - Main container
• .page-control__tabs - Container for tabs
• .tabs-position-left - Align tabs to the left
• .tabs-position-center - Align tabs to the center
• .tabs-position-right - Align tabs to the right

Tab Classes

• .page-control__tab - Individual tab
• .page-control__tab.active - Active tab
• .page-control__tab__icon - Tab icon
• .page-control__tab__caption - Tab caption/title
• .page-control__tab__closer - Tab close button
• .page-control__tab__menu - Tab context menu
• .page-control__tab__menu__holder - Container for tab menu

Service Classes

• .page-control__tab__service - Service buttons container
• .page-control__tab__append - Add tab button
• .page-control__service-button - Service button
• .page-control__invisible_tabs_holder - Container for overflow tabs

Features

1. Tab Management: Create, activate, close, and rename tabs
2. Overflow Handling: Automatically moves tabs to a dropdown when there’s not enough space
3. Context Menus: Provides context menus for tabs with various actions
4. Reference Control: Can control the visibility of referenced elements based on the active tab
5. Custom Actions: Supports custom actions for tabs and the page control
6. Tab Icons: Supports icons and images for tabs
7. Tab Positioning: Supports different tab alignment options

Best Practices

1. Use clear, concise tab titles to help users navigate content
2. Consider using icons alongside text for better visual recognition
3. Use reference control for complex interfaces to show/hide content based on the active tab
4. Implement appropriate event handlers to respond to tab changes
5. Consider disabling tab closing for important tabs using the canClose option
6. Use custom tab actions for frequently used operations
7. For applications with many tabs, consider grouping related tabs or using a hierarchical structure