up.script up.hello(element, [options])

JavaScript function

Manually compiles a page fragment that has been inserted into the DOM by external code.

All registered compilers and macros will be called with matches in the given element.

The up:fragment:inserted event is emitted on the compiled element.

Unpoly automatically calls up.hello()

When the page is manipulated using Unpoly functions or HTML selectors, Unpoly will automatically call up.hello() on new fragments:

let link = document.querySelector('a[href]')
let { fragment } = await up.follow(link)
// The fragment is already compiled. No need to call up.hello().

You only ever need to use up.hello() after creating DOM elements without Unpoly's involvement, for example:

• Creating elements with document.createElement().
• Setting the innerHTML property on an existing element
• Parsing HTML into elements using browser APIs like DOMParser().
• Elements created by other libraries

In this case compilers will not run automatically and some of Unpoly's own HTML selectors will not be active. We can address this by manually calling up.hello() on new elements:

let element = document.createElement('div')
element.innerHTML = '<a href="/path" up-follow>click me</a>'
// The element is not compiled yet. We must compile it manually:
up.hello(element)

Recompiling elements

It is safe to call up.hello() multiple times with the same elements. In particular every compiler function is guaranteed to only run once for each matching element.

If a new compiler is registered after initial compilation, that new compiler is run automatically on current elements.

Detecting compiler errors

If a compiler function throws an error, up.hello() will still finish the compilation and not throw an error.

Instead compiler errors will print to the error console and emit an error event on window:

window.addEventListener('error', function(error) {
  alert("Got an error " + error.name)
})

up.hello(element)

See errors in user code for details.

Awaiting asynchronous compilation

Unpoly supports async compiler functions:

up.compiler('textarea.wysiwyg', async function(textarea) { // mark: async
  let editor = await import('wysiwyg-editor') // mark: await
  await editor.init(textarea) // mark: await
  return () => editor.destroy(textarea)
})

The up.hello() function returns a promise that fulfills when all synchronous and asynchronous compilers have terminated:

let textarea = up.element.createFromHTML('<textarea class="wysiwyg"></textarea>')
await up.hello(textarea) // mark: await
// chip: WYISWYG editor is now initialized

The fulfillment value is the same element that was passed as an argument:

let html = '<textarea class="wysiwyg"></textarea>'
let textarea = await up.hello(up.element.createFromHTML(html))