CarouselView plugin for nativescript

Setup

tns plugin add nativescript-carousel-view

Platform Support

|Platform|Supported|Version|NativeView| | ------------------- | :-----------: | :-----------: | :------------------: | |iOS|Yes|iOS 8.1+|UIPageViewController| |Android|Yes|API 15+|ViewPager|

Usage

First add the xmlns namespace:

xmlns:controls="nativescript-carousel-view"

Then add the control:

<controls:CarouselView
    id="carouselView"
    position="0"
    orientation="horizontal"
    interPageSpacing="5"
    itemsSource="{{ itemsSource }}"
    templateSelector="{{ templateSelector }}"/>

Bindable Properties

orientation: horizontal, vertical (default horizontal).

itemsSource: collection of objects used as bindingContext for each page.

position: selected page when carousel starts (default 0).

interPageSpacing: margin/space between pages (default 0).

interPageSpacingColor: color for the margin/space between pages (default #FFFFFF).

showIndicators: show page indicators (default true).

IndicatorsShape: Circle or Square indicators shape (default Circle).

indicatorsTintColor: color for the unselected dots (default #c0c0c0).

indicatorsCurrentPageColor: color for the selected dot (default #808080).

templateSelector: a class implementing the provided ITemplateSelector interface.

animateTransition: enables transition animation when swiping programmatically (default true).

Template selector should return a valid {N} view. As advice, put each view in separate files and load them with builder. Also, notice that you have to assign the bindingContext of the returning view.

TYPESCRIPT

import { ITemplateSelector } from "nativescript-carousel-view";
import builder = require("ui/builder");
var frame = require('ui/frame');

export class MyTemplateSelector implements ITemplateSelector {
    
    OnSelectTemplate(position: number, bindingContext: any) {

        var page = frame.topmost().currentPage;

        var view = builder.load({
            path: "~/Views/Slides",
            name: "slider-view",
            page: page
        });

        // required
        view.bindingContext = bindingContext;

        return view;
    }
}

ViewModel

import observable = require("data/observable");
import observableArrayModule = require("data/observable-array");
import { MyTemplateSelector } from "../Views/Slides/template-selector";

export class MainViewModel extends observable.Observable {

    public templateSelector: MyTemplateSelector;
    public itemsSource: observableArrayModule.ObservableArray<Person>;

    constructor() {
        super();

        // Initialize default values.

        this.templateSelector = new MyTemplateSelector();

        var person = new Person();
        person.first = "Alexander";
        person.last = "Reyes";

        var items = [ person, person, person, person, person ];
        this.itemsSource = new observableArrayModule.ObservableArray<Person>(items);
    }
}

JAVASCRIPT

"use strict";
var builder = require("ui/builder");
var frame = require('ui/frame');

var MyTemplateSelector = (function () {
    function MyTemplateSelector() {
    }
    MyTemplateSelector.prototype.OnSelectTemplate = function (position, bindingContext) {

        var page = frame.topmost().currentPage;

        var view = builder.load({
            path: "~/Views/Slides",
            name: "slider-view",
            page: page
        });

        view.bindingContext = bindingContext;

        return view;
    };
    return MyTemplateSelector;
}());

exports.MyTemplateSelector = MyTemplateSelector;

ViewModel

"use strict";
var observable = require("data/observable");
var observableArrayModule = require("data/observable-array");
var template_selector = require("../Views/Slides/template-selector");

var MainViewModel = (function (_super) {
    __extends(MainViewModel, _super);
    function MainViewModel() {
        var _this = _super.call(this) || this;
        _this.templateSelector = new template_selector.MyTemplateSelector();
        _this.itemsSource = new observableArrayModule.ObservableArray(items);
        return _this;
    }
    return MainViewModel;
}(observable.Observable));

exports.MainViewModel = MainViewModel;

Event Handlers

positionSelected: triggers when the selected page changes.

var carouselView = <CarouselView>page.getViewById("carouselView");

carouselView.on("positionSelected", function(eventData){
    console.log(eventData.eventName + " has been raised! by: " + eventData.object);
});

Methods

insertPage (position, bindingContext): insert a page at a given position.

await carouselView.insertPage(5, person);
carouselView.setCurrentPage(5);

removePage (position): remove a page at given position (this will also remove the corresponding item from itemsSource).

await carouselView.removePage(5);

setCurrentPage (position): slide programmatically to a given position.

Requirements for TypeScript developers

• TypeScript >= 2.1.1 (npm install -g [email protected])

Please follow this tutorial to add TypeScript >= 2.1.1 and async/await support to your project:

https://www.nativescript.org/blog/use-async-await-with-typescript-in-nativescript-today

Roadmap

• Remove setCurrentPage, implement as position propertyChangedEvent (requires lot of refactoring)
• Indicators tap event
• PullToLoadMore event

Collaborators

• alexrainman

Release Notes

2.9.0

[New feature] animateTransition, enables transition animation when swiping programmatically (default true).

2.8.0

[Update] itemsSource now supports empty observable array.

2.7.1

[New feature] Circle or Square indicatorsShape property (default Circle).

2.6.1

[Update] orientation property is now expressed as string (horizontal, vertical), Orientation enum from "ui/enums" is supported.

[New feature] interPageSpacingColor property to change the color of the margin/space between pages (default #FFFFFF).

[New feature] indicatorsTintColor property to change the color of unselected dots (default #c0c0c0).

[New feature] indicatorsCurrentPageColor property to change the color of selected dot (default #808080).

2.6.0

[Udpate] Matching version number with Xamarin.Forms CarouselView

2.2.0

[iOS] Small fix to avoid UIPageViewController.View go outside its container bounds

[Update] showIndicators property now does what it supposed to do, hide/show indicators :)

[Update] itemsSourceChanged method removed, implemented as a propertyChangedEvent

2.1.0

[Enhancement] Adding page indicators

2.0.6

[Bug] CSS not applying to slides #6 (fixed)

[Enhancement] Removing left and right overscroll in Android vertical carousel

2.0.5

[Bug] Adding another touch gesture to slider-view does not work (fixed)

2.0.4

Updated README.

2.0.3

[Bug] fixing interPageSpacing in Android.

2.0.2

[Bug] onLoaded() not being called on carousel pages (Fixed).

License

MIT.

Ported from CarouselView for Xamarin.Forms: https://github.com/alexrainman/CarouselView