refactor(slides): update slide methods and API docs

add to docs including how to use the slides and rename methods.

BREAKING CHANGE:

The Slides component has been refactored. Many methods and events were
renamed.

The following events have been renamed:

- `slideChangeStart` has been renamed `willChange`
- `change` has been renamed `didChange`

The following methods have been renamed:

`next()` has been renamed to `slideNext()`
`prev()` has been renamed to `slidePrev()`
`getIndex()` has been renamed to `getActiveIndex()`
`getNumSlides()` has been renamed to `length()`
`isAtEnd()` has been renamed to `isEnd()`
`isAtBeginning()` has been renamed to `isBeginning()`
`getSliderWidget()` has been renamed to `getSlider()`

The following method was added: `slideTo()`

All methods have been documented in the API docs:
http://ionicframework.com/docs/v2/api/components/slides/Slides/

references #5508, references driftyco/ionic-site#458

ionic/components/slides/slides.scss

@@ -1,10 +1,5 @@
 @import "../../globals.core";
 
-ion-swipe-slides {
-  display: block;
-  width: 100%;
-  height: 100%;
-}
 
 /**
  * Swiper 3.1.2

ionic/components/slides/slides.ts

@@ -7,7 +7,7 @@ import {Gesture} from '../../gestures/gesture';
 import {DragGesture} from '../../gestures/drag-gesture';
 import {dom} from '../../util';
 import {CSS} from '../../util/dom';
-import {debounce, isTrueProperty, defaults} from '../../util/util';
+import {debounce, isTrueProperty, isPresent, defaults} from '../../util/util';
 
 import {Swiper} from './swiper-widget';
 import {Scroll} from '../scroll/scroll';
@@ -16,38 +16,88 @@ import {Scroll} from '../scroll/scroll';
 /**
  * @name Slides
  * @description
- * Slides is a slide box implementation based on Swiper.js
+ * The Slides component is a multi-section container. Each section can be swiped
+ * or dragged between. It contains any number of [Slide](../Slide) components.
+ *
+ *
+ * ### Creating
+ * You should use a template to create slides and listen to slide events. The template
+ * should contain the slide container, an `<ion-slides>` element, and any number of
+ * [Slide](../Slide) components, written as `<ion-slide>`. Any configuration of the
+ * slides should be passed in the `options` property of the `<ion-slides>` element.
+ * You can listen to events such as the slide changing by placing the event on the
+ * `<ion-slides>` element. See [Usage](#usage) below for more information on
+ * creating slides.
+ *
+ *
+ * ### Configuring
+ * There are several configuration options that can be passed to Slides. These should
+ * be passed in the `options` property of the `<ion-slides>` element upon creation.
+ * You can allow the slides to loop around from the last to the first, set autoplay
+ * on the slides so it will automatically switch between them, and more.
+ *
+ * Properties to pass in options:
+ *
+ * | Property              | Type      | Default        | Description                                                                                |
+ * |-----------------------|-----------|----------------|--------------------------------------------------------------------------------------------|
+ * | autoplay              | `number`  | -              | Delay between transitions (in ms). If this parameter is not passed, autoplay is disabled.  |
+ * | direction             | `string`  | 'horizontal'   | Swipe direction: 'horizontal' or 'vertical'.                                               |
+ * | initialSlide          | `number`  | 0              | Index number of initial slide                                                              |
+ * | loop                  | `boolean` | false          | Whether to continuously loop from the last slide to the first slide.                       |
+ * | speed                 | `number`  | 300            | Duration of transition between slides (in ms).                                             |
+ *
+ * See [Usage](#usage) below for more information on configuring slides.
+ *
+ *
+ * ### Navigating
+ * After creating and configuring the slides, you can navigate between them
+ * by swiping or calling methods on the `Slides` instance. You can call `slideTo()` to
+ * navigate to a specific slide, or `slideNext()` to change to the slide that follows
+ * the active slide. All of the [methods](#instance-methods) provided by the `Slides`
+ * instance are listed below. See [Usage](#usage) below for more information on
+ * navigating between slides.
+ *
+ *
+ * ### Limitations
+ * The Slides component wraps the [Swiper](http://www.idangero.us/swiper/) component
+ * built by iDangero.us. This means that all of the Swiper API isn't exposed on the
+ * Slides component. See the [`getSlider()`](#getSlider) method for information on
+ * getting the `Swiper` instance and using its methods directly.
+ *
  *
  * @usage
- * ```ts
+ * ```html
- * @Page({
+ * <ion-slides>
- *  template: `
- *     <ion-slides pager (change)="onSlideChanged($event)" (move)="onSlideMove($event)">
  *   <ion-slide>
- *        <h3>Thank you for choosing the Awesome App!</h3>
+ *     <p>Slide 1</p>
- *        <p>
+ *     <button (click)="goToSlide(3)">Navigate</button>
- *          The number one app for everything awesome.
- *        </p>
  *   </ion-slide>
  *   <ion-slide>
- *        <h3>Using Awesome</h3>
+ *     <p>Slide 2</p>
- *         <div id="list">
- *           <h5>Just three steps:</h5>
- *           <ol>
- *             <li>Be awesome</li>
- *             <li>Stay awesome</li>
- *             <li>There is no step 3</li>
- *           </ol>
- *         </div>
  *   </ion-slide>
  *   <ion-slide>
- *        <h3>Any questions?</h3>
+ *     <p>Slide 3</p>
  *   </ion-slide>
  * </ion-slides>
- *    `
- *})
- *
  * ```
+ *
+ * ```ts
+ * import {ViewChild} from 'angular2/core';
+ * import {App, Slides} from 'ionic-angular';
+ *
+ *
+ * @App({
+ *   templateUrl: 'main.html'
+ * })
+ * class MyApp {
+ *   @ViewChild(Slides) slider: Slides;
+ *
+ *   goToSlide(index) {
+ *     this.slider.slideTo(index, 500);
+ *   }
+ * }
+ * ```
+ *
  * @demo /docs/v2/demos/slides/
  * @see {@link /docs/v2/components#slides Slides Component Docs}
  *
@@ -73,7 +123,7 @@ import {Scroll} from '../scroll/scroll';
     '</div>',
   directives: [NgClass],
   host: {
-    '[id]': 'slideId'
+    '[class]': 'slideId'
   },
   changeDetection: ChangeDetectionStrategy.OnPush,
   encapsulation: ViewEncapsulation.None,
@@ -169,49 +219,56 @@ export class Slides extends Ion {
   };
 
   /**
-   * @input {boolean} Whether the slide should show the pager or not
+   * @input {Object} Any configuration for the slides
-   */
-  @Input() pager: any;
-
-  /**
-   * @input {any} Any slider options you want to configure, see swiper parameters: http://www.idangero.us/swiper/api/
    */
   @Input() options: any;
 
   /**
-   * @input {number} Whether or not the slider can zoom in or out
+   * @private Deprecated
+   */
+  @Input() pager: any;
+
+  /**
+   * @private Deprecated
    */
   @Input() zoom: any;
 
   /**
-   * @input {number} how long it should take to zoom a slide
+   * @private Deprecated
    */
   @Input() zoomDuration: any;
 
   /**
-   * @input {number} the max scale an slide can be zoomed
+   * @private Deprecated
    */
   @Input() zoomMax: any;
 
   /**
-   * @output {any} expression to evaluate when a slide has been changed
+   * @private Deprecated
-   */
-  @Output() change: EventEmitter<any> = new EventEmitter();
-
-  /**
-   * @output {any} expression to evaluate when a slide change starts
    */
   @Output() slideChangeStart: EventEmitter<any> = new EventEmitter();
 
   /**
-   * @output {any} expression to evaluate when a slide moves
+   * @private Deprecated
+   */
+  @Output() change: EventEmitter<any> = new EventEmitter();
+
+  /**
+   * @output {any} Expression to evaluate when a slide change starts.
+   */
+  @Output() willChange: EventEmitter<any> = new EventEmitter();
+
+  /**
+   * @output {any} Expression to evaluate when a slide change ends.
+   */
+  @Output() didChange: EventEmitter<any> = new EventEmitter();
+
+  /**
+   * @output {any} Expression to evaluate when a slide moves.
    */
   @Output() move: EventEmitter<any> = new EventEmitter();
 
-  /**
+
-   * @private
-   * @param {ElementRef} elementRef  TODO
-   */
   constructor(elementRef: ElementRef) {
     super(elementRef);
     this.rapidUpdate = debounce(() => {
@@ -230,12 +287,40 @@ export class Slides extends Ion {
       this.options = {};
     }
 
+    if (isPresent(this.pager)) {
+      // beta.5 2016-04-18 deprecated warning
+      // Pager should be passed as an option
+      console.warn('The "pager" attribute has been deprecated. Please pass it in options.');
+      // Remove this with the deprecation warning
       this.showPager = isTrueProperty(this.pager);
+    }
 
-    let paginationId = '#' + this.slideId + ' .swiper-pagination';
+    if (isPresent(this.zoom)) {
+      // beta.5 2016-04-18 deprecated warning
+      // Zoom should be passed as an option
+      console.warn('The "zoom" attribute has been deprecated. Please pass it in options.');
+    }
+
+    if (isPresent(this.change)) {
+      // beta.5 2016-04-18 deprecated warning
+      // change has been renamed to didChange
+      console.warn('The "change" event has been deprecated. Please use "didChange" instead.');
+    }
+
+    if (isPresent(this.slideChangeStart)) {
+      // beta.5 2016-04-18 deprecated warning
+      // slideChangeStart has been renamed to willChange
+      console.warn('The "slideChangeStart" event has been deprecated. Please use "willChange" instead.');
+    }
+
+    if (isPresent(this.options.pager)) {
+      this.showPager = isTrueProperty(this.options.pager);
+    }
+
+    let paginationId = '.' + this.slideId + ' .swiper-pagination';
 
     var options = defaults({
-      pagination: paginationId,
+      pagination: paginationId
     }, this.options);
 
     options.onTap = (swiper, e) => {
@@ -259,11 +344,17 @@ export class Slides extends Ion {
       return this.options.onTransitionEnd && this.options.onTransitionEnd(swiper, e);
     };
     options.onSlideChangeStart = (swiper) => {
+      // TODO deprecated 2016-04-18
       this.slideChangeStart.emit(swiper);
+
+      this.willChange.emit(swiper);
       return this.options.onSlideChangeStart && this.options.onSlideChangeStart(swiper);
     };
     options.onSlideChangeEnd = (swiper) => {
+      // TODO deprecated 2016-04-18
       this.change.emit(swiper);
+
+      this.didChange.emit(swiper);
       return this.options.onSlideChangeEnd && this.options.onSlideChangeEnd(swiper);
     };
     options.onLazyImageLoad = (swiper, slide, img) => {
@@ -277,6 +368,7 @@ export class Slides extends Ion {
       return this.options.onSliderMove && this.options.onSliderMove(swiper, e);
     };
 
+
     setTimeout(() => {
       var swiper = new Swiper(this.getNativeElement().children[0], options);
       this.slider = swiper;
@@ -284,7 +376,7 @@ export class Slides extends Ion {
 
     /*
     * TODO: Finish this
-    if (util.isTrueProperty(this.zoom)) {
+    if (isTrueProperty(this.zoom)) {
       this.enableZoom = true;
       setTimeout(() => {
         this.initZoom();
@@ -308,7 +400,6 @@ export class Slides extends Ion {
    * @private
    */
   onDoubleTap(swiper, e) {
-
     this.toggleZoom(swiper, e);
   }
   /**
@@ -620,65 +711,89 @@ export class Slides extends Ion {
       this.slider.update();
 
       // Don't allow pager to show with > 10 slides
-      if (this.slider.slides.length > 10) {
+      if (this.length() > 10) {
         this.showPager = false;
       }
     });
   }
 
   /**
-   * @private
+   * Transition to the specified slide.
+   *
+   * @param {number} index  The index number of the slide.
+   * @param {number} speed  Transition duration (in ms). Optional.
+   * @param {boolean} runCallbacks  Whether or not to emit the `willChange`/`didChange` events. Optional. Default true.
    */
-  slideTo(slideIndex: number, speed: number, runCallbacks: boolean) {
+  slideTo(index: number, speed: number, runCallbacks: boolean) {
-    this.slider.slideTo(slideIndex, speed, runCallbacks);
+    this.slider.slideTo(index, speed, runCallbacks);
   }
 
   /**
-   * @private
+   * Transition to the next slide.
+   *
+   * @param {number} speed  Transition duration (in ms). Optional.
+   * @param {boolean} runCallbacks  Whether or not to emit the `willChange`/`didChange` events. Optional. Default true.
    */
-  next() {
+  slideNext(speed: number, runCallbacks: boolean) {
-    this.slider.slideNext();
+    this.slider.slideNext(runCallbacks, speed);
   }
 
   /**
-   * @private
+   * Transition to the previous slide.
+   *
+   * @param {number} speed  Transition duration (in ms). Optional.
+   * @param {boolean} runCallbacks  Whether or not to emit the `willChange`/`didChange` events. Optional. Default true.
    */
-  prev() {
+  slidePrev(speed: number, runCallbacks: boolean) {
-    this.slider.slidePrev();
+    this.slider.slidePrev(runCallbacks, speed);
   }
 
   /**
-   * @private
+   * Get the index of the active slide.
+   *
+   * @returns {number} The index number of the current slide.
    */
-  getIndex(): number {
+  getActiveIndex(): number {
     return this.slider.activeIndex;
   }
 
   /**
-   * @private
+   * Get the total number of slides.
+   *
+   * @returns {number} The total number of slides.
    */
-  getNumSlides(): number {
+  length(): number {
     return this.slider.slides.length;
   }
 
   /**
-   * @private
+   * Get whether or not the current slide is the last slide.
+   *
+   * @returns {boolean} If the slide is the last slide or not.
    */
-  isAtEnd(): boolean {
+  isEnd(): boolean {
     return this.slider.isEnd;
   }
 
   /**
-   * @private
+   * Get whether or not the current slide is the first slide.
+   *
+   * @returns {boolean} If the slide is the first slide or not.
    */
-  isAtBeginning(): boolean {
+  isBeginning(): boolean {
     return this.slider.isBeginning;
   }
 
   /**
-   * @private
+   * Get the `Swiper` instance.
+   *
+   * The Slides component wraps the `Swiper` component built by iDangero.us. See the
+   * [Swiper API Docs](http://idangero.us/swiper/api/) for information on using
+   * the `Swiper` instance directly.
+   *
+   * @returns {Swiper}
    */
-  getSliderWidget() {
+  getSlider() {
     return this.slider;
   }
 }
@@ -686,7 +801,11 @@ export class Slides extends Ion {
  /**
   * @name Slide
   * @description
-  * `ion-slide` is a child component of `ion-slides` and is where all your individule slide content will be rendered too.
+  * The Slide component is a child component of [Slides](../Slides). The template
+  * should be written as `ion-slide`. Any slide content should be written
+  * in this component and it should be used in conjunction with [Slides](../Slides).
+  *
+  * See the [Slides API Docs](../Slides) for more usage information.
   *
   * @demo /docs/v2/demos/slides/
   * @see {@link /docs/v2/api/components/slides/Slides/ Slides API Docs}

ionic/components/slides/swiper-widget.d.ts

@@ -6,7 +6,7 @@ export declare class Swiper {
   isEnd: boolean;
   isBeginning: boolean;
   update(): any;
-  slideNext(): any;
+  slideNext(runCallbacks: boolean, speed: number);
-  slidePrev(): any;
+  slidePrev(runCallbacks: boolean, speed: number);
   slideTo(slideIndex: number, speed: number, runCallbacks: boolean);
 }