3.15
Search docs… /
Menu
Skill

up.script up.macro(selector, [options], macro)
JavaScript function

Registers a compiler that is run before all other compilers.

A macro lets you set attributes that will be compiled afterward.

If you want default attributes for every link and form, consider customizing your navigation options or configuring Unpoly to handle everything.

Example

In this example every link opens a modal with a custom animation shake:

<a href="/page1" up-layer="new modal" up-class="warning" up-animation="shake">Page 1</a>
<a href="/page2" up-layer="new modal" up-class="warning" up-animation="shake">Page 2</a>
<a href="/page3" up-layer="new modal" up-class="warning" up-animation="shake">Page 3</a>

A new [shake-modal] attribute would make the same links shorter:

<a href="/page1" shake-modal>Page 1</a>
<a href="/page2" shake-modal>Page 2</a>
<a href="/page3" shake-modal>Page 3</a>

We can define the [shake-modal] attribute by registering a macro that sets the [up-layer], [up-class], and [up-animation] attributes for us:

up.macro('[shake-modal]', function(link) {
  link.setAttribute('up-layer', 'new modal')
  link.setAttribute('up-class', 'warning')
  link.setAttribute('up-animation', 'shake')
})

Parameters

selector
required

The selector to match.

Type: string
[options.priority=0]
optional

The priority of this compiler.

Compilers with a higher priority are run first. Two compilers with the same priority are run in the order they were registered.

Type: number
[options.batch=false]
optional

If set to true and a fragment insertion contains multiple elements matching selector, the compiler function is only called once with all these elements.

Type: boolean
macro
required

The function to call when an element matching selector is inserted.

Up to three arguments can be accepted:

  1. The newly inserted element matching the selector
  2. Any data attached to the element
  3. Meta information about the current render pass

The function may return a destructor function that is called before it is removed from the DOM. The destructor function is called with the compiled element.

The compiler function can be async.

Type: Function(element, data, meta): (Function|Array<Function>|Promise<Function>|undefined)