2016-10-31 10:10:14 -05:00
# electron-tabs
> Simple tabs for Electron applications
2016-11-02 11:04:19 -05:00
![Electron Tab Demo ](screenshot.jpg )
2016-11-01 10:28:30 -05:00
## Installation
2016-10-31 10:10:14 -05:00
2016-11-01 10:28:30 -05:00
```
$ npm install --save electron-tabs
```
2017-07-02 06:32:27 -05:00
## Demo
```
$ npm run demo
```
2016-11-01 10:28:30 -05:00
## Usage
2016-11-02 11:13:41 -05:00
Add the following elements to the app page:
2016-10-31 10:10:14 -05:00
```html
2016-11-02 11:13:41 -05:00
< div class = "etabs-tabgroup" >
< div class = "etabs-tabs" > < / div >
< div class = "etabs-buttons" > < / div >
< / div >
2016-11-02 06:41:18 -05:00
< div class = "etabs-views" > < / div >
2016-10-31 10:10:14 -05:00
```
2016-11-01 10:28:30 -05:00
And call the module in the renderer process:
2016-10-31 10:10:14 -05:00
```javascript
const TabGroup = require("electron-tabs");
2016-11-01 10:28:30 -05:00
```
2016-10-31 10:10:14 -05:00
2016-11-01 10:28:30 -05:00
Then you can initialize a tab group and add tabs to it:
2016-10-31 10:10:14 -05:00
2016-11-01 10:28:30 -05:00
```javascript
let tabGroup = new TabGroup();
2016-10-31 10:10:14 -05:00
let tab = tabGroup.addTab({
title: "Electron",
2016-11-01 10:28:30 -05:00
src: "http://electron.atom.io",
visible: true
2016-10-31 10:10:14 -05:00
});
```
2016-11-02 11:13:41 -05:00
If you don't want to write your own styles, you can also insert the sample electron-tabs stylesheet in the page header:
```html
< link rel = "stylesheet" href = "node_modules/electron-tabs/electron-tabs.css" >
```
2016-11-01 10:28:30 -05:00
## API
### Tab Group
Represents the main tab container.
#### `new TabGroup(options)`
`options` must be an object. The following options are available:
2016-11-02 06:41:18 -05:00
* `tabContainerSelector` (default: `".etabs-tabs"` ): CSS selector to target the element where tabs are inserted.
* `buttonsContainerSelector` (default: `".etabs-buttons"` ): CSS selector to target the element where the "New Tab" button are inserted.
* `viewContainerSelector` (default: `".etabs-views"` ): CSS selector to target the element where the view are inserted.
* `tabClass` (default: `"etabs-tab"` ): class to add to tab elements.
* `viewClass` (default: `"etabs-view"` ): class to add to webview elements.
2016-11-02 08:48:08 -05:00
* `closeButtonText` (default: `"✖"` ): "close tab" button text.
* `newTabButtonText` (default: `"+"` ): "New Tab" button text.
2016-11-01 10:28:30 -05:00
* `newTab` (default: `undefined` ): arguments to use when `.addTab()` is called without parameters. It can be an object or a function which returns an object. It determines the options to use when the "New Tab" button is triggered. If you leave it undefined then the "New Tab" button won't be displayed.
* `ready` (default: `undefined` ): a callback function to call once the tab group is ready. The `TabGroup` instance is passed as the only parameter.
#### `tabGroup.addTab(options)`
Add a new tab to the tab group and returns a `Tab` instance.
* `title` : tab title.
* `src` : URL to the page which will be loaded into the view. This is actually the same than `options.webview.src` .
2017-06-25 08:29:45 -05:00
* `badge` : optional text to put into a badge, badge will be hidden if it's falsey
2016-11-01 10:28:30 -05:00
* `iconURL` : optional URL to the tab icon.
2017-02-15 14:47:18 -05:00
* `icon` : optional code for a tab icon. Can be used with symbol libraries (example with Font Awesome: `icon: 'fa fa-icon-name'` ). This attribute is ignored if an `iconURL` was given.
2016-11-01 10:28:30 -05:00
* `closable` (default: `true` ): if set to `true` the close button won't be displayed and the user won't be able to close the tab. See also `tab.close()` .
* `webviewAttributes` : attributes to add to the webview tag. See [webview documentation ](http://electron.atom.io/docs/api/web-view-tag/#tag-attributes ).
2016-11-02 10:37:05 -05:00
* `visible` (default: `true` ): set this to `false` if you don't want to display the tab once it is loaded. If set to `false` then you will need to call `tab.show()` to display the tab.
2016-11-02 10:37:23 -05:00
* `active` (default: `false` ): set this to `true` if you want to activate the tab once it is loaded. Otherwise you will need to call `tab.activate()` .
2016-11-01 10:28:30 -05:00
* `ready` : a callback function to call once the tab is ready. The `Tab` instance is passed as the only parameter.
#### `tabGroup.getTab(id)`
Retrieve an instance of `Tab` from its `id` (return `null` if not found).
#### `tabGroup.getActiveTab()`
Return the currently active tab (otherwise return `null` ).
2017-09-14 10:23:49 -05:00
#### `tabGroup.getTabs()`
Return all registered tabs.
#### `tabGroup.eachTab(fn, thisArg)`
Loop through the list of tabs in `tabGroup` and execute the `fn` function for each tab. `fn` is called with the following parameters:
* `currentTab` : the current tab object.
* `index` : the index of the current tab being processed.
* `tabs` : the full array of tabs (similar to `tabGroup.getTabs()` ).
`thisArg` (optional) is the value to use as `this` when executing `fn` .
2016-11-01 10:28:30 -05:00
### Tab
Instances of `Tab` are returned by the `tabGroup.addTab()` method.
#### `tab.setTitle(title)`
Set tab title.
#### `tab.getTitle()`
Get current tab title.
2017-06-25 08:29:45 -05:00
#### `tab.setBadge(badge)`
Set tab badge.
#### `tab.getBadge()`
Get current tab badge.
2017-02-15 14:47:18 -05:00
#### `tab.setIcon (iconURL, icon)`
2016-11-01 10:28:30 -05:00
2017-02-15 14:47:18 -05:00
Set tab icon (a iconURL or an icon must be given).
2016-11-01 10:28:30 -05:00
#### `tab.getIcon()`
2017-02-15 14:47:18 -05:00
Get current tab icon URL / icon.
2016-11-01 10:28:30 -05:00
2017-10-26 19:03:37 -05:00
#### `tab.setPosition(newPosition)`
2017-10-26 20:55:12 -05:00
Move tab to the specified position. A negative value is an offset from the right.
2017-10-26 19:03:37 -05:00
2017-10-26 20:55:12 -05:00
To move a tab to the leftmost position:
2017-10-26 19:03:37 -05:00
2017-10-26 20:55:12 -05:00
```javascript
tab.setPosition(1);
```
> Note: a position of 0 also moves the tab to the leftmost position
To move a tab to the rightmost position:
```javascript
tab.setPosition(-1);
```
#### `tab.getPosition(fromRight)`
2017-10-26 21:13:19 -05:00
Get the tab position. If `fromRight` is true the index returned is negative and is the offset from the right.
2017-10-26 19:03:37 -05:00
2016-11-01 10:28:30 -05:00
#### `tab.activate()`
Activate this tab. The class "active" is added to the active tab.
#### `tab.show(flag)`
Toggle the "visible" class on the tab. `tab.hide()` is an alias to `tab.show(false)` .
#### `tab.flash(flag)`
Toggle the "flash" class on the tab. `tab.unflash()` is an alias to `tab.flash(false)` .
#### `tab.close(force)`
Close the tab (and activate another tab if relevant). When `force` is set to `true` the tab will be closed even if it is not `closable` .
### Access webview element
You can access the webview element and use its methods with through the `Tab.webview` attribute. See [webview documentation ](http://electron.atom.io/docs/api/web-view-tag/#methods ).
```javascript
let webview = tab.webview;
webview.loadURL("file://path/to/new/page.html");
```
### Events
The following events are available:
* `tabGroup.on("tab-added", (tab, tabGroup) => { ... });`
* `tabGroup.on("tab-removed", (tab, tabGroup) => { ... });`
* `tabGroup.on("tab-active", (tab, tabGroup) => { ... });`
2017-02-16 10:13:07 -05:00
* `tab.on("webview-ready", (tab) => { ... });`
2016-11-01 10:28:30 -05:00
* `tab.on("title-changed", (title, tab) => { ... });`
2017-02-15 14:47:18 -05:00
* `tab.on("icon-changed", (icon, tab) => { ... });`
2016-11-01 10:28:30 -05:00
* `tab.on("active", (tab) => { ... });`
* `tab.on("visible", (tab) => { ... });`
* `tab.on("hidden", (tab) => { ... });`
* `tab.on("flash", (tab) => { ... });`
* `tab.on("unflash", (tab) => { ... });`
* `tab.on("close", (tab) => { ... });`
2017-04-04 08:05:24 -05:00
* `tab.on("closing", (tab) => { ... });`
2016-11-01 10:28:30 -05:00
2016-11-02 12:19:56 -05:00
## Drag and drop support
Electron-tabs is compatible with [Dragula ](https://github.com/bevacqua/dragula ) so you can easily make your tabs draggable.
Install Dragula:
```
npm install dragula --save
```
Don't forget to add a link to its stylesheet in the header:
```html
< link rel = "stylesheet" href = "node_modules/dist/dragula.css" >
```
Then call Dragula in your script once tabGroup is ready:
```javascript
const TabGroup = require("electron-tabs");
const dragula = require("dragula");
var tabGroup = new TabGroup({
ready: function (tabGroup) {
dragula([tabGroup.tabContainer], {
direction: "horizontal"
});
}
});
```
2016-10-31 10:10:14 -05:00
## License
2017-04-04 08:05:24 -05:00
The MIT License (MIT) - Copyright (c) 2016 Thomas Brouard