Abstract

html-js is a low-level DOM manipulation and batching utility. It contains various methods for creating, adding and removing DOM elements, as well as managing events and attributes. It is also possible to use built-in methods for certain selectors.

Links

• Wiki documentation.
• Main Git repository.

Features

• Method chaining pattern
• DOM Element manipulation
• Custom event manipulation
• Property and reflection attributes
• Batching by selector

Implementations

useHtml

useHtml is a hook for ReactJS that helps to access the DOM element.

export const Component: React.FC = () => {
  const ref = useHtml(element => { /* DOM manipulations with html-js */ });
  
  return <div ref={ref} />;
};

Example

Creating a simple button with a click response. create() will create a button element. append will add other elements (more than one is possible) to the created element. addListeners will create a subscription to the onclick event.

const renderButton() {
  const button = append(
    create('button', {}, 'primary'),
    'Hello!'
  );

  return addListeners(button, {
    click: () => console.log('Hello Clicked!')
  });
}

This can also be written in one line.

const button = addListeners(
  append(
    create('button', {}, 'primary'),
    'Hello!'
  ), {
    click: () => console.log('Hello Clicked!')
  }
);

This will produce HTML like this

<button class="primary">Hello!</button>  <!-- with onclick listener -->

Uses

Basic

To get any element, you can use the get() function. It is equivalent to a querySelector() and will return only one element or undefined.

const div = get('#root');

You can pass it as a simple selector, or you can specify in the first argument the element for which you want to make a request.

const div = get(document, '#root');

The create() function will create the element. This is similar to document.createElement().

const div = create('div');

The create function can take more arguments: attributes and style classes.

const div = create('div', { tabindex: 0 }, 'my-class', "then-class");

The previous example will generate HTML code like this:

<div tabindex="0" class="my-class then-class"></div>

Then we can add something else to the created element using the append() function.

const dest = create('div');
const div = append(dest, 'Text');

You can use any nesting and number of arguments.

const div = append(
  create('div'),
  append(
    create('b'),
    'Hello'
  ),
  append(
    create('em'),
    'World!'
  );
);

Get something like this:

<div><b>Hello</b><em>World!</em></div>

There are also many other methods: addClass(), addAttribute(), etc. As well as methods for checking the values of attributes and classes. For example, let's add the tabindex attribute to the created div:

const div = addAttributes(
  create('div')
  { tabindex: 0 }
);

Events

The addListeners() function is responsible for subscribing to events. One works similar to addEventListener(). You can subscribe to any events. Even custom ones.

const button = addListeners(
  create('button'),
  {
    click: () => console.log('Clicked!'),
    customEvent: () => console.log('Hello!')
  }
);

You can use the subscribe-unsubscribe pattern.

const unsubscriber = subscribe(get('#root'), { click: () => { ... } });
unsubscriber();  // Call for unsubscribe events

Properties

You can add properties to elements that will be able to call a callback function if they have changed. This can be done using the addProperty() method.

const div = addProperty(
  create('div'),
  'message',
  () => console.log('message changed!')
);

You can also display property values as element attributes. For example, you can display the value of the message property.

const options = {
  callback: () => console.log('message changed!'),
  reflect: true
}

const div = addProperty(create('div'), 'message', options);

If we then do div.message = 'Hello!', the HTML code will look something like this:

<div message="Hello!"></div>

Custom Events

You can create and catch custom events associated with changing properties. For example, let's say we have a foo property on a nested element and we want it to catch a DOM event.

const container = addListeners(
  create('div'),
  {
    fooChanged: () => console.log('Foo changed!')
  }
);

To do this, you can use the addEventProperty() function, which will additionally generate fooChanged event if the property has changed.

const fire = addEventProperty(create('div'), 'foo');

Then we will add an element with a property to our container that will listen to the event.

const div = append(container, fire);

Ready. All that remains is to change the property.

fire.foo = 'Hello!'

Batching

You can apply library functions or custom handlers to many elements that match the selector at once. To do this, you need to use the select() or selectAll() functions, which work similarly to the standard ones. They return an object with a batch() method that takes a handler for all the elements found by the selector.

const batcher = select('div');
batcher.batch(addAttribute, 'foo');

select function can be passed several selectors at once or a root element from which to start the search.

const batcher = select(get('#root'), 'div', 'span', 'a');

You can also receive values after batching in the form of an array. For example, you can collect all the links on the form.

const batcher = select<HTMLLinkElement>('a');
const hrefs = batcher.batch(element => element.href);

You can run multiple selectors in a row or add DOM elements to the batching.

const batcher = select('div')
    .selectAll('span')
    .append(get('#dom-element'));

batcher.batch(...);