From 9eca13c0d19c0322ee4a2324d6b17643c142567d Mon Sep 17 00:00:00 2001 From: Theodore Brown Date: Mon, 15 Feb 2016 23:23:44 -0600 Subject: [PATCH] Add documentation for pikaday methods and properties Also fixed `yearRange` property to accept a number, and removed invalid `gogoYear` method --- pikaday/pikaday-tests.ts | 3 + pikaday/pikaday.d.ts | 245 ++++++++++++++++++++++++++++++++++----- 2 files changed, 219 insertions(+), 29 deletions(-) diff --git a/pikaday/pikaday-tests.ts b/pikaday/pikaday-tests.ts index 78a3b378f..f98d4afce 100644 --- a/pikaday/pikaday-tests.ts +++ b/pikaday/pikaday-tests.ts @@ -26,6 +26,7 @@ new Pikaday({field: $('#datepicker')[0]}); console.log(this.getMoment().format('Do MMMM YYYY')); } }); + picker.toString(); picker.toString('YYYY-MM-DD'); picker.getDate(); @@ -40,6 +41,8 @@ new Pikaday({field: $('#datepicker')[0]}); picker.gotoYear(2015); picker.setMinDate(new Date); picker.setMaxDate(new Date); + picker.setStartRange(new Date); + picker.setEndRange(new Date); picker.isVisible(); picker.show(); picker.adjustPosition(); diff --git a/pikaday/pikaday.d.ts b/pikaday/pikaday.d.ts index 4229213f0..c4d4c6bf0 100644 --- a/pikaday/pikaday.d.ts +++ b/pikaday/pikaday.d.ts @@ -6,52 +6,118 @@ /// declare class Pikaday { - el:HTMLElement; + el: HTMLElement; constructor(options: Pikaday.PikadayOptions); - toString():string; - toString(format:string):string; + /** + * Returns the selected date in a string format. If Moment.js exists + * (recommended) then Pikaday can return any format that Moment + * understands, otherwise you're stuck with JavaScript's default. + */ + toString(format?: string): string; - getDate():Date|void; + /** + * Returns a JavaScript Date object for the selected day, or null if + * no date is selected. + */ + getDate(): Date; - setDate(date:string|Date, triggerOnSelect?:boolean):void; + /** + * Set the current selection. This will be restricted within the bounds + * of minDate and maxDate options if they're specified. A boolean (true) + * can optionally be passed as the second parameter to prevent triggering + * of the onSelect callback, allowing the date to be set silently. + */ + setDate(date: string | Date, triggerOnSelect?: boolean): void; - getMoment():moment.Moment; + /** + * Returns a Moment.js object for the selected date (Moment must be + * loaded before Pikaday). + */ + getMoment(): moment.Moment; - setMoment(moment:any):void; + /** + * Set the current selection with a Moment.js object (see setDate). + */ + setMoment(moment: any): void; - gotoDate(date:Date):void; + /** + * Change the current view to see a specific date. + */ + gotoDate(date: Date): void; - gotoToday():void; + /** + * Shortcut for picker.gotoDate(new Date()) + */ + gotoToday(): void; - gotoMonth(monthIndex:number):void; + /** + * Change the current view by month (0: January, 1: Februrary, etc). + */ + gotoMonth(monthIndex: number): void; - gotoYear(year:number):void; + /** + * Go to the next month (this will change year if necessary). + */ + nextMonth(): void; - nextMonth():void; + /** + * Go to the previous month (this will change year if necessary). + */ + prevMonth(): void; + + /** + * Change the year being viewed. + */ + gotoYear(year: number): void; - prevMonth():void; + /** + * Update the minimum/earliest date that can be selected. + */ + setMinDate(date: Date): void; - gogoYear(year:number):void; + /** + * Update the maximum/latest date that can be selected. + */ + setMaxDate(date: Date): void; - setMinDate(date:Date):void; + /** + * Update the range start date. For using two Pikaday instances to + * select a date range. + */ + setStartRange(date: Date): void; + + /** + * Update the range end date. For using two Pikaday instances to select + * a date range. + */ + setEndRange(date: Date): void; - setMaxDate(date:Date):void; + /** + * Returns true if the picker is visible. + */ + isVisible(): boolean; - setEndRange(date:Date):void; + /** + * Make the picker visible. + */ + show(): void; - setStartRange(date:Date):void; + /** + * Hide the picker making it invisible. + */ + hide(): void; - isVisible():boolean; + /** + * Recalculate and change the position of the picker. + */ + adjustPosition(): void; - show():void; - - hide():void; - - adjustPosition():void; - - destroy():void; + /** + * Hide the picker and remove all event listeners - no going back! + */ + destroy(): void; } // merge the Pikaday class declaration with a module @@ -65,32 +131,153 @@ declare module Pikaday { } interface PikadayOptions { + /** + * Bind the datepicker to a form field. + */ field?: HTMLElement; + + /** + * The default output format for toString() and field value. + * Requires Moment.js for custom formatting. + */ format?: string; + + /** + * Use a different element to trigger opening the datepicker. + * Default: field element. + */ trigger?: HTMLElement; + + /** + * Automatically show/hide the datepicker on field focus. + * Default: true if field is set. + */ bound?: boolean; + + /** + * Preferred position of the datepicker relative to the form field + * (e.g. 'top right'). Automatic adjustment may occur to avoid + * displaying outside the viewport. Default: 'bottom left'. + */ position?: string; + + /** + * Can be set to false to not reposition the datepicker within the + * viewport, forcing it to take the configured position. Default: true. + */ reposition?: boolean; + + /** + * DOM node to render calendar into, see container example. + * Default: undefined. + */ container?: HTMLElement; + + /** + * The initial date to view when first opened. + */ defaultDate?: Date; + + /** + * Make the defaultDate the initial selected value. + */ setDefaultDate?: boolean; + + /** + * First day of the week (0: Sunday, 1: Monday, etc). + */ firstDay?: number; + + /** + * The earliest date that can be selected (this should be a native + * Date object - e.g. new Date() or moment().toDate()). + */ minDate?: Date; + + /** + * The latest date that can be selected (this should be a native + * Date object - e.g. new Date() or moment().toDate()). + */ maxDate?: Date; + + /** + * Disallow selection of Saturdays and Sundays. + */ disableWeekends?: boolean; - disableDayFn?: (date:Date) => boolean; - yearRange?: number[]; + + /** + * Callback function that gets passed a Date object for each day + * in view. Should return true to disable selection of that day. + */ + disableDayFn?: (date: Date) => boolean; + + /** + * Number of years either side (e.g. 10) or array of upper/lower range + * (e.g. [1900, 2015]). + */ + yearRange?: number | number[]; + + /** + * Show the ISO week number at the head of the row. Default: false. + */ showWeekNumber?: boolean; + + /** + * Reverse the calendar for right-to-left languages. Default: false. + */ isRTL?: boolean; + + /** + * Language defaults for month and weekday names. + */ i18n?: PikadayI18nConfig; + + /** + * Additional text to append to the year in the title. + */ yearSuffix?: string; + + /** + * Render the month after the year in the title. Default: false. + */ showMonthAfterYear?: boolean; + + /** + * Number of visible calendars. + */ numberOfMonths?: number; + + /** + * When numberOfMonths is used, this will help you to choose where the + * main calendar will be (default left, can be set to right). Only used + * for the first display or when a selected date is not already visible. + */ mainCalendar?: string; + + /** + * Define a class name that can be used as a hook for styling different + * themes. Default: null. + */ theme?: string; - onSelect?: (date:Date) => void; + + /** + * Callback function for when a date is selected. + */ + onSelect?: (date: Date) => void; + + /** + * Callback function for when the picker becomes visible. + */ onOpen?: () => void; + + /** + * Callback function for when the picker is hidden. + */ onClose?: () => void; + + /** + * Callback function for when the picker draws a new month. + */ onDraw?: () => void; } }