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 includingdata-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 adiv
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" />
Navigate to URL
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>
- 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:
booleantrue 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