Class: Button

PR. Button

This component is associated with the buttons that perfom specific actions such as navigating to a page/article/weblink etc.

A 'data-action' attribute specifies the action that this button has to perform. When the button is tapped, the action and relevant data from other attributes are delegated to the app.

HTML Parameters

The following parameters are required

data-widget="BUTTON" Required
The identifier for the widget type.
data-action="{{string}}" Required
The action associated with the button. Buttons can have multiple actions, often associated with multiple targets.

The following parameters are sometimes required depending on the action of the button.

data-target="{{string}}" Additionally Required
Many button actions require a target to operate on.
data-link-index="{{number}} Additionally Required
The page number to link to. Index begins at 1.
data-link-article="{{string}} Additionally Required
The article to link to.
data-src="{{string}}" Additionally Required
A source file the button needs to operate (e.g. zoomable image button).
data-target-slide="{{string}}" Additionally Required
The specific slide to move a specified slideshow to.

The following parameters are optional but are recommended.

id="{{id}} Optional
It is usually preferable to include this but it is not strictly necessary unless you want to reference the button from another source (i.e. fired by dropping a transformable or completing an animation).

Button Actions

The following is the complete list of actions that a button can trigger, these should be added as parameter to the data-action field. They should have a corresponding target to perform the action on.

Note that using multiple actions is perfectly valid but will require multiple targets, the number of actions and targets must match even if they are repeated. See the multiple actions example.

Navigation Actions

These actions handle navigating the app.

NAVIGATE_NEXT_PAGE
Navigates to the next page of the current issue
NAVIGATE_PREVIOUS_PAGE
Navigates to the previous page of the current issue
NAVIGATE_TO_PAGE
Navigates to a specific page in the current issue. Additionally requires a data-link-index parameter to specify the required page. See specific page navigation example.
NAVIGATE_TO_ARTICLE
Navigates to a specific article within the current issue. Requires data-link-article to specify the article. Defaults to page 1 of the specified article but the page can also be specified by including data-link-index. See specific page/article navigation example.
NAVIGATE_TO_URL
Navigates to a specific URL using data-target
ISSUE_SCREEN
Navigates back to the issue screen.

Media Actions

Media sources are video/audio. Video or Audio widgets should be specified using data-target.

TOGGLE_MEDIA
Toggles the play/pause status of a media source.
PLAY_MEDIA
Plays the media source.
PAUSE_MEDIA
Pauses the media source.

Popup Actions

Popup widget should be specified using data-target.

TOGGLE_POPUP
Toggles the show/hide status of a popup.
SHOW_POPUP
Shows the popup.
HIDE_POPUP
Hides the popup.

Slideshow Actions

Slideshow widget should be specified using data-target. Moving to a specific slide also requires data-target-slide to be specified.

NEXT_SLIDE
Progresses the slideshow to the next slide.
PREVIOUS_SLIDE
Regresses the slideshow to the previous slide.
GO_TO_SLIDE
Moves the slideshow to a specific slide. Requires data-target-slide to be specified.

Additional Actions

These are additional actions that a button can perform.

TAKE_SCREENSHOT
Takes a screenshot of the current display and saves it to the operating system.
RESET_PAGE
Resets the page to it’s initial state.
ZOOMABLE_IMAGE
Opens a specified zoomable image in a separate tab/popup. Requires data-src to specify the image to open.
PLAY_ANIMATION
Starts the animation specified by data-target.

Examples

Standard Button Parameters
The following example shows the HTML for a button that is actioned by user interaction and triggers navigation to the next page. A unique ID is not strictly required but is strongly recommended.

id Optional
A unique id for the HTML element.
data-widget="BUTTON" Required
Button identifier.
data-action="{{button-action}}" Required
The action for the button.
<!-- Navigate to next page button -->
<div id="example_id" data-widget="BUTTON" data-action="NAVIGATE_NEXT_PAGE">
<img class="example_class" src="example_img.png" />
</div>

Button for navigating to a specific page
Buttons can be used for navigating an issue but will require an addition parameter to work. The parameter below is in addition to the standard button parameters.

data-action="{{NAVIGATE_TO_PAGE}}" Required
The action for the button.
data-link-index="{{number}}" Required
The page number to navigate to. First page in the issue is page 1.
<!-- Navigate to specified page button -->
<div id="example_id" data-widget="BUTTON" data-action="NAVIGATE_TO_PAGE" data-link-index="1" >
<img class="example_class" src="example_img.png" />
</div>
Button for navigating to a specific article

In addition to specifying a specific page, buttons can also be used to navigate straight to the opening page of an article. The parameter below is in addition to the standard button parameters.

data-action="{{NAVIGATE_TO_ARTICLE}}" Required
The action for the button.
data-link-article="{{string}}" Required
The article id obtained from the AppStudio portal.
<!-- Navigate to specified article button -->
<div id="example_id" data-widget="BUTTON" data-action="NAVIGATE_TO_ARTICLE" data-link-article="news" >
<img class="example_class" src="example_img.png" />
</div>

Button for navigating to a specific page within an article
Linking to a specific page within an article is also possible, just combine the link-index and link-article data parameters. The parameters below are in addition to the standard button parameters.

data-action="{{NAVIGATE_TO_ARTICLE}}" Required
The action for the button.
data-link-index="{{number}}" Required
The page number to navigate to. First page in the issue is page 1.
data-link-article="{{string}}" Required
The article id obtained from the AppStudio portal.
<!-- Navigate to a specified page within an article -->
<div id="example_id" data-widget="BUTTON" data-action="NAVIGATE_TO_ARTICLE" data-link-article="news" data-link-index="1" >
<img class="example_class" src="example_img.png" />
</div>

Different Base Element
Whilst a button would normally be attached to a div element there is no requirement to do so, the following example where the div element has been removed and the widget is attached straight to an image defining it’s appearance is perfectly valid.

<!-- Play Media Button -->
<img id="uniqueid2"
class="videoPlayButton button"
data-widget="BUTTON"
data-action="PLAY_MEDIA"
data-target="uniqueid1"
src="../assets/videoplay.png" />

A common use-case is to navigate to a URL using a button. The protocol (http, https or mailto) should be included. The navigate to url action can also be used to set up a mail link. Query parameters can also be used.

Common social media sites such as Facebook often include complex URL’s as part of their linking structure and these can be used to build links via the button widget too (an example is not included as Facebook comment threads are often pruned so may not still be active but it is only a matter of substituting the content of the data-target parameter with the URL that Facebook provides for links).

data-action="NAVIGATE_TO_URL" Required
The list of actions to perform.
data-target="{{target}}" Required
The article id obtained from the AppStudio portal.
<!-- Navigate to an external URL -->
<div data-widget="BUTTON" data-action="NAVIGATE_TO_URL" data-target="http://www.appstudio.net">
<img class="example_class" src="example_img.png" />
</div>

<!-- Setting up a mail button -->
<div data-widget="BUTTON" data-action="NAVIGATE_TO_URL" data-target="mailto:everybody@appstudio.net?subject=my app is awesome">
<img class="example_class" src="example_img.png" />
</div>

Multiple Action Button
A button can fire more than one action, but special syntax is required to make sure it operates correctly. The number of actions on the button must match the number of targets and the order is important i.e. action 1 will refer to target 1. The list of actions and targets should be comma separated and closed up (i.e. not contain any whitespace).

If you want to specify more targets for an action then you need to repeat the action e.g. if you want to toggle 3 different popups then your action parameter would be data-action="TOGGLE_POPUP,TOGGLE_POPUP,TOGGLE_POPUP" while your target array would contain the id's of the popups to toggle data-target="UNIQUE_ID1,UNIQUE_ID2,UNIQUE_ID3". So long as you remember that the number of actions must match the number of targets then all will be good.

<div data-widget="BUTTON" data-action="TOGGLE_POPUP,TOGGLE_MEDIA" data-target="popup_id,video_id">
<img class="example_class" src="example_img.png" />
</div>
Complex Button Example

As long as a button has a unique ID this ID can be used to reference and fire the button (and it’s corresponding actions) from other widgets.

The following example shows a complex use-case for a hidden off-screen button that fires an off-screen audio widget and opens a popup when dropping a transformable widget into it’s dropzone (some parameters for the transformable, popup and audio widgets are omitted for brevity, they also use inline styles for brevity—a stylesheet is usually recommended).

<!-- UniqueID1 - Audio widget -->
<div id="uniqueid1"
data-widget="AUDIO"
data-audio-type="inline"
data-src="../assets/some-audio.mp3"
style="position:absolute;left:-9999px;" >
</div>

<!-- UniqueID2 - Popup widget-->
<div id="uniqueid2"
class="hiddenPopup"
data-layer="popupLayer"
data-widget="POPUP">
<p>Some content inside the popup</p>
<img src="../assets/popup-content-image.png />
</div>

<!-- UniqueID3 - Button to fire audio widget -->
<div id="uniqueid3"
data-widget="BUTTON"
data-action="PLAY_MEDIA,TOGGLE_POPUP"
data-target="uniqueid1,uniqueID2"
style="position:absolute;left:-9999px;">
</div>

<!-- UniqueID4 - Transformable - Triggers button on drop -->
<div id="uniqueid4"
data-widget="TRANSFORMABLE"
data-moveable="true"
data-dropzone-target="dropzone-id"
data-dropzone-action-target="uniqueid3">
<img src="../assets/some-image.png" />
</div>
Author:
  • AppStudio Widgets
Source:
  • widgets/Button.js, line 2

Extends

  • PR.BaseWidget

Members

action_String

The action associated with the button. The value of the 'data-action' attribute is stored in this variable.

Source:
  • widgets/Button.js, line 303

elHTMLDivElement

The HTML element for the button

Source:
  • widgets/Button.js, line 329

idstring

The id of the HTML element

Source:
  • widgets/Button.js, line 335

outsideProximityboolean

Has the interaction event moved outside of the proximity

Source:
  • widgets/Button.js, line 315

proximitynumber

click/tap proximity

Source:
  • widgets/Button.js, line 353

startXnumber

x coord of click/tap

Source:
  • widgets/Button.js, line 341

startYnumber

y coord of click/tap

Source:
  • widgets/Button.js, line 347

userInteractionboolean

Does the button respond to user interaction?

Source:
  • widgets/Button.js, line 309

Methods

checkProximity( start, end ) → {boolean}

Checks to see whether two numbers are within the proximity setting (note: this is one-dimensional, params are numbers, not coords or points).
Proximity is set as a constant for this widget, referenced by this.proximity.

Parameters:
Name Type Description
start number

the first number (usually referencing start location)

end number

the last number (usually referencing end location)

Returns:
boolean

true if both params are within the proximity, false otherwise

Example:
undefined
Source:
  • widgets/Button.js, line 722
To Do:
  • this should probably be moved to core/utils

getDataAction( ) → {*}

Getter for the action_ variable.

Returns:
*
Source:
  • widgets/Button.js, line 693

handleEvent( event )

Default handler that's triggered automatically, if interaction events are added with 'this' as a handler.
This way scope is automatically resolved without using bind(this).

Parameters:
Name Type Description
event
Source:
  • widgets/Button.js, line 561

initialize( element )

Acts like a constructor, this function triggered by default when you create an object.

Parameters:
Name Type Description
element

The HTML DOM element which acts like a slideshow.

Throws:
Error HTML element not attached.
Source:
  • widgets/Button.js, line 364

onTap_( event )

Event handler when a button is pressed

Parameters:
Name Type Description
event event
Source:
  • widgets/Button.js, line 397

setDataAction( action )

Setter for the action_ variable.

Parameters:
Name Type Description
action
Source:
  • widgets/Button.js, line 701
Top