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:

<AbsoluteLayout id="slideShow" loaded="load_slideShow">
  <GridLayout backgroundColor="#ffffff">
    <Label text="Slide 1" horizontalAlignment="center" />
  </GridLayout>
  <GridLayout backgroundColor="#f2f2f2">
    <Label text="Slide 2" horizontalAlignment="center" />
  </GridLayout>
  <GridLayout backgroundColor="#ffffff">
    <Label text="Slide 3" horizontalAlignment="center" />
  </GridLayout>
</AbsoluteLayout>

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:

<AbsoluteLayout id="slideShow" loaded="load_slideShow" />

… Or an itemTemplate can be initiated through a Repeater:

<AbsoluteLayout id="slideShow" loaded="load_slideShow">
  <Repeater items="{{ slides }}">
    <Repeater.itemTemplate>
      <GridLayout>
        <Label text="{{ text }}" />
      </GridLayout>
    </Repeater.itemTemplate>
  </Repeater>
</AbsoluteLayout>

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 = require("nativescript-na-slideshow");

exports.load_slideShow = function(args) {
  var view = args.object;
  var slideShow = new NASlideShow();
  
  slideShow.init(view);
};

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 = require("ui/frame");
var observableArray = require("data/observable-array").ObservableArray;
var container = frameModule.topmost().currentPage.getViewById("slideShow");
var slideShow = new NASlideShow();

slideShow.init(container, {
  items: new ObservableArray("Slide 1", "Slide 2", "Slide 3"),
  itemTemplate: '<GridLayout><Label text="{{ $value }}" horizontalAlignment="center" /></GridLayout>',
  indicators: {
    forceVisibility: true,
    verticalAlignment: "top",
    color: "#ffffff"
  }
});

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 = require("ui/layouts/grid-layout").GridLayout;
var Label = require("ui/label").Label;

var slideView = new GridLayout();
var textLabel = new Label();
textLabel.text = "Slide 4";
slideView.insertChild(textLabel, 0);

slideShow.insertSlide(slideView, {
  indicator: {
    icon: "+",
    float: true
  }
});

ObservableArray

slideShow.insertSlide("Slide 4", {
  indicator: {
    icon: "+",
    float: true
  }
});

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.removeSlide(0);

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.on("slideChange", function(eventData) {
  console.log("Slide index: " + eventData.index);
});

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.setSlide(0, { text: "Updated content", backgroundColor: "#ffffff" });

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.scrollToSlide(slideShow.getSlidesCount()-1, true);

Other methods

• getSlide(index) - Get slide at specified index.
  • Returns slide view/value
• getSlidesCount() - Get the total amount of slides.
  • Returns number
• getSlideIndex() - Get the current slide index.
  • Returns number
• 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 to disabled (see init() documentation).
• Added clipToBounds property to init() (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() and setSlide()
• 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 (see init() documentation).
• appendSlide() has been renamed to insertSlide().
• insertSlide() can now insert the slide at a specified index using the atIndex 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

• NordlingArt

License

MIT - for {N} version 2.0.0+