Fusion Component

A Fusion Component is a web component configured for use in Activator. This document will describe all things necessary to get started with using and building Fusion Components. Only components for developing slides (or web pages) are discussed. In the code you may see references to email components, however these are not possible to define by users.

Requirements

Everything required is available in the Fusion Shared Resource that is supplied by Anthill or a client using Activator.

The following are important 3rd party modules used in development of Fusion Components:

• lit-element https://lit-element.polymer-project.org/

• lit-html https://lit-html.polymer-project.org/

• redux https://redux.js.org/

File and Folder Structure

Components live in one of two places in a shared resource:

• src/components

• src/fusion/slide

The components folder contains custom components, i.e. components created by you or another developer for a specific purpose.

The components in fusion/slide folder contains the official components supplied by Anthill Agency, the developers of Activator.

A component itself is a folder with at least an index.js file. Other files can be added as necessary for the development and use of the component. It’s recommended that images and other assets are added to assets folder in root, and that reusable code is added as a mixin and imported from the mixin folder.

Naming Conventions

A web component should have a namespace, e.g. the name of an agency or developer initials. Official Fusion Components use the ‘fusion' namespace, e.g. fusion-list. You should NOT use the ‘fusion’ namespace when creating your own components.

The Anatomy of a Component

A Fusion Component is a lit-element web component with some added configuration and access to a redux store handling states and levels (z-index).

Here is an example (fusion-group):

import { html, css } from 'lit-element';
import { FusionComponent } from '../../';
import {
  BorderedElement, ElementsAligner, BackgroundImageArea,
} from '../../mixins';
import { getValueObject, intersectMap } from '../../utils';

class FusionGroup extends FusionComponent, [
  BorderedElement,
  ElementsAligner,
  BackgroundImageArea,
]) {
  static get properties() {
    const { top, left, ...borderedProps } = super.properties;
    return {
      top,
      left,
      width: {
        type: String,
        fieldType: 'Number',
        value: '400px',
      },
      height: {
        type: String,
        fieldType: 'Number',
        value: '400px',
      },
      'background-color': {
        type: String,
        fieldType: 'ColorPicker',
        value: 'rgba(255, 255, 255, 0)',
      },
      ...borderedProps,
    };
  }

  static get options() {
    return {
      componentName: 'fusion-group',
      componentUIName: 'Group Container',
      componentCategory: 'UI',
      componentDescription: 'Group components and other elements in order to move and copy/paste together',
      isTextEdit: false,
      nestedComponents: ['*'],
      defaultTemplate: '',
      resizable: 'all',
      draggable: 'xy',
      rotatable: true,
      sortable: false,
      ...super.options,
    };
  }

  update(changedProps) {
    super.update(changedProps);
    if (this.isRendered) {
      this.borderChanges(changedProps);
    }
  }

  borderChanges(props) {
    if (this.constructor.isBorderChanged(props)) {
      this.constructor.sizeTriggers.forEach(prop => this.setSize(prop));
    }
  }

  setSize(prop) {
    const { num } = getValueObject(this[prop]);
    const size = this.getSizeByBorder(num);
    this.setElementProp(prop, size);
    this.setAttribute(prop, size);
  }

  static get styles() {
    return [
      super.styles,
      css`
        :host {
          display: block;
        }
        .fusion-group {
          width: 100%;
          height: 100%;
          background-color: var(--background-color);
          border: var(--border-width) var(--border-style) var(--border-color);
          border-radius: var(--border-radius);
          box-sizing: border-box;
        }
      `,
    ];
  }

  render() {
    super.render();
    return html`
      <style>
        ${this.dynamicStyles}
      </style>
      <div class='fusion-group'>
        <slot></slot>
      </div>
      ${this.constructor.systemSlotTemplate}
    `;
  }
}

export { FusionGroup };

Let’s break down some important parts, referring to the line numbers.

1: Here we import tools from the lit-element module that allow us to create a web component.

2: We then import the FusionComponent module that will help us build a component compatible with Activator.

3: We import some helper scripts to make it easier to create our component

8: Here we define the class for the component, providing our helper scripts as dependencies.

13: Defines custom properties the web component can accept

37: Sets the options used by Activator application to display the component and menus

57: lit-element lifecycle method

64,70: Custom methods

96: lit-element render method. Creates the HTML with styles that will be rendered in the browser.

110: The class must be exported so that it can be imported and included in content

Building Web Components for Use in Activator

Please refer to the official lit-element and lit-html documentation for general understanding of how to build web components using these libraries.

• https://lit-element.polymer-project.org/

• https://lit-html.polymer-project.org/

On top of that, the Fusion library adds some settings that allow Activator to import the components and create a UI for them in the editor.

There are two types of settings: properties and options.

The properties are the attributes that can be set on the component and will most often translate into a CSS style rule, e.g. background-color.

Options are settings that define how the component should behave in Activator UI, e.g. if it should be resizable and draggable.

Defining Properties

A property is an object which can have the following keys:

(Some properties of lit-element has been omitted, please see lit-element properties documentation)

• type

  • [Default: String]

  • See lit-element documentation

  • Possible values: String, Number, Boolean, Array, Object

• fieldType

  • [Default: ‘String’]

  • The field type to use in UI to capture input from user

  • Possible values: ‘String’, ‘Number’, ‘Boolean’, ‘Select’, ‘ColorPicker’, ‘Modal’, ‘hidden’

  • Required for custom props

• assetType

  • Type of asset to target. Will define what content is displayed in modal window when changing source.

  • Possible values: ‘Image’, ‘Video’

• value

  • The default value of the property

• min

  • Used when defining a minimum value

• step

  • Used when defining a step value, e.g. for a slider

• selectOptions

  • Options that can be selected. Used together with ‘Select’ fieldType.

• prop

  • Required for custom props

  • true or false

• browserNotSupported

  • List of browsers not supported

  • Example: browserNotSupported: ['ie']

• propertyGroup

  • Defines which UI property section the component property will be shown.

  • Possible values: 'action', 'activeState', 'adjust', 'alignment', 'allowLayouts', 'animation', 'asset', 'audio', 'background', 'border', 'closeButton', 'component', 'controls', 'deviceVisibility', 'error', 'field', 'fragment', 'handle', 'image', 'innerPadding', 'input', 'layout', 'layoutDirection', 'line', 'link', 'list', 'listItem', 'margin', 'media', 'other', 'padding', 'placeholder', 'position', 'references', 'scroll', 'separator', 'shape', 'size', 'slider', 'slideshowIndicators', 'slideshowNavigation', 'slideshowState', 'sortableList', 'tab', 'tab-border', 'tabs', 'table', 'tabGroup', 'text', 'veevaMonitoring'.

  • Example: propertyGroup: 'layout'

• propertyArea

  • Defines which UI area tab the component property will be shown in.

  • Possible values: 'settings', 'style'

  • Default: 'style'

Defining Options

The options object allow configuration of the component in relation to Activator.

• componentName - STRING

  • The tag name that will be used

• componentUIName - STRING

  • Name of the component as it should appear in a UI, e.g. in Activator component list

• componentCategory - STRING

  • Category to place the component in. Will group components in Activator UI

• componentDescription - STRING

  • Short description of what the component is about

• isTextEdit - BOOLEAN

  • Set to true if text edit controls should be loaded in Activator

• nestedComponents - ARRAY

  • Defines what other components can be nested within this one

  • Empty array, [], means that no other component can be nested

• excludedComponents - ARRAY

  • Defines what other components cannot be nested within this one

• defaultTemplate - STRING

  • Used to populate component when added, if no content is provided

  • Example: ‘<p>Default Headline</p>’

• resizable - BOOLEAN/STRING

  • If it should be possible to resize the element

  • Use false if it shouldn’t be resizable (default for responsive content)

  • Use ‘all’ (default for absolutely positioned content) or individual flags: ‘e,w’

• draggable - BOOLEAN/STRING

  • If it should be possible to move the element if positioned absolutely

  • Use false if it shouldn’t be draggable (default for responsive content)

  • Use ‘x' and 'y’ to define if it can be moved horizontally and/or vertically

  • Example: ‘xy’ mean that the element can be moved both horizontally and vertically

• rotatable - BOOLEAN

  • If it should be possible to rotate the element or not

  • Use false if it shouldn’t be rotatable (default for responsive content)

  • Use true if it should be rotatable (default for absolutely positioned content)

• sortable - BOOLEAN

  • If it should be possible to sort child items, or not

  • Use false if it shouldn’t be sortable (default)