The Alexa motion scale responsive component AlexaMotionScale displays content in a series of pages with a widget-specific "zoom" animation for changing pages. You use Alexa Presentation Language (APL) components and responsive components or templates to define the pages to show.
Compatibility
AlexaMotionScale is designed to work with the following widget viewport profiles in the alexa-viewport-profiles package:
Widget Medium (@hubWidgetMedium)
If you use AlexaMotionScale on an unsupported viewport, you might have unexpected results. For details about viewport profiles, see Viewport Profiles.
The latest version of the alexa-layouts package is 1.7.0. AlexaMotionScale was introduced in version 1.5.0.
AlexaMotionScale parameters
The following table shows the AlexaMotionScale properties that work with the widget viewport profiles. Not all parameters apply to all viewport profiles. The "Widget support" column indicates the widget viewport profiles that support each parameter. For details about viewport profiles, see Viewport Profiles.
All parameters except type are optional.
Name
Type
Default
Description
Widget support
Version added
data
Array
—
Data to bind into the AlexaMotionScale. When provided, AlexaMotionScale uses the data array inflation method. This means that the components in items are inflated one time for each value in data.
Medium
1.5.0
initialPage
Integer
0
The zero-based index of the starting page to display.
Medium
1.5.0
items
Any
—
An array of components or a single component to display.
Medium
1.5.0
navigation
String
wrap
Specifies the allowed navigation direction. Possible values are normal, none, wrap, forward-only. These options work the same as a standard Pager component. For details about pager navigation options, see the navigation property for the Pager component.
Medium
1.5.0
onPageChanged
Array
—
Commands to run when the page changes. These commands run after the pager has fully switched to the new page.
Medium
1.5.0
pagerId
String
—
An identifier to use for the underlying Pager component within the AlexaMotionScale layout. Set this property to an ID if you want to target the AlexaMotionScale with commands, such as AutoPage and SetPage.
Medium
1.5.0
Define the pages to display
Provide the pages to display in AlexaMotionScale in the items property.
AlexaMotionScale is a multi-child component. Therefore, how the items array works to define pages depends on whether you also set the data property:
When data contains an array of values, AlexaMotionScale uses the data array inflation method. This means that the components in items are inflated one time for each value in data.
Note: The data property doesn't have a default. If you aren't using the data property in the MotionScale, assign data to an empty array ([])
The AlexaMotionScale component doesn't display any content on its own. You must provide the components or layouts to display in the items property.
Widget-specific animation when changing pages
AlexaMotionScale uses a custom "zoom" page-change animation. When the pager changes pages, the current page scales down and fades out as the new page scales up and fades in. The animation is the same regardless of the direction of the pager.
AlexaMotionScale
For a widget pager with an alternative "swipe away" page transition, see Motion Pager.
AlexaMotionScale example with AlexaTextList
The following example shows an AlexaMotionScale with two pages. Each page displays an AlexaTextList with several list items. The AlexaMotionScale uses a tick event handler to change pages every three seconds.
{"type":"APL","version":"2023.2","license":"Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License http://aws.amazon.com/asl/","theme":"dark","import":[{"name":"alexa-layouts","version":"1.7.0"}],"mainTemplate":{"parameters":["currentView"],"items":[{"type":"Container","height":"100%","width":"100%","direction":"column","items":[{"type":"AlexaBackground"},{"type":"AlexaMotionScale","pagerId":"WidgetPager","width":"100%","height":"100%","initialPage":0,"navigation":"wrap","data":"${currentView.lists}","handleTick":[{"minimumDelay":3000,"commands":[{"type":"SetPage","sequencer":"pagerSequencer","componentId":"WidgetPager","position":"relative","value":1}]}],"items":[{"type":"AlexaTextList","hideOrdinal":true,"headerTitle":" ","primaryAction":[{"type":"SendEvent","arguments":["ListItemSelected","${ordinal}","${data.itemId}"]}],"listItems":"${data.listItemsToShow}"}]},{"type":"AlexaHeader","id":"header","headerTitle":"Calendar","width":"100%","position":"absolute"}]}]}}
If you want to display content over a background image, consider whether the background should be part of the animation. For example, you could modify the previous example to set the backgroundImageSource property on the AlexaTextList template to add a background image behind the list items. However, this solution includes the background image in the zoom animation.
To keep the background image static and animate the list, place your background image outside of the AlexaMotionScale component. The following example shows a custom list with a static header and background. The example uses the same data source shown in AlexaMotionScale with AlexaTextList.
{"type":"APL","version":"2023.2","license":"Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License http://aws.amazon.com/asl/","theme":"dark","import":[{"name":"alexa-layouts","version":"1.7.0"}],"mainTemplate":{"parameters":["currentView"],"items":[{"type":"Container","height":"100%","width":"100%","direction":"column","paddingBottom":"@spacingLarge","items":[{"type":"AlexaBackground","backgroundImageSource":"https://d2o906d8ln7ui1.cloudfront.net/images/widget/widget-bg-1.jpeg","colorOverlay":true},{"type":"AlexaHeader","id":"header","headerTitle":"Calendar","width":"100%"},{"type":"AlexaMotionScale","pagerId":"WidgetPager","width":"100%","height":"100%","initialPage":0,"navigation":"wrap","data":"${currentView.lists}","handleTick":[{"minimumDelay":3000,"commands":[{"type":"SetPage","sequencer":"pagerSequencer","componentId":"WidgetPager","position":"relative","value":1}]}],"items":[{"type":"Sequence","width":"100%","height":"100%","data":"${data.listItemsToShow}","numbered":true,"item":[{"type":"AlexaTextListItem","primaryText":"${data.primaryText}","secondaryText":"${data.secondaryText}","primaryAction":{"type":"SendEvent","arguments":["ListItemSelected","${ordinal}","${data.itemId}"]}}]}]}]}]}}
AlexaMotionScale with a static background
AlexaMotionScale with simple array of child components inflation
The following example shows an AlexaMotionScale that uses the simple array of child components inflation method to display three pages. The pager displays each component in items as a separate page.
{"type":"APL","version":"2022.2","license":"Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License http://aws.amazon.com/asl/","theme":"dark","import":[{"name":"alexa-layouts","version":"1.6.0"}],"mainTemplate":{"parameters":["currentView"],"items":[{"type":"Container","height":"100%","width":"100%","items":[{"type":"AlexaBackground"},{"type":"AlexaHeader","headerTitle":"AlexaMotionScale that doesn't use data array inflation","headerTitleCanUseTwoLines":true},{"type":"AlexaMotionScale","pagerId":"WidgetPager","width":"100%","height":"100%","initialPage":0,"navigation":"wrap","data":[],"handleTick":[{"minimumDelay":3000,"commands":[{"type":"SetPage","sequencer":"pagerSequencer","componentId":"WidgetPager","position":"relative","value":1}]}],"items":[{"type":"Text","text":"This is the first page","textAlign":"center"},{"type":"Text","text":"This is the second page","textAlign":"center"},{"type":"Text","text":"This is the third page","textAlign":"center"}]}]}]}}
