Getting Started

The central structure in Declarity is the Entity, which is simply a javascript class. It analogous to a React component, but with some importand differences:

• Entity classes do not inherit from any specific class, instead of a class like React.Component

• In an Entity class, the render method is not required.

• methods in an Entity should be bound to the instance of the class. This can be done with either the arrow function, or binding within the class's constructor.

Let's define an Entity class.

class MyEntity {
  create = () => {
    console.log('Entity has been created!')
  }
}

export default MyEntity

To register the Entity, pass it to Declarity.register()

Declarity.register(<MyEntity key="my-entity" />

A couple points:

• You can (and should!) use JSX.
• A key prop is used in the entity instance. As of now every entity instance requires a key.

When the entity is registered, the create() method of our entity will be called.

Now we will add some more functionality to our Entity. Assuming we are in a browser:

class MyEntity {
  create = () => {
    const greeting = document.createElement('h1')
    greeting.innerText = "Hello There!";

    let body = document.getElementsByTagName('body')[0];
    body.appendChild(greeting);

    return { greeting }
  }
}

When the Entity is created, it will append an h1 element to the document body. At this point we can continue to build out our Entity class with other lifecycle methods, which we will touch in other pages of this documentation.

Also note the return { greeting } line. In Declarity, you may set state from within the create() and update() lifecycle methods by returning the new state from the method. In this case we are saving the greeting DOM node reference so that we do not need to fetch again later on.

Our Entity can also be given an update() method:

class MyEntity {
  create = () => {
    const greeting = document.createElement('h1')
    greeting.innerText = "Hello There!";

    let body = document.getElementsByTagName('body')[0];
    body.appendChild(greeting);

    return { greeting }
  }

  update = ({ state }) => {
    const { greeting } = state;

    greeting.innerText = "Awesome Person!";
  }
}

Now every time that the tree which our entity exists in is re-rendered, update() will be called.

Note the destructured { state } passed a parameter into the update function. Instead of having instance properties like React's this.props and this.state , Declarity passed all these properties as parameters. props state context are all available, as well as many others. For more info see the Entity class methods documentation.

In addition to the create() and update() methods, Declarity also supports good number of other lifecycle methods. Many of these are directly inspired from React, such as willMount() and didUpdate().

Let's remove our greeting node when the entity is unmounted:

class MyEntity {
  create = () => {
    const greeting = document.createElement('h1')
    greeting.innerText = "Hello There!";

    let body = document.getElementsByTagName('body')[0];
    body.appendChild(greeting);

    return { greeting }
  }

  update = ({ state }) => {
    const { greeting } = state;

    greeting.innerText = "Awesome Person!";
  }

  willUnmount = ({ state }) => {
    const { greeting } = state;

    greeting.remove();
  }
}

Unmounting occurs whenever an entity that had a certain key is no longer in the entity tree when it is re-rendered. In the case of willUnmount(), the method is called before the unmounting process occurs.