lib/TWiki/Contrib/JSCalendarContrib.pm
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
=begin twiki
colas@0
     2
colas@0
     3
Read [[%ATTACHURL%/doc/html/reference.html][the Mishoo documentation]] or
colas@0
     4
[[%ATTACHURL%][visit the demo page]] for detailed information on using the
colas@0
     5
calendar widget.
colas@0
     6
colas@0
     7
This package also includes a small Perl module to make using the calendar
colas@0
     8
easier from TWiki plugins. This module includes the functions:
colas@0
     9
colas@0
    10
=cut
colas@0
    11
colas@0
    12
package TWiki::Contrib::JSCalendarContrib;
colas@0
    13
colas@0
    14
use strict;
colas@0
    15
colas@0
    16
require TWiki::Func;    # The plugins API
colas@0
    17
colas@0
    18
use vars qw( $VERSION $RELEASE $SHORTDESCRIPTION );
colas@0
    19
colas@0
    20
$VERSION = '$Rev: 16236 (22 Jan 2008) $';
colas@0
    21
$RELEASE = 'TWiki-4';
colas@0
    22
$SHORTDESCRIPTION = "[[http://dynarch.com/mishoo/calendar.epl][Mishoo JSCalendar]], packaged for use by plugins, skins and add-ons";
colas@0
    23
colas@0
    24
# Max width of different mishoo format components
colas@0
    25
my %w = (
colas@0
    26
    a => 3,	# abbreviated weekday name
colas@0
    27
    A => 9,	# full weekday name
colas@0
    28
    b => 3,	# abbreviated month name
colas@0
    29
    B => 9,	# full month name
colas@0
    30
    C => 2,	# century number
colas@0
    31
    d => 2,	# the day of the month ( 00 .. 31 )
colas@0
    32
    e => 2,	# the day of the month ( 0 .. 31 )
colas@0
    33
    H => 2,	# hour ( 00 .. 23 )
colas@0
    34
    I => 2,	# hour ( 01 .. 12 )
colas@0
    35
    j => 3,	# day of the year ( 000 .. 366 )
colas@0
    36
    k => 2,	# hour ( 0 .. 23 )
colas@0
    37
    l => 2,	# hour ( 1 .. 12 )
colas@0
    38
    m => 2,	# month ( 01 .. 12 )
colas@0
    39
    M => 2,	# minute ( 00 .. 59 )
colas@0
    40
    n => 1,	# a newline character
colas@0
    41
    p => 2,	# ``PM'' or ``AM''
colas@0
    42
    P => 2,	# ``pm'' or ``am''
colas@0
    43
    S => 2,	# second ( 00 .. 59 )
colas@0
    44
    s => 12,# number of seconds since Epoch
colas@0
    45
    t => 1,	# a tab character
colas@0
    46
    U => 2,	# the week number
colas@0
    47
    u => 1,	# the day of the week ( 1 .. 7, 1 = MON )
colas@0
    48
    W => 2,	# the week number
colas@0
    49
    w => 1,	# the day of the week ( 0 .. 6, 0 = SUN )
colas@0
    50
    V => 2,	# the week number
colas@0
    51
    y => 2,	# year without the century ( 00 .. 99 )
colas@0
    52
    Y => 4,	# year including the century ( ex. 1979 )
colas@0
    53
);
colas@0
    54
colas@0
    55
=begin twiki
colas@0
    56
colas@0
    57
---+++ TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \%cssClass]) -> $html
colas@0
    58
colas@0
    59
This is the simplest way to use calendars from a plugin.
colas@0
    60
   * =$name= is the name of the CGI parameter for the calendar
colas@0
    61
     (it should be unique),
colas@0
    62
   * =$value= is the current value of the parameter (may be undef)
colas@0
    63
   * =$format= is the format to use (optional; the default is set
colas@0
    64
     in =configure=). The HTML returned will display a date field
colas@0
    65
     and a drop-down calendar.
colas@0
    66
   * =\%options= is an optional hash containing base options for
colas@0
    67
     the textfield.
colas@0
    68
Example:
colas@0
    69
<verbatim>
colas@0
    70
use TWiki::Contrib::JSCalendarContrib;
colas@0
    71
...
colas@0
    72
my $fromDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
colas@0
    73
   'from', '1 April 1999');
colas@0
    74
my $toDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
colas@0
    75
   'to', undef, '%Y');
colas@0
    76
</verbatim>
colas@0
    77
colas@0
    78
=cut
colas@0
    79
colas@0
    80
sub renderDateForEdit {
colas@0
    81
    my ($name, $value, $format, $options) = @_;
colas@0
    82
colas@0
    83
    $format ||= $TWiki::cfg{JSCalendarContrib}{format} || '%e %B %Y';
colas@0
    84
colas@0
    85
    addHEAD('twiki');
colas@0
    86
colas@0
    87
    # Work out how wide it has to be from the format
colas@0
    88
    # SMELL: add a space because pattern skin default fonts on FF make the
colas@0
    89
    # box half a character too narrow if the exact size is used
colas@0
    90
    my $wide = $format.' ';
colas@0
    91
    $wide =~ s/(%(.))/$w{$2} ? ('_' x $w{$2}) : $1/ge;
colas@0
    92
    $options ||= {};
colas@0
    93
    $options->{name} = $name;
colas@0
    94
    $options->{id} = 'id_'.$name;
colas@0
    95
    $options->{value} = $value || '';
colas@0
    96
    $options->{size} ||= length($wide);
colas@0
    97
colas@0
    98
    return CGI::textfield($options)
colas@0
    99
      . CGI::image_button(
colas@0
   100
          -name => 'img_'.$name,
colas@0
   101
          -onclick =>
colas@0
   102
            "javascript: return showCalendar('id_$name','$format')",
colas@0
   103
            -src=> TWiki::Func::getPubUrlPath() . '/' .
colas@0
   104
              TWiki::Func::getTwikiWebname() .
colas@0
   105
                  '/JSCalendarContrib/img.gif',
colas@0
   106
          -alt => 'Calendar',
colas@0
   107
          -align => 'middle');
colas@0
   108
}
colas@0
   109
colas@0
   110
=begin twiki
colas@0
   111
colas@0
   112
---+++ TWiki::Contrib::JSCalendarContrib::addHEAD($setup)
colas@0
   113
colas@0
   114
This function will automatically add the headers for the calendar to the page
colas@0
   115
being rendered. It's intended for use when you want more control over the
colas@0
   116
formatting of your calendars than =renderDateForEdit= affords. =$setup= is
colas@0
   117
the name of
colas@0
   118
the calendar setup module; it can either be omitted, in which case the method
colas@0
   119
described in the Mishoo documentation can be used to create calendars, or it
colas@0
   120
can be ='twiki'=, in which case a Javascript helper function called
colas@0
   121
'showCalendar' is added that simplifies using calendars to set a value in a
colas@0
   122
text field. For example, say we wanted to display the date with the calendar
colas@0
   123
icon _before_ the text field, using the format =%Y %b %e=
colas@0
   124
<verbatim>
colas@0
   125
# Add styles and javascript for the calendar
colas@0
   126
use TWiki::Contrib::JSCalendarContrib;
colas@0
   127
...
colas@0
   128
colas@0
   129
sub commonTagsHandler {
colas@0
   130
  ....
colas@0
   131
  # Enable 'showCalendar'
colas@0
   132
  TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
colas@0
   133
colas@0
   134
  my $cal = CGI::image_button(
colas@0
   135
      -name => 'img_datefield',
colas@0
   136
      -onclick =>
colas@0
   137
       "return showCalendar('id_datefield','%Y %b %e')",
colas@0
   138
      -src=> TWiki::Func::getPubUrlPath() . '/' .
colas@0
   139
             TWiki::Func::getTwikiWebname() .
colas@0
   140
             '/JSCalendarContrib/img.gif',
colas@0
   141
      -alt => 'Calendar',
colas@0
   142
      -align => 'middle' )
colas@0
   143
    . CGI::textfield(
colas@0
   144
      { name => 'date', id => "id_datefield" });
colas@0
   145
  ....
colas@0
   146
}
colas@0
   147
</verbatim>
colas@0
   148
The first parameter to =showCalendar= is the id of the textfield, and the second parameter is the . See the Mishoo documentation for details of the '$e %B %Y' parameter.
colas@0
   149
colas@0
   150
=addHEAD= can be called from =commonTagsHandler= for adding the header to all pages, or from =beforeEditHandler= just for edit pages etc.
colas@0
   151
colas@0
   152
=cut
colas@0
   153
colas@0
   154
sub addHEAD {
colas@0
   155
    my $setup = shift;
colas@0
   156
    $setup ||= 'calendar-setup';
colas@0
   157
    my $style = $TWiki::cfg{JSCalendarContrib}{style} || 'blue';
colas@0
   158
    my $lang = $TWiki::cfg{JSCalendarContrib}{lang} || 'en';
colas@0
   159
    my $base = '%PUBURLPATH%/%TWIKIWEB%/JSCalendarContrib';
colas@0
   160
    eval {
colas@0
   161
        require TWiki::Contrib::BehaviourContrib;
colas@0
   162
        if (defined(&TWiki::Contrib::BehaviourContrib::addHEAD)) {
colas@0
   163
            TWiki::Contrib::BehaviourContrib::addHEAD();
colas@0
   164
        } else {
colas@0
   165
            TWiki::Func::addToHEAD(
colas@0
   166
                'BEHAVIOURCONTRIB',
colas@0
   167
                '<script type="text/javascript" src="%PUBURLPATH%/%TWIKIWEB%/BehaviourContrib/behaviour.compressed.js"></script>');
colas@0
   168
        }
colas@0
   169
    };
colas@0
   170
    my $head = <<HERE;
colas@0
   171
<style type='text/css' media='all'>
colas@0
   172
  \@import url('$base/calendar-$style.css');
colas@0
   173
  .calendar {z-index:2000;}
colas@0
   174
</style>
colas@0
   175
<script type='text/javascript' src='$base/calendar.js'></script>
colas@0
   176
<script type='text/javascript' src='$base/lang/calendar-$lang.js'></script>
colas@0
   177
HERE
colas@0
   178
    TWiki::Func::addToHEAD( 'JSCALENDARCONTRIB', $head );
colas@0
   179
colas@0
   180
    # Add the setup separately; there might be different setups required
colas@0
   181
    # in a single HTML page.
colas@0
   182
    $head = <<HERE;
colas@0
   183
<script type='text/javascript' src='$base/$setup.js'></script>
colas@0
   184
HERE
colas@0
   185
    TWiki::Func::addToHEAD( 'JSCALENDARCONTRIB_'.$setup, $head );
colas@0
   186
}
colas@0
   187
colas@0
   188
1;