blueshoes php application framework and cms            javascript_components
[ class tree: javascript_components ] [ index: javascript_components ] [ all elements ]

Class: Bs_DatePicker

Source Location: /components/datepicker/Bs_DatePicker.class.js.php

Class Overview


JavaScript DatePicker Component.


Author(s):

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 95]
JavaScript DatePicker Component.

Lets the user type in a date or select it from a popin calendar visually. Works like the windows date utility where you set the system date.

Features:

  • IE6 and NS(Mozilla7) compliant.
  • Simulates a normal HTML-form text input field; so your form-hanling will not change.
  • Reads american (mm/dd/yyyy), european (dd.mm.yyyy) and iso (yyyy-mm-dd) dates.
  • Validates the dates, also detects things like 2003-02-29 as wrong.
  • Can work with dates from before 1970.
  • Customized GUI (Colors can be customized.)
Includes (+Dependences):

1 <script type="text/javascript" src="/_bsJavascript/core/lang/Bs_Misc.lib.js"></script>
2 <script type="text/javascript" src="/_bsJavascript/core/form/Bs_FormFieldSelect.class.js" ></script>
3 <script type="text/javascript" src="/_bsJavascript/core/components/Bs_DatePicker.class.js"></script>
4 <script type="text/javascript" src="/_bsJavascript/components/toolbar/Bs_Button.class.js"></script>

How to use:

  1. Have a look at the example (see example link below)
  2. Create a function in the HTML-header called init(). Place the javascript code that instanciates and inits this component into init().
  3. Place an 'onLoad' in your body-tag: e.g. <body onLoad="init();">
  4. In the HTML body: Place a div- or span-tag with an unique ID where you want the componet to be.
How it works:
  • [After instanciating and initializing the object]. Call the drawInto([tag id]) methode. This will search the HTML code for a tag with the given id and insert HTML- and JS- code dynamically (using DOM) to display the component and handle it.
  • This class generates a normal HTML text input field and saves the value in there. When used in a form, it will be submitted like any other HTML-form-field.
What is returned to the server:
  +------------------------+--------------------------------------------------+
  | fieldName              | string, date in format you set. e.g. "2003-12-03"|
  +------------------------+--------------------------------------------------+
  | fieldName +"_month"    | int, (month 1=jan 12=dez)  e.g. "12"             |
  +------------------------+--------------------------------------------------+
  | fieldName +"_year"     | int, (4 digit year)        e.g. "2003"           |
  +------------------------+--------------------------------------------------+

common javascript pitfalls (about date handling):

  • parseInt('09') won't return what you'd think. numbers with a 0 in front are treated as octal in javascript. use parseInt('09', 10) to specify the base 10.
  • mozilla (at least 1.2beta) returns 2 digits for pre2000 dates in Date.getYear(). example: 98 for 1998. for post2000 years it returns 3 strange digits. for 2003 it returns 103 and for 2004 it returns 104. rick says that it returns the 'years since 1900', which makes sense. i think that's bullshit. todo: check getFullYear() if that helps, but it is js1.3 :/
  • the javascript Date object has the methods getYear() to fetch the year getMonth() to fetch the month and not getDay() but getDate() to fetch the day. how stupid.
  • while the year 2003 means 2003 and the day 3 means the 3rd of the month, the month 2 does not mean february in javascript. months start at 0 (january) and end at 11 (december). very confusing.
  • in js the weekday 0 is sunday, not monday. monday is 1, tuesday is 2, ...




Tags:

copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>
example:  example not found
example:  example not found
todo:  if for example 2002-01-31 is selected, then the user switches the month using the select field to february, the date should read 2002-02-28 and not 2002-02-31.


[ Top ]


Class Variables

$dateFormat =  'iso'

[line 308]

How the date should be shown to the user and submitted to the server.

!!! DEPRECATED !!!

Possible values (default is 'iso'):

   'eu'  => dd.mm.yyyy (eg 31.12.2003)
   'us'  => mm/dd/yyyy (eg 12/31/2003)
   'iso' => yyyy-mm-dd (eg 2003-12-31)
 
If you change this value at runtime (after rendering) you have to call updateInputField() to make the change active immediatly.




Tags:

see:  Bs_DatePicker::dateToIsoDate()
access:  public
deprecated:  use internalDateFormat and displayDateFormat instead.

Type:   string


[ Top ]

$dateInputClassName =

[line 202]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$dayBgColor =  'white'

[line 188]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayBgColorActive =  '#0A246A'

[line 190]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayBgColorOver =  '#FFFFE1'

[line 192]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayClassName =

[line 206]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$dayFontColor =  'black'

[line 187]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayFontColorActive =  'white'

[line 189]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayHeaderBgColor =  '#808080'

[line 186]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayHeaderClassName =

[line 205]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$dayHeaderFontColor =  '#D4D0C8'

[line 185]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$daysEn = array('Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday')

[line 157]

The english day names.

Abbreviated forms are made by just using the first 1, 2 or 3 characters.




Tags:

see:  Bs_DatePicker::$monthLongEn
access:  public

Type:   array


[ Top ]

$daysNumChars =  2

[line 167]

The number of chars to display for the abbreviated day names.

A value of 1, 2 or 3 makes sense. 0 means all but is not recommended.




Tags:

see:  Bs_DatePicker::$daysEn
access:  public

Type:   int


[ Top ]

$dayTableAttributeString =  'width="100%" border="0" cellspacing="0" cellpadding="3"'

[line 221]

The table attributes of the day table.

By changing this you can for example add horizontal and vertical lines between the days.

Note:

  • 'bgcolor' and 'class' cannot be used here, they will be added manually,




Tags:


Type:   string


[ Top ]

$dayTableBgColor =  'white'

[line 191]

Customize look. By setting a collor code (e.g. '#D4D0C8') or collor string (e.g. 'white') you can customize the look.



Tags:

access:  public

Type:   mixed


[ Top ]

$dayTableClassName =

[line 201]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$displayDateFormat =  'iso'

[line 287]

How the date should be shown to the user.

Possible values (default is 'iso'):

   'eu'  => dd.mm.yyyy (eg 31.12.2003)
   'us'  => mm/dd/yyyy (eg 12/31/2003)
   'iso' => yyyy-mm-dd (eg 2003-12-31)
 




Tags:

var:  displayDateFormat
todo:  implement this
since:  bs4.5
see:  this.internalDateFormat
access:  public

Type:   string


[ Top ]

$fieldName =  fieldName

[line 115]

When submitting the form, you'll receive the date value under this name.

In other words you'll receive the data back to the server as if you had placed


1 <input type=text name="[the fieldName]" id="[the fieldName]" value="[the value]">

into your HTML-form.




Tags:

access:  public

Type:   string


[ Top ]

$internalDateFormat =  'iso'

[line 269]

How the date should be submitted to the server.

Possible values (default is 'iso'):

   'eu'  => dd.mm.yyyy (eg 31.12.2003)
   'us'  => mm/dd/yyyy (eg 12/31/2003)
   'iso' => yyyy-mm-dd (eg 2003-12-31)
 




Tags:

var:  internalDateFormat
todo:  implement this
since:  bs4.5
see:  this.displayDateFormat
access:  public

Type:   string


[ Top ]

$jsBaseDir =  '/_bsJavascript/'

[line 123]

the base dir to the blueshoes javascript directory.

if you don't use the framework you should change it, see the examples.




Tags:

var:  jsBaseDir
access:  public

Type:   string


[ Top ]

$monthLongEn = array('January', 'February', 'March', 'April', 'Mai', 'June', 'July', 'August', 'September', 'October', 'November', 'December')

[line 139]

The full english month names.

abbreviated forms are made by just using the first 1, 2 or 3 characters.




Tags:

var:  monthLongEn (vector)
see:  Bs_DatePicker::$daysEn
access:  public

Type:   array


[ Top ]

$monthNumChars =  0

[line 148]

The number of chars to display for the abbreviated month names (0=all).

A value of 0(=all), 2 or 3 makes sense. 1 is not recommended.




Tags:

see:  Bs_DatePicker::$monthLongEn
access:  public

Type:   int


[ Top ]

$monthSelectClassName =

[line 203]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$openByInit =  false

[line 130]

If the datePicker should be open by default.



Tags:

var:  default is false.
access:  public

Type:   bool


[ Top ]

$toggleButton =

[line 368]

instance of Bs_Button. used to open/close the calendar layer.



Tags:

since:  bs4.4
access:  public

Type:   object toggleButton


[ Top ]

$useSpinEditForYear =  (typeof(Bs_NumberField) != 'undefined')

[line 179]

if the year input field should be converted into a Bs_NumberField.

Default is true *IF* Bs_NumberField is present (by included); otherwise false. it is great fun. see the example 1 at: http://www.blueshoes.org/_bsJavascript/components/datepicker/examples/example1.html




Tags:

var:  useSpinEditForYear
since:  bs4.4
access:  public

Type:   bool


[ Top ]

$validateErrorMsgEn =  "Not a valid date: '__VALUE__'. Try again or use the date picker. Valid formats are:\nAmerican mm/dd/yyyy (eg 12/31/2003)\nEuropean dd.mm.yyyy (eg 31.12.2003)\nISO yyyy-mm-dd (eg 2003-12-31)"

[line 241]

Date validation error message in English.

The special string '__VALUE__' can be used and will be replaced with the user-supplied date.




Tags:

see:  validateErrorMsgDe
access:  public

Type:   string


[ Top ]

$width =  150

[line 232]

The width of the whole date picker box in pixel, 150 is a good value.

note that the text input field currently uses the same width (size), even if a dateInputClassName (css) is defined.




Tags:

access:  public

Type:   int


[ Top ]

$yearInputClassName =

[line 204]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.

This is more for the advanced user.




Tags:

access:  public

Type:   string


[ Top ]

$_constructor =

[line 1190]


Type:   mixed


[ Top ]



Class Methods


method convertField [line 516]

bool convertField( string fieldId)

takes an existing html form field (of type text) and upgrades it into a Bs_DatePicker field.



Tags:

return:  true on success, false on failure.
access:  public


Parameters:

string   fieldId   fieldId

[ Top ]

method dateToIsoDate [line 921]

string dateToIsoDate( string someDate)

Takes any date and converts it to iso date.

iso date:

  • yyyy-mm-dd (eg 2003-12-31)
some date:
  • european: dd.mm.yyyy (eg 31.12.2003)
  • american: mm/dd/yyyy (eg 12/31/2003)
  • iso : yyyy-mm-dd (eg 2003-12-31)
short forms:
  • the day, month and year may be shortened, so 1.12.03 would be valid. if the year is shortened then < 30 means 2000 and >= 30 means 1900. 29=>2029, 30=>1930, 31=>1931 ...
something like 31.2.2003 is not valid because the feb never has 31 days.




Tags:

return:  (iso date, see above)
throws:  bool false (if not a valid date.)
access:  public


Parameters:

string   someDate   someDate (see above)

[ Top ]

method drawInto [line 502]

bool drawInto( string tagId)

Renders the datepicker component and places it into the page.



Tags:

return:  true on success, false on failure.
access:  public


Parameters:

string   tagId   tagId id of the tag. (Use <div> or <span> to hole the ID)

[ Top ]

method getCurrentDateFormatted [line 798]

string getCurrentDateFormatted( )

Returns the current internal date formatted based on dateFormat.



Tags:

return:  (empty string if no current date.)
see:  Bs_DatePicker::$dateFormat
access:  public


[ Top ]

method getCurrentDateReadable [line 762]

string getCurrentDateReadable( )

Returns the set date in a human-readable format.

examples:

  • for post-1970 dates: "Monday, January 1st 2003"
  • for pre-1970 dates: "January 1st 1960"




Tags:

return:  (empty string if no date was set so far.)
access:  public


[ Top ]

method getNumberOfDays [line 1153]

int getNumberOfDays( int year, int month)

Tells how many days the given month has.



Tags:

return:  (28-31)
access:  public


Parameters:

int   year   year (eg 2003)
int   month   month (1=jan, 12=dec)

[ Top ]

method isLeapYear [line 1142]

bool isLeapYear( int year)

Tells if the year specified is a leap year or not.

NOTE: on't use years pre-1582.




Tags:

return:  TRUE if leapYear; FALSE otherwise
access:  public


Parameters:

int   year   year

[ Top ]

method render [line 548]

string render( bool noInputField)

renders the component and returns the generated html code.

We added this method to the public API for the advanced user. It's half-private :). This is a call for the advanced user, who would like to fetch the html- / js- that is rendered to make this component running.
The average user will normally use drawInto(), that will render and place the code into the site in one simple step.




Tags:



Parameters:

bool   noInputField   noInputField (set to true if you don't want the input field.)

[ Top ]

method resetDate [line 399]

void resetDate( )

Sets the internal date with 0 and the return field to "".

Has the same effect as setting the text form field to "" (empty string) - this is to signal that *no* date has been set.




Tags:

access:  public


[ Top ]

method seedInternalWithCurrentDate [line 465]

void seedInternalWithCurrentDate( )

Sets the internal date with todays date. this gets done if no internal date is set - so the datepicker can start somewhere.

The text form field will still remain empty.




Tags:

access:  public


[ Top ]

method setDateByChunks [line 414]

bool setDateByChunks( int year, int month, int day)

Set the date.



Tags:

return:  TRUE if date is valid; FALSE otherwise
access:  public


Parameters:

int   year   year (4 digits if you can)
int   month   month (1-12)
int   day   day (1-31)

[ Top ]

method setDateByIso [line 444]

bool setDateByIso( string isoDate)

Set the date using ISO format e.g. 2003-02-23.

To reset the date you also may set an empty string - signaling that *no* date is set.




Tags:

return:  TRUE if date is valid; FALSE otherwise
access:  public


Parameters:

string   isoDate   isoDate

[ Top ]

method setDateByJunks [line 433]

bool setDateByJunks( int year, int month, int day)

Set the date.



Tags:

return:  TRUE if date is valid; FALSE otherwise
deprecated:  because of typo 'Junks' (instead of Chunks :) use setDateByChunks() it's the same.
access:  public


Parameters:

int   year   year (4 digits if you can)
int   month   month (1-12)
int   day   day (1-31)

[ Top ]

method toggleSelector [line 1080]

void toggleSelector( )

shows/hides the date selector box.



Tags:

access:  public


[ Top ]


Documentation generated on Mon, 29 Dec 2003 22:18:18 +0100 by phpDocumentor 1.2.3