Skip to content

Commit 33f5d7a

Browse files
scottgonzalezscottgonzalez
committed
Datepicker: Add overview and code examples for utility methods. Fixes jquery#92.
1 parent 68ea6ac commit 33f5d7a

File tree

1 file changed

+145
-5
lines changed

1 file changed

+145
-5
lines changed

‎entries/datepicker.xml

+145-5
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,153 @@
2525
</ul>
2626

2727
<h3 id="utility-functions">Utility functions</h3>
28+
29+
<h4>$.datepicker.setDefaults( settings )</h4>
30+
<p>Change the default settings for all date pickers.</p>
31+
<p>Use the <a href="#method-option"><code>option()</code></a> method to change settings for individual instances.</p>
32+
<div>
33+
<strong>Code examples:</strong>
34+
<p>Set all date pickers to open on focus or a click on an icon.</p>
35+
<pre><code>
36+
$.datepicker.setDefaults({
37+
showOn: "both",
38+
buttonImageOnly: true,
39+
buttonImage: "calendar.gif",
40+
buttonText: "Calendar"
41+
});
42+
</code></pre>
43+
<p>Set all date pickers to have French text.</p>
44+
<pre><code>
45+
$.datepicker.setDefaults( $.datepicker.regional[ "fr" ] );
46+
</code></pre>
47+
</div>
48+
49+
<h4>$.datepicker.formatDate( format, date, settings )</h4>
50+
<p>Format a date into a string value with a specified format.</p>
51+
<p>The format can be combinations of the following:</p>
52+
<ul>
53+
<li>d - day of month (no leading zero)</li>
54+
<li>dd - day of month (two digit)</li>
55+
<li>o - day of the year (no leading zeros)</li>
56+
<li>oo - day of the year (three digit)</li>
57+
<li>D - day name short</li>
58+
<li>DD - day name long</li>
59+
<li>m - month of year (no leading zero)</li>
60+
<li>mm - month of year (two digit)</li>
61+
<li>M - month name short</li>
62+
<li>MM - month name long</li>
63+
<li>y - year (two digit)</li>
64+
<li>yy - year (four digit)</li>
65+
<li>@ - Unix timestamp (ms since 01/01/1970)</li>
66+
<li> ! - Windows ticks (100ns since 01/01/0001)</li>
67+
<li>'...' - literal text</li>
68+
<li>'' - single quote</li>
69+
<li>anything else - literal text</li>
70+
</ul>
71+
<p>There are also a number of predefined standard date formats available from <code>$.datepicker</code>:</p>
2872
<ul>
29-
<li>$.datepicker.setDefaults( settings ) - Set settings for all datepicker instances.</li>
30-
<li>$.datepicker.formatDate( format, date, settings ) - Format a date into a string value with a specified format.</li>
31-
<li>$.datepicker.parseDate( format, value, settings ) - Extract a date from a string value with a specified format.</li>
32-
<li>$.datepicker.iso8601Week( date ) - Determine the week of the year for a given date: 1 to 53.</li>
33-
<li>$.datepicker.noWeekends - Set as beforeShowDay function to prevent selection of weekends.</li>
73+
<li>ATOM - 'yy-mm-dd' (Same as RFC 3339/ISO 8601)</li>
74+
<li>COOKIE - 'D, dd M yy'</li>
75+
<li>ISO_8601 - 'yy-mm-dd'</li>
76+
<li>RFC_822 - 'D, d M y' (See RFC 822)</li>
77+
<li>RFC_850 - 'DD, dd-M-y' (See RFC 850)</li>
78+
<li>RFC_1036 - 'D, d M y' (See RFC 1036)</li>
79+
<li>RFC_1123 - 'D, d M yy' (See RFC 1123)</li>
80+
<li>RFC_2822 - 'D, d M yy' (See RFC 2822)</li>
81+
<li>RSS - 'D, d M y' (Same as RFC 822)</li>
82+
<li>TICKS - '!'</li>
83+
<li>TIMESTAMP - '@'</li>
84+
<li>W3C - 'yy-mm-dd' (Same as ISO 8601)</li>
3485
</ul>
86+
<div>
87+
<strong>Code examples:</strong>
88+
<p>Display the date in ISO format. Produces "2007-01-26".</p>
89+
<pre><code>
90+
$.datepicker.formatDate( "yy-mm-dd", new Date( 2007, 1 - 1, 26 ) );
91+
</code></pre>
92+
<p>Display the date in expanded French format. Produces "Samedi, Juillet 14, 2007".</p>
93+
<pre><code>
94+
$.datepicker.formatDate( "DD, MM d, yy", new Date( 2007, 7 - 1, 14 ), {
95+
dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
96+
dayNames: $.datepicker.regional[ "fr" ].dayNames,
97+
monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
98+
monthNames: $.datepicker.regional[ "fr" ].monthNames
99+
});
100+
</code></pre>
101+
</div>
102+
103+
<h4>$.datepicker.parseDate( format, value, settings )</h4>
104+
<p>Extract a date from a string value with a specified format.</p>
105+
<p>The format can be combinations of the following:</p>
106+
<ul>
107+
<li>d - day of month (no leading zero)</li>
108+
<li>dd - day of month (two digit)</li>
109+
<li>o - day of year (no leading zeros)</li>
110+
<li>oo - day of year (three digit)</li>
111+
<li>D - day name short</li>
112+
<li>DD - day name long</li>
113+
<li>m - month of year (no leading zero)</li>
114+
<li>mm - month of year (two digit)</li>
115+
<li>M - month name short</li>
116+
<li>MM - month name long</li>
117+
<li>y - year (two digit)</li>
118+
<li>yy - year (four digit)</li>
119+
<li>@ - Unix timestamp (ms since 01/01/1970)</li>
120+
<li> ! - Windows ticks (100ns since 01/01/0001)</li>
121+
<li>'...' - literal text</li>
122+
<li>'' - single quote</li>
123+
<li>anything else - literal text</li>
124+
</ul>
125+
<p>A number of exceptions may be thrown:</p>
126+
<ul>
127+
<li>'Invalid arguments' if either format or value is null</li>
128+
<li>'Missing number at position nn' if format indicated a numeric value that is not then found</li>
129+
<li>'Unknown name at position nn' if format indicated day or month name that is not then found</li>
130+
<li>'Unexpected literal at position nn' if format indicated a literal value that is not then found</li>
131+
<li>'Invalid date' if the date is invalid, such as '31/02/2007'</li>
132+
</ul>
133+
<div>
134+
<strong>Code examples:</strong>
135+
<p>Extract a date in ISO format.</p>
136+
<pre><code>
137+
$.datepicker.parseDate( "yy-mm-dd", "2007-01-26" );
138+
</code></pre>
139+
<p>Extract a date in expanded French format.</p>
140+
<pre><code>
141+
$.datepicker.parseDate( "DD, MM d, yy", "Samedi, Juillet 14, 2007", {
142+
shortYearCuroff: 20,
143+
dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
144+
dayNames: $.datepicker.regional[ "fr" ].dayNames,
145+
monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
146+
monthNames: $.datepicker.regional[ "fr" ].monthNames
147+
});
148+
</code></pre>
149+
</div>
150+
151+
<h4>$.datepicker.iso8601Week( date )</h4>
152+
<p>Determine the week of the year for a given date: 1 to 53.</p>
153+
<p>This function uses the ISO 8601 definition of a week: weeks start on a Monday and the first week of the year contains January 4. This means that up to three days from the previous year may be included in the of first week of the current year, and that up to three days from the current year may be included in the last week of the previous year.</p>
154+
<p>This function is the default implementation for the <a href="#option-calculateWeek"><code>calculateWeek</code></a> option.</p>
155+
<div>
156+
<strong>Code examples:</strong>
157+
<p>Find the week of the year for a date.</p>
158+
<pre><code>
159+
$.datepicker.iso8601Week( new Date( 2007, 1 - 1, 26 ) );
160+
</code></pre>
161+
</div>
162+
163+
<h4>$.datepicker.noWeekends</h4>
164+
<p>Set as beforeShowDay function to prevent selection of weekends.</p>
165+
<p>We can provide the <code>noWeekends()</code> function into the <a href="#option-beforeShowDay"><code>beforeShowDay</code></a> option which will calculate all the weekdays and provide an array of <code>true</code>/<code>false</code> values indicating whether a date is selectable.</p>
166+
<div>
167+
<strong>Code examples:</strong>
168+
<p>Set the DatePicker so no weekend is selectable</p>
169+
<pre><code>
170+
$( "#datepicker" ).datepicker({
171+
beforeShowDay: $.datepicker.noWeekends
172+
});
173+
</code></pre>
174+
</div>
35175

36176
<h3>Localization</h3>
37177
<p>Datepicker provides support for localizing its content to cater for different languages and date formats. Each localization is contained within its own file with the language code appended to the name, e.g., <code>jquery.ui.datepicker-fr.js</code> for French. The desired localization file should be included after the main datepicker code. Each localization file adds its settings to the set of available localizations and automatically applies them as defaults for all instances.</p>

0 commit comments

Comments
 (0)