Skip to Content

jQuery.dates documentation

Note: This documentation page will no longer be maintained. Please visit the documentation on the project site for up to date information.

Creative Commons License

This work is licensed under a Creative Commons Attribution-Share Alike 2.5 Canada License.

  Library Description:
      This library aims to add more robust date functionality to Javascript.
      The goal is to allow developers to use dates in a natural way, without 
      worrying about what format a date may be in, or the underlying math for 
      the date calculations.
  
  Credits:
      The parseDate() method is heavily based on Matt Kruse's logic within 
      his dates library.  ( http://www.mattkruse.com/javascript/date/ )
      Matt's work is licensed under the GPL.  If you use or modify the 
      parseDate routine for your own puposes, please give Matt the credit
      he is due.
      
      The date picker drawing routines are based on code found at
      http://jszen.blogspot.com/2007/03/how-to-build-simple-calendar-with.html
      I do not see any license or copyright notice there at this time 
      (I could be blind).  But this blogger deserves credit for their posting
      which lead me to the code contained herein.
      
      All other code was written from scratch by Shawn Grover, based on 
      accumulated experience with Javascript and dates.


  Usage:
      - Only two global variables are used for the routine.  The names have 
        been chosen to avoid likely name conflicts with other libraries.
      - All the code, with the exception of the two global variables and the
        jQuery plugin code is contained within a single object called "o2s".  
        This has been done to emulate a namespace and minimize name conflicts.
  
      - Include your libraries:
          
          
          
      - After the libraries are included, you have access to the functions.
       
      DATE PICKER
      ===========
        The date picker calendar will appear directly below the element it 
        is associated with.
        
        Possible Options:
            {
              //the date format to use for the selected date
              //the format string is based on the formatting function defined below
              format    : "yyyy-mm-dd",
              
              //what date should be highlight by default when the date picker
              //initially becomes visible?
              //if null or not set, defaults to the date in the text box, 
              //or the current date if the text box does not contain a date
              date      :   new Date(),
              
              //should a different form element be update
              //used when adding an anchor, image, or text that will trigger
              //the date picker, but the date should be stored somewhere else
              //once selected
              //- the referenced object must be a DOM element.
              parent    :   object
            }
          
        Samples
          
          - adding a datepicker to a textbox, with default settings:
                $("#mytextboxID").datePicker();
            
          - adding a datepicker to an anchor tag, but updating a text box
                $("#myanchorID").datePicker({parent : $("#mytextboxID")[0] });
                
      IS DATE
      =======
         Often we need to know if a string of text is a valid date.  This method
         returns true/false if the text string can be seen as a date.
         
         Usage
          o2s.isDate("datestring", formatstring);
          
          $("#mytextboxID").isDate(formatstring);
              
              **  note the jQuery .dateAdd() does not return a
              jQuery object.
              
        The formatstring parameter is optional.  It is the same type of format 
        string used in the format() and parseDate() methods below.
        
         
      DATE FORMAT
      ===========
        The date format function can be called directly via:
        
            o2s.format(date, format);
            
        OR a jQuery method is available for use with text boxes that contain a date:
        
            $("#mytextboxID").dateFormat("ddd, dd mmmm yyyy");
            
            - this will make sure the value within the textbox is formatted to the 
              desired structure, if possible.
              
        The format string uses the following tokens to determine what values to insert:

Formatting Tokens
  d     - day of month (not padded)       h     - hour, 12 hour clock (not padded)
  dd    - day of month (zero padded)      hh    - hour, 12 hour clock (zero padded)
  ddd   - day name, abbreviated           H     - hour, 24 hour clock (not padded)
  dddd  - day name, full                  HH    - hour, 24 hour clock (zero padded)
  m     - month number (not padded)       i     - minutes (not padded)
  mm    - month number (zero padded)      ii    - minutes (zero padded)
  mmm   - month name, abbreviated         s     - seconds (not padded)
  mmmm  - month name, full                ss    - seconds (zero padded)
  y     - two digit year (not padded)     a     - am / pm (lowercase)
  yy    - two digit year (zero padded)    A     - AM / PM (uppercase)
  yyyy  - four digit year                 O     - timze zone offset from GMT.  
  j     - ordinal day/julian date                 (that is a letter OH, not zero)
  jjj   - ordinal day/julian date (same as "j")
  
Prebuilt formats
  short       - "m/d/yy"              
  medium      - "mmm d yyyy"          
  long        - "mmmm d yyyy"         
  shorttime   - "m/d/yy HH:ii"        
  mediumtime  - "mmm d yyyy HH:ii"    
  longtime    - "mmmm d yyyy hh:ii:ss A O"
  iso8610     - "yyyy-mm-ddTHH:ii:ss O"
  yyyymmdd    - "yyyy-mm-dd"

        Any text in the formatting string that is not one of the tokens above,
        will be inserted into the output directly.
        
        Examples:     (assuming a date of 1 Jun 2007 15:05:30)
        
        "dddd, dd mmmm yyyy"    =>    "Friday, 01 June 2007"
        "d : mmm : yy"          =>    "1 : Jun : 07"
        "shorttime"             =>    "1/7/07 15:05"
        "hh:ii a = HH:ii"       =>    "03:05 pm = 15:05"
        
    PARSE DATE
    ==========
      The parseDate function attempts to extract a date object from an arbitrary 
      string.  A format string can be specified to facilitate a quicker check.
      If the format string is omitted, the formats found in the commonformats
      array will be tried until a valid date object is found, or the full list 
      has been completed.
      
      NOTE: It is possible for a date string to match more than one date format.
      In this event you will see odd dates appear.  Specify a format string to 
      minimize these odd behaviors, or thoroughly test the formats you are 
      expecting to make sure the desired behavior is seen.  If needed, 
      modify the commonformats array to suit your needs.
      
      The format string uses the same tokens for the format method described above.
      
      If a date object cannot be determined, a null value is returned
      
      Usage:
        standard javascript:
            var d = o2s.parseDate(date, format);
            
        jQuery
            var d = $("#mytextboxID").parseDate(format);
            
    DATE DIFF
    =========
      This function determines the quantity of a given unit between two dates.
      For instance, how many hours between now and chirstmas, how many years
      between events, how many hours from the start time to now (i.e. duration)
    
      Units:  ms  - milliseconds      d - days
              s   - seconds           w - weeks
              i   - minutes           y - years
              h   - hours
      
      Usage:  
        standard Javascript
          var d = o2s.dateDiff("unit",startdate, enddate);
          
        jQuery
          var d = $("#mytextboxID").dateDiff("unit", date);
          
          **  note the jQuery .dateDiff() does not return a
              jQuery object.
          
    DATE ADD
    ========
      This function adds a specified number of units to a date, to derive 
      a new date.  (i.e. add 3 weeks to the current date, what is the date 45 
      days after chirstmas, etc.)
    
      Units:  ms  - milliseconds      d - days
              s   - seconds           w - weeks
              i   - minutes           y - years
              h   - hours
      
      Usage:  
        standard Javascript
          var d = o2s.dateAdd("unit",qty, date);
          
        jQuery
          var d = $("#mytextboxID").dateAdd("unit", qty);
    
              **  note the jQuery .dateAdd() does not return a
              jQuery object.