bajaux/spandrel

(require("bajaux/spandrel"))(arg, paramsopt) → {function}

Description:

• The purpose of spandrel is to provide a reasonably pure-functional,
  diffable method of defining a nested structure of bajaux Widgets and
  supporting HTML. Rather than require Widget implementors to manually code
  calls to initialize() or buildFor(), spandrel allows you to provide
  your desired structure of HTML elements and their associated Widget
  instances, and handle the work of updating the document as that structure
  may change over time.

  See Building Composite Widgets With spandrel for in-depth information.

Source:

• spandrel.js, line 138

Since:

• Niagara 4.10

Examples

Generate a static widget

const StaticWidget = spandrel([
  '<label>Name: </label>',
  '<input type="text" value="{{ props.name }}">',
  {
    dom: '<span></span>',
    value: false,
    properties: 'inherit'
  }
]);
return fe.buildFor({
  dom: $('#myStaticWidget'),
  type: StaticWidget,
  properties: { name: 'Logan', trueText: 'Good', falseText: 'Not So Good' }
});

Generate a dynamic widget with a field editor for each slot

const DynamicWidget = spandrel(comp => comp.getSlots().toArray().map(slot => ({
  dom: '<div class="componentSlot"/>',
  kids: [
    `<label>${ slot.getName() }: </label>`,
    { dom: '<span/>', complex: comp, slot: slot }
  ]
})));

return fe.buildFor({
  dom: $('#myDynamicWidget'),
  type: DynamicWidget,
  value: myComponent
});

Subclass an existing dynamic spandrel widget, making changes before rendering.

// our superclass will render a <label> element, with a background
// determined by a widget property.
const LabelWidget = spandrel((value, { properties }) => {
  const label = document.createElement('label');
  label.innerText = value;
  label.style.background = properties.background || '';
  return label;
});

const RedLabelWidget = spandrel((value, { renderSuper }) => {

  // renderSuper will call back to the superclass, allowing your subclass
  // to edit the data before spandrel renders it to the page.
  //
  // you can optionally pass a function to renderSuper that will tweak the
  // widget state before the superclass renders its data. if no tweaking is
  // desired, just renderSuper() is fine.
  //
  return renderSuper((state) => {
    state.properties.background = 'lightpink';

    // remember to return the new state.
    return state;
  })
    .then((label) => {
      // renderSuper will resolve the data exactly as rendered by the
      // superclass.
      label.style.color = 'red';
      return label;
    });
}, { extends: LabelWidget });

Parameters:

Name	Type	Attributes	Default	Description
arg	module:bajaux/spandrel~SpandrelData | function
params	object	<optional>	{}	params Properties Name Type Attributes Description extends function <optional> optionally specify a Widget superclass to extend strategy string <optional> optionally specify a known lookup strategy for dynamically building widgets. Currently, the only accepted value is niagara, which will instruct spandrel to use the Niagara registry to perform widget lookups (introducing a dependency on the webEditors module). If included, it overrides the manager parameter. manager module:bajaux/lifecycle/WidgetManager <optional> optionally provide your own WidgetManager to manage Widget lifecycle

Returns:

Type

function

Description:

• API Status: Development

Source:

• spandrel.js, line 8