none
[openafs-wiki.git] / TWiki / JSCalendarContrib.mdwn
1 # <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
2
3 [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
4
5 <div>
6   <ul>
7     <li><a href="#Summary of Contents"> Summary of Contents</a></li>
8     <li><a href="#Detailed Documentation"> Detailed Documentation</a><ul>
9         <li><a href="#Settings"> Settings</a></li>
10         <li><a href="#Installation Instructions"> Installation Instructions</a></li>
11         <li><a href="#Contrib Info"> Contrib Info</a></li>
12       </ul>
13     </li>
14   </ul>
15 </div>
16
17 ## <a name="Summary of Contents"></a> Summary of Contents
18
19 This module packages the [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl) Javascript in a form suitable for use with TWiki.
20
21 ## <a name="Detailed Documentation"></a> Detailed Documentation
22
23 Read [the Mishoo documentation](http://www.dementia.org/twiki//view/doc/html/reference.html) or [visit the demo page](http://www.dementia.org/twiki//view).
24
25 This package provides a `renderFormFieldForEditHandler` that could be invoked by a plugin to ensure that forms use the [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl) for editing.
26
27 This package also includes a small Perl module to make using the calendar easier from TWiki plugins. This module includes the function:
28
29     addHEAD( $setup )
30
31 that can automatically add the required headers to the page being rendered. `$setup` is the name of the calendar setup module; it can either be ommitted, in which case the method described in the Mishoo documentation can be used to create calendars, or it can be `'twiki'`, in which case a helper function is added that simplifies using calendars to set a value in a text field. For example,
32
33         # Add styles and javascript for the calendar
34         require TWiki::Contrib::JSCalendarContrib;
35         if( $@ || !$TWiki::Contrib::JSCalendarContrib::VERSION ||
36             $TWiki::Contrib::JSCalendarContrib::VERSION < 0.961 ) {
37             TWiki::Func::writeWarning('JSCalendarContrib >=0.961 not found '.$@);
38         } else {
39             TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
40         }
41
42         $html .= CGI::textfield(
43             { name => 'datefield',
44               id => "id_datefield" });
45         $html .=
46               CGI::image_button(
47                           -name => 'datefield_calendar',
48                           -onclick =>
49                               "return showCalendar('id_datefield','%e %B %Y')",
50                           -src=> TWiki::Func::getPubUrlPath() . '/' .
51                             TWiki::Func::getTwikiWebname() .
52                                 '/JSCalendarContrib/img.gif',
53                           -alt => 'Calendar',
54                           -align => 'MIDDLE' );
55                 }
56             }
57
58 The first parameter to showCalendar is the id of the textfield. See the Mishoo documentation for details of the '$e %B %Y' parameter.
59
60 Note that the header will only be added once, regardless of the number of times that addHEAD is called.
61
62 `addHEAD` can be called from `commonTagsHandler` for adding the header to all pages, or to `beforeEditHandler` just for edit pages etc.
63
64 ### <a name="Settings"></a> Settings
65
66 - Name of the perl package
67   - Set STUB = TWiki::Contrib::JSCalendarContrib
68 - What do I do
69   - Set SHORTDESCRIPTION = [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
70
71 ### <a name="Installation Instructions"></a> Installation Instructions
72
73 - Download the archive from the Plugins web (see below)
74 - Unpack it in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
75   <tr>
76     <th bgcolor="#99CCCC"><strong> File: </strong></th>
77     <th bgcolor="#99CCCC"><strong> Description: </strong></th>
78   </tr>
79   <tr>
80     <td><code><b>data/TWiki/JSCalendarContrib.txt</b></code></td>
81     <td>   </td>
82   </tr>
83   <tr>
84     <td><code><b>lib/TWiki/Contrib/JSCalendarContrib.pm</b></code></td>
85     <td>   </td>
86   </tr>
87   <tr>
88     <td><code><b>pub/TWiki/JSCalendarContrib/twiki.js</b></code></td>
89     <td>   </td>
90   </tr>
91   <tr>
92     <td><code><b>pub/TWiki/JSCalendarContrib/bugtest-hidden-selects.html</b></code></td>
93     <td>   </td>
94   </tr>
95   <tr>
96     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue2.css</b></code></td>
97     <td>   </td>
98   </tr>
99   <tr>
100     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue.css</b></code></td>
101     <td>   </td>
102   </tr>
103   <tr>
104     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-brown.css</b></code></td>
105     <td>   </td>
106   </tr>
107   <tr>
108     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-green.css</b></code></td>
109     <td>   </td>
110   </tr>
111   <tr>
112     <td><code><b>pub/TWiki/JSCalendarContrib/calendar.js</b></code></td>
113     <td>   </td>
114   </tr>
115   <tr>
116     <td><code><b>pub/TWiki/JSCalendarContrib/calendar.php</b></code></td>
117     <td>   </td>
118   </tr>
119   <tr>
120     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup.js</b></code></td>
121     <td>   </td>
122   </tr>
123   <tr>
124     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup_stripped.js</b></code></td>
125     <td>   </td>
126   </tr>
127   <tr>
128     <td><code><b>pub/TWiki/JSCalendarContrib/calendar_stripped.js</b></code></td>
129     <td>   </td>
130   </tr>
131   <tr>
132     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-system.css</b></code></td>
133     <td>   </td>
134   </tr>
135   <tr>
136     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-tas.css</b></code></td>
137     <td>   </td>
138   </tr>
139   <tr>
140     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-1.css</b></code></td>
141     <td>   </td>
142   </tr>
143   <tr>
144     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-2.css</b></code></td>
145     <td>   </td>
146   </tr>
147   <tr>
148     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-1.css</b></code></td>
149     <td>   </td>
150   </tr>
151   <tr>
152     <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-2.css</b></code></td>
153     <td>   </td>
154   </tr>
155   <tr>
156     <td><code><b>pub/TWiki/JSCalendarContrib/ChangeLog</b></code></td>
157     <td>   </td>
158   </tr>
159   <tr>
160     <td><code><b>pub/TWiki/JSCalendarContrib/dayinfo.html</b></code></td>
161     <td>   </td>
162   </tr>
163   <tr>
164     <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/field-button.jpg</b></code></td>
165     <td>   </td>
166   </tr>
167   <tr>
168     <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.css</b></code></td>
169     <td>   </td>
170   </tr>
171   <tr>
172     <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.html</b></code></td>
173     <td>   </td>
174   </tr>
175   <tr>
176     <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference-Z-S.css</b></code></td>
177     <td>   </td>
178   </tr>
179   <tr>
180     <td><code><b>pub/TWiki/JSCalendarContrib/doc/reference.pdf</b></code></td>
181     <td>   </td>
182   </tr>
183   <tr>
184     <td><code><b>pub/TWiki/JSCalendarContrib/img.gif</b></code></td>
185     <td>   </td>
186   </tr>
187   <tr>
188     <td><code><b>pub/TWiki/JSCalendarContrib/index.html</b></code></td>
189     <td>   </td>
190   </tr>
191   <tr>
192     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-af.js</b></code></td>
193     <td>   </td>
194   </tr>
195   <tr>
196     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-al.js</b></code></td>
197     <td>   </td>
198   </tr>
199   <tr>
200     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-bg.js</b></code></td>
201     <td>   </td>
202   </tr>
203   <tr>
204     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5.js</b></code></td>
205     <td>   </td>
206   </tr>
207   <tr>
208     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5-utf8.js</b></code></td>
209     <td>   </td>
210   </tr>
211   <tr>
212     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-br.js</b></code></td>
213     <td>   </td>
214   </tr>
215   <tr>
216     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ca.js</b></code></td>
217     <td>   </td>
218   </tr>
219   <tr>
220     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-utf8.js</b></code></td>
221     <td>   </td>
222   </tr>
223   <tr>
224     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-win.js</b></code></td>
225     <td>   </td>
226   </tr>
227   <tr>
228     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-da.js</b></code></td>
229     <td>   </td>
230   </tr>
231   <tr>
232     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-de.js</b></code></td>
233     <td>   </td>
234   </tr>
235   <tr>
236     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-du.js</b></code></td>
237     <td>   </td>
238   </tr>
239   <tr>
240     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-el.js</b></code></td>
241     <td>   </td>
242   </tr>
243   <tr>
244     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-en.js</b></code></td>
245     <td>   </td>
246   </tr>
247   <tr>
248     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-es.js</b></code></td>
249     <td>   </td>
250   </tr>
251   <tr>
252     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fi.js</b></code></td>
253     <td>   </td>
254   </tr>
255   <tr>
256     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fr.js</b></code></td>
257     <td>   </td>
258   </tr>
259   <tr>
260     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-he-utf8.js</b></code></td>
261     <td>   </td>
262   </tr>
263   <tr>
264     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr.js</b></code></td>
265     <td>   </td>
266   </tr>
267   <tr>
268     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr-utf8.js</b></code></td>
269     <td>   </td>
270   </tr>
271   <tr>
272     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hu.js</b></code></td>
273     <td>   </td>
274   </tr>
275   <tr>
276     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-it.js</b></code></td>
277     <td>   </td>
278   </tr>
279   <tr>
280     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-jp.js</b></code></td>
281     <td>   </td>
282   </tr>
283   <tr>
284     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko.js</b></code></td>
285     <td>   </td>
286   </tr>
287   <tr>
288     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko-utf8.js</b></code></td>
289     <td>   </td>
290   </tr>
291   <tr>
292     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt.js</b></code></td>
293     <td>   </td>
294   </tr>
295   <tr>
296     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt-utf8.js</b></code></td>
297     <td>   </td>
298   </tr>
299   <tr>
300     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lv.js</b></code></td>
301     <td>   </td>
302   </tr>
303   <tr>
304     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-nl.js</b></code></td>
305     <td>   </td>
306   </tr>
307   <tr>
308     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-no.js</b></code></td>
309     <td>   </td>
310   </tr>
311   <tr>
312     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl.js</b></code></td>
313     <td>   </td>
314   </tr>
315   <tr>
316     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl-utf8.js</b></code></td>
317     <td>   </td>
318   </tr>
319   <tr>
320     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pt.js</b></code></td>
321     <td>   </td>
322   </tr>
323   <tr>
324     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ro.js</b></code></td>
325     <td>   </td>
326   </tr>
327   <tr>
328     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru_win_.js</b></code></td>
329     <td>   </td>
330   </tr>
331   <tr>
332     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru.js</b></code></td>
333     <td>   </td>
334   </tr>
335   <tr>
336     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-si.js</b></code></td>
337     <td>   </td>
338   </tr>
339   <tr>
340     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sk.js</b></code></td>
341     <td>   </td>
342   </tr>
343   <tr>
344     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sp.js</b></code></td>
345     <td>   </td>
346   </tr>
347   <tr>
348     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sv.js</b></code></td>
349     <td>   </td>
350   </tr>
351   <tr>
352     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-tr.js</b></code></td>
353     <td>   </td>
354   </tr>
355   <tr>
356     <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-zh.js</b></code></td>
357     <td>   </td>
358   </tr>
359   <tr>
360     <td><code><b>pub/TWiki/JSCalendarContrib/lang/cn_utf8.js</b></code></td>
361     <td>   </td>
362   </tr>
363   <tr>
364     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/active-bg.gif</b></code></td>
365     <td>   </td>
366   </tr>
367   <tr>
368     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/dark-bg.gif</b></code></td>
369     <td>   </td>
370   </tr>
371   <tr>
372     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/hover-bg.gif</b></code></td>
373     <td>   </td>
374   </tr>
375   <tr>
376     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/menuarrow.gif</b></code></td>
377     <td>   </td>
378   </tr>
379   <tr>
380     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/normal-bg.gif</b></code></td>
381     <td>   </td>
382   </tr>
383   <tr>
384     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/rowhover-bg.gif</b></code></td>
385     <td>   </td>
386   </tr>
387   <tr>
388     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/status-bg.gif</b></code></td>
389     <td>   </td>
390   </tr>
391   <tr>
392     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/theme.css</b></code></td>
393     <td>   </td>
394   </tr>
395   <tr>
396     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/title-bg.gif</b></code></td>
397     <td>   </td>
398   </tr>
399   <tr>
400     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/today-bg.gif</b></code></td>
401     <td>   </td>
402   </tr>
403   <tr>
404     <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/transparent-bg.png</b></code></td>
405     <td>   </td>
406   </tr>
407   <tr>
408     <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow.gif</b></code></td>
409     <td>   </td>
410   </tr>
411   <tr>
412     <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow2.gif</b></code></td>
413     <td>   </td>
414   </tr>
415   <tr>
416     <td><code><b>pub/TWiki/JSCalendarContrib/multiple-dates.html</b></code></td>
417     <td>   </td>
418   </tr>
419   <tr>
420     <td><code><b>pub/TWiki/JSCalendarContrib/README</b></code></td>
421     <td>   </td>
422   </tr>
423   <tr>
424     <td><code><b>pub/TWiki/JSCalendarContrib/release-notes.html</b></code></td>
425     <td>   </td>
426   </tr>
427   <tr>
428     <td><code><b>pub/TWiki/JSCalendarContrib/simple-1.html</b></code></td>
429     <td>   </td>
430   </tr>
431   <tr>
432     <td><code><b>pub/TWiki/JSCalendarContrib/simple-2.html</b></code></td>
433     <td>   </td>
434   </tr>
435   <tr>
436     <td><code><b>pub/TWiki/JSCalendarContrib/simple-3.html</b></code></td>
437     <td>   </td>
438   </tr>
439   <tr>
440     <td><code><b>pub/TWiki/JSCalendarContrib/test.php</b></code></td>
441     <td>   </td>
442   </tr>
443   <tr>
444     <td><code><b>pub/TWiki/JSCalendarContrib/test-position.html</b></code></td>
445     <td>   </td>
446   </tr>
447 </table>
448
449 - Make sure that all files are readable by the web server user
450 - An administrator can customize the appearance of the calendar by setting the following in `LocalSite.cfg`<table border="1" cellpadding="0" cellspacing="0">
451   <tr>
452     <th bgcolor="#99CCCC"><strong> Setting </strong></th>
453     <th bgcolor="#99CCCC"><strong> Default </strong></th>
454   </tr>
455   <tr>
456     <td><code>$TWiki::cfg{JSCalendarContrib}{style}</code></td>
457     <td><code>'blue'</code></td>
458   </tr>
459   <tr>
460     <td><code>$TWiki::cfg{JSCalendarContrib}{lang}</code></td>
461     <td><code>'en'</code></td>
462   </tr>
463   <tr>
464     <td><code>$TWiki::cfg{JSCalendarContrib}{format}</code></td>
465     <td><code>'%e %b %Y'</code></td>
466   </tr>
467 </table>
468
469 ### <a name="Contrib Info"></a> Contrib Info
470
471 <table border="1" cellpadding="0" cellspacing="0">
472   <tr>
473     <td align="right"> Author: </td>
474     <td> TWiki:Main/CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a></td>
475   </tr>
476   <tr>
477     <td align="right"> Version: </td>
478     <td> 11704 of the Mishoo calendar </td>
479   </tr>
480   <tr>
481     <td align="right"> Copyright ©: </td>
482     <td> See <a href="http://www.dementia.org/twiki//view/doc/html/reference.html" target="_top">the Mishoo documentation</a></td>
483   </tr>
484   <tr>
485     <td align="right"> License: </td>
486     <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
487   </tr>
488   <tr>
489     <td align="right"> Dependencies: </td>
490     <td> None </td>
491   </tr>
492   <tr>
493     <td> Change History: </td>
494     <td>   </td>
495   </tr>
496   <tr>
497     <td> 11594 </td>
498     <td> Allow format to be configured. </td>
499   </tr>
500   <tr>
501     <td> 11415 </td>
502     <td> Add a <code>renderFormFieldForEditHandler</code> so other plugins can forward to this handler to add the date field to the [[Main/TWikiForms]]. (TWiki:Main.ThomasWeigert) </td>
503   </tr>
504   <tr>
505     <td> 10247 </td>
506     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2054" rel="nofollow">Item2054</a> put the calendar at z-index 2000, way above pattern skin divs. </td>
507   </tr>
508   <tr>
509     <td> 6634 </td>
510     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item453" rel="nofollow">Item453</a> removed [[Main/EditTablePlugins]] private copy of the Mishoo JS calendar, and made sure it works with [[Main/JSCalendarContrib]]. Improved the documentation of the JSCalendar while I was there. </td>
511   </tr>
512   <tr>
513     <td> 6626 </td>
514     <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item468" rel="nofollow">Item468</a> updated docs for Dakar release </td>
515   </tr>
516   <tr>
517     <td> 5048 </td>
518     <td> Cairo readiness </td>
519   </tr>
520   <tr>
521     <td> 5039 </td>
522     <td> Split from [[Main/SharedCode]]</td>
523   </tr>
524   <tr>
525     <td align="right"> 27 Dec 2005 </td>
526     <td> updated to calendar version 1.0; set style for Safari to win2k-1 </td>
527   </tr>
528   <tr>
529     <td align="right"> 14 Aug 2004 </td>
530     <td> Separated out from [[Main/SharedCode]] module </td>
531   </tr>
532   <tr>
533     <td align="right"> Home: </td>
534     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
535   </tr>
536   <tr>
537     <td align="right"> Feedback: </td>
538     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
539   </tr>
540   <tr>
541     <td align="right"> Appraisal: </td>
542     <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
543   </tr>
544 </table>
545
546 **_Related Topics:_** [[TWikiPreferences]]