Component

Component

Definition of a Panel component/app, implemented as an HTML custom element. App logic and configuration is defined by extending this class. Instantiating a component is typically not done by calling the constructor directly, but either by including the tag in HTML markup, or by using the DOM API method document.createElement.

Constructor

new Component()

Source:
Examples

Defining a Panel component

class MyWidget extends Component {
  get config() {
    return {
      // options go here
    };
  }

  myMethod() {
    // etc
  }
}

Registering the custom element definition for the DOM

customElements.define('my-widget', MyWidget);

Adding an instance of the element to the DOM

<my-widget some-attr></my-widget>

Extends

  • WebComponent

Members

config :object

Defines standard component configuration.
Type:
  • object
Properties:
Name Type Attributes Default Description
template function function transforming state object to virtual dom tree
helpers object <optional>
 {} properties and functions injected automatically into template state object
routes object <optional>
 {} object mapping string route expressions to handler functions
appState object <optional>
 {} (app root component only) state object to share with nested descendant components; if not set, root component shares entire state object with all descendants
defaultState object <optional>
 {} default entries for component state
hooks object <optional>
 {} extra rendering/lifecycle callbacks
Properties
Name Type Attributes Description
preUpdate function <optional>
 called before an update is applied
postUpdate function <optional>
 called after an update is applied
updateSync boolean <optional>
 false whether to apply updates to DOM immediately, instead of batching to one update per frame
useShadowDom boolean <optional>
 false whether to use Shadow DOM
css string <optional>
 '' component-specific Shadow DOM stylesheet
Source:
Example
get config() {
  return {
    template: state => h('.name', `My name is ${name}`),
    routes: {
      'wombat/:wombatId': (stateUpdate={}, wombatId) => {
        // route handler implementation
      },
    },
  };
}

helpers :object

Template helper functions defined in config object, and exposed to template code as $helpers. This getter uses the component's internal config cache.
Type:
  • object
Source:
Example
{
  myHelper: () => 'some return value',
}

Methods

_syncAttrs()

Validates attrsSchema and syncs element attributes defined in attrsSchema
Source:

_updateAttr(attr)

Parses html attribute using type information from attrsSchema and updates this._attrs
Parameters:
Name Type Description
attr string attribute name
Source:

attr(attr)

gets the parsed value of an attribute
Parameters:
Name Type Description
attr string attribute name
Source:

attrs() → {object}

Returns the parsed attrs as a key-value POJO
Source:
Returns:
parsed attribute values from attrsSchema
Type
object

child(tagName, configopt) → {object}

For use inside view templates, to create a child Panel component nested under this component, which will share its state object and update cycle.
Parameters:
Name Type Attributes Default Description
tagName string the HTML element tag name of the custom element to be created
config object <optional>
 {} snabbdom node config (second argument of h())
Source:
Returns:
snabbdom vnode
Type
object
Example
{template: state => h('.header', this.child('my-child-widget'))}

findPanelParentByTagName(tagName) → {object}

Searches the component's Panel ancestors for the first component of the given type (HTML tag name).
Parameters:
Name Type Description
tagName string tag name of the parent to search for
Source:
Throws:
Throws an error if no parent component with the given tag name is found.
Returns:
Panel component
Type
object
Example
myWidget.findPanelParentByTagName('my-app');

getConfig(key)

Fetches a value from the component's configuration map (a combination of values supplied in the config() getter and defaults applied automatically).
Parameters:
Name Type Description
key string key of config item to fetch
Source:
Returns:
value associated with key
Example
myWidget.getConfig('css');
Executes the route handler matching the given URL fragment, and updates the URL, as though the user had navigated explicitly to that address.
Parameters:
Name Type Attributes Default Description
fragment string URL fragment to navigate to
stateUpdate object <optional>
 {} update to apply to state object when routing
Source:
Example
myApp.navigate('wombat/54', {color: 'blue'});

onConnected(fn)

Helper function which will queue a function to be run once the component has been initialized and added to the DOM. If the component has already had its connectedCallback run, the function will run immediately. It can optionally return a function to be enqueued to be run just before the component is removed from the DOM. This occurs during the disconnectedCallback lifecycle.
Parameters:
Name Type Description
fn function callback to be run after the component has been added to the DOM. If this callback returns another function, the returned function will be run when the component disconnects from the DOM.
Source:
Example
myApp.onConnected(() => {
  const handleResize = () => calculateSize();
  document.body.addEventListener(`resize`, handleResize);
  return () => document.body.removeEventListener(`resize`, handleResize);
});

onDisconnected(fn)

Helper function which will queue a function to be run just before the component is removed from the DOM. This occurs during the disconnectedCallback lifecycle.
Parameters:
Name Type Description
fn function callback to be run just before the component is removed from the DOM
Source:
Example
connectedCallback() {
  const shiftKeyListener = () => {
    if (ev.keyCode === SHIFT_KEY_CODE) {
      const doingRangeSelect = ev.type === `keydown` && this.isMouseOver && this.lastSelectedRowIdx !== null;
      if (this.state.doingRangeSelect !== doingRangeSelect) {
        this.update({doingRangeSelect});
      }
    }
  }
  document.body.addEventListener(`keydown`, shiftKeyListener);
  this.onDisconnected(() => {
    document.body.removeEventListener(`keydown`, shiftKeyListener);
  });
}

setConfig(key, val)

Sets a value in the component's configuration map after element initialization.
Parameters:
Name Type Description
key string key of config item to set
val value to associate with key
Source:
Example
myWidget.setConfig('template', () => h('.new-template', 'Hi'));

shouldUpdate(state) → {boolean}

To be overridden by subclasses, defining conditional logic for whether a component should rerender its template given the state to be applied. In most cases this method can be left untouched, but can provide improved performance when dealing with very many DOM elements.
Parameters:
Name Type Description
state object state object to be used when rendering
Source:
Returns:
whether or not to render/update this component
Type
boolean
Example
shouldUpdate(state) {
  // don't need to rerender if result set ID hasn't changed
  return state.largeResultSetID !== this._cachedResultID;
}

update(stateUpdateopt)

Applies a state update, triggering a re-render check of the component as well as any other components sharing the same state. This is the primary means of updating the DOM in a Panel application.
Parameters:
Name Type Attributes Default Description
stateUpdate object | function <optional>
 {} keys and values of entries to update in the component's state object
Source:
Example
myWidget.update({name: 'Bob'});

updateApp(stateUpdateopt)

Applies a state update specifically to app state shared across components. In apps which don't specify `appState` in the root component config, all state is shared across all parent and child components and the standard update() method should be used instead.
Parameters:
Name Type Attributes Default Description
stateUpdate object <optional>
 {} keys and values of entries to update in the app's appState object
Source:
Example
myWidget.updateApp({name: 'Bob'});