File: documentation.txt

Extended Date Class Documentation

One of the most awkward things about the Date object is that it doesn't behave like other objects. You can use it as a template to create date objects but it isn't really implemented by the browser as a JavaScript object so it doesn't follow the usual inheritance rules. Working around this limitation in order to be able to define an extended date template without actually adding methods to the Date object itself presented a challenge with this object solves. It perhaps isn't the neatest solution but it does work.

The extDate object defined below provides full features date processing. Simply include the code in your page and then define your date fields as dateobject = new extDate(); instead of dateobject = new Date(); and not only will all the regular date methods be available for you to use (with the exception of the deprecated getYear and setYear) but you will also have access to a fairly exhaustive collection of additional methods.

Properties
==========

    The only properties this object has are private and cannot be accessed from outside of the methods.

Methods
=======

All the usual methods for Dates (apart from the deprecated ones) are available as well as all of the following which have been broken up into several groups to make them easier to explain.

Update Dates and Times
----------------------

This group of methods allow you to add a specified period to a date or time. You can also subtract periods just by making the value to be added negative.

There are a number of methods that I have added to the date object to make these additions and subtractions easy. Firstly there are those that only add or subtract one part of the date or time. The purpose of these methods is obvious from their names and each takes one parameter which is a number representing the period in the units that the method names indicate.

    dateobject.addYears(num_years);
    dateobject.addMonths(num_months);
    dateobject.addDays(num_days);
    dateobject.addHours(num_hours);
    dateobject.addMinutes(num_minutes);
    dateobject.addSeconds(num_seconds);

There is also one method that allows you to update all six of these at the same time using one call and passing the six values.

    dateobject.addPeriod(num_years, num_months, num_days, num_hours, num_minutes, num_seconds);


Compare Dates and Times
-----------------------

This group of methods will make many of the date comparisons that you are likely to need a much easier prospect. In each case since we are comparing dates the parameters that these methods expect are themselves date objects. These first two compare dates anre return the number of days between them. The difference between the two is that the business day version doesn't count Saturdays and Sundays. Note that the result will be a positive number of days regardless of which of the two dates comes first.

    dateobject.dayDiff(dateobject2);
    dateobject.busDayDiff(dateobject2);

This next method is the one to use for determining someone's age on any date. Simply pass in their date of birth as the date object parameter and the function returns their age in whole years without the imprecision that some people end up with in their calculations. This method will increase their age by one only on their birthday.

    dateobject.ageLastBirthday(date_of_birth);

Another useful comparison is to be able to test if one date/time is between two other date/times and so this method takes two date objects as parameters and returns true if the value of this date object is between them and false if it isn't.

    dateobject.isBetween(dateobject1, dateobject2);


Date Formatting
---------------

The biggest part of this library deals with the extraction of information about the date/time and formatting it. The easiest way to use this part of the library is to use the format method which takes one parameter which identifies to the method what information to retrieve and what format to retrieve it in. Most of the values that go in this character string are based on those that PHP uses for its equivalent method. The differences from the PHP one relate to the fact that JavaScript has no access to information about the current timezone to which the computer is set and therefore can't actually return the timezone name. As there are a number of additional pieces of information that can be relatively easily obtained and which the PHP version leaves out, I have added those as well.

    dateobject.format(format_string);

The following characters have the specified meanings when included in the format_string.

        d Day of the month, 2 digits with leading zeros 1-31
        D A textual representation of a day, three letters Mon through Sun
        j Day of the month without leading zeros 1 to 31
        l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
        N ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
        S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
        w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
        z The day of the year (starting from 0) 0 through 365
        W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
        F A full textual representation of a month, such as January or March January through December
        m Numeric representation of a month, with leading zeros 01 through 12
        M A short textual representation of a month, three letters Jan through Dec
        n Numeric representation of a month, without leading zeros 1 through 12
        t Number of days in the given month 28 through 31
        L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
        o ISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
        Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
        y A two digit representation of a year Examples: 99 or 03
        a Lowercase Ante meridiem and Post meridiem am or pm
        A Uppercase Ante meridiem and Post meridiem AM or PM
        B Swatch Internet time 000 through 999
        g 12-hour format of an hour without leading zeros 1 through 12
        G 24-hour format of an hour without leading zeros 0 through 23
        h 12-hour format of an hour with leading zeros 01 through 12
        H 24-hour format of an hour with leading zeros 00 through 23
        i Minutes with leading zeros 00 to 59
        s Seconds, with leading zeros 00 through 59
        u Microseconds (as JavaScript only calculates milliseconds the last three digits will always be zero)
        e Timezone identifier (does nothing as JavaScript has no access to this info)
        I (capital i) Whether or not the date is in daylight saving time 1 if Daylight Saving Time, 0 otherwise.
        O Difference to Greenwich time (GMT) in hours Example: +0200
        P Difference to Greenwich time (GMT) with colon between hours and minutes Example: +02:00
        T Timezone abbreviation (does nothing as JavaScript has no access to this info)
        Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 50400
        c ISO 8601 date Example: 2004-02-12T15:19:21+00:00
        r RFC 2822 formatted date Example: Thu, 21 Dec 2000 16:01:07 +0200
        U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)

    and the following additions just for JavaScript

        X week number where weeks run Sunday to Saturday and 1st Jan is always in week 1
        x as X but with a leading zero where the week number is less than 10
        R day of year with 1st Jan = 001 (always 3 digits including leading zeroes).
        J Julian Day number
        K returns 'DST' for daylight saving time, otherwise returns 'Std'
        ^ escapes the meaning of the following character so that it will display in the string returned instead of being interpreted as above

The following methods can also be called separately when you do not need the full power of the format method.

    dateobject.tzAlign(dateobject2) // will adjust the time of dateobject2 to put it on the same timezone as dateobject
    dateobject.getSDay(); // returns day of week Saturday = 0, Friday = 6
    dateobject.getMday(); // returns day of week Monday = 0, Sunday = 6
    dateobject.getISOYear(); // returns the year in which most of the days of the current Monday to Sunday week fall ? same as format('o')
    dateobject.getISOWeek(); // gets the current week number same as format(W')
    dateobject.getJulian(); // gets the Julian day number same as format('J')
    dateobject.getMonthName(); // gets the month name same as format('F')
    dateobject.getMonthShort(); // gets month short name same as format('M')
    dateobject.getDayName(); // gets the name of the day of the week same as format('l')
    dateobject.getDayShort(); // gets day short name same as format('D')
    dateobject.getOrdinal(); // gets the ordinal same as format('S')
    dateobject.getDOY(); // gets the day of the year (1st Jan = 1)
    dateobject.getWeek(); // gets the week number same as format('X')
    dateobject.getStdTimezoneOffset(); // gets the standard timezone even if the computer is on daylight saving time (except if dst runs all year around)
    dateobject.getDST(); // true if on daylight saving time and there is at least part of the year that isn't on daylight saving time, otherwise false
    dateobject.getSwatch(); // the Swatch beat equivalent to the current time same as format('B')

The other date formatting method that this object provides is toCalendar() which will return a table node containing a complete HTML calendar for the month with the current day of the month having a class of 'today' attached. You can pass an optional function into this method and if any of the dates are clicked on then that function will be called with the year, month, and day that was selected as the first three parameters, the second and subsequent parameters passed to toCalendar will be passed through as the fourth and subsequent parameters to the callback.