Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nextapps-de/winbox
WinBox is a modern HTML5 window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source!
https://github.com/nextapps-de/winbox
box desktop desktop-app desktop-widget frame popup winbox window window-manager windowmanager windows
Last synced: 4 days ago
JSON representation
WinBox is a modern HTML5 window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source!
- Host: GitHub
- URL: https://github.com/nextapps-de/winbox
- Owner: nextapps-de
- License: apache-2.0
- Created: 2021-04-12T16:55:39.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-08-15T08:08:46.000Z (4 months ago)
- Last Synced: 2024-10-29T15:02:12.939Z (about 2 months ago)
- Topics: box, desktop, desktop-app, desktop-widget, frame, popup, winbox, window, window-manager, windowmanager, windows
- Language: JavaScript
- Homepage:
- Size: 523 KB
- Stars: 6,225
- Watchers: 71
- Forks: 201
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome - nextapps-de/winbox - WinBox is a modern HTML5 window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source! (JavaScript)
- awesome-random-stuff - nextapps-de/winbox: WinBox is a professional HTML5 window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source! - WinBox is a professional HTML5 window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source! - nextapps-de/winbox (Uncategorized / Uncategorized)
README
Modern window manager for the web: lightweight, outstanding performance, no dependencies, fully customizable, open source!
Demo • Getting Started • Options • API • Themes • Customize • Changelog
### Live Demo and Code Examples
https://nextapps-de.github.io/winbox/
## Support this Project
Hello my name is Thomas, also known as ts-thomas. This is a personal project which I fully made in my free time. It is hosted by the Github account from the company Nextapps where I work to give it more exposure.
I have never received any financial support for this project from the company Nextapps as some of you might have guessed, since it is a free and open source project.
I'm really happy that WinBox.js is getting so much positive feedback and also feature requests. Please feel free to support me by making a personal donation which helps me a lot to keep this project alive and also to providing all the contribution to keep WinBox.js on a professional top-end level.
Thanks a lot,
Thomas (ts-thomas)
### Plugins / Add-ons / Extensions
Vue 2 and 3 (a wrapper component that adds the ability to mount Vue components in WinBox.js):
https://github.com/wobsoriano/vue-winbox
A React controlled component for WinBox.js, with full Reactful props and state.:
https://github.com/rickonono3/react-winbox
__Get Latest Stable Build (Recommended):__
Bundle: (all assets bundled into one single file: js + css + html + icons)
winbox.bundle.min.js
Download
https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/winbox.bundle.min.js
Non-Bundled: (js and css are separated, css includes icons as base64)
winbox.min.js
Download
https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/js/winbox.min.js
winbox.min.css
Download
https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/dist/css/winbox.min.css
Sources: (not bundled at all, images as url to original resources)
ES6 Modules
Download
The /src/js folder of this Github repository
LESS Files (source)
Download
The /src/css folder of this Github repository
winbox.css (compiled)
Download
https://rawcdn.githack.com/nextapps-de/winbox/0.2.82/src/css/winbox.css
src.zip
Download
Download all source files including image original resources.
__Get Latest (NPM):__
```cmd
npm install winbox
```
### Use Bundled Version (Recommended)
> The bundled version includes all assets like js, css, html and icon images as base64.
A best practice is to load the library as async and use some modern preloading mechanism:
```html
```
When you get troubles with unavailable references then remove the `async` or `defer` from this example and invest some minutes later to find out how you can properly load js assets asynchronously today.
### Use Non-Bundled Version
The non-bundled version needs to load js and css separately (css already includes icons as base64).
```html
```
You can also load the non-bundled version in the same way.
### ES6 Modules
The ES6 modules are located in `src/js/`. But you need to load the stylesheet file explicitly since this is just automatically loaded by the bundled version.
```html
```
```html
import WinBox from "./src/js/winbox.js";
```
You can also load modules via CDN, e.g.:
```html
import WinBox from "https://unpkg.com/[email protected]/src/js/winbox.js";
```
The ES6 modules are not minified. Please use your favored bundler or build tool for this purpose.
Constructor:
- new **WinBox**(title, options\) : winbox
Global methods:
- WinBox.**new**(title, options\) : winbox
- WinBox.**stack**() : Array\
Instance member methods:
- winbox.**mount**(src)
- winbox.**unmount**(dest)
- winbox.**setUrl**(string)
- winbox.**setTitle**(string)
- winbox.**setIcon**(url)
- winbox.**move**(x, y)
- winbox.**resize**(width, height)
- winbox.**close**(boolean)
- winbox.**focus**(state)
- winbox.**blur**(state)
- winbox.**hide**(state)
- winbox.**show**(state)
- winbox.**minimize**(state)
- winbox.**maximize**(state)
- winbox.**fullscreen**(state)
- winbox.**restore**(state)
- winbox.**setBackground**(string)
- winbox.**addClass**(name)
- winbox.**removeClass**(name)
- winbox.**hasClass**(name)
- winbox.**toggleClass**(name)
- winbox.**addControl**(options)
- winbox.**removeControl**(name)
Instance properties (readonly):
- winbox.**id**
- winbox.**index**
- winbox.**window**
- winbox.**body**
Instance properties (writable):
- winbox.**x**
- winbox.**y**
- winbox.**width**
- winbox.**height**
- winbox.**top**
- winbox.**right**
- winbox.**bottom**
- winbox.**left**
- winbox.**minwidth**
- winbox.**minheight**
- winbox.**maxwidth**
- winbox.**maxheight**
Instance state boolean properties (readonly):
- winbox.**min**
- winbox.**max**
- winbox.**full**
- winbox.**hidden**
- winbox.**focused**
Callback methods:
- winbox.**oncreate**
- winbox.**onshow**
- winbox.**onhide**
- winbox.**onclose**
- winbox.**onfocus**
- winbox.**onblur**
- winbox.**onmove**
- winbox.**onresize**
- winbox.**onfullscreen**
- winbox.**onmaximize**
- winbox.**onminimize**
- winbox.**onrestore**
Option
Values
Description
id
number | string
Set a unique id to the window. Used to define custom styles in css, query elements by context or just to identify the corresponding window instance. If no ID was set it will automatically create one for you.
index
number
Set the initial z-index of the window to this value (will be increased automatically when unfocused/focused).
title
string
The window title.
mount
HTMLElement
Mount an element (widget, template, etc.) to the window body.
html
string
Set the innerHTML of the window body.
url
string
Open URL inside the window (loaded via iframe).
width
height
number | string
Set the initial width/height of the window (supports units "px" and "%").
minwidth
minheight
number | string
Set the minimal width/height of the window (supports units "px" and "%"). Should be at least the height of the window header title bar.
maxwidth
maxheight
number | string
Set the maximum width/height of the window (supports units "px" and "%").
autosize
boolean
Automatically size the window to fit the window contents.
overflow
boolean
Allow the window to move outside the viewport.
x
y
number | string
Set the initial position of the window (supports: "right" for x-axis, "bottom" for y-axis, "center" for both, units "px" and "%" for both).
max
boolean
Automatically toggles the window into maximized state when created.
min
boolean
Automatically toggles the window into minimized state when created.
hidden
boolean
Automatically toggles the window into hidden state when created.
modal
boolean
Shows the window as modal.
top
right
bottom
left
number | string
Set or limit the viewport of the window's available area (supports units "px" and "%"). Also used for custom splitscreen configurations.
background
string
Set the background of the window (supports all CSS styles which are also supported by the style-attribute "background", e.g. colors, transparent colors, hsl, gradients, background images)
border
number
Set the border width of the window (supports all the browsers css units).
icon
string
Make the titlebar icon visible and set the image source to this url.
class
string
Add one or more classnames to the window (multiple classnames as array or separated with whitespaces e.g. "class-a class-b"). Used to define custom styles in css, query elements by context (also within CSS) or just to tag the corresponding window instance.
WinBox provides you some useful Built-in Control Classes to easily setup a custom configuration.
oncreate
function(options)
Callback triggered when the winbox element is being created. You can modify all these winbox options from this table passed as first parameter.
onmove
function(x, y)
Callback triggered when the window moves.
onresize
function(width, height)
Callback triggered when the window resizes.
onfullscreen
function()
Callback triggered when the window enters fullscreen.
onminimize
function()
Callback triggered when the window enters minimized mode.
onmaximize
function()
Callback triggered when the window enters maximize mode.
onrestore
function()
Callback triggered when the window returns to a windowed state from a Fullscreen, Minimized or Maximized state.
onhide
function()
Callback triggered when the window is hidden with win.hide()
onshow
function()
Callback triggered when the window is shown with win.show()
onclose
function(force)
Callbacks triggered when the window is closing. The keyword this inside the callback function refers to the corresponding WinBox instance. Note: the event 'onclose' will be triggered right before closing and stops closing when a callback was applied and returns a truthy value.
onfocus
function()
Callback triggered when a window goes into focused state.
onblur
function()
Callback triggered when a window lost the focused state.
## Create and Setup Window
> When no `root` was specified the window will append to the `document.body`.
```js
new WinBox("Window Title");
```
Alternatively:
```js
WinBox.new("Window Title");
```
Alternatively:
```js
new WinBox({ title: "Window Title" });
```
Alternatively:
```js
var winbox = WinBox();
winbox.setTitle("Window Title");
```
#### Custom Root
> The root is the unique element in a document where the window will append to. In most cases that is usually the `document.body` which is the default root. Multiple roots at the same time are just partially supported (they share the same viewport actually).
```js
new WinBox("Window Title", {
root: document.body
});
```
#### Custom Color
> Supports all CSS styles which are also supported by the style-attribute "background", e.g. colors, rgba, hsl, gradients, background images.
```js
new WinBox("Custom Color", {
background: "#ff005d"
});
```
Alternatively:
```js
var winbox = new WinBox("Custom Color");
winbox.setBackground("#ff005d");
```
#### Custom Border
> Supports all units.
```js
new WinBox({
title: "Custom Border",
border: "1em"
});
```
You can also define multiple border values (the order is: top, right, bottom, left):
```js
new WinBox({
title: "Custom Border",
border: "0 1em 15px 1em"
});
```
#### Custom Titlebar Icon
> Supports all datatypes which are also supported by the style-attribute "background-image", e.g. URL, base64 encoded data. The default icon size is 20 x 20 pixels.
```js
new WinBox({
title: "Custom Icon",
icon: "img/icon.svg"
});
```
Alternatively:
```js
var winbox = new WinBox("Custom Icon");
winbox.setIcon("img/icon.svg");
```
See below in the style section to find out how to easily customize the titlebar icon style via css.
#### Custom Viewport
> Define the available area (relative to the document) in which the window can move or could be resized (supports units "px" and "%").
```js
new WinBox("Custom Viewport", {
top: "50px",
right: "5%",
bottom: 50,
left: "5%"
});
```
Alternatively (but just support numbers!):
```js
var winbox = new WinBox("Custom Viewport");
winbox.top = 50;
winbox.right = 200;
winbox.bottom = 0;
winbox.left = 200
```
> Supports keywords `"right"` for x-axis, `"bottom"` for y-axis, `"center"` for both, units `px` and `%` also for both.
```js
new WinBox("Custom Viewport", {
x: "center",
y: "center",
width: "50%",
height: "50%"
});
```
```js
new WinBox("Custom Viewport", {
x: "right",
y: "bottom",
width: "200px",
height: "200px"
});
```
Alternatively (also supports same units and keywords as above):
```js
var winbox = new WinBox("Custom Viewport");
winbox.resize("50%", "50%")
.move("center", "center");
```
Alternatively (just support numeric values as `px` when directly assigned!):
```js
var winbox = new WinBox("Custom Viewport");
winbox.width = 200;
winbox.height = 200;
winbox.resize();
winbox.x = 100;
winbox.y = 100;
winbox.move();
```
> In some cases you need to execute `.resize()` before `.move()` to properly apply relative positions which is taking the windows size into account.
Allow the window to move outside the viewport borders on left, right and bottom (default is "false").
```js
new WinBox({
title: "Overflow Window",
overflow: true
});
```
```js
new WinBox({
title: "Modal Window",
modal: true
});
```
The window stack gets you an ordered list of every created window which wasn't already closed. The last focused windows is placed as last entry in the Array.
```js
const a = new WinBox("A"); // window A gets focused
const b = new WinBox("B"); // window B gets focused
const c = new WinBox("C"); // window C gets focused
a.focus(); // window A gets focused
// get window stack ordered by focus history
const stack = WinBox.stack(); // [B, C, A]
```
> Feel free to create your own themes and share them with us.
You will find all themes here.
Load the corresponding css files (or use a bundler), e.g.:
```html
```
Just add the name of the theme via `class`:
```js
var winbox = new WinBox({
title: "Theme: Modern",
class: "modern"
});
```
Alternatively:
```js
var winbox = new WinBox("Theme: Modern");
winbox.addClass("modern");
```
You can change themes during the lifetime of the window.
## Manage Window Content
#### Set innerHTML
> Do not forget to sanitize any user inputs which is part of the __html__ as this can lead to unintended XSS!
```js
new WinBox("Set innerHTML", {
html: "
Lorem Ipsum
"
});
```
Alternatively:
```js
var winbox = new WinBox("Set innerHTML");
winbox.body.innerHTML = "
Lorem Ipsum
";
```
> When cloning you can easily create multiple window instances of the same content in parallel.
```html
Lorem Ipsum
Lorem ipsum [...]
```
```js
var node = document.getElementById("content");
new WinBox("Mount DOM", {
mount: node.cloneNode(true)
});
```
Alternatively:
```js
var node = document.getElementById("content");
var winbox = new WinBox("Mount DOM");
winbox.mount(node.cloneNode(true));
```
#### Mount DOM (Singleton) + Auto-Unmount
> A singleton is a unique fragment which can move inside the document. When creating multiple windows and mounting the same fragment to it, the fragment will leave the old window (see the method above for cloning).
> This workaround is also compatible if you are using server-side rendering.
You can simply use a hidden backstore to hold contents, as well you can use any other strategy like a templating engine etc.
```html
Lorem Ipsum
Lorem ipsum [...]
```
```js
var node = document.getElementById("content");
new WinBox("Mount DOM", {
mount: node
});
```
> Auto-Unmount is a helpful feature which automatically moves back the fragment to the backstore source when closing the window.
Alternatively:
```js
var node = document.getElementById("content");
var winbox = new WinBox("Mount DOM");
winbox.mount(node);
```
```html
Lorem Ipsum
Lorem ipsum [...]
```
```js
var node = document.getElementById("content");
var winbox = new WinBox("Mount DOM");
```
Move fragment from hidden backstore to the window body:
```js
winbox.mount(node);
```
Move fragment back to the hidden backstore source:
```js
winbox.unmount();
```
Or move fragment to another destination:
```js
winbox.unmount(document.getElementById("backstore-2"));
```
Or just auto-unmount as default when closing:
```js
winbox.close();
```
Override default auto-unmount behavior when closing the window:
```js
new WinBox("Mount DOM", {
mount: node,
onclose: function(){
this.unmount(document.getElementById("backstore-2"));
}
});
```
#### Manual Mount Contents
Feel free to use the `winbox.body` directly:
```js
var node = document.getElementById("content");
var winbox = new WinBox("Mount DOM");
winbox.body.appendChild(node);
```
Or delegate it as a root to your templating engine, e.g.:
```js
Mikado(template).mount(winbox.body).render(data);
```
#### Open URI / URL
> Do not forget to sanitize any user inputs when it is part of the __url__ as this can lead to unintended XSS!
The onload callback is optionally.
```js
new WinBox("Open URL", {
url: "https://wikipedia.com",
onload: function(){ /* extern page loaded */}
});
```
> You can use every URI scheme which is supported by `src` attribute, e.g. URL, image or video, base64 encoded data.
Alternatively:
```js
var winbox = new WinBox("Open URL");
winbox.setUrl("https://wikipedia.com", function(){
/* extern page loaded */
});
```
## The WinBox Window Instance
Window States / Information:
```js
var winbox = new WinBox();
console.log("Window ID:", winbox.id);
console.log("Window Index:", winbox.index);
console.log("Current Maximize State:", winbox.max);
console.log("Current Minimize State:", winbox.min);
console.log("Current Fullscreen State:", winbox.full);
console.log("Current Hidden State:", winbox.hidden);
console.log("Current Focused State:", winbox.focused);
```
Window Size:
```js
var winbox = new WinBox();
winbox.width = 200;
winbox.height = 200;
winbox.resize();
console.log("Current Width:", winbox.width);
console.log("Current Height:", winbox.height);
```
Window Position:
```js
var winbox = new WinBox();
winbox.x = 100;
winbox.y = 100;
winbox.move();
console.log("Current Position X:", winbox.x);
console.log("Current Position Y:", winbox.y);
```
Window Viewport:
```js
var winbox = new WinBox();
winbox.top = 50;
winbox.right = 50;
winbox.bottom = 50;
winbox.left = 50;
// update window if needed:
winbox.resize().move();
console.log("Current Viewport Top:", winbox.top);
console.log("Current Viewport Right:", winbox.right);
console.log("Current Viewport Bottom:", winbox.bottom);
console.log("Current Viewport Left:", winbox.left);
```
The window body acts like the `document.body` and has a scroll pane:
```js
var winbox = new WinBox();
winbox.body.innerHTML = "
Lorem Ipsum
";
```
Get the DOM element from the window outer frame:
```js
var winbox = new WinBox();
var root = winbox.window;
```
You also can get the window element by DOM id:
```js
var winbox = new WinBox();
var root = document.getElementById(winbox.id);
```
> The window element points to the window most outer root element which also holds the window control and state classes:
You can access and modify the window DOM element directly:
```js
const root = winbox.window;
const hidden = root.classList.contains("hide");
const focused = root.classList.contains("focus");
root.classList.remove("modal");
root.classList.add("my-theme");
root.classList.toggle("my-toggle");
```
Or as an equivalent to the example above by using the WinBox built-in methods respectively:
```js
const hidden = winbox.hasClass("hide");
const focused = winbox.hasClass("focus");
winbox.removeClass("modal");
winbox.addClass("my-theme");
winbox.toggleClass("my-toggle");
```
You can grab the `winbox` instance from the window outer frame DOM element:
```js
var winbox = new WinBox();
// assume you have a DOM reference to the winbox window:
var window_element = document.getElementById(winbox.id);
// grab corresponding instance from window element:
winbox = window_element.winbox;
```
#### Controls
```js
var winbox = new WinBox();
```
Focus a window (bring up to front):
```js
winbox.focus();
winbox.focus(true);
winbox.blur(false);
```
Blur a focused window:
```js
winbox.blur();
winbox.blur(true);
winbox.focus(false);
```
Set the minimized state of a window:
```js
winbox.minimize();
winbox.minimize(true);
winbox.minimize(false);
```
Set the maximized state of a window:
```js
winbox.maximize();
winbox.maximize(true);
winbox.maximize(false);
```
Set the fullscreen state of a window:
```js
winbox.fullscreen();
winbox.fullscreen(true);
winbox.fullscreen(false);
```
Restore the state of a window:
```js
winbox.restore();
```
Hide a specific window:
```js
winbox.hide();
winbox.hide(true);
winbox.show(false);
```
Show a specific hidden window:
```js
winbox.show();
winbox.show(true);
winbox.hide(false);
```
Close and destroy a window:
```js
winbox.close();
```
Close and destroy a window depending on custom conditional (e.g. by a confirmation status):
```js
winbox.close(false || true);
```
#### Chaining Methods
```js
var winbox = WinBox();
winbox.setTitle("Title")
.setBackground("#fff")
.resize("50%", "50%")
.move("center", "center")
.mount(document.getElementById("content"));
```
> When using "center" as position you need to call `.resize()` before `.move()`.
#### Callbacks
You can assign callbacks via the option payload when creating a window.
> The keyword `this` in your callback function refers to the corresponding WinBox Instance.
```js
var winbox = WinBox({
oncreate: function(options){
options.autosize = true;
},
onfocus: function(){
this.setBackground("#fff");
},
onblur: function(){
this.setBackground("#999");
},
onresize: function(width, height){
console.log("width:", width, "height:", height);
},
onfullscreen: function(){
this.setBackground("#666");
},
onminimize: function(){
this.setBackground("#999");
},
onmaximize: function(){
this.setBackground("#AAA");
},
onrestore: function(){
this.setBackground("#DDD");
},
onmove: function(x, y){
console.log("x:", x, "y:", y);
},
onclose: function(force){
// return "true" to skip the closing
// return "false" to allow closing
// use delegated force parameter optionally
return !confirm("Close window?");
}
});
```
#### The "onclose" callback
> The event `onclose` will be triggered right before closing and __stops__ closing when a callback was applied and returns a __truthy value__.
Within your callback function just return `true` to stops the closing or return `false` to perform closing as default.
```js
new WinBox({
onclose: function(){
// return "true" to skip the closing
// return "false" to allow closing
if(do_some_checks()){
return true;
}
}
});
```
The `force` parameter from the `winbox.close(boolean)` will be delegated to your callback function as the first parameter. You need to handle the "force" state in your callback function.
```js
var winbox = WinBox({
onclose: function onclose(force){
// use delegated force parameter optionally
return !force && !confirm("Close window?");
}
});
```
Close the window and execute callback as default (will show the prompt from example above):
```js
winbox.close();
```
Force closing the window (does not show the prompt from example above):
```js
winbox.close(true);
```
WinBox provides you some built-in control classes you can pass when creating a window instance.
> All control classes from this list could be added or removed during lifetime of the window (after creation). State classes like `max`, `min`, `full`, `hidden` and `focus` could not be changed manually! For this purpose use the WinBox member methods accordingly e.g. `maximize()`, `minimize()`, `hide()`.
Classname
Description
no-animation
Disables the windows transition animation
no-shadow
Disables the windows drop shadow
no-header
Hide the window header incl. title and toolbar
no-min
Hide the minimize icon
no-max
Hide the maximize icon
no-full
Hide the fullscreen icon
no-close
Hide the close icon
no-resize
Disables the window resizing capability
no-move
Disables the window moving capability
> Without the header the user isn't able to move the window frame. It may be useful for creating fixed popups.
Pass in classnames when creating the window to apply behaviour:
```js
const winbox = WinBox({
class: [ "no-min", "no-max", "no-full", "no-resize", "no-move" ]
});
```
> The example above is a good start to create classical popups.
Alternatively you can use a whitespace separated string:
```js
const winbox = WinBox({
class: "no-min no-max no-full no-resize no-move"
});
```
You can add or remove all control classes from above along the window's lifetime:
```js
const winbox = WinBox();
winbox.addClass("no-resize")
.addClass("no-move");
```
```js
winbox.removeClass("no-resize")
.removeClass("no-move");
```
```js
winbox.toggleClass("no-resize")
.toggleClass("no-move");
```
```js
const state = winbox.hasClass("no-resize") &&
winbox.hasClass("no-move");
```
## Custom Splitscreen
Use the viewport limit to define your own splitscreen areas, e.g. for a simple vertical split:
```js
new WinBox("Split Left", {
right: "50%"
});
new WinBox("Split Right", {
left: "50%"
});
```
Same way you can also define custom sizes and positions for each split as well as complex grids, e.g.:
```js
new WinBox("Split Top-Left", { right: "66%", bottom: "50%", max: true });
new WinBox("Split Bottom-Left", { right: "66%", top: "50%", max: true });
new WinBox("Split Middle", { left: "34%", right: "34%", max: true });
new WinBox("Split Top-Right", { left: "66%", bottom: "50%", max: true });
new WinBox("Split Bottom-Right", { left: "66%", top: "50%", max: true });
```
The splitscreen from above will look like this grid:
```
---------------------------------------------
| | | |
| | | |
| Top Left | | Top Right |
| | | |
| | | |
--------------- Middle ----------------
| | | |
| | | |
| Bottom Left | | Bottom Right |
| | | |
| | | |
---------------------------------------------
```
You can set the values for the viewport dynamically, doing this makes it possible to size the grid dynamically and also change the grid schema.
This example will add a custom control button `.wb-like` to the window heading toolbar along some CSS for icon styling:
```css
.wb-like {
background-size: 20px auto;
}
.wb-like.active {
background-image: url(demo/heart-filled.svg) !important;
}
```
Attach a control to the window toolbar:
```js
winbox.addControl({
// the position index
index: 1,
// classname to apply styling
class: "wb-like",
// icon url when not specified via classname
image: "demo/heart.svg",
// click listener
click: function(event, winbox){
// the winbox instance will be passed as 2nd parameter
console.log(winbox.id);
// "this" refers to the button which was clicked:
this.classList.toggle("active");
}
});
```
Remove a control from the window toolbar:
```js
winbox.removeControl("wb-like")
.removeControl("wb-min");
```
You can fully customize the WinBox window layout by providing a custom `template` via the config during creation. This way you can add new elements to the window or re-arrange them.
This example will add a control button `.wb-custom` to the window toolbar by using a custom template along some CSS:
```css
.wb-custom {
background-image: url(demo/icon-github.svg);
background-size: 17px auto;
}
```
Create by using a custom template:
```js
const template = document.createElement("div");
template.innerHTML = `
`;
new WinBox("Custom Template", { template });
```
> The `.wb-drag` element needs to be existing when the user should be able to move the window by dragging the heading toolbar.
> Additionally, take a look into the themes folder to get some ideas how to customize the window.
The window boilerplate:
Hide or disable specific icons:
```css
.wb-min { display: none }
.wb-full { display: none }
.wb-max { display: none }
.wb-close { display: none }
```
Modify a specific icon:
```css
.wb-max {
background-image: url(src/img/max.png);
background-position: center;
background-size: 15px auto;
}
```
Use black standard icons (useful for bright backgrounds):
```css
.wb-control { filter: invert(1) }
```
Modify or disable resizing areas on the window borders:
```css
/* north */
.wb-n { display: none }
/* east */
.wb-e { display: none }
/* south */
.wb-s { display: none }
/* west */
.wb-w { display: none }
/* north-west */
.wb-nw { display: none }
/* north-east */
.wb-ne { display: none }
/* south-west */
.wb-sw { display: none }
/* south-east */
.wb-se { display: none }
```
Modify or disable the window drop shadow:
```css
.winbox { box-shadow: none }
```
Style the header title:
```css
.wb-title { font-size: 12px }
```
Style the titlebar icon:
```css
.wb-icon {
width: 35px;
background-size: 35px 35px;
}
```
Style the window background (frame):
```css
.winbox {
background: linear-gradient(90deg, #ff00f0, #0050ff);
border-radius: 12px 12px 0 0;
}
```
Style the body of a window element and set the frame border:
```css
.wb-body {
/* the width of window frame border: */
margin: 4px;
color: #fff;
background: #131820;
}
```
> The margin of `.wb-body` corresponds to the width of the window border.
Apply styles when window is in "minimized" state:
```css
.winbox {
border-radius: 10px;
}
.winbox.min {
border-radius: 0;
}
.winbox.min .windbox-title {
font-size: 12px;
}
```
Apply styles when window is NOT in "minimized" state:
```css
.winbox:not(.min) {
/* apply styles */
}
```
Apply styles when window is in "maximized" state:
```css
.winbox {
border-radius: 10px;
}
.winbox.max {
border-radius: 0;
}
.winbox.max .wb-max {
opacity: 0.5;
}
```
Apply styles when window is NOT in "maximized" state:
```css
.winbox:not(.max) {
/* apply styles */
}
```
Apply styles when window is in "fullscreen" state:
```css
.wb-body:fullscreen {
/* apply styles */
}
```
Apply styles when window is in "focus" state:
```css
.winbox {
background: #999;
}
.winbox.focus {
background: #0050ff;
}
.winbox .wb-control {
display: none;
}
.winbox.focus .wb-control {
display: block;
}
```
Apply styles when window is NOT in "focus" state (the same logic from example above, but shorter):
```css
.winbox:not(.focus) {
background: #999;
}
.winbox:not(.focus) .wb-control {
display: none;
}
```
Apply styles when window is in "modal" state:
```css
.winbox.modal .wb-close { display: none }
```
Customize the modal background overlay:
```css
.winbox.modal:after {
background: #0d1117;
opacity: 0.5;
animation: none;
}
```
#### Style Scrollbars
```css
.wb-body::-webkit-scrollbar {
width: 12px;
}
.wb-body::-webkit-scrollbar-track {
background: transparent;
}
.wb-body::-webkit-scrollbar-thumb {
border-radius: 10px;
background: #263040;
}
.wb-body::-webkit-scrollbar-thumb:window-inactive {
background: #181f2a;
}
.wb-body::-webkit-scrollbar-corner {
background: transparent;
}
```
## Useful Hints
Often you need to hide specific content parts when it was mounted to a window or hiding when NOT inside a window:
Now you can add the two classes `"wb-hide"` and `"wb-show"` to any element to control visibility between the two states "inside" and "outside" a window:
```html
Hide this header when in windowed mode
Hide this footer when NOT in windowed mode
```
The `display` property when using `"wb-show"` might not fit your needs. Please change this css class definition to your desired display-state accordingly.
```js
new WinBox({
mount: document.getElementById("content")
});
```
#### Best Practices
- Use a non-scrolling body element to get the best user experience on mobile devices.
- Or provide an alternative view strategy for mobile devices, e.g. when the device is a touch device then open a classical app view. If a mouse pointer is available, then mount this view to the WinBox window. Also, you can place a switch button in your application where the user can also toggle between these two modes.
## WinBox on Angular application
Step 1: Install WinBox library
```
npm i winbox
```
Step 2: Install WinBox types
```
npm i @types/winbox --save-dev
```
Step 3: Import WinBox in a component
```ts
import { Component } from '@angular/core';
import 'winbox';
declare const WinBox: WinBox.WinBoxConstructor;
@Component({
selector: 'my-app',
template: 'Open Window'
})
export class AppComponent {
openWindow() {
WinBox.new();
}
}
```
## WinBox on Vue application
https://github.com/wobsoriano/vue-winbox
It uses the native [teleport](https://v3.vuejs.org/api/built-in-components.html#teleport) component in Vue 3 and recommends https://github.com/LinusBorg/vue-simple-portal for Vue 2 users.
## WinBox on React application
https://github.com/rickonono3/react-winbox
A React controlled component for WinBox.js, with full Reactful props and state. Includes all configurations of WinBox.js by using React component props.
## Custom Builds
Go to the root directory of WinBox and run:
```cmd
npm install
```
Perform a build:
```cmd
npm run build
```
The final build is located in the `dist/` folder.
---
Copyright 2021-2023 Thomas Wilkerling, Hosted by Nextapps GmbH
Released under the Apache 2.0 License