root/plugins/sfJQueryDateTimeFormWidgetPlugin/README

#sfJQueryDateTimePickerPlugin#

A plugin using juqery TimePicker library to provide a dropdown of time based on specification of intervals and start and stop times.

The most recent version of this plugin includes a validator class which can be used to bind value based on a datetime format. 

The version of the plugin also comes with javascript and css assets for the time picker.

## Installation ##

  * Install jQuery (http://www.jquery.com) somewhere under your web folder (preferably under web/js).

  * Install jQuery-UI (http://www.jqueryui.com) somewhere under your web folder (preferably under web/js).

  * Install Datejs (http://www.datejs.com) somewhere under your web folder (preferably under web/js).

  * Add the jQuery, timePicker, jQuery-UI and Datejs JavaScript files to the javascripts list in your application's config/view.yml file.
  
  * Add any CSS files you want to use for timePicker and datePicker, and add them to the stylesheets list in view.yml.

        [php]
        stylesheets:    [ ... , /sfJQueryDateTimeFormWidgetPlugin/css/timePicker.css, ... ]

        javascripts:    [ ... , /sfJQueryDateTimeFormWidgetPlugin/js/jquery.timePicker.js, ... ]


  * Install the plugin.
      Using symfony command line:
          ./symfony plugin:install sfJQueryTimeDateFormWidgetPlugin
      Or get the latest version from the subversion repository:
          svn co http://svn.symfony-project.com/plugins/sfJQueryTimeDateFormWidgetPlugin plugins/sfJQueryTimeDateFormWidgetPlugin

  * If you installed by subversion, activate the plugin in the config/ProjectConfiguration.class.php file (this will have already been done automatically if you used the plugin:install symfony command).

        [php]
        class ProjectConfiguration extends sfProjectConfiguration
        {
          public function setup()
          {
            ...
            $this->enablePlugins('sfJQueryTimeDateFormWidgetPlugin');
            ...
          }
        }

  * Publish the Assets.
      Using symfony command line:
          ./symfony plugin:publish-assets


## How to use ##

  * Edit a form, for example lib/form/doctrine/MyForm.class.php.  To use the date component, do something like this:

        [php]   
        $params = $this->getOption('params');

        $options = array(
                         'widget_name'=>'time',
                         'params'=>$params,
                         'default_date'=>date('Y-m-d'),
                         'default_time'=>date('h:i A')
                        );

        $this->setWidget('time',new sfJQueryDateTimeWidget($options));
        $this->setValidator('time', new sfJQueryDateTimeValidator(array('widget_name'=>'time')));


  * Clear your cache.
        ./symfony cc

  * Test your form.

## Widget Options ##

  * widget_name    (string) 
        the name of the widget
  * time_interval  (string)
        a number from one to 60 to minumize minute selection
  * params         (array)
        an array of form request data
  * default_date   (string)
        the default date for the date picker in YYYY-mm-dd 
  * default_time   (string) 
        the default time for the time picker in hh:ii AA
  * time_start_stop     (array)
        an array with two keys:
          * start  (string)
                the start time of the time picker in HH.MM
          * stop   (string)
                the stop time of the time picker in HH.MM
  * time_image     (string)
        a path to an image to display as the time picker button
       
## Validator Options ##

   * widget_name (string): The name of the widget (to retrieve specific input value)
   * date_format (string): The format to use when submitting a date with time (default to Y-m-d h:i A)
   * with_time (string): true if the validator must return a time, false otherwise
   * date_output (string): The format to use when returning a date (default to Y-m-d)
   * datetime_output (string): The format to use when returning a date with time (default to Y-m-d H:i:s)