lib/TWiki/Contrib/JSCalendarContrib.pm
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/lib/TWiki/Contrib/JSCalendarContrib.pm	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,188 @@
     1.4 +=begin twiki
     1.5 +
     1.6 +Read [[%ATTACHURL%/doc/html/reference.html][the Mishoo documentation]] or
     1.7 +[[%ATTACHURL%][visit the demo page]] for detailed information on using the
     1.8 +calendar widget.
     1.9 +
    1.10 +This package also includes a small Perl module to make using the calendar
    1.11 +easier from TWiki plugins. This module includes the functions:
    1.12 +
    1.13 +=cut
    1.14 +
    1.15 +package TWiki::Contrib::JSCalendarContrib;
    1.16 +
    1.17 +use strict;
    1.18 +
    1.19 +require TWiki::Func;    # The plugins API
    1.20 +
    1.21 +use vars qw( $VERSION $RELEASE $SHORTDESCRIPTION );
    1.22 +
    1.23 +$VERSION = '$Rev: 16236 (22 Jan 2008) $';
    1.24 +$RELEASE = 'TWiki-4';
    1.25 +$SHORTDESCRIPTION = "[[http://dynarch.com/mishoo/calendar.epl][Mishoo JSCalendar]], packaged for use by plugins, skins and add-ons";
    1.26 +
    1.27 +# Max width of different mishoo format components
    1.28 +my %w = (
    1.29 +    a => 3,	# abbreviated weekday name
    1.30 +    A => 9,	# full weekday name
    1.31 +    b => 3,	# abbreviated month name
    1.32 +    B => 9,	# full month name
    1.33 +    C => 2,	# century number
    1.34 +    d => 2,	# the day of the month ( 00 .. 31 )
    1.35 +    e => 2,	# the day of the month ( 0 .. 31 )
    1.36 +    H => 2,	# hour ( 00 .. 23 )
    1.37 +    I => 2,	# hour ( 01 .. 12 )
    1.38 +    j => 3,	# day of the year ( 000 .. 366 )
    1.39 +    k => 2,	# hour ( 0 .. 23 )
    1.40 +    l => 2,	# hour ( 1 .. 12 )
    1.41 +    m => 2,	# month ( 01 .. 12 )
    1.42 +    M => 2,	# minute ( 00 .. 59 )
    1.43 +    n => 1,	# a newline character
    1.44 +    p => 2,	# ``PM'' or ``AM''
    1.45 +    P => 2,	# ``pm'' or ``am''
    1.46 +    S => 2,	# second ( 00 .. 59 )
    1.47 +    s => 12,# number of seconds since Epoch
    1.48 +    t => 1,	# a tab character
    1.49 +    U => 2,	# the week number
    1.50 +    u => 1,	# the day of the week ( 1 .. 7, 1 = MON )
    1.51 +    W => 2,	# the week number
    1.52 +    w => 1,	# the day of the week ( 0 .. 6, 0 = SUN )
    1.53 +    V => 2,	# the week number
    1.54 +    y => 2,	# year without the century ( 00 .. 99 )
    1.55 +    Y => 4,	# year including the century ( ex. 1979 )
    1.56 +);
    1.57 +
    1.58 +=begin twiki
    1.59 +
    1.60 +---+++ TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \%cssClass]) -> $html
    1.61 +
    1.62 +This is the simplest way to use calendars from a plugin.
    1.63 +   * =$name= is the name of the CGI parameter for the calendar
    1.64 +     (it should be unique),
    1.65 +   * =$value= is the current value of the parameter (may be undef)
    1.66 +   * =$format= is the format to use (optional; the default is set
    1.67 +     in =configure=). The HTML returned will display a date field
    1.68 +     and a drop-down calendar.
    1.69 +   * =\%options= is an optional hash containing base options for
    1.70 +     the textfield.
    1.71 +Example:
    1.72 +<verbatim>
    1.73 +use TWiki::Contrib::JSCalendarContrib;
    1.74 +...
    1.75 +my $fromDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
    1.76 +   'from', '1 April 1999');
    1.77 +my $toDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
    1.78 +   'to', undef, '%Y');
    1.79 +</verbatim>
    1.80 +
    1.81 +=cut
    1.82 +
    1.83 +sub renderDateForEdit {
    1.84 +    my ($name, $value, $format, $options) = @_;
    1.85 +
    1.86 +    $format ||= $TWiki::cfg{JSCalendarContrib}{format} || '%e %B %Y';
    1.87 +
    1.88 +    addHEAD('twiki');
    1.89 +
    1.90 +    # Work out how wide it has to be from the format
    1.91 +    # SMELL: add a space because pattern skin default fonts on FF make the
    1.92 +    # box half a character too narrow if the exact size is used
    1.93 +    my $wide = $format.' ';
    1.94 +    $wide =~ s/(%(.))/$w{$2} ? ('_' x $w{$2}) : $1/ge;
    1.95 +    $options ||= {};
    1.96 +    $options->{name} = $name;
    1.97 +    $options->{id} = 'id_'.$name;
    1.98 +    $options->{value} = $value || '';
    1.99 +    $options->{size} ||= length($wide);
   1.100 +
   1.101 +    return CGI::textfield($options)
   1.102 +      . CGI::image_button(
   1.103 +          -name => 'img_'.$name,
   1.104 +          -onclick =>
   1.105 +            "javascript: return showCalendar('id_$name','$format')",
   1.106 +            -src=> TWiki::Func::getPubUrlPath() . '/' .
   1.107 +              TWiki::Func::getTwikiWebname() .
   1.108 +                  '/JSCalendarContrib/img.gif',
   1.109 +          -alt => 'Calendar',
   1.110 +          -align => 'middle');
   1.111 +}
   1.112 +
   1.113 +=begin twiki
   1.114 +
   1.115 +---+++ TWiki::Contrib::JSCalendarContrib::addHEAD($setup)
   1.116 +
   1.117 +This function will automatically add the headers for the calendar to the page
   1.118 +being rendered. It's intended for use when you want more control over the
   1.119 +formatting of your calendars than =renderDateForEdit= affords. =$setup= is
   1.120 +the name of
   1.121 +the calendar setup module; it can either be omitted, in which case the method
   1.122 +described in the Mishoo documentation can be used to create calendars, or it
   1.123 +can be ='twiki'=, in which case a Javascript helper function called
   1.124 +'showCalendar' is added that simplifies using calendars to set a value in a
   1.125 +text field. For example, say we wanted to display the date with the calendar
   1.126 +icon _before_ the text field, using the format =%Y %b %e=
   1.127 +<verbatim>
   1.128 +# Add styles and javascript for the calendar
   1.129 +use TWiki::Contrib::JSCalendarContrib;
   1.130 +...
   1.131 +
   1.132 +sub commonTagsHandler {
   1.133 +  ....
   1.134 +  # Enable 'showCalendar'
   1.135 +  TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
   1.136 +
   1.137 +  my $cal = CGI::image_button(
   1.138 +      -name => 'img_datefield',
   1.139 +      -onclick =>
   1.140 +       "return showCalendar('id_datefield','%Y %b %e')",
   1.141 +      -src=> TWiki::Func::getPubUrlPath() . '/' .
   1.142 +             TWiki::Func::getTwikiWebname() .
   1.143 +             '/JSCalendarContrib/img.gif',
   1.144 +      -alt => 'Calendar',
   1.145 +      -align => 'middle' )
   1.146 +    . CGI::textfield(
   1.147 +      { name => 'date', id => "id_datefield" });
   1.148 +  ....
   1.149 +}
   1.150 +</verbatim>
   1.151 +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.
   1.152 +
   1.153 +=addHEAD= can be called from =commonTagsHandler= for adding the header to all pages, or from =beforeEditHandler= just for edit pages etc.
   1.154 +
   1.155 +=cut
   1.156 +
   1.157 +sub addHEAD {
   1.158 +    my $setup = shift;
   1.159 +    $setup ||= 'calendar-setup';
   1.160 +    my $style = $TWiki::cfg{JSCalendarContrib}{style} || 'blue';
   1.161 +    my $lang = $TWiki::cfg{JSCalendarContrib}{lang} || 'en';
   1.162 +    my $base = '%PUBURLPATH%/%TWIKIWEB%/JSCalendarContrib';
   1.163 +    eval {
   1.164 +        require TWiki::Contrib::BehaviourContrib;
   1.165 +        if (defined(&TWiki::Contrib::BehaviourContrib::addHEAD)) {
   1.166 +            TWiki::Contrib::BehaviourContrib::addHEAD();
   1.167 +        } else {
   1.168 +            TWiki::Func::addToHEAD(
   1.169 +                'BEHAVIOURCONTRIB',
   1.170 +                '<script type="text/javascript" src="%PUBURLPATH%/%TWIKIWEB%/BehaviourContrib/behaviour.compressed.js"></script>');
   1.171 +        }
   1.172 +    };
   1.173 +    my $head = <<HERE;
   1.174 +<style type='text/css' media='all'>
   1.175 +  \@import url('$base/calendar-$style.css');
   1.176 +  .calendar {z-index:2000;}
   1.177 +</style>
   1.178 +<script type='text/javascript' src='$base/calendar.js'></script>
   1.179 +<script type='text/javascript' src='$base/lang/calendar-$lang.js'></script>
   1.180 +HERE
   1.181 +    TWiki::Func::addToHEAD( 'JSCALENDARCONTRIB', $head );
   1.182 +
   1.183 +    # Add the setup separately; there might be different setups required
   1.184 +    # in a single HTML page.
   1.185 +    $head = <<HERE;
   1.186 +<script type='text/javascript' src='$base/$setup.js'></script>
   1.187 +HERE
   1.188 +    TWiki::Func::addToHEAD( 'JSCALENDARCONTRIB_'.$setup, $head );
   1.189 +}
   1.190 +
   1.191 +1;