html
Premium DOM Component
Dockable Panels
Expand, collapse, dock and float by Read Write Tools Nov 5, 2020
Abstract |
---|
The rwt-dockable-panels DOM component is an accordion-style component with panels that expand/collapse and dock/float. |
Motivation
Some apps have lots of interactive manipulations for working with a canvas or object. Putting the tools and options for these manipulation commands within menus is a weak design pattern. The use of floatable, dockable, and collapsable panels is a better alternative because it lets the user initiate commands with shorter mouse transit times and fewer clicks. It also provides the user with a personalized mental map of where the commands can be initiated, something that a hierarchical menu doesn't do well.
The component has these features:
- The component comprises a collection of panels that contain logically related information.
- Each panel has a titlebar for self-identification and a panel area comprising DOM elements.
- The titlebar has an expand/collapse button which allows the panel's elements to be shown or hidden.
- The titlebar has a float/dock button which allows the panel to be detached/attached from the main panel.
- Floating panels can be moved with the mouse by dragging the titlebar.
- The initial position of the menu is relative to any one of the four viewport corners.
In the wild
To see an example of this component in use, visit the simply.earth website. It uses this component for its Tangent, Scale, Rotate, Locate, and Identify panels. To understand what's going on under the hood, use the browser's inspector to view the HTML source code and network activity, and follow along as you read this documentation.
Installation
Prerequisites
The rwt-dockable-panels DOM component works in any browser that supports modern W3C standards. Templates are written using BLUEPHRASE notation, which can be compiled into HTML using the free Read Write View desktop app. It has no other prerequisites. Distribution and installation are done with either NPM or via Github.
Download
Download using NPM
OPTION
1: Familiar with Node.js and the package.json
file?
Great. Install the component with this command:
npm install rwt-dockable-panels
OPTION
2: No prior experience using NPM?
Just follow these general steps:
- Install Node.js/NPM on your development computer.
- Create a
package.json
file in the root of your web project using the command:
npm init
npm install rwt-dockable-panels
Important note: This DOM component uses Node.js and NPM and package.json
as a convenient distribution and installation mechanism. The DOM component itself does not need them.
Download using Github
If you prefer using Github directly, simply follow these steps:
- Create a
node_modules
directory in the root of your web project. - Clone the rwt-dockable-panels DOM component into it using the command:
git clone https://github.com/readwritetools/rwt-dockable-panels.git
Using the DOM component
After installation, you need to add two things to your HTML page to make use of it:
- Add a
script
tag to load the component'srwt-dockable-panels.js
file:
<script src='/node_modules/rwt-dockable-panels/rwt-dockable-panels.js' type=module></script>
-
Add the component tag somewhere on the page.
-
For scripting purposes, apply an
id
attribute. -
For WAI-ARIA accessibility apply a
role=contentinfo
attribute. -
Apply a
corner
attribute with one of these values to set the location of the toolbar relative to its parent.top-right
top-left
bottom-right
-
bottom-left
[default]
-
Apply a
sourceref
attribute with a reference to a JSON file containing the panel configuration. (Or optionally use the programmatic interface for panel configuration.) -
Optionally, apply a
state
attribute to set the initial state of the toolbar.-
closed
The toolbar menu should initially be collapsed. -
open
[default] The toolbar menu should initially be expanded.
-
-
Optionally, apply a
shortcut
attribute with a value like'F1'
,'F2'
,'F3'
, to allow the toolbar to be opened and closed using the keyboard. -
Optionally, apply an
embedded
attribute with a value of "embedded" when the component is used inside another DOM component.
-
Example:
<rwt-dockable-panels id=toolbarId sourceref='/panels.json' corner=top-right state=open shortcut='F1' role=contentinfo></rwt-dockable-panels>
Panel configuration
The panels can be configured programmatically or through a JSON file. Both accept similar objects, described here:
JSON file configuration
A JSON file containing a collection of panel configurations can be specified as
an attribute of the component. Do this with HTML like <rwt-dockable-panels sourceref='panels.json'></rwt-dockable-panels>
The JSON object should contain an object with two properties:
-
toolbar
an object for configuring the entire component, having:-
titlebar
the plain text or HTML to use for the main menu.
-
-
panels
an array of panel objects for configuring the panels, having:-
options
an object to configure each panel's basic properties:-
id
the HTML identifier for the panel -
titlebar
the text title for the panel -
tabIndex
the HTML tabIndex, optional -
tooltip
the fly-over popup title for the panel, optional
-
-
panelLines
an array of line objects to configure the elements of the panel, line by line.-
lineType
specifies what to put on the line, see below -
id
the HTML identifier for the line's principal element, see below
-
-
These are the possible lineTypes and their configuration properties:
-
"input"
-
labelText
the text to place before theINPUT
element -
id
the identifier for theINPUT
element -
textAfter
any text to place after theINPUT
element, optional -
tooltip
the fly-over popup title for theINPUT
element, optional
-
-
"button"
-
buttonText
the text to place on theBUTTON
element -
id
the identifier for theBUTTON
element -
tooltip
the fly-over popup title for theBUTTON
element, optional
-
-
"multi-button"
-
buttons
an array of objects to define each button, having:-
buttonText
the text to place on theBUTTON
element -
id
the identifier for theBUTTON
element -
tooltip
the fly-over popup title for theBUTTON
element, optional
-
-
-
"dropdown"
-
labelText
the text to place before theSELECT
element -
id
the identifier for theSELECT
element -
tooltip
the fly-over popup title for theSELECT
element, optional -
selections
an array ofOPTION
S, specified as objects, each having:-
v
theOPTION
value -
t
theOPTION
text
-
-
-
"slider+input"
-
id
is the identifier to be assigned to the textINPUT
being created (the range slider will append "-slider" to this id) -
curve
is the distribution of slider values: "callback", "linear" or "log"; defaults to linear if not defined -
fromSlider
is a callback function that synchronizesINPUT
value when the current slider position changes -
toSlider
is a callback function that synchronizes the current slider position when theINPUT
value changes -
fromUser
is a callback function to convert user text to internal value -
toUser
is a callback function to convert internal value to user text -
numDecimals
is the number of decimal points kept in the internal value (defaults to 2). -
minValue
is the minimum acceptable "value" in user units; defaults to "" if not specified -
maxValue
is the maximum acceptable "value" in user units; defaults to "" if not specified -
minPosition
is the minimum slider position; defaults to 0 if not specified -
maxPosition
is the maximum slider position; defaults to 100 if not specified -
stepPosition
is the accuracy of the slider; defaults to 1 if not specified -
labelText
is the text to be displayed in theLABEL
before the twoINPUT
elements -
tooltip
is the text to display on hover, optional -
widthInPx
is a string value specifying the width of the input field, with a trailing 'px', optional -
textAfter
is the optional short text to display after theINPUT
, optional
-
-
"generic"
-
id
the identifier for the "chef-generic" panel's outerDIV
element -
innerHTML
is the generic HTML to be displayed -
heightInPx
the CSS value for the panel's height, defaults to 'fit-content' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
-
"custom"
-
id
the identifier for the "chef-custom" panel's outerDIV
element -
innerHTML
is the custom HTML to be displayed -
heightInPx
the CSS value for the panel's height, defaults to 'fit-content' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
-
"table"
-
id
is the identifier to be assigned to theTABLE
being created -
innerHTML
is the TABLE's inner HTML -
minHeightInPx
is a number of pixels, expressed as a string ending in 'px', like '156px' -
maxHeightInPx
is a number of pixels, expressed as a string ending in 'px', like '156px' -
heightInPx
the CSS value for the panel's height, defaults to '100%' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
Programmatic configuration
The component has methods to programmatically configure panels. They use objects with the same properties as just described. The methods are:
- setTitlebar (html)
- sets the topmost menu titlebar
- appendPanel (panelId, options, panelLines)
-
creates a new panel and adds it to the component, returning
elPanel
which can be used in subsequent API methods.-
panelID
is a String which will be the identifer for the panel -
options
is an anonymous object having: -
titlebar
String -
expandable
Boolean, defaults to true -
dockable
Boolean, defaults to true -
tabIndex
Number -
tooltip
String -
panelLines
is an array of anonymous objects each containing theoptions
for a single line within the panel area below the titlebar, and where thelineType
determines which other properties are used.
-
- appendInputLine (elPanel, options)
-
The appendInputLine function creates a line with a label and an input. The possible
options
are:-
lineType
must have a value of'input'
-
labelText
the text to place before theINPUT
element -
id
the identifier for theINPUT
element -
textAfter
any text to place after theINPUT
element, optional -
tooltip
the fly-over popup title for theINPUT
element, optional
-
- appendSingleButton (elPanel, options)
-
creates an internal button for doing something user-defined. The possible
options
are:-
lineType
must have a value of'button'
-
buttonText
the text to place on theBUTTON
element -
id
the identifier for theBUTTON
element -
tooltip
the fly-over popup title for theBUTTON
element, optional
-
- appendMultiButtons (elPanel, options)
-
creates multiple buttons that logically work together and visually appear on one line. The possible
options
are:buttons
is an array of objects, each having:-
lineType
must have a value of'multi-button'
-
buttonText
the text to place on theBUTTON
element -
id
the identifier for theBUTTON
element -
tooltip
the fly-over popup title for theBUTTON
element, optional
-
- appendDropdown (elPanel, options)
-
creates a line with a label and a select element. The possible
options
are:-
lineType
must have a value of'dropdown'
-
labelText
the text to place before theSELECT
element -
id
the identifier for theSELECT
element -
tooltip
the fly-over popup title for theSELECT
element, optional -
selections
an array ofOPTION
S, specified as objects, each having: -
v
theOPTION
value -
t
theOPTION
text
-
- appendSliderWithInput (elPanel, options)
-
creates a line with a label and two
INPUT
s: a slider/input combo. The possibleoptions
are:-
lineType
must have a value of'slider+input'
-
id
is the identifier to be assigned to the textINPUT
being created (the range slider will append "-slider" to this id) -
curve
is the distribution of slider values: "callback", "linear" or "log"; defaults to linear if not defined -
fromSlider
is a callback function that synchronizesINPUT
value when the current slider position changes -
toSlider
is a callback function that synchronizes the current slider position when theINPUT
value changes -
fromUser
is a callback function to convert user text to internal value -
toUser
is a callback function to convert internal value to user text -
numDecimals
is the number of decimal points kept in the internal value (defaults to 2). -
minValue
is the minimum acceptable "value" in user units; defaults to "" if not specified -
maxValue
is the maximum acceptable "value" in user units; defaults to "" if not specified -
minPosition
is the minimum slider position; defaults to 0 if not specified -
maxPosition
is the maximum slider position; defaults to 100 if not specified -
stepPosition
is the accuracy of the slider; defaults to 1 if not specified -
labelText
is the text to be displayed in theLABEL
before the twoINPUT
elements -
tooltip
is the text to display on hover, optional -
widthInPx
is a string value specifying the width of the input field, with a trailing 'px', optional -
textAfter
is the optional short text to display after theINPUT
, optional
-
- appendGenericArea (elPanel, options)
-
creates a <div> styled with CSS class 'chef-generic'. The possible
options
are:-
lineType
must have a value of'generic'
-
id
the identifier for the generic panel's outerDIV
element -
innerHTML
is the generic HTML to be displayed -
heightInPx
the CSS value for the panel's height, defaults to 'fit-content' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
- appendCustomArea (elPanel, options)
-
creates a <div> styled with CSS class 'chef-custom'. The possible
options
are:-
lineType
must have a value of'custom'
-
id
the identifier for the custom panel's outerDIV
element -
innerHTML
is the custom HTML to be displayed -
heightInPx
the CSS value for the panel's height, defaults to 'fit-content' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
- appendTableArea (elPanel, options)
-
creates a <table> suitable for use with dynamic HTML. The possible
options
are:-
lineType
must have a value of'table'
-
id
is the identifier to be assigned to theTABLE
being created -
innerHTML
is the TABLE's inner HTML -
minHeightInPx
is a number of pixels, expressed as a string ending in 'px', like '156px' -
maxHeightInPx
is a number of pixels, expressed as a string ending in 'px', like '156px' -
heightInPx
the CSS value for the panel's height, defaults to '100%' -
overflowX
Whether to show a horizontal scrollbar: "scroll", "hidden", "clip", "auto" -
overflowY
Whether to show a vertical scrollbar: "scroll", "hidden", "clip", "auto"
-
Programmatic manipulation
The component also has methods to programmatically manipulate the toolbar and its panels.
- openToolbar ()
- shows all the panels in their current expand/collapse state
- closeToolbar ()
- leaves only the 'hamburger' button visible
- toggleToolbar ()
- reverse the current toolbar expand/collapse state
- expandPanel (panelID)
- shows all of the panel's lines
- collapsePanel (panelID)
- shows only the panel's titlebar
- detachPanel (panelID)
- detaches the panel from the toolbar, allowing it to float independently
- attachPanel (panelID)
- reattaches the panel to the toolbar
- presetDetachedX(panelID, css)
- Preset the panel's distance from left edge / right edge of the component when detached. "css" is the value to assign to the component's "left" or "right" CSS property.
- presetDetachedY(panelID, css)
- Preset the panel's distance from top edge / bottom edge of the component when detached. "css" is the value to assign to the component's "top" or "bottom" CSS property.
- presetDetachedWidth(panelID, css)
- Preset the panel's width when detached. "css" is the value to assign to the component's "width" CSS property.
- presetDetachedHeight(panelID, css)
- Preset the panel's height when detached. "css" is the value to assign to the component's "height" CSS property.
Programmatic access
The component has methods to access the inner buttons and titlebars.
- getMenuElement (panelID)
- returns the panel with the given identifer
- getExpandButton (panelID)
- returns the expand/collapse button for a given panel
- getFloatButton (panelID)
- returns the float/dock button for a given panel
- getTitlebar (panelID)
- returns the titlebar for a given panel
Customization
Initial position
Initially the toolbar is positioned a certain distance from one of the
viewport's corners, specified using the corner
attribute and two of these offset
variables.
rwt-dockable-panels {
--top: 30px;
--bottom: 30px;
--left: 30px;
--right: 30px;
--z-index: 1;
}
Visuals and color scheme
The font for the component can be changed with the --font-family
variable.
The width of the component can be set with the --width
variable.
The default color palette for the menu uses a dark mode theme. You can use CSS to override the variables' defaults:
rwt-dockable-panels {
--color: var(--pure-white);
--border-color: var(--pure-white);
--background-color1: var(--surfie-green);
--background-color2: var(--coral-atoll);
--background-color3: var(--tiber);
--background-color4: var(--eden);
}
Life-cycle events
The component issues life-cycle events.
component-loaded
- Sent when the component is fully loaded and ready to be used. As a convenience you can use the
waitOnLoading()
method which returns a promise that resolves when thecomponent-loaded
event is received. Call this asynchronously withawait
.
Reference
![]() | Documentation | READ WRITE HUB |
![]() | Source code | github |
![]() | Component catalog | DOM COMPONENTS |
![]() | Package installation | npm |
![]() | Publication venue | READ WRITE STACK |
License
The rwt-dockable-panels DOM component is not freeware. After evaluating it and before using it in a public-facing website, eBook, mobile app, or desktop application, you must obtain a license from Read Write Tools .
Dockable Panels Software License Agreement
Copyright © 2023 Read Write Tools.
- This Software License Agreement ("Agreement") is a legal contract between you and Read Write Tools ("RWT"). The "Materials" subject to this Agreement include the "Dockable Panels" software and associated documentation.
- By using these Materials, you agree to abide by the terms and conditions of this Agreement.
- The Materials are protected by United States copyright law, and international treaties on intellectual property rights. The Materials are licensed, not sold to you, and can only be used in accordance with the terms of this Agreement. RWT is and remains the owner of all titles, rights and interests in the Materials, and RWT reserves all rights not specifically granted under this Agreement.
- Subject to the terms of this Agreement, RWT hereby grants to you a limited, non-exclusive license to use the Materials subject to the following conditions:
- You may not distribute, publish, sub-license, sell, rent, or lease the Materials.
- You may not decompile or reverse engineer any source code included in the software.
- You may not modify or extend any source code included in the software.
- Your license to use the software is limited to the purpose for which it was originally intended, and does not include permission to extract, link to, or use parts on a separate basis.
- An eBook published under a single title and author.
- A mobile app for distribution under a single app name.
- A desktop application published under a single application name.
- A website published under a single domain name. For this purpose, and by way of example, the domain names "alpha.example.com" and "beta.example.com" are considered to be separate websites.
- A load-balanced collection of web servers, used to provide access to a single website under a single domain name.
Activation
To activate your license, copy the rwt-registration-keys.js
file to the root
directory of your website, providing the customer-number
and access-key
sent to
your email address, and replacing example.com
with your website's hostname.
Follow this example:
export default [{ "product-key": "rwt-dockable-panels", "registration": "example.com", "customer-number": "CN-xxx-yyyyy", "access-key": "AK-xxx-yyyyy" }]