Behavior Attributes

Behavior attributes are the main way to add interactivity to a Hyperview app. Behavior attributes enable rich interactions with a declarative syntax, powered by server-side logic.

Behaviors are based on a simple hypermedia model:

1. A behavior executes when it gets triggered, usually due to user input.
2. At the start of execution, the behavior requests new Hyperview content (XML), either from a remote location (via HTTP request) or locally (from a document fragment)
3. The request completes with Hyperview content (XML).
4. The new Hyperview content (XML) gets shown on the device, either by loading it in a new screen, or by injecting it into the current screen.

The set of behavior attributes described in this document give control over the steps outlined above. At a high level, the attributes define:

• trigger: What interaction causes the behavior to execute?
• href: What content should get requested?
• verb: How should the content get requested?
• action: What should the client do with the content?
• target: Where in the app should the client perform the action?

Note: When an href attribute is found on an element, Hyperview wraps the element with a "tappable" view. It is possible to customize the styles applied to that wrapping view by specifying the href-style property. See Styles.

The rest of the document describes in-depth how these attributes work together.

trigger

Type	Required
press (default), longPress, pressIn, pressOut, visible, refresh, load, select, deselect, focus, blur, submit, change, on-event	No

press

Triggers on a press-in/press-out combination on the element, uninterrupted by a gesture.

These elements support the press trigger:

• <view>
• <text>
• <image>

longPress

Triggers on a press and hold without a press-out, uninterraupted by a gesture.

These elements support the longPress trigger:

• <view>
• <text>
• <image>

pressIn

Triggers immediately when the element is touched.

These elements support the pressIn trigger:

• <view>
• <text>
• <image>

pressOut

Triggers immediately when a touch is released from an element.

These elements support the pressOut trigger:

• <view>
• <text>
• <image>

visible

Triggers when the element is visible on the device's display. If the element is visible when the screen loads, the behavior will execute immediately. Otherwise, the action will trigger when the element is scrolled into view.

These elements support the visible trigger:

• <view>
• <text>
• <image>

refresh

Triggers on a pull-to-refresh gesture.

These elements support the refresh trigger:

• <view>
• <text>
• <image>
• <list>
• <section-list>

load

Triggers when the element is first loaded in the screen or update fragment.

Elements with hide="true" are not loaded in the screen. This means any hidden element (or child element) with the load trigger will not be executed.

These elements support the load trigger:

• <view>
• <text>
• <image>

select

Triggers when the element is selected. Only works on selectable elements.

These elements support the select trigger:

• <option>

deselect

Triggers when the element is deselected. Only works on selectable elements.

These elements support the deselect trigger:

• <option>

focus

Triggers when the element is focused. Only works on focusable elements.

These elements support the focus trigger:

• <text-field>
• <date-field>
• <picker-field>

blur

Triggers when the element loses focus. Only works on focusable elements.

These elements support the blur trigger:

• <text-field>
• <date-field>
• <picker-field>

submit

Triggers when the element loses focus. Only works on submitable elements.

These elements support the submit trigger:

• <text-field>
• <date-field>
• <picker-field>

change

Triggers when the element value changes. Only works on editable elements.

NOTE: when using the change trigger on a <text-field> that include the mask attribute, the behavior will be triggered even if the mask prevents the pressed key from being set.

NOTE: on a <text-field>, the change trigger can be paired with the debounce attribute, which can be set with the number of milliseconds to debounce change events, i.e. debounce="200" will debounce the change event to 200ms after the last change on the text field occured.

These elements support the change trigger:

• <text-field>
• <date-field>
• <picker-field>
• <switch>

on-event

Triggers when the element captures an event with the specified event-name. This trigger requires an event-name attribute to be present and may be triggered from any hyperview screen.

These elements support the on-event trigger:

• <view>
• <text>

The on-event trigger may also be combined with once and delay.

Debugging tip

In __DEV__ mode, the console will log the element which captures an event

back

Triggers when the screen is being closed by behavior action (back or close), or by using a swipe gesture or physical back button (Android). As long as there are any visible behaviors with a back trigger, the screen can not be closed.

NOTE: Only works when using internal Navigators. See navigator.

These elements support the back trigger:

• <view>

Supported triggers

Not all elements support behavior attributes or <behavior> elements. Those that do may not support every trigger. This list below defines which elements can have behaviors, and which triggers they support.

<view>

<view> supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• press
• longPress
• pressIn
• pressOut
• visible
• refresh
• load
• on-event
• back

<text>

• <text> supports behavior attributes (or <behavior> elements as direct children) with the following triggers:
  • press
  • longPress
  • pressIn
  • pressOut
  • visible
  • refresh
  • load
  • on-event

<image>

<image>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• press
• longPress
• pressIn
• pressOut
• visible
• refresh
• load

<list>

<list>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• refresh

<section-list>

• <section-list>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:
  • refresh

<option>

<option>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• select
• deselect

<text-field>

<text-field>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• focus
• blur
• change
• submit

<date-field>

<date-field>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• focus
• blur
• change
• submit

<picker-field>

<picker-field>: supports behavior attributes (or <behavior> elements as direct children) with the following triggers:

• focus
• blur
• change
• submit

href

Type	Required
string	Yes

The href attribute is required for all built-in behaviors. However, custom behaviors may not require an href.

The only required attribute to create a behavior, href specifies how to retrieve new app content in response to a trigger. There are three accepted formats:

Relative URIs

In the "relative URI" format, href is a path starting with a /. This path is combined with the protocol and host of the request used to fetch the current document to create a URL. When the behavior triggers, new content will be fetched via HTTP from the full URL.

For example, assume the following doc is loaded from https://mysite.com:

<doc xmlns="https://hyperview.org/hyperview">
  <screen>
    <body>
      <text href="/hello/world?param=true">Hello</text>
    </body>
  </screen>
</doc>

When the user presses "Hello", content for the next screen will be requested from https://mysite.com/hello/world?param=true.

Absolute URLs

In the "absolute URL" format, href is a full URL, with protocol, host, path, query params, etc. New content will be fetched via HTTP from the URL as-is.

For example, assume the following doc is loaded from https://mysite.com/home:

<doc