Skip to content

Latest commit

 

History

History
317 lines (271 loc) · 7.19 KB

amp-actions-and-events.md

File metadata and controls

317 lines (271 loc) · 7.19 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 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 a hide action globally that you can trigger on any HTML element.

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 (any that fires change event)

Including: input[type=radio], input[type=checkbox] and select.

Event Description
change Fired when the value of the element is changed.

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.

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-carousel[type="slides"]

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

amp-video, amp-youtube

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

AMP target

AMP target is a special target. It's provided by the AMP runtime and implements top-level actions that apply to the whole document.

Action Description
goBack Navigates back in history.
setState Updates local bindable state. Requires amp-bind.