From bd4dc668b6b78747004da7e647c75204279539b6 Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Thu, 16 Jul 2015 15:42:19 -0700 Subject: [PATCH] feat(datepicker): add docs with usage for $mdDateLocale --- src/components/datepicker/calendar.js | 4 +- src/components/datepicker/calendar.spec.js | 4 +- src/components/datepicker/calendarMonth.js | 6 +- src/components/datepicker/dateLocale.spec.js | 26 +++--- .../datepicker/dateLocaleProvider.js | 79 +++++++++++++------ src/components/datepicker/datePicker.js | 8 +- src/components/datepicker/datePicker.spec.js | 2 +- 7 files changed, 80 insertions(+), 49 deletions(-) diff --git a/src/components/datepicker/calendar.js b/src/components/datepicker/calendar.js index 0420a732b88..abdfa22f0c2 100644 --- a/src/components/datepicker/calendar.js +++ b/src/components/datepicker/calendar.js @@ -76,7 +76,7 @@ * @ngInject @constructor */ function CalendarCtrl($element, $attrs, $scope, $animate, $q, $mdConstant, - $mdTheming, $$mdDateUtil, $$mdDateLocale, $mdInkRipple, $mdUtil) { + $mdTheming, $$mdDateUtil, $mdDateLocale, $mdInkRipple, $mdUtil) { $mdTheming($element); /** * Dummy array-like object for virtual-repeat to iterate over. The length is the total @@ -104,7 +104,7 @@ this.dateUtil = $$mdDateUtil; /** @final */ - this.dateLocale = $$mdDateLocale; + this.dateLocale = $mdDateLocale; /** @final {!angular.JQLite} */ this.$element = $element; diff --git a/src/components/datepicker/calendar.spec.js b/src/components/datepicker/calendar.spec.js index 22844d6b023..7e56d4b4e55 100644 --- a/src/components/datepicker/calendar.spec.js +++ b/src/components/datepicker/calendar.spec.js @@ -98,7 +98,7 @@ describe('md-calendar', function() { $compile = $injector.get('$compile'); $rootScope = $injector.get('$rootScope'); $$rAF = $injector.get('$$rAF'); - dateLocale = $injector.get('$$mdDateLocale'); + dateLocale = $injector.get('$mdDateLocale'); dateUtil = $injector.get('$$mdDateUtil'); $mdUtil = $injector.get('$mdUtil'); keyCodes = $injector.get('$mdConstant').KEY_CODE; @@ -136,7 +136,7 @@ describe('md-calendar', function() { expect(extractRowText(header)).toEqual(['S', 'M', 'T', 'W', 'T', 'F' ,'S']); }); - it('should use $$mdDateLocale.shortDays as weeks header values', function() { + it('should use $mdDateLocale.shortDays as weeks header values', function() { var oldShortDays = dateLocale.shortDays; dateLocale.shortDays = ['SZ', 'MZ', 'TZ', 'WZ', 'TZ', 'FZ', 'SZ']; diff --git a/src/components/datepicker/calendarMonth.js b/src/components/datepicker/calendarMonth.js index f51e25fbe95..b0d7f0ab375 100644 --- a/src/components/datepicker/calendarMonth.js +++ b/src/components/datepicker/calendarMonth.js @@ -48,9 +48,9 @@ * Controller for a single calendar month. * @ngInject @constructor */ - function CalendarMonthCtrl($element, $$mdDateUtil, $$mdDateLocale) { + function CalendarMonthCtrl($element, $$mdDateUtil, $mdDateLocale) { this.dateUtil = $$mdDateUtil; - this.dateLocale = $$mdDateLocale; + this.dateLocale = $mdDateLocale; this.$element = $element; this.calendarCtrl = null; @@ -108,7 +108,7 @@ selectionIndicator.textContent = this.dateLocale.dates[opt_date.getDate()]; cell.setAttribute('tabindex', '-1'); - cell.setAttribute('aria-label', this.dateLocale.longAnnounceFormatter(opt_date)); + cell.setAttribute('aria-label', this.dateLocale.longDateFormatter(opt_date)); cell.id = calendarCtrl.getDateId(opt_date); cell.addEventListener('click', calendarCtrl.cellClickHandler); diff --git a/src/components/datepicker/dateLocale.spec.js b/src/components/datepicker/dateLocale.spec.js index 9175356a631..d8bdaeb6d42 100644 --- a/src/components/datepicker/dateLocale.spec.js +++ b/src/components/datepicker/dateLocale.spec.js @@ -1,5 +1,5 @@ -describe('$$mdDateLocale', function() { +describe('$mdDateLocale', function() { var dateLocale, dateUtil; // Fake $locale with made-up days and months. @@ -19,8 +19,8 @@ describe('$$mdDateLocale', function() { $provide.value('$locale', $localeFake); })); - beforeEach(inject(function($$mdDateLocale, $$mdDateUtil) { - dateLocale = $$mdDateLocale; + beforeEach(inject(function($mdDateLocale, $$mdDateUtil) { + dateLocale = $mdDateLocale; dateUtil = $$mdDateUtil; })); @@ -55,23 +55,23 @@ describe('$$mdDateLocale', function() { 'X12', 'X13', 'X14', 'X15', 'X16', 'X17', 'X18', 'X19', 'X20', 'X21', 'X22', 'X23', 'X24', 'X25', 'X26', 'X27', 'X28', 'X29', 'X30', 'X31']; - beforeEach(module(function($$mdDateLocaleProvider) { - $$mdDateLocaleProvider.months = fakeMonths; - $$mdDateLocaleProvider.shortMonths = fakeshortMonths; - $$mdDateLocaleProvider.days = fakeDays; - $$mdDateLocaleProvider.shortDays = fakeShortDays; - $$mdDateLocaleProvider.dates = fakeDates; - $$mdDateLocaleProvider.formatDate = function() { + beforeEach(module(function($mdDateLocaleProvider) { + $mdDateLocaleProvider.months = fakeMonths; + $mdDateLocaleProvider.shortMonths = fakeshortMonths; + $mdDateLocaleProvider.days = fakeDays; + $mdDateLocaleProvider.shortDays = fakeShortDays; + $mdDateLocaleProvider.dates = fakeDates; + $mdDateLocaleProvider.formatDate = function() { return 'Your birthday!' }; - $$mdDateLocaleProvider.parseDate = function() { + $mdDateLocaleProvider.parseDate = function() { return new Date(1969, 6, 16); }; })); - beforeEach(inject(function($$mdDateLocale, $$mdDateUtil) { - dateLocale = $$mdDateLocale; + beforeEach(inject(function($mdDateLocale, $$mdDateUtil) { + dateLocale = $mdDateLocale; dateUtil = $$mdDateUtil; })); diff --git a/src/components/datepicker/dateLocaleProvider.js b/src/components/datepicker/dateLocaleProvider.js index af619200a49..2446cdd2065 100644 --- a/src/components/datepicker/dateLocaleProvider.js +++ b/src/components/datepicker/dateLocaleProvider.js @@ -5,6 +5,53 @@ * Provider that allows the user to specify messages, formatters, and parsers for date * internationalization. */ + + + /** + * @ngdoc service + * @name $mdDateLocaleProvider + * @module material.components.datepicker + * + * @description + * The `$mdDateLocaleProvider` is the provider that creates the `$mdDateLocale` service. + * This provider that allows the user to specify messages, formatters, and parsers for date + * internationalization. The `$mdDateLocale` service itself is consumed by Angular Material + * components that that deal with dates. + * + * @usage + * + * myAppModule.config(function($mdDateLocaleProvider) { + * + * // Example of a French localization. + * $mdDateLocaleProvider.months = ['Janvier', 'Février', 'Mars', ...]; + * $mdDateLocaleProvider.shortMonths = ['Janv', 'Févr', 'Mars', ...]; + * $mdDateLocaleProvider.days = ['Lundi', 'Mardi', 'Mercredi', ...]; + * $mdDateLocaleProvider.shortDays = ['L', 'M', 'M', ...]; + * $mdDateLocaleProvider.dates = [1, 2, 3, 4, 5, 6, ...]; + * + * // Example uses moment.js to parse and format dates. + * $mdDateLocaleProvider.formatDate = function(date) { + * return moment(date).format + * }; + * $mdDateLocaleProvider.parseDate = function(dateString) { + * return moment(dateString).toDate('L'); + * }; + * + * $mdDateLocaleProvider.monthHeaderFormatter = function(date) { + * $mdDateLocale.shortMonths[date.getMonth()] + ' ' + date.getFullYear(); + * }; + * + * $mdDateLocaleProvider.weekNumberFormatter = function(weekNumber) { + * return 'Semaine ' + weekNumber; + * }; + * + * $mdDateLocaleProvider.msgCalendar = 'Calendrier'; + * $mdDateLocaleProvider.msgOpenCalendar = 'Ouvrir le calendrier'; + * + * }); + * + * + */ angular.module('material.components.datepicker').config(function($provide) { // TODO(jelbourn): Assert provided values are correctly formatted. Need assertions. @@ -50,18 +97,11 @@ this.weekNumberFormatter = null; /** - * Function that formats a date into a short aria-live announcement that is read when - * the focused date changes within the same month. - * @type {function(Date): string} - */ - this.shortAnnounceFormatter = null; - - /** - * Function that formats a date into a long aria-live announcement that is read when - * the focused date changes to a date in a different month. + * Function that formats a date into a long aria-label that is read + * when the focused date changes. * @type {function(Date): string} */ - this.longAnnounceFormatter = null; + this.longDateFormatter = null; /** * ARIA label for the calendar "dialog" used in the datepicker. @@ -120,21 +160,11 @@ } /** - * Default formatter for short aria-live announcements. - * @param {!Date} date - * @returns {string} - */ - function defaultShortAnnounceFormatter(date) { - // Example: 'Tuesday 12' - return service.days[date.getDay()] + ' ' + service.dates[date.getDate()]; - } - - /** - * Default formatter for long aria-live announcements. + * Default formatter for date cell aria-labels. * @param {!Date} date * @returns {string} */ - function defaultLongAnnounceFormatter(date) { + function defaultLongDateFormatter(date) { // Example: 'Thursday June 18 2015' return [ service.days[date.getDay()], @@ -170,8 +200,7 @@ parseDate: this.parseDate || defaultParseDate, monthHeaderFormatter: this.monthHeaderFormatter || defaultMonthHeaderFormatter, weekNumberFormatter: this.weekNumberFormatter || defaultWeekNumberFormatter, - shortAnnounceFormatter: this.shortAnnounceFormatter || defaultShortAnnounceFormatter, - longAnnounceFormatter: this.longAnnounceFormatter || defaultLongAnnounceFormatter, + longDateFormatter: this.longDateFormatter || defaultLongDateFormatter, msgCalendar: this.msgCalendar || defaultMsgCalendar, msgOpenCalendar: this.msgOpenCalendar || defaultMsgOpenCalendar }); @@ -179,6 +208,6 @@ return service; }; - $provide.provider('$$mdDateLocale', new DateLocaleProvider()); + $provide.provider('$mdDateLocale', new DateLocaleProvider()); }); })(); diff --git a/src/components/datepicker/datePicker.js b/src/components/datepicker/datePicker.js index fdeebc2aa48..e79e74d1351 100644 --- a/src/components/datepicker/datePicker.js +++ b/src/components/datepicker/datePicker.js @@ -29,6 +29,8 @@ * * @description * `` is a component used to select a single date. + * For information on how to configure internationalization for the date piicker, + * see `$mdDateLocaleProvider`. * * @usage * @@ -45,7 +47,7 @@ '' + '
' + '' + @@ -90,7 +92,7 @@ * @ngInject @constructor */ function DatePickerCtrl($scope, $element, $attrs, $compile, $timeout, $mdConstant, $mdTheming, - $mdUtil, $$mdDateLocale, $$mdDateUtil, $$rAF) { + $mdUtil, $mdDateLocale, $$mdDateUtil, $$rAF) { /** @final */ this.$compile = $compile; @@ -98,7 +100,7 @@ this.$timeout = $timeout; /** @final */ - this.dateLocale = $$mdDateLocale; + this.dateLocale = $mdDateLocale; /** @final */ this.dateUtil = $$mdDateUtil; diff --git a/src/components/datepicker/datePicker.spec.js b/src/components/datepicker/datePicker.spec.js index aa78b38064c..a6a3ece68a9 100644 --- a/src/components/datepicker/datePicker.spec.js +++ b/src/components/datepicker/datePicker.spec.js @@ -16,7 +16,7 @@ describe('md-date-picker', function() { $$rAF = $injector.get('$$rAF'); $animate = $injector.get('$animate'); dateUtil = $injector.get('$$mdDateUtil'); - dateLocale = $injector.get('$$mdDateLocale'); + dateLocale = $injector.get('$mdDateLocale'); $timeout = $injector.get('$timeout'); keyCodes = $injector.get('$mdConstant').KEY_CODE;