Skip to content

Latest commit

 

History

History
381 lines (330 loc) · 9.67 KB

amp-actions-and-events.md

File metadata and controls

381 lines (330 loc) · 9.67 KB
Raw

Actions and Events in AMP

The on attribute is used to install event handlers on elements. The events that are supported depend on the element.

The value for the syntax is a simple domain specific language of the form:

eventName:targetId[.methodName[(arg1=value, arg2=value)]]

Here's what each part of this means: eventName required This is the name of the event that an element exposes.

targetId required This is the DOM id for the element, or a predefined special target you'd like to execute an action on in response to the event. In the following example, the targetId is the DOM id of the amp-lightbox target, photo-slides.

<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Show Images</button>

methodName optional for elements with default actions This is the method that the target element (referenced by targetId) exposes and you'd like to execute when the event is triggered.

AMP has a concept of a default action that elements can implement. So when omitting the methodName AMP will execute that default method.

arg=value optional Some actions, if documented, may accept arguments. The arguments are defined between parentheses in key=value notation. The accepted values are:

  • simple unquoted strings: simple-value
  • quoted strings: "string value" or 'string value'
  • boolean values: true or false
  • numbers: 11 or 1.1
  • dot-syntax reference to event data: event.someDataVariableName

Handling Multiple Events

You can listen to multiple events on an element by separating the two events with a semicolon ;.

Example: on="submit-success:lightbox1;submit-error:lightbox2"

Multiple Actions For One Event

You can execute multiple actions in sequence for the same event by separating the two actions with a comma ','.

Example: on="tap:target1.actionA,target2.actionB"

Globally defined Events and Actions

Currently AMP defines tap event globally that you can listen to on any HTML element (including amp-elements).

AMP also defines hide, show and toggleVisibility actions globally that you can trigger on any HTML element.

{% call callout('Note', type='note') %}Note: {% endcall %} An element can only be shown if it was previously hidden by a hide or toggleVisibility action, or by using the hidden attribute. show does not support elements hidden by CSS display:none or AMP's layout=nodisplay

For example, the following is possible in AMP.

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

Element Specific Events

* - all elements

Event Description
tap Fired when the element is clicked/tapped.

Input Elements

Event Description Elements Data
change Fired when the value of the element is changed and committed. input[type="range"] event.min : The minimum value of the range
event.value : The current value of the range
event.max : The maximum value of the range
input[type="radio"], input[type="checkbox"] event.checked : If the element is checked
input[type="text"], select event.value : String of the text or selected option
input-debounced Fired when the value of the element is changed. This is similar to the standard input event, but it only fires when 300ms have passed after the value of the input has stopped changing. Elements that fire input event. Same as above.

amp-carousel[type="slides"]

Event Description Data
slideChange Fired when the user manually changes the carousel's current slide. Does not fire on autoplay or the goToSlide action. event.index : slide number

amp-selector

Event Description Data
select Fired when the user manually selects an option. event.targetOption : The option attribute value of the selected element

form

Event Description Data
submit Fired when the form is submitted.
submit-success Fired when the form submission response is success. event.response : JSON response
submit-error Fired when the form submission response is an error. event.response : JSON response

Element Specific Actions

* (all elements)

Action Description
hide Hides the target element.
show Shows the target element.
toggleVisibility Toggles the visibility of the target element.

amp-carousel[type="slides"]

Action Description
goToSlide(index=INTEGER) Advances the carousel to a specified slide index.

amp-image-lightbox

Action Description
open (default) Opens the image lightbox with the source image being the one that triggered the action.

amp-lightbox

Action Description
open (default) Opens the lightbox.
close Closes the lightbox.

amp-live-list

Action Description
update (default) Updates the DOM items to show updated content.

amp-sidebar

Action Description
open (default) Opens the sidebar.
close Closes the sidebar.
toggle Toggles the state of the sidebar.

amp-state

Action Description
(default) Updates the amp-state's data with the data contained in the event. Requires amp-bind.

amp-user-notification

Action Description
dismiss (default) Hides the referenced user notification element.

amp-video, amp-youtube

Action Description
play Plays the video.
pause Pauses the video.
mute Mutes the video.
unmute Unmutes the video.

form

Action Description
submit Submits the form.

Special targets

The following are targets provided by the AMP system that have special requirements:

AMP

The AMP target is provided by the AMP runtime and implements top-level actions that apply to the whole document.

Action Description
navigateTo(url=STRING) Navigates current window to given URL. Supports standard URL subsitutions. Can only be invoked via tap or change events.
goBack Navigates back in history.
setState Updates amp-bind's state. See details.

amp-access

The amp-access target is provided by the AMP Access extension.

It's special because

  1. You can't give an arbitrary ID to this target. The target is always amp-access.
  2. The actions for amp-access are dynamic depending on the structure of the AMP Access Configruation.

See details about using the amp-access target.