rwt-dockable-panels
v1.0.33
Published
Expand, collapse, dock and float accordion-style, standards-based DOM component
Downloads
38
Maintainers
Readme
html
Premium DOM Component
Dockable Panels
Expand, collapse, dock and 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
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 paneltitlebar
the text title for the paneltabIndex
the HTML tabIndex, optionaltooltip
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 belowid
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
elementid
the identifier for theINPUT
elementtextAfter
any text to place after theINPUT
element, optionaltooltip
the fly-over popup title for theINPUT
element, optional
"button"
buttonText
the text to place on theBUTTON
elementid
the identifier for theBUTTON
elementtooltip
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
elementid
the identifier for theBUTTON
elementtooltip
the fly-over popup title for theBUTTON
element, optional
"dropdown"
labelText
the text to place before theSELECT
elementid
the identifier for theSELECT
elementtooltip
the fly-over popup title for theSELECT
element, optionalselections
an array ofOPTION
S, specified as objects, each having:v
theOPTION
valuet
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 definedfromSlider
is a callback function that synchronizesINPUT
value when the current slider position changestoSlider
is a callback function that synchronizes the current slider position when theINPUT
value changesfromUser
is a callback function to convert user text to internal valuetoUser
is a callback function to convert internal value to user textnumDecimals
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 specifiedmaxValue
is the maximum acceptable "value" in user units; defaults to "" if not specifiedminPosition
is the minimum slider position; defaults to 0 if not specifiedmaxPosition
is the maximum slider position; defaults to 100 if not specifiedstepPosition
is the accuracy of the slider; defaults to 1 if not specifiedlabelText
is the text to be displayed in theLABEL
before the twoINPUT
elementstooltip
is the text to display on hover, optionalwidthInPx
is a string value specifying the width of the input field, with a trailing 'px', optionaltextAfter
is the optional short text to display after theINPUT
, optional
"generic"
id
the identifier for the "chef-generic" panel's outerDIV
elementinnerHTML
is the generic HTML to be displayedheightInPx
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
elementinnerHTML
is the custom HTML to be displayedheightInPx
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 createdinnerHTML
is the TABLE's inner HTMLminHeightInPx
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:
Programmatic manipulation
The component also has methods to programmatically manipulate the toolbar and its panels.
Programmatic access
The component has methods to access the inner buttons and titlebars.
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.
Reference
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 .
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: