Element

What is 'element'?

Element is a low-level building block for web components.

It is represented by a custom tag in the markup with state and channel attributes:

<my-element state="elState" channel="reactionChannel"></my-element>

Element is an interactive piece of the screen with fully incapsulated behaviour.

Consists of associated logic, template and styles.

How to reason about it?

The usecases are somthing like:

• search box
• tab
• user avatar
• user details form
• ...

The main idea is that element NEVER interacts with other elements DIRECTLY. It only changes it's state as a reaction to outer "forces".

Usage

Definition

yaf.element({
  // String.
  // Element's tag name. Should be camelCase. The tag name in template will be 'my-element'
  name: 'myElement', 

  // String. 
  //The content of the associated style tag
  styles: require('./styles.css'),

  // String. 
  // The content of the associated template
  template: require('./template.html'), 

  // Map (String : Module|String).
  // The map of Alias Names and module objects to be used with element's associated logic
  inject: {
     // AMD/CommonJS format, will inject module.exports as ComponentAliasName
     // It's the same as var ComponentAliasName = require('../some-other-component');
    'ComponentAliasName' : require('../some-other-component'),

    // Angular format, will inject MySuperDirective using angular's DI
    // Also, it will add the injected angular-module to dependencies 
    'MySuperDirective' : 'my-super-module',

    // Mixed Angular-CJS/AMD format
    'MyCjsDirective' : require('../path/to/angular-module').name
  },

  // Map (String : NonFunction)
  // The default state of the element. Will be {} if not defined.
  // Will be created automatically if not linked in the template using 'state' attribute.
  state : {
    // Can be referenced inside the template using 'state.someValue'
    someValue: 'xxx'
  },
  
  // Object (String : NonFunction)
  // The default values for the element options configuration. Will be {} if not defined.
  // Each field is mapped to HTML attribute.
  options : {
     // Can be overridden by DOM-element attribute 'maxlength'
     maxlength : 50
  },

  // Function.
  // The associated element's logic. Will be called when element is attached to DOM and linked with it's state.
  ready: function(){
     
    // associated DOM-element
    this.element;

    // current linked state map
    this.state;

    // current parsed options map
    this.options;

    // the map of values, available in template. Defaults to {}
    this.templateScope;

    // the map of injected components 
    this.injector;

    // the injected component reference
    this.injector.ComponentAliasName;

  }
});

Simplest form

yaf.element({
  name: 'myElement',
  styles: require('./styles.css'),
  template: require('./template.html')
});

Usage Conventions

• Element MUST bind it's state to some namespace through HTML state attribute. (controlled by user)

<!-- incorrect -->
<my-element></my-element>

• Element MUST change only it's state. (controlled by user)
• Element CAN react on channel signals. (controlled by framework)
• Element CAN omit channel binding through HTML channel attribute.

Framework Implementation Requirements

• Element MUST create a className on the associated DOM-element using it's name (controlled by framework):

'myElement' -> '.my-element'

• Element MUST manage it's styles and template attachment and detachment. (controlled by framework)
• Element MUST create the associated DOM-element. (controlled by framework)
• Element SHOULD provide the API with scope attributes.
• Element MUST have some default state. (controlled by framework, fallback to a default empty object state)
• Element MUST have some default state. (controlled by framework, fallback to a default empty object state)
• Element CAN react on channel signals. (controlled by framework)
• Element CAN omit channel binding through HTML channel attribute.