Package: Controls

Class: Zebra_Form_Date

source file: /includes/Date.php

Class Overview

XSS_Clean
|
--Zebra_Form_Control
|
--Zebra_Form_Date

Class for date controls.

Author(s):

Copyright:

  • (c) 2006 - 2016 Stefan Gabos

Inherited methods

Class: Zebra_Form_Control

Zebra_Form_Control::change_case()
Call this method to instruct the script to force all letters typed by the user, to either uppercase or lowercase, in real-time.
Zebra_Form_Control::disable_spam_filter()
Disables the SPAM filter for the control.
Zebra_Form_Control::disable_xss_filters()
Disables XSS filtering of the control's submitted value.
Zebra_Form_Control::get_attributes()
Returns the values of requested attributes.
Zebra_Form_Control::lock()
Locks the control's value. A locked control will preserve its default value after the form is submitted even if the user altered it.
Zebra_Form_Control::reset()
Resets the control's submitted value (empties text fields, unchecks radio buttons/checkboxes, etc).
Zebra_Form_Control::set_attributes()
Sets one or more of the control's attributes.
Zebra_Form_Control::set_rule()
Sets a single or an array of validation rules for the control.
Zebra_Form_Control::_render_attributes()
Converts the array with control's attributes to valid HTML markup interpreted by the toHTML() method

Class: XSS_Clean

XSS_Clean::sanitize()
Sanitizes submitted data so that Cross Site Scripting Hacks can be prevented.

Class methods

constructor __construct()

void __construct ( string $id , [ string $default = ''] , [ array $attributes = ''] )

Adds a date control to the form.

Do not instantiate this class directly! Use the add() method instead!

The output of this control will be a textbox control with an icon to the right of it.
Clicking the icon will open an inline JavaScript date picker.

  1. // create a new form
  2. $form new Zebra_Form('my_form');
  3.  
  4. // add a date control to the form
  5. $mydate $form->add('date''my_date'date('Y-m-d'));
  6.  
  7. // you *have* to set the "date" rule
  8. $mydate->set_rule(array(
  9.     'date'  =>  array('error''Invalid date specified!'),
  10. ));
  11.  
  12. // set the date's format
  13. $mydate->format('M d, Y');
  14.  
  15. // don't forget to always call this method before rendering the form
  16. if ($form->validate()) {
  17.  
  18.     // get the date in YYYY-MM-DD format so you can play with is easily
  19.     $date $mydate->get_date();
  20.  
  21. }
  22.  
  23. // output the form using an automatically generated template
  24. $form->render();
Parameters:
string $id

Unique name to identify the control in the form.

The control's name attribute will be the same as the id attribute!

This is the name to be used when referring to the control's value in the POST/GET superglobals, after the form is submitted.

This is also the name of the variable to be used in custom template files, in order to display the control.

  1. // in a template file, in order to print the generated HTML
  2. // for a control named "my_date", one would use:
  3. echo $my_date;
string $default (Optional) Default date, formatted according to format.
array $attributes

(Optional) An array of attributes valid for input controls (size, readonly, style, etc)

Must be specified as an associative array, in the form of attribute => value.

  1. // setting the "readonly" attribute
  2. $obj $form->add(
  3.     'date',
  4.     'my_date',
  5.     '',
  6.     array(
  7.         'readonly' => 'readonly'
  8.     )
  9. );

See set_attributes() on how to set attributes, other than through the constructor.

The following attributes are automatically set when the control is created and should not be altered manually:

type, id, name, value, class

Top

method always_visible()

void always_visible ( string $element )

Should the date picker be always visible?

Setting this property to a jQuery element will result in the date picker being always visible, the indicated element acting as the date picker's container;

Note that when this property is set to TRUE, the always_show_clear() will be automatically set to TRUE.

  1. $date $form->add('date''my_date');
  2.  
  3. // an element having the ID "container"
  4. // will be the date picker's container
  5. $date->always_visible('$("#container")');
Parameters:
string $element A jQuery selector pointing to an existing element from the page to be used as the date picker's container.
Top

method container()

void container ( string $element )

Use this method to instruct the library to open a date picker inside a specific element - useful when you want the date picker to open at a specific position.

  1. $date $form->add('date''my_date');
  2.  
  3. // the date picker will open inside this element
  4. $date->container('$("#container")');
Tags:
since: 2.9.8
Parameters:
string $element

A jQuery selector pointing to an existing element from the page to be used as the date picker's container.

By default, all date pickers are placed at the end of the <body> element

Top

method custom_classes()

void custom_classes ( array $custom_classes )

Dates that should have custom classes applied to them.

  1. $date $form->add('date''my_date');
  2.  
  3. // apply "myclass1" custom class to the first day, of every month, of every year
  4. $date->custom_classes(array(
  5.     'myclass1'  =>  array('01 * *'),
  6. ));
Tags:
since: 2.9.8
Parameters:
array $custom_classes

An array in the form of

  1. array(
  2.     'myclass1'array(dates_to_apply_myclass1_to),
  3.     'myclass2'array(dates_to_apply_myclass2_to),
  4. )

...where "dates_to_apply_myclassx_to" is an array of dates in the same format as required for disabled_dates property.

Custom classes will be applied only in the day picker view and not on month/year views! Also note that the class name will have the “_disabled” suffix added if the day the class is applied to is disabled.

In order for the styles in your custom classes to be applied, make sure you are using the following syntax:

  1. .Zebra_DatePicker .dp_daypicker td.myclass1 .. }
  2. .Zebra_DatePicker .dp_daypicker td.myclass1_disabled .. }

Default is FALSE, no custom classes

Top

method default_position()

void default_position ( string $position )

The position of the date picker relative to the element it is attached to.

Note that, regardless of this setting, the date picker's position will be automatically adjusted to fit in the view port, if needed.

This property will be ignored if always_visible or container properties are set

  1. $date $form->add('date''my_date');
  2.  
  3. // the date picker will open *below* the element is attached to
  4. $date->default_position('below');
Tags:
since: 2.9.8
Parameters:
string $position

The position of the date picker relative to the element it is attached to.

Possible values are "above" and "below".

Default is "above"

Top

method direction()

void direction ( mixed $direction )

Direction of the calendar.

  1. $obj $form->add('date''mydate')
  2.  
  3. // calendar starts tomorrow and seven days after that are selectable
  4. $obj->direction(array(17));
  5.  
  6. // calendar starts today and seven days after that are selectable
  7. $obj->direction(array(true7));
  8.  
  9. // calendar starts on January 1st 2013 and has no ending date
  10. // (assuming "format" is YYYY-MM-DD)
  11. $obj->direction(array('2013-01-01'false));
  12.  
  13. // calendar ends today and starts on January 1st 2012
  14. // assuming "format" is YYYY-MM-DD)
  15. $obj->direction(array(false'2012-01-01'));
Parameters:
mixed $direction

A positive or negative integer:

  • n (a positive integer) creates a future-only calendar beginning at n days after today;
  • -n (a negative integer) creates a past-only calendar ending at n days before today;

  • if n is 0, the calendar has no restrictions.
Use boolean TRUE for a future-only calendar starting with today and use boolean FALSE for a past-only calendar ending today.

You may also set this property to an array with two elements in the following combinations:

  • first item is boolean TRUE (calendar starts today), an integer > 0 (calendar starts n days after today), or a valid date given in the format defined by the "format" attribute (calendar starts at the specified date), and the second item is boolean FALSE (the calendar has no ending date), an integer > 0 (calendar ends n days after the starting date), or a valid date given in the format defined by the "format" attribute and which occurs after the starting date (calendar ends at the specified date)
  • first item is boolean FALSE (calendar ends today), an integer < 0 (calendar ends n days before today), or a valid date given in the format defined by the "format" attribute (calendar ends at the specified date), and the second item is an integer > 0 (calendar ends n days before the ending date), or a valid date given in the format defined by the "format" attribute and which occurs before the starting date (calendar starts at the specified date)

Note that disabled_dates() will still apply!

Default is 0 (no restrictions).

Top

method disabled_dates()

void disabled_dates ( array $disabled_dates )

Disables selection of specific dates or range of dates in the calendar.

  1. $obj $form->add('date''mydate')
  2.  
  3. // disable January 1, 2012
  4. $obj->disabled_dates(array('1 1 2012'));
  5.  
  6. // disable all days in January 2012
  7. $obj->disabled_dates(array('* 1 2012'));
  8.  
  9. // disable January 1 through 10 in 2012
  10. $obj->disabled_dates(array('1-10 1 2012'));
  11.  
  12. // disable January 1 and 10 in 2012
  13. $obj->disabled_dates(array('1,10 1 2012'));
  14.  
  15. // disable 1 through 10, and then 20th, 22nd and 24th
  16. // of January through March for every year
  17. $obj->disabled_dates(array('1-10,20,22,24 1-3 *'));
  18.  
  19. // disable all Saturdays and Sundays
  20. $obj->disabled_dates(array('* * * 0,6'));
  21.  
  22. // disable 1st and 2nd of July 2012,
  23. // and all of August of 2012;
  24. $obj->disabled_dates(array('01 07 2012''02 07 2012''* 08 2012'));
Parameters:
array $disabled_dates

An array of strings representing disabled dates. Values in the string have to be in the following format: "day month year weekday" where "weekday" is optional and can be 0-6 (Saturday to Sunday); The syntax is similar to cron's syntax: the values are separated by spaces and may contain * (asterisk) - (dash) and , (comma) delimiters.

Default is FALSE, no disabled dates.

Top

method disable_zebra_datepicker()

void disable_zebra_datepicker ( )

By default, Zebra_Form relies on Zebra_DatePicker for Date controls. If you want to use a different date picker, you have to disable the built-in one by calling this method.

Make sure the language used by the custom date picker is the same as the language() of the library, or validation of the date will fail! Also, note that format, direction and disabled dates will still apply and will be taken into account when validating the date, but the other properties will be ignored as are specific to Zebra_DatePicker!

Tags:
since: 2.8.7
Top

method enabled_dates()

void enabled_dates ( array $enabled_dates )

Enables selection of specific dates or range of dates in the calendar, after dates have been previously disabled via disabled_dates().

Tags:
since: 2.9.3
Parameters:
array $enabled_dates

An array of enabled dates in the same format as required for as argument for the disabled_dates() method. To be used together with disabled_dates() by first setting "disabled_dates" to something like array('* * * *') (which will disable everything) and then setting "enabled_dates" to, say, array('* * * 0,6') to enable just weekends.

Default is FALSE, all dates are enabled (unless, specificaly disabled via disabled_dates()).

Top

method first_day_of_week()

void first_day_of_week ( integer $day )

Week's starting day.

Parameters:
integer $day

Valid values are 0 to 6, Sunday to Saturday.

Default is 1, Monday.

Top

method format()

void format ( string $format )

Sets the format of the returned date.

Parameters:
string $format

Format of the returned date.

Accepts the following characters for date formatting: d, D, j, l, N, w, S, F, m, M, n, Y, y borrowing syntax from (PHP's date function)

Note that when setting a date format without days (‘d’, ‘j’), the users will be able to select only years and months, and when setting a format without months and days (‘F’, ‘m’, ‘M’, ‘n’, ‘t’, ‘d’, ‘j’), the users will be able to select only years.

Also note that the value of the "view" property (see below) may be overridden if it is the case: a value of "days" for the "view" property makes no sense if the date format doesn’t allow the selection of days.

Default format is Y-m-d

Top

method get_date()

string get_date ( )

To be used after the form is submitted!

Returns submitted date in the YYYY-MM-DD format so that it's directly usable with a database engine or with PHP's strtotime function.

Tags:
return: Returns submitted date in the YYYY-MM-DD format, or an empty string if control was submitted with no value (empty).
Top

method header_captions()

void header_captions ( $captions $captions )

Captions in the datepicker's header, for the 3 possible views: days, months, years.

For each of the 3 views the following special characters may be used borrowing from PHP's "date" function's syntax: m, n, F, M, y and Y; any of these will be replaced at runtime with the appropriate date fragment, depending on the currently viewed date. two more special characters are also available Y1 and Y2 (upper case representing years with 4 digits, lowercase representing years with 2 digits) which represent "currently selected year - 7" and "currently selected year + 4" and which only make sense used in the "years" view.

Even though any of these special characters may be used in any of the 3 views, you should use m, n, F, M for the "days" view and y, Y, Y1, Y2, y1, y2 for the "months" and "years" view or you may get unexpected results!

Text and HTML can also be used, and will be rendered as it is, as in the example below (the library is smart enough to not replace special characters when used in words or HTML tags):

  1.     'days'      =>  'Departure:<br>F, Y',
  2.     'months'    =>  'Departure:<br>Y',
  3.     'years'     =>  'Departure:<br>Y1 - Y2'
  4. ));

Default is

  1.     'days'      =>  'F, Y',
  2.     'months'    =>  'Y',
  3.     'years'     =>  'Y1 - Y2'
  4. ));
Parameters:
$captions $captions An associative array containing captions in the datepicker's header, for the 3 possible views: days, months, years.
Top

method header_navigation()

void header_navigation ( $navigation $navigation )

Sets the HTML to be used for the previous month/next month buttons.

Parameters:
$navigation $navigation

An array with 2 elements containing the HTML to be used for the previous month/next month buttons.

Default is array('&#171;','&#187;')

Top

method icon_position()

void icon_position ( string $position )

The position of the date picker's inside the element it is attached to.

  1. $date $form->add('date''my_date');
  2.  
  3. // position the date picker's icon to the left
  4. $date->icon_position('left');
Tags:
since: 2.9.8
Parameters:
string $position

The position of the date picker's inside the element it is attached to.

Possible values are "left" and "right".

Default is "right"

Top

method inside()

void inside ( boolean $value )

Sets whether the icon for opening the datepicker should be inside or outside the element.

Parameters:
boolean $value

If set to FALSE, the icon will be placed to the right of the parent element, while if set to TRUE it will be placed to the right of the parent element, but *inside* the element itself.

Default is TRUE.

Top

method offset()

void offset ( array $value )

Sets the offset, in pixels (x, y), to shift the date picker’s position relative to the top-left of the icon that toggles the date picker.

Parameters:
array $value

An array indicating the offset, in pixels (x, y), to shift the date picker’s position relative to the top-left of the icon that toggles the date picker.

Default is array(5, -5).

Top

method open_icon_only()

void open_icon_only ( array $value )

Sets whether the date picker should be shown *only* when clicking the icon.

Parameters:
array $value

An array indicating the offset, in pixels (x, y), to shift the date picker’s position relative to the top-left of the icon that toggles the date picker.

Default is FALSE.

Top

method pair()

void pair ( string $value )

Pairs the date element with another date element from the page, so that the other date element will use the current date element’s value as starting date.

  1. // let's assume this will be the starting date
  2. $date1 $form->add('date''starting_date');
  3.  
  4. // dates are selectable in the future, starting with today
  5. $date1->direction(true);
  6.  
  7. // indicate another date element that will use this
  8. // element's value as starting date
  9. $date1->pair('ending_date');
  10.  
  11. // the other date element
  12. $date2 $form->add('date''ending_date');
  13.  
  14. // start one day after the reference date
  15. // (that is, one day after whaterver is selected in the first element)
  16. $date2->direction(1);
Parameters:
string $value

The ID of another "date" element which will use the current date element's value as starting date.

Note that the rules set in the "direction" property will still apply, only that the reference date will not be the current system date but the value selected in the current date picker.

Default is FALSE (not paired with another date picker)

Top

method readonly_element()

void readonly_element ( boolean $value )

Sets whether the element the calendar is attached to should be read-only.

Parameters:
boolean $value

The setting's value

If set to TRUE, a date can be set only through the date picker and cannot be enetered manually.

Default is TRUE.

Top

method select_other_months()

void select_other_months ( string $value )

Should days from previous and/or next month be selectable when visible?

Tags:
since: 2.9.3
Parameters:
string $value

The setting's value

Note that if set to TRUE, the value of show_other_months() will be considered TRUE regardless of the actual value!

Default is TRUE.

Top

method show_clear_date()

void show_clear_date ( [ string $value = 0] )

Should the "Clear date" button be visible?

Parameters:
string $value

The setting's value

Accepted values are:

  • 0 (zero) – the button for clearing a previously selected date is shown only if a previously selected date already exists; this means that if the input the date picker is attached to is empty, and the user selects a date for the first time, this button will not be visible; once the user picked a date and opens the date picker again, this time the button will be visible.

  • TRUE will make the button visible all the time
  • FALSE will disable the button
Default is "0" (without quotes)

Top

method show_icon()

void show_icon ( boolean $visible )

Should a calendar icon be added to the elements the plugin is attached to?

  1. $date $form->add('date''my_date');
  2.  
  3. // do not show the icon
  4. $date->show_icon(false);
Tags:
since: 2.9.8
Parameters:
boolean $visible

When set to TRUE the plugin will attach a calendar icon to the elements the plugin is attached to.

Default is TRUE

Top

method show_other_months()

void show_other_months ( [ string $value = true] )

Should days from previous and/or next month be visible?

Tags:
since: 2.9.3
Parameters:
string $value

The setting's value

Default is TRUE.

Top

method show_select_today()

void show_select_today ( [ string $value = 'Today'] )

Should the "Today" button be visible?

Tags:
since: 2.9.4
Parameters:
string $value

The setting's value

Setting this property to anything but a boolean FALSE will enable the button and will use the property's value as caption for the button; setting it to FALSE will disable the button.

Default is "Today"

Top

method show_week_number()

void show_week_number ( string $value )

Sets whether an extra column should be shown, showing the number of each week.

Parameters:
string $value

Anything other than FALSE will enable this feature, and use the given value as column title. For example, show_week_number: ‘Wk’ would enable this feature and have "Wk" as the column’s title.

Default is FALSE.

Top

method start_date()

void start_date ( date $value )

Sets a default date to start the date picker with.

Parameters:
date $value

A default date to start the date picker with,

Must be specified in the format defined by the "format" property, or it will be ignored!

Note that this value is used only if there is no value in the field the date picker is attached to!

Default is FALSE.

Top

method strict()

void strict ( boolean $value )

Sets whether default values, in the input field the date picker is attached to, be deleted if they are not valid according to direction() and/or disabled_dates().

Parameters:
boolean $value

If set to TRUE, default values, in the input field the date picker is attached to, will be deleted if they are not valid according to direction and/or disabled_dates.

Default is FALSE.

Top

method toHTML()

string toHTML ( )

Generates the control's HTML code.

This method is automatically called by the render() method!

Tags:
return: The control's HTML code
Top

method view()

void view ( string $view )

Sets how should the date picker start.

Parameters:
string $view

How should the date picker start.

Valid values are "days", "months" and "years".

Note that the date picker is always cycling days-months-years when clicking in the date picker's header, and years-months-days when selecting dates (unless one or more of the views are missing due to the date's format)

Also note that the value of the "view" property may be overridden if the date's format requires so! (i.e. "days" for the "view" property makes no sense if the date format doesn't allow the selection of days)

Default is "days".

Top

method weekend_days()

void weekend_days ( array $days )

Sets the days of the week that are to be considered as "weekend days".

Parameters:
array $days

An array of days of the week that are to be considered as "weekend days".

Valid values are 0 to 6 (Sunday to Saturday).

Default is array(0,6) (Saturday and Sunday).

Top

method zero_pad()

void zero_pad ( boolean $state )

Should day numbers < 10 be padded with zero?

Parameters:
boolean $state

When set to TRUE, day numbers < 10 will be prefixed with 0.

Default is FALSE.

Top