ProxyComponent

ProxyComponent

Definition of a generic Component which proxies attributes and events between itself and a variable child component.

Constructor

new ProxyComponent()

Source:

Extends

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
Overrides:
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
Inherited From:
Source:
Example
{
  myHelper: () => 'some return value',
}

localConfig

Override this to extend the default configuration.
Source:
See:

observedEvents :Array.<string>

Defines the names of events which will be emitted by the wrapped component. Bubbling events will bubble through, but non-composed events from ShadowDOM elements will not and will be re-dispatched from the proxy.
Type:
  • Array.<string>
Source:

Methods

allowEvent(ev) → {boolean}

Override this method to stop events from being bubbled through this element.
Parameters:
Name Type Description
ev Event event to check
Source:
Returns:
whether event should bubble through
Type
boolean
Example

filter specific events out

class MyWidget extends ProxyComponent {
  allowEvent(ev) {
    // don't propagate click events for the v2 component
    return this.getTargetElementTag() !== `my-widget-v2` && ev.type !== `click`;
  }
}

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())
Inherited From:
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
Inherited From:
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
Inherited From:
Source:
Returns:
value associated with key
Example
myWidget.getConfig('css');

getTargetElementTag() → {string}

Override to determine which tag to instantiate as the child. This is where all switching logic should go.
Source:
Returns:
- tag name of the component to instantiate
Type
string
Example

a URL based feature flag

class MyWidget extends ProxyComponent {
  getTargetElementTag() {
    if (window.location.search.includes('enable_beta') {
      return 'my-widget-v2';
    }

    return 'my-widget-v1'
  }
}
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
Inherited From:
Source:
Example
myApp.navigate('wombat/54', {color: 'blue'});

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
Inherited From:
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
Inherited From:
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 <optional>
{} keys and values of entries to update in the component's state object
Inherited From:
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
Inherited From:
Source:
Example
myWidget.updateApp({name: 'Bob'});