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 - 2013 Stefan Gabos

Methods

Inherited properties

Class: Zebra_Form_Control

Zebra_Form_Control::$attributes
Zebra_Form_Control::$private_attributes
Zebra_Form_Control::$rules

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::get_submitted_value()
Returns the control's value after the form is submitted.
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. // set the date's format
  8. $mydate->format('M d, Y');
  9.  
  10. // don't forget to always call this method before rendering the form
  11. if ($form->validate()) {
  12.  
  13.     // get the date in YYYY-MM-DD format so you can play with is easily
  14.     $date = $mydate->get_date();
  15.  
  16. }
  17.  
  18. // output the form using an automatically generated template
  19. $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_show_clear()

void always_show_clear ( )

Should the "Clear" button be always visible?

By default, 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.

The caption of the button can be changed in the Zebra_Form::language file.

Setting this property to TRUE will make this button visible all the time.

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 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(1, 7));
  5.  
  6. // calendar starts today and seven days after that are selectable
  7. $obj->direction(array(true, 7));
  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_date(array('1 1 2012'));
  5.  
  6. // disable all days in January 2012
  7. $obj->disabled_date(array('* 1 2012'));
  8.  
  9. // disable January 1 through 10 in 2012
  10. $obj->disabled_date(array('1-10 1 2012'));
  11.  
  12. // disable January 1 and 10 in 2012
  13. $obj->disabled_date(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_date(array('1-10,20,22,24 1-3 *'));
  18.  
  19. // disable all Saturdays and Sundays
  20. $obj->disabled_date(array('* * * 0,6'));
  21.  
  22. // disable 1st and 2nd of July 2012,
  23. // and all of August of 2012;
  24. $obj->disabled_date(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 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 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 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(20, -5).
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 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 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