NativeScript NA Slideshow plugin
NOTE! Android is currently not supported.
Installation
$ tns plugin add nativescript-na-slideshow
Usage
XML
Slides can be added manually inside the XML as below:
It is important that the slide container is an AbsoluteLayout
or else problems will occur. Slides can also, instead of being static like above, be created using an ObservableArray
. To do this, the container has to either stay empty - as such:
… Or an itemTemplate can be initiated through a Repeater:
Note that when doing it this way, the Repeater.itemsLayout
tag will be ignored if ever set. So no need to use that.
Before heading to the JavaScript part, make sure the loaded
attribute is set as in the example: loaded="load_slideShow"
. This is needed for the JavaScript code to turn the container into a slideshow.
JS
Once the XML has been set up, the plugin will now be able to transform the container into a slideshow. To do this, see below:
var NASlideShow = ; exports { var view = argsobject; var slideShow = ; slideShow;};
Once this has been done, the slideshow is now up and running!
Instance properties
In the JS example above, the init()
function used the default properties. Here is a list of all properties that exist (showing default values):
items: false // An ObservableArray instance. itemTemplate: "<GridLayout />" // The view template for each slide (has to be written as an XML string). See the Repeater documentation for further information. enableBounce: false // Scroll bouncing disabled by default. fallbackWidth: screen width // In case the inherited width doesn't load in time. fallbackHeight: screen height // In case the inherited height doesn't load in time. clipToBounds: true // Similar to "overflow" in CSS indicators: size: 10 // The indicators' size. color: "#808080" // The indicators' color. activeColor: false // The active indicator's color. borderWidth: 0 // The indicators' border width. borderColor: "#404040" // The indicators' border color. horizontalAlignment: "center" // The horizontal alignment of the indicators. verticalAlignment: "bottom" // The vertical alignment of the indicators. iconShadow: false // Icon shadow. Can be a boolean or an object forceVisibility: false // By default, indicators will only show up if there are 2 slides or more. disabled: false // Disable the indicators.
The itemTemplate property is special because, according to the Repeater documentation, it has to be a string in XML format.
The fallbackWidth and fallbackHeight properties are sometimes needed when the inherited width and height haven't yet been set during view loaded state.
indicators.iconShadow can be customized by making it an object instead. These are the default properties:
color: "#000000" // HEX color alpha: 1 // Opacity (1 to 0) x: 0 // Horizontal offset y: 0 // Vertical offset radius: 2 // Radius amount
Methods
init()
This must be called to initiate the slideshow view.
init(template, props)
- template - The view container (template) that is going to become the slideshow.
- props - Set any instance properties (optional).
var frameModule = ;var observableArray = ObservableArray;var container = frameModulecurrentPage;var slideShow = ; slideShow;
insertSlide()
Call this to insert new slides. Depending on whether the slideshow was initiated using XML only or an ObservableArray
instance, the view parameter works a little differently.
insertSlide(slideView, props)
- slideView - The view container/string/object that is going to become the slideshow.
- props - Set any instance properties (optional).
XML
var GridLayout = GridLayout;var Label = Label; var slideView = ;var textLabel = ;textLabeltext = "Slide 4";slideView; slideShow;
ObservableArray
slideShow;
The props parameter's defaults are:
atIndex: last // Inserts the slide at specified index number. indicator: icon: false // Custom icon (or character) instead of a dot. fontFamily: false // The icon font family. float: false // Set to true to make the icon float to the right, as in not adjusting the indicators horizontal alignment.
The float property is ignored if atIndex is set to anything but the last, or if the slideshow instance has horizontalAlignment set to "right". This is to prevent visual bugs.
removeSlide()
Remove a slide at specified index.
removeSlide(index)
- index - The slide to remove at specified index.
To remove the first slide:
slideShow;
on()
Event listener for each slide scroll. When a slide has finished scrolling, the event will be called.
on("slideChange", callback)
- "slideChange" - The only available eventName.
- callback - The callback on each notification.
slideShow;
The eventData parameter inside the callback function contains the following properties:
- eventName - The event's name.
- object - The slideshow view.
- index - The current slide index.
- length - The total amount of slides.
setSlide()
Sets a new view/value to existing slide.
setSlide(index, value)
- index - The slide view/value at specified index.
- value - The slide view/value (depends if slideShow uses ObservableArray or not).
To set the first slide:
slideShow;
scrollToSlide()
Sets a new view/value to existing slide.
scrollToSlide(index, animated)
- index - The slide to scroll to at specified index.
- animated - Boolean parameter. Whether the scrolling should animate or not (defaults to false).
To scroll to the last slide (animated):
slideShow;
Other methods
getSlide(index)
- Get slide at specified index.- Returns slide view/value
getSlidesCount()
- Get the total amount of slides.- Returns
number
- Returns
getSlideIndex()
- Get the current slide index.- Returns
number
- Returns
clearSlides()
- Clears the whole slideshow.
Other properties
view
- Returns the slideshow view object (the view container/template that was used to initiate the slideshow).viewsList
- List of all children views:scrollView
- The ScrollView.container
- The internal container for the slideshow.indicators
- The indicators view.repeater
- The Repeater view (only available when using ObservableArray).
items
- Returns the ObservableArray (only available when using ObservableArray).
Known issues
- No Android compatibility, yet.
History
Version 1.5.0 (3 December 2016)
- Better code structure.
- Bug fix:
forceVisibility
when set to false, was ignored when removing second last slide.
Version 1.4.3 (17 October 2016)
- Bug fix:
clipToBounds
property not working correctly.
Version 1.4.2 (16 October 2016)
- Changed indicators property from
disable
todisabled
(seeinit()
documentation). - Added
clipToBounds
property toinit()
(see documentation).
Version 1.4.1 (13 October 2016)
- Bug fixes:
- Unable to insert new slide when one slide has already been removed (using ObservableArray/Repeater).
- Active slide indicator not retaining its color when a slide has been removed.
Version 1.4.0 (12 October 2016)
- New method:
clearSlides()
- Ability to also create Repeater from XML (see Usage).
Version 1.3.2 (16 September 2016)
- New method:
scrollToSlide()
Version 1.3.1 (15 September 2016)
- Hotfix:
forceVisibility
was ignored completely.
Version 1.3.0 (15 September 2016)
- New methods:
getSlide()
andsetSlide()
- You can now set a custom color on the active slide indicator.
- Fixed a bug with
forceVisibility
. - Fixed a bug where
removeSlide()
on last index would crash the app.
Version 1.2.0 (12 September 2016)
Apologize for the fast updates (same day, wow). This one has lots of additions:
- New method:
removeSlide()
- Added horizontal and vertical alignments to the indicators (see
init()
documentation). - Added
iconShadow
property to the indicators (seeinit()
documentation). appendSlide()
has been renamed toinsertSlide()
.insertSlide()
can now insert the slide at a specified index using theatIndex
property.- Fixed a bug where if the ObservableArray was empty during
init()
, an indicator dot would appear anyway.
Version 1.1.0 (12 September 2016)
- New method:
getSlidesCount()
- Updated README.md
- Bug fixes. There were problems with the
appendSlide()
function.
Version 1.0.0 (9 September 2016)
init()
appendSlide()
on()
getSlideIndex()
Credits
License
MIT - for {N} version 2.0.0+