Skip to main content

SipaComponent

SipaComponent​

Easy but powerful component class implementation to create your reusable components

new SipaComponent(data, options)​

ParamTypeDefaultDescription
dataObject.<String, *>object of properties
optionsObject
options.sipa_hiddenbooleanfalseinitial visibility state
options.sipa_cachebooleantrueuse node caching for templates
options.sipa_classesstringadditional classes for component tag
options.sipa_aliasstringalias to access from parent by uniq accessor name
options.sipa_render_periodnumber100max once per period (ms), a component is rerendered again on data changed. Set to 0 for unlimited renderings at the same time.
options.sipa_custom_attributesObject.<string, string>additional custom attributes on the component tag
options.contentstringHTML content inside the component element, available for slots

Example

const component = new SipaComponent({
         name: "Foo",
         age: 45,
     }, {
         sipa_hidden: true,
         sipa_classes: "dark-style",
         sipa_custom_attributes: {
             id: "special-instance",
             disabled: "disabled",
             onclick: "alert('hello world!')",
             style: "color: red;"
         }
     });

sipaComponent._data : Object​

The components data representation

sipaComponent._meta : Meta​

The components meta data for internal management

sipaComponent._component_id_incrementer : number​

Kind: instance property of SipaComponent

sipaComponent._component_instances : function​

class

sipaComponent._registered_components : function​

class

sipaComponent.initTemplate()​

Ensure that the template is initialized, so that all nested children are available.

You may for example call this method, before subscribing to children events, to ensure that the children are available.

If the component has already been appended or rendered to the DOM, the template is of course already initialized implicitly. But in some cases you don't know, if it already happened or you know, that it couldn't have happened. E.g. in the constructor of your component.

sipaComponent.html(options) → string​

Kind: instance method of SipaComponent

Returns: string - rendered HTML template() with current values of data

ParamTypeDefaultDescription
optionsObject
options.cachebooleantrueuse node cache

sipaComponent.node(options) → Element​

Kind: instance method of SipaComponent

Returns: Element - element representation of html()

ParamTypeDefaultDescription
optionsObject
options.cachebooleantrueuse node cache

sipaComponent.append(query_selector) → SipaComponent​

Create a DOM node of the instance and append it to the given css query selector

ParamType
query_selectorstring

sipaComponent.prepend(query_selector) → SipaComponent​

Create a DOM node of the instance and prepend it to the given css query selector

ParamType
query_selectorstring

sipaComponent.replaceWith(query_selector) → SipaComponent​

Create a DOM node of the instance and replace it to the given css query selector

ParamType
query_selectorstring

sipaComponent.alias() → string​

Get the sipa alias of the current instance

sipaComponent.cloneData() → Object​

Get cloned data of the current instance.

Please note: Because the data is cloned, there are no longer any references to the original data. This means that this data can be changed without risk. However, it also means that the instance data of the component cannot be changed by modifying the cloned data.

So you may use this, if you want to do some independent data processing while keeping the original data state of the component instance.

If you want to modify the instance data, use the update() method!

sipaComponent.resetToData(data, options) → SipaComponent​

Set cloned data of the current instance

ParamTypeDefaultDescription
dataObject
optionsObject
options.renderbooleantruerender component after data update

sipaComponent.value()​

Value representation of the component. Should be usually overwritten by the inherited component class.

sipaComponent.element() → Element | undefined​

Get the (first) element of the current instance that is in the DOM

sipaComponent.elements() → Array.<Element>​

Get all elements of the current instance that is in the DOM.

sipaComponent.selector() → string​

Get the unique css selector of the current instance(s) element(s)

Returns: string - css selector

sipaComponent.destroy() → SipaComponent​

Destroy the components DOM representation and class data representation

sipaComponent.isDestroyed() → boolean​

Check if the current instance is destroyed

Returns: boolean - true if destroyed

sipaComponent.remove() → SipaComponent​

Remove the DOM representation(s), but keep the class data representation

sipaComponent.update(data, options) → SipaComponent​

Update the data of the instance and its children by alias if available. Then rerender its view.

ParamTypeDefaultDescription
dataData
optionsObject
options.renderbooleantruererender DOM elements after data update
options.resetbooleanfalseif false, merge given data with existing, otherwise reset component data to given data
options.cachebooleantrueuse node cache or not on component and all(!) children and their children

Example

<example-component enabled="false">
    <nested-component sipa-alias="my_nest" name="'foo'"></nested-component>
    <other-nested-component sipa-alias="other" age="77"></nested-component>
</example-component>

const my_instance = new ExampleComponent();

my_instance.update({
    enabled: true,
    my_nest: {
        name: "bar",
    },
    other: {
        age: 111,
    }
});

sipaComponent.render(options) → SipaComponent​

Render component again

ParamTypeDefaultDescription
optionsObject
options.cachebooleantrueuse node cache or not on component and all(!) children and their children
options.render_periodbooleanoverwrite default render period (_meta.sipa._render_period) only once

sipaComponent.addClass(class_name, options) → SipaComponent​

Add given class to the current instance tag element and store its state

ParamTypeDefaultDescription
class_namestringone or more classes separated by space
optionsObject
options.updatebooleantruererender current instance DOM with new class

sipaComponent.hasClass(class_name) → boolean​

Check if current component instance has given class(es) in its class state

Returns: boolean - true if class is set

ParamDescription
class_nameone or more classes that must be included

Example

<example-component class="test bingo">Example</example-component>

const my_instance = new ExampleComponent();

my_instance.hasClass("test");
// => true
my_instance.hasClass("bingo test");
// => true
my_instance.hasClass("test togo");
// => false

sipaComponent.removeClass(class_name, options) → SipaComponent​

Remove given class from the current instance tag element and its state

ParamTypeDefaultDescription
class_namestringone or more classes separated by space
optionsObject
options.updatebooleantruererender current instance DOM without removed class

sipaComponent.show(options) → SipaComponent​

Show current instance

ParamTypeDefault
optionsObject
options.updatebooleantrue

sipaComponent.hide(options) → SipaComponent​

Hide current instance

ParamTypeDefault
optionsObject
options.updatebooleantrue

sipaComponent.isHidden() → boolean​

Check if current instance is hidden

sipaComponent.isVisible() → boolean​

Check if current instance is visible

sipaComponent.children() → Object.<string, SipaComponent>​

Return children components of the current component with its sipa-aliases as their keys.

To work, the instance must already have been rendered at least once. To ensure explicitly, call initTemplate() before, e.g. when accessing children() in the instances constructor.

Returns: Object.<string, SipaComponent> - Object<alias, component>

Example

<example-component>
    <nested-component sipa-alias="my_nest"></nested-component>
    <other-nested-component sipa-alias="other"></nested-component>
</example-component>

const my_instance = new ExampleComponent();

my_instance.children();
// => { my_nest: NestedComponent, other: OtherNestedComponent }

sipaComponent.childrenAliases() → Array.<string>​

Return all keys for children aliases

sipaComponent.childrenValues() → Array.<SipaComponent>​

Return all values of children

sipaComponent.hasChildren() → boolean​

Check if the component has any children or not

sipaComponent.slots() → Object.<string, Element>​

Return all instantiated slot elements of the current instance by name.

To work, the instance must already have been rendered at least once. To ensure explicitly, call initTemplate() before, e.g. when accessing slots() in the instances constructor.

sipaComponent.parent() → undefined | SipaComponent​

Get parent component, if current component is a child component

Returns: undefined | SipaComponent - component

sipaComponent.hasParent() → boolean​

Check if the component has a parent or not

sipaComponent.parentTop() → SipaComponent​

Get the top level parent component, that has no parent component. Will return the current component, if no parent exists.

Returns: SipaComponent - component

Example

<example-component>
    <nested-component sipa-alias="my_nest">
        <other-nested-component sipa-alias="other"></nested-component>
    </nested-component>
</example-component>

const my_instance = new ExampleComponent();

my_instance.children().my_nest.children().other.parentTop();
// => ExampleComponent

sipaComponent.syncNestedReferences(options)​

Refresh all data references from top parent to all nested children and children below. This is used after the first rendering of the component for example.

After that, the update() will manage refreshing to direct children and parent components.

You may want to call this method, if you have a special case and modify the _data attribute manually.

ParamTypeDescription
optionsObject
options.update_dataObjectupdate data if given

sipaComponent.events() → SipaEvents​

Events of the component to subscribe, unsubscribe or trigger

sipaComponent._inheritedClass() → SipaComponent​

Get inherited class

sipaComponent._applyTemplateId(html) → string​

Add sipa-id attribute to given template html

ParamType
htmlstring

sipaComponent._applySlots(parsed, html) → string​

Replace slots to given parsed template

ParamTypeDescription
parsedChildNode
htmlstringraw for performance reasons

sipaComponent._applyTemplateClasses(args) → string | ChildNode​

Add class attribute to given template html. If html string given, return html. If ChildNode given, return ChildNode. (for performance reasons)

ParamType
argsObject
args.htmlstring
args.parsedChildNode

sipaComponent._applyTemplateHiddenState(args) → string | ChildNode​

Check and set display style to given template html

ParamType
argsObject
args.htmlstring
args.parsedChildNode

sipaComponent._applyTemplateChildrenComponents(args, options) → string | ChildNode​

Replace children components to given template html

ParamTypeDefaultDescription
argsObject
args.htmlstring
args.parsedChildNode
optionsObject
options.cachebooleantrueuse node cache

sipaComponent._applyTemplateSipaList(args, options) → string | ChildNode​

Replace children components to given template html

ParamTypeDefaultDescription
argsObject
args.htmlstring
args.parsedChildNode
optionsObject
options.cachebooleantrueuse node cache

sipaComponent._applyTemplateCustomAttributes(args) → string | ChildNode​

Apply custom attributes to given html template

ParamType
argsObject
args.htmlstring
args.parsedChildNode

sipaComponent._synchronizeDataToChildren(options)​

Synchronize children data from current instance to its children

ParamTypeDefaultDescription
optionsObject
options.recursivebooleanfalsesynchronize through all children trees
options.update_dataObjectupdate data if given

sipaComponent._synchronizeDataToParent()​

Refresh data reference from current instance to its parent

sipaComponent._addChild(child)​

Add component child class instance to list of current instance children

ParamType
childSipaComponent

SipaComponent.all(options) → * | function​

Return all instances of the component

ParamTypeDefaultDescription
optionsObject
options.include_childrenbooleanfalseinclude embedded children components

SipaComponent.bySipaId(sipa_id) → undefined | SipaComponent​

Get instance of current component class by sipa-id

ParamType
sipa_idnumber

Example

<example-component sipa-id="1">Initialized component</example-component>

SipaComponent.bySipaId(1);
// => ExampleComponent

SipaComponent.byId(id) → undefined | SipaComponent​

Get instance of current component class by id attribute

ParamType
idnumber

Example

<example-component attr-id="my-unique-id">Component declaration in body</example-component>

SipaComponent.byId("my-unique-id");
// => ExampleComponent

SipaComponent.destroyAll()​

Destroy all instances of current component class

SipaComponent.init(css_selector) → Array.<SipaComponent>​

Initialize all uninitialized components of the current component class in the DOM inside the given css selector automatically.

ParamTypeDefault
css_selectorstring"'body'"

SipaComponent.initElement(element, options) → SipaComponent​

Init given element as the current component class

Returns: SipaComponent - component instance

ParamTypeDescription
elementElement
optionsObject
options.sipa_componentSipaComponentif given, reinit given component instance
options.parent_dataObjectdata of parent element, if this is a child

SipaComponent.initChildComponents(component) → Element​

Init child components of the given component if available

ParamType
componentSipaComponent

SipaComponent.tagName() → string​

Get tag name of current component class

Example

<example-component>blub</example-component>

const my_instance = new ExampleComponent();

my_instance.tagName();
// => "example-component"

SipaComponent.instanceOfElement(element) → SipaComponent​

Get the component instance of the given element or one of its parent

ParamType
elementHTMLElement

Example

<example-component sipa-id="1">
    <nested-component sipa-id="2">
        <span id="nested_span">nested</span>
    </nested-component>
    <span id="top_span">top</span>
</example-component>

const nested_span = document.getElementById("nested_span");
SipaComponent.instanceOfElement(nested_span);
// => NestedComponent

const top_span = document.getElementById("top_span");
SipaComponent.instanceOfElement(top_span);
// => ExampleComponent

SipaComponent.registerComponent(component)​

Register given component class.

You need to register every new component that extends by SipaComponent to make it available.

ParamType
componentSipaComponent

Example

class MyComponent extends SipaComponent {
    ...
}

SipaComponent.registerComponent(MyComponent);

SipaComponent._parseHtml(html) → ChildNode​

Parse Html string to element and return the first element of the string

Param
html

SipaComponent._generateUniqueId() → number​

Generate unique component id (auto increment)

SipaComponent.template() → string​

Returns the template. Can be with embedded with EJS.

Example

class MyComponent extends SipaComponent {
  ...
}

MyComponent.template = () => {
    return `
<my-component>
    Hello <%= name %>!
    <% if(age > 77) { %>
        <br>You are very old!
    <% } %>
</my-component>
    `;
}

SipaComponent.Meta : Object​

Kind: static typedef of SipaComponent
Properties

NameTypeDefaultDescription
sipaObjectall sipa meta info
sipa.idnumberauto increment
sipa.classesstringinternal state representation for classes managed by components methods addClass() and removeClass()
sipa.hiddenbooleanfalsestate representation of hide() and show() methods
sipa.cachebooleantrueuse node caching for templates
sipa.aliasstringalias to access children by uniq accessor name
sipa.childrenArray.<SipaComponent>array of children sipa components
sipa.parentSipaComponentparent sipa component when using nested components
sipa.liststringparent sipa components _data reference, if the component has been initialized by using sipa-list
sipa.original_displaystringstore original display style when using hide() to restore on show()
sipa.changed_visibilitybooleaninfo if visibility has been changed at least once
sipa.custom_attributesObject.<string, string>state representation of declarative custom attributes defined with attr- prefix
sipa.body_nodesNodeListbody as childNodes of original declarative element
sipa._destroyedbooleanfalseFlag to determine if object has been destroyed
sipa._data_changedbooleantrueFlag for caching rendered nodes
sipa._cached_nodeElementStore cached node to reuse when rendering again without any data change or update()
sipa._render_periodnumber100Only one rendering per period in milliseconds for performance reasons. Disabled when option is 0. Caution: when rendering several times in this period, only the first and last rendering will happen at 0ms and 100ms

SipaComponent.Data : Object​

Kind: static typedef of SipaComponent

SipaComponent.Options : Object​

Kind: static typedef of SipaComponent
Properties

NameTypeDefault
update_view_only_when_visiblebooleanfalse

_sync_nested_references : boolean​

Sync nested references automatically after every render update May be disabled on performance cases. Then overwrite to 'false' at the inherited class.

instance(element) → SipaComponent​

Get instance of current component. For usage in component templates

Handy shortcut alias for SipaComponent.instanceOfElement().

ParamType
elementElement

Example

class MyComponent extends SipaComponent {
  dance() {
  }
}

class SuperComponent extends SipaComponent {
    superMan() {
    }
}

MyComponent.template = () => {
    return `
<my-component onclick="instance(this).dance();" onblur="instance(this).children().supp.superMan();">
    Hello <%= name %>!
    <super-component sipa-alias="supp" attr-onclick="instance(this).superMan();" attr-onblur="instance(this).parent().dance();"></super-component>
</my-component>
    `;
}