view | history | commit | commitdiff
marquex
2015-07-23 8abb28c2b289d7d86d85b4bd24f475775a57a99d
commit | author | age
9fb8e8 1 react-datetime
4afe21 2 ===============================
18dc17 3 A date and time picker in the same React.js component. It can be used as a datepicker, timepicker or both at the same time.
4afe21 4
eba92b 5 It allows to edit even date's milliseconds.
M 6
18dc17 7 This project started as a fork of https://github.com/quri/react-bootstrap-datetimepicker but the code and the API has changed a lot.
ce8749 8
f13618 9 Usage
LC 10 ===============================
11
12 Installation :
13 ```
9fb8e8 14 npm install react-datetime
f13618 15 ```
LC 16
17 Then
18 ```javascript
9fb8e8 19 require('react-datetime');
f13618 20
LC 21 ...
22
23 render: function() {
9fb8e8 24   return <Datetime />;
f13618 25 }
LC 26 ```
18dc17 27 [See this example working](http://codepen.io/arqex/pen/BNRNBw).
f13618 28
LC 29 API
30 ===============================
31
32 | Name         | Type    | Default | Description |
33 | ------------ | ------- | ------- | ----------- |
c658ad 34 | **value** | Date | new Date() | Represents the value for the compones, in order to use it as a [controlled component](https://facebook.github.io/react/docs/forms.html#controlled-components). This prop is parsed by moment.js, so it is possible to use a date string or a moment.js date. |
M 35 | **defaultValue** | Date | new Date() | Represents the inital value for the component to use it as a [uncontrolled component](https://facebook.github.io/react/docs/forms.html#uncontrolled-components). This prop is parsed by moment.js, so it is possible to use a date string or a moment.js date. |
cbe644 36 | **dateFormat**   | `bool` or `string`  | `true` | Defines the format for the date. It accepts any [moment.js date format](http://momentjs.com/docs/#/displaying/format/). If `true` the date will be displayed using the defaults for the current locale. If `false` the datepicker is disabled and the component can be used as timepicker. |
M 37 | **timeFormat**   | `bool` or `string`  | `true` | Defines the format for the time. It accepts any [moment.js time format](http://momentjs.com/docs/#/displaying/format/). If `true` the time will be displayed using the defaults for the current locale. If `false` the timepicker is disabled and the component can be used as datepicker. |
c37f80 38 | **input** | boolean | true | Wether to show an input field to edit the date manually. |
M 39 | **locale** | string | null | Manually set the locale for the react-datetime instance. Moment.js locale needs to be loaded to be used, see [i18n docs](#i18n).
baa9f1 40 | **onChange** | function | empty function | Callback trigger when the date changes. The callback receives the selected `moment` object as only parameter. |
cc4dda 41 | **onBlur** | function | empty function | Callback trigger for when the user clicks outside of the input, simulating a regular onBlur. The callback receives the selected `moment` object as only parameter. |
9fb8e8 42 | **viewMode** | string or number | 'days' | The default view to display when the picker is shown. ('years', 'months', 'days', 'time') |
8abb28 43 | **className** | string | `""` | Extra class names for the component markup. |
4cdcdb 44 | **inputProps** | object | undefined | Defines additional attributes for the input element of the component. |
baa9f1 45 | **isValidDate** | function | () => true | Define the dates that can be selected. The function receives `(currentDate, selectedDate)` and should return a `true` or `false` whether the `currentDate` is valid or not. See [selectable dates](#selectable-dates).|
eba92b 46 | **renderDay** | function | DOM.td( day ) | Customize the way that the days are shown in the day picker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, and must return a React component. See [appearance customization](#appearance_customization) |
M 47 | **renderMonth** | function | DOM.td( month ) | Customize the way that the months are shown in the month picker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, and must return a React component. See [appearance customization](#appearance_customization) |
48 | **renderYear** | function | DOM.td( year ) | Customize the way that the years are shown in the year picker. The accepted function has the `selectedDate`, the current date and the default calculated `props` for the cell, and must return a React component. See [appearance customization](#appearance_customization) |
f13618 49
c37f80 50 ## i18n
M 51 Different language and date formats are supported by react-datetime. React uses [moment.js](http://momentjs.com/) to format the dates, and the easiest way of changing the language of the calendar is [changing the moment.js locale](http://momentjs.com/docs/#/i18n/changing-locale/).
52
53 ```js
54 var moment = require('moment');
55 require('moment/locale/fr');
56 // Now react-datetime will be in french
57 ```
58
59 If there are multiple locales loaded, you can use the prop `locale` to define what language should be used by the instance:
60 ```js
182c2b 61 <Datetime locale="fr-ca" />
c37f80 62 <Datetime locale="de" />
M 63 ```
64 [Here you can see the i18n example working](http://codepen.io/arqex/pen/PqJMQV).
65
eba92b 66 ## Appearance customization
M 67 It is possible to customize the way that the datetime picker display the days, months and years in the calendar. To adapt the calendar to every need it is possible to use the props `renderDay( props, currentDate, selectedDate )`, `renderMonth( props, month, year, selectedDate )` and `renderYear( props, year, selectedDate )` of react-datetime.
68
69 ```js
70 var MyDTPicker = React.createClass({
71     render: function(){
72         return <Datetime
73             renderDay={ this.renderDay } 
74             renderMonth={ this.renderMonth } 
75             renderYear={ this.renderYear }
76         />;
77     },
78     renderDay: function( selectedDate, currentDate, props ){
79         return <td {...props}>{ currentDate.date() }</td>;
80     },
81     renderMonth: function( selectedDate, currentMonthDate, props ){
82         return <td {...props}>{ month }</td>;
83     },
84     renderDay: function( selectedDate, year, props ){
85         return <td {...props}>{ currentDate.date() }</td>;
86     }
87 });
88 ```
89
90 * `props` is the object that react-date picker has calculated for this object. It is convenient to use this object as the props for your custom component, since it knows how to handle the click event and its `className` attribute is used by the default styles.
91 * `selectedDate` and `currentDate` are Moment.js objects and can be used to change the output depending on the selected date, or the date for the current day.
92 * `month` and `year` are the numeric representation of the current month and year to be displayed. Notice that the possible `month` values go from `0` to `11`.
93
baa9f1 94 ## Selectable dates
M 95 It is possible to disable dates in the calendar if we don't want the user to select them. It is possible thanks to the prop `isValidDate`, which admits a function in the form `function( currentDate, selectedDate )` where both arguments are moment.js objects. The function should return `true` for selectable dates, and `false` for disabled ones.
96
97 If we want to disable all the dates before today we can do like
98 ```js
99 var valid = function( current ){
100     var limit = new Date(); // Today
101
102     // Yesterday
103     limit.setDate(limit.getDate() - 1);
104
105     // Only dates after yesterday are ok
106     return current > limit;
107 };
108 <Datetime isValidDate={ valid } />
109 ```
110
111 If we want only odd dates to be valid we could do like
112 ```js
113 var valid = function( current ){
114     return current.date() % 2;
115 };
116 <Datetime isValidDate={ valid } />
117 ```
118
ce8749 119 Contributions
LC 120 ===============================
9fb8e8 121 Any help is always welcome :)
M 122
8abb28 123 ### [Changelog](CHANGELOG.md)
M 124
9fb8e8 125 ### [MIT Licensed](LICENSE)