source: admin-center/trunk/fuentes/admin-center.install/usr/share/admin-center/lib/bower_components/eonasdan-bootstrap-datetimepicker/docs/ContributorsGuide.md @ 6782

Last change on this file since 6782 was 6782, checked in by kbut, 20 months ago

add moment and datetimepicker bootstrap plugin

File size: 7.6 KB
Line 
1This guide is aimed to contributors wishing to understand the internals of the code in order to change/evolve the component.
2
3**Note:** this guide refers to **version 4** which is currently in beta and will be updated as we progress
4
5## Introduction
6This component consists actually of 2 subcomponent UI widgets one for the date and one for the time selection process. The developers can configure which of those are needed and also the granularity that the component will allow the users to select a date/time. Developers also choose the format that the selected datetime will be displayed in the input field.
7The component uses on `jQuery`, `moment.js` and `bootstrap` libraries.
8
9## Code
10### Private variables
11
12* `element` - Holds the DOM element this instance is attached to
13
14* `options` - Holds an object with the curently set options for the specific instance of the component. Don't directly change the properties of that object use the public API methods instead. DO NOT expose this object or its properties outside of the component.
15
16* `picker` - Reference variable to the created instance `(this)`
17
18* `date` - Holds the moment object for the model value of the component. **DON'T** directly change this variable unless you **REALLY** know what you are doing. Use `setValue()` function to set it. It handles all component logic for updating the model value and emitting all the appropriate events
19
20* `viewDate` - Holds the currently selected value that the user has selected through the widget. This is not the model value this is the view value. Changing this usually requires a subsequent call to `update()` function
21
22* `unset` - A `boolean` variable that holds wheather the components model value is set or not. Model's value starts as `unset = true` and if is either set by the user or programmatically through the api to a valid value then it is set to `false`. If subsequent events lead to an invalid value then this variable is set to `true` again. Setting this variable usually takes place in the `setValue()` function.
23
24* `input` - Hold the DOM input element this instance is attached to
25
26* `component` - Holds a reference to the .input-group DOM element that the widget is attached or false if it is attached directly on an input field
27
28* `widget` - Holds a reference to the DOM element containing the widget or `false` if the widget is hidden
29
30* `use24hours` - Holds whether the component uses 24 hours format or not. This is initialized on the `format()` function
31
32* `minViewModeNumber` - Holds the Numeric equivelant of the options.minViewMode parameter
33
34* `format` - Holds the current format string that is used for formating the date model value. Note this is not the same thing as the `options.format` as the second could be set to `false` in which case the first takes the locale's `L` or `LT` value
35
36* `currentViewMode` - Hold the state of the current viewMode for the DatePicker subcomponent
37
38* `actions` - An object containing all the functions that can be called when the users clicks on the widget
39
40* `datePickerModes` - An array of objects with configuration parameters for the different views of the DatePicker subcomponent
41
42* `viewModes` - An array of strings containing all the possible strings that `options.viewMode` can take through `viewMode()` public api function
43
44* `directionModes` - An array of strings containing all the possible strings that `options.direction` can take through `direction()` public api function
45
46* `orientationModes` - An array of strings containing all the possible strings that `options.orientation` can take through `orientation()` public api function
47
48### Private functions
49
50#### Widget related
51
52* `getDatePickerTemplate()` - returns a string containing the html code for the date picker subcomponent
53
54* `getTimePickerTemplate()` - returns a string containing the html code for the time picker subcomponent
55
56* `getTemplate()` - returns a string with containing the html code for all the DateTimePicker component
57
58* `place()` - handles the placement of the widget's dropdown
59
60* `updateMonths()` - updates the html subpage related to the months for Date picker view
61
62* `updateYears()` - updates the html subpage related to the years for Date picker view
63
64* `fillDate()` - updates the html subpage related to the days for Date picker view
65
66* `fillHours()` - Creates the hours spans for the hours subview of the Time subcomponent
67
68* `fillMinutes()` - Creates the minutes spans for the hours subview of the Time subcomponent
69
70* `fillSeconds()` - Creates the seconds spans for the hours subview of the Time subcomponent
71
72* `fillTime()` - Creates the main subview of the Time subcomponent
73
74* `update()` - updates the UI of part of the widget
75
76* `fillDow()` - Creates the day names in the days subview on the Date subcomponent
77
78* `fillMonths()` - Creates the month spans for the months subview of the Date subcomponent
79
80* `createWidget()` - creates the UI widget end attaches widget event listeners
81
82* `destroyWidget()` - destroys the UI widget DOM element and detaches widget event listeners
83
84* `showMode(dir)` - toggles between the various subpage related views of the DateTimePicker
85
86#### Events related
87
88* `notifyEvent(e)` - Use this function when you want to send en event to listener this could be used as a filter later
89
90* `stopEvent(e)` - Shortcut for stopping propagation of events
91
92* `doAction(e)` - Proxy function to call all the UI related click events
93
94* `keydown(e)` - Function to trap
95
96* `change(e)` - Listener function to track change events occuring on the `input` dom element the component is attached to
97
98* `attachDatePickerElementEvents()` - Attaches listeners to the existing DOM elements the component is attached to. Called upon construction of each datetimepicker instance
99
100* `detachDatePickerElementEvents()` - Detaches listeners from the DOM element the component is attached to. Called on `destroy()`
101
102* `attachDatePickerWidgetEvents()` - Attaches listeners on the components widget. Called on `show()`
103
104* `detachDatePickerWidgetEvents()` - Detaches listeners on the components widget. Called on `hide()`
105
106#### Model related
107
108* `setValue(targetMoment)` - Sets the model value of the component takes a moment object. An `error` event will be emmited if the `targetMoment` does not pass the configured validations. Otherwise the `date` variable will be set and the relevant events will be fired.
109
110* `isValid(targetMoment, granularity)` - returns `true` if the `targetMoment` moment object is valid according to the components set validation rules (`min/maxDates`, `disabled/enabledDates` and `daysOfWeekDisabled`). You may pass a second variable to check only up the the specific granularity `year, month, day, hour, minute, second`
111
112#### Utilities
113
114* `indexGivenDates (givenDatesArray)` - Function that takes the array from `enabledDates()` and `disabledDates()` public functions and stores them as object keys to enable quick lookup
115
116* `isInEnableDates(date)` - Checks whether if the given moment object exists in the `options.enabledDates` object
117
118* `isInDisableDates(date)` - Checks whether if the given moment object exists in the `options.disabledDates` array
119
120* `dataToOptions()` - Parses `data-date-*` options set on the input dom element the component is attached to and returns an object with them
121
122* `isInFixed()` - Checks if the dom element or its parents has a fixed position css rule.
123
124* `parseInputDate(date)` - Parses a date parameter with moment using the component's `options.format` and `options.useStrict`. It returns a `moment` object or false if `parsedMoment#isValid()` returns `false`. Use this to parse date inputs from outside the component (public API calls).
125
126* `init()` - Initializes the component. Called when the component instance is created
Note: See TracBrowser for help on using the repository browser.