phosphor-widget
The core Phosphor widget class.
Phosphor widgets provide several useful behaviours:
-
Widget Hierarchy - A widget is a JS object which wraps a DOM node and establishes a live parent-child relationship. While this may seem trivial, it allows for the implementation of advanced message passing and notification behaviors, and provides a sane pattern for component reuse.
-
Messages - Standard messages include show/hide, attach/detach, resize, and close, to name just a few. Desktop GUI toolkits have had these for ages, but they are missing from the DOM. These sorts of messages are critical for creating a desktop-like experience in the browser. Users can also define their own custom messages to support advanced behavior.
-
Unopinionated Design - Any DOM content can be added to a widget. Examples exist for React and others, but the
node
attribute of aWidget
is just a standard DOM node, so content generated by nearly any framework can be hosted by a widget.
Package Install
Prerequisites
npm install --save phosphor-widget
Source Build
Prerequisites
git clone https://github.com/phosphorjs/phosphor-widget.gitcd phosphor-widgetnpm install
Rebuild
npm run cleannpm run build
Run Tests
Follow the source build instructions first.
# run tests in Firefox npm test # run tests in Chrome npm run test:chrome # run tests in IE npm run test:ie
Build Docs
Follow the source build instructions first.
npm run docs
Navigate to docs/index.html
.
Supported Runtimes
The runtime versions which are currently known to work are listed below. Earlier versions may also work, but come with no guarantees.
- IE 11+
- Firefox 32+
- Chrome 38+
Bundle for the Browser
Follow the package install instructions first.
Any bundler that understands how to require()
files with .js
and .css
extensions can be used with this package.
Usage Examples
Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.
A Widget
is the base class of the phosphor widget hierarchy. A Widget
has
a node
property, which is a standard DOM node. For simple UIs or for custom
generated content, the content nodes can be added directly to a widget's node:
; ;;widget.node.appendChilddiv;
A Widget
also inherits from
NodeWrapper,
which means setting the node id and toggling CSS classes is simple:
;widget.id = 'main';widget.addClass'foo';widget.addClass'bar';widget.removeClass'foo';widget.toggleClass'bar', false;
A widget can be attached to the DOM with the attach
method, which ensures
that the proper attachment messages are dispatched to the widget hierarchy.
;widget.attachdocument.body;
Likewise, a widget can be detached from the DOM with the detach
method,
though it is more common to simply dispose
of the widget.
;widget.attachdocument.body; // sometime later...widget.detach; // or almost equivalentlywidget.dispose;
Children can be added to a widget by using a layout
.
; ;; ;layout.myAddMethodfoo;layout.myAddMethodbar; ;parent.layout = layout;
The Layout
class is a low-level abstract base class which must be subclassed
to be useful. While it provides the greatest level of control and flexibility,
it requires a decent amount of code and a solid understanding of the framework
to use successfully. The AbstractLayout
class is provided to ease the burden
of writing layouts, but comes with a slight reduction in flexibility. However,
most layouts and container widgets can be built on top of the concrete
Panel and
PanelLayout classes.
The amount of flexibility offered by the base widget and layout classes allows a user to create nearly any application using content generated by nearly any framework. The PhosphorJS project provides several useful widgets, panels, and layouts out of the box. Some of the more commonly used are: