NAME

Krang::Widget - interface widgets for use by Krang::CGI modules

SYNOPSIS

  use Krang::ClassLoader Widget => qw(category_chooser date_chooser decode_date);

  $chooser = category_chooser(name => 'category_id',
                              query => $query);

  $date_chooser = date_chooser(name => 'cover_date',
                               date=>$date_obj);

  $date_obj = decode_date(name => 'cover_date',
                          query => $query);

  $url_html = format_url(url => 'http://my.host/some/long/url.html',
                         linkto => "javascript:Krang.preview('media','" . $id . "')");

DESCRIPTION

This modules exports a set of generally useful CGI widgets.

INTERFACE

• $chooser_html = category_chooser(name => 'category_id', query => $query)
  
• ($chooser_interface, $chooser_html) = template_chooser(name => 'category_id', query => $query);
  
In scalar context returns a block of HTML implementing the standard Krang category chooser.

In list context returns the chooser interface (show button, clear button, display of selected element) separately.

Available parameters are as follows:

• name (required)
  
Unique name of the chooser. If you have multiple choosers on the same page then they must have different names. Must be alphanumeric.
• query (required)
  
The CGI.pm query object for this request.
• field
  
The form field which will be set to the category_id of the choosen category. Defaults to the value set for name if not set.
• site_id
  
If specified, chooser will limit selection to only this site and its descendant categories.
• onchange
  
can be set to the name of a JavaScript function that will be called when the user picks a category.
• label
  
change the label on the button which defaults to 'Choose'.
• display
  
setting to false will supress displaying the chosen category URL next to the button.
• formname
  
the name of the form in which the chooser appears. If not specified, will default to the first form in your HTML document.
• title
  
the title on the chooser window. Defaults to 'Choose a Category'.
• may_see
  
Hide categories which are hidden to the current user. Defaults to 1.
• may_edit
  
Hide categories which are read-only to the current user. Defaults to 0.
• persistkey
  
Hash key that indicates where in the session hash to look for a pre-existing value.
• allow_clear
  
Shows a button labeled 'Clear' that allows a user to undo their choice. Defaults to true.

The template for the category chooser is located in Widget/category_chooser.tmpl.

• $chooser = category_chooser_object(name => 'category_id', query => $query)
  
Creates and returns an HTML::PopupTreeSelect::Dynamic object for use with categories. This is used to create the HTML for the original widget and to dynamically supply the limbs of the tree on demand in AJAX requests.

Available parameters are as follows:

• name (required)
  
Unique name of the chooser. If you have multiple choosers on the same page then they must have different names. Must be alphanumeric.
• query (required)
  
The CGI.pm query object for this request.
• label
  
change the label on the button which defaults to 'Choose'.
• field
  
The form field which will be set to the category_id of the choosen category. Defaults to the value set for name if not set.
• site_id
  
If specified, chooser will limit selection to only this site and its descendant categories.
• title
  
the title on the chooser window. Defaults to 'Choose a Category'.
• may_see
  
Hide categories which are hidden to the current user. Defaults to 1.
• may_edit
  
Hide categories which are read-only to the current user. Defaults to 0.
• persistkey
  
Hash key that indicates where in the session hash to look for a pre-existing value.

• $chooser_html = time_chooser(name => 'time', query => $query)
  
Returns a block of HTML implementing the standard Krang time chooser. The name and query parameters are required.

Additional optional parameters are as follows:

  hour      - if set (in 24 hour format, i.e. 0-23) , chooser will
              be prepopulated with that hour.  If not set,
              will default to current hour (localtime)
              unless "nochoice" is true, in which case chooser
              will be set to blank ('Hour').

  minute    - if set, chooser will be prepopulated with that
              minute.  If not set, will default to current
              minute (from localtime) unless "nochoice" is 
              true, in which chooser will be set to blank ('Minute').

  nochoice  - if set to a true value, Hour/Minute/AM
              will be provided as default choices in the chooser.
              The value "0" will be returned if a user chooses
              the "no choice" option.

  onchange  - JavaScript code to be executed when the date is changed.

The time_chooser() implements itself in HTML via a text input with some JavaScript popup magic. The string input from the user can be retrieved via the CGI query object using the same name given during the creation of the widget.

• $date_obj = decode_time(name => 'daily_time', query => $query)
  
Reads CGI data submitted via a standard Krang time_chooser and returns 2 integers representing the hour and minute that were selected.

If decode_time() is unable to parse the time it will return 2 undef values.

Standard Krang time choosers can be created via time_chooser().

• $chooser_html = datetime_chooser(name => 'date', query => $query)
  
Returns a block of HTML implementing the standard Krang datetime chooser. The name and query parameters are required.

Additional optional parameters are as follows:

  date      - if set to a date object (Time::Piece), chooser will
              be prepopulated with that datetime.  If not set to a
              date object, will default to current date (localtime)
              unless "nochoice" is true, in which case chooser
              will be set to blank. Please note that seconds are
              ALWAYS set to '00', regardless of what seconds may
              actually be.

  nochoice  - if set to a true value, Month/Day/Year/Hour/Minute/AM
              will be provided as default choices in the chooser.
              Used in conjunction with the "date" parameter, the
              chooser may be set to default to no date.
              The value "0" will be returned if a user chooses
              the "no choice" option.

  onchange  - JavaScript code to be executed when either the date
              or time values are changed.

The datetime_chooser() implements via the date_chooser() and time_chooser(). The values input by the user can be retrieved via decode_datetime().

• $chooser_html = date_chooser(name => 'cover_date')
  
Returns a block of HTML implementing the standard Krang date chooser. The name and query parameters are required.

Additional optional parameters are as follows:

  date      - if set to a date object (L<Time::Piece> or L<DateTime>), 
              chooser will be prepopulated with that date. If not set 
              to a date object, will default to current date (localtime) 
              unless "nochoice" is true, in which case chooser will be 
              set to blank.

  nochoice  - if set to a true value, blanks will be provided
              as choices in the chooser.  Used in conjunction
              with the "date" parameter, the chooser may be
              set to default to no date.

              The value "0" will be returned if a user chooses
              the "no choice" option.

  onchange  - JavaScript code to be executed when the date value
              is changed.

The date_chooser() implements itself in HTML via a text input with a JavaScript popup calendar. The full string typed by the user can be retrieved via the CGI object, or you can retrieve a Time::Piece object via decode_date().

• $datetime_object = decode_date(name => 'cover_datetime', query => $query)
  
Reads CGI data submitted via a standard Krang datetime chooser and returns a datetime object (Time::Piece). The name and query parameters are required.

If decode_datetime() is unable to retrieve a date it will return undef.

Standard Krang datetime choosers can be created via datetime_chooser().

If 'no_time_is_end' is set to 1, then datetimes with no Hour/Min/Sec will translate to date:23:59:59 (defualt is to date:00:00:00)

• $date_obj = decode_date(name => 'cover_date', query => $query)
  
Reads CGI data submitted via a standard Krang date chooser and returns a date object (Time::Piece). The name and query parameters are required.

If decode_date() is unable to retrieve a date it will return undef.

Standard Krang date choosers can be created via date_chooser().

• $url_html = format_url(url => 'http://my.host/url.html', linkto => 'url.html', length => 15);
  
Returns a block of HTML implementing the standard Krang url display/link style. The url parameter is required.

The optional linkto parameter, if provided, will be used as the HTML ``href'' to which users are directed when they click any line in the URL. If not specified, the URL will be displayed as non-linking HTML.

The optional length parameter, if provided, will be used as number of characters after which a new line should be created. If not specified, the default length of 15 will be used.

• $chooser_html = template_chooser(name => 'category_id', query => $query)
  
• ($chooser_interface, $chooser_html) = template_chooser(name => 'category_id', query => $query);
  
In scalar context returns a block of HTML implementing the standard Krang template chooser.

In list context returns the chooser interface (show button, clear button, display of selected element) separately.

Available parameters are as follows:

• name (required)
  
Unique name of the chooser. If you have multiple choosers on the same page then they must have different names. Must be alphanumeric.
• query (required)
  
The CGI.pm query object for this request.
• field
  
The form field which will be set to the template_id of the choosen category. Defaults to the value set for name if not set.
• onchange
  
Can be set to the name of a JavaScript function that will be called when the user picks a category.
• label
  
Change the label on the button which defaults to 'Choose'.
• display
  
Setting to false will supress displaying the chosen template name next to the button.
• formname
  
The name of the form in which the chooser appears. If not specified, will default to the first form in your HTML document.
• title
  
The title on the chooser window. Defaults to 'Choose a Template'.
• persistkey
  
Hash key that indicates where in the session hash to look for a pre-existing value.

The template for the category chooser is located in Widget/template_chooser.tmpl.

• $chooser = template_chooser_object(name => 'category_id', query => $query)
  
Creates and returns an HTML::PopupTreeSelect::Dynamic object for use with templates. This is used to create the HTML for the original widget and to dynamically supply the limbs of the tree on demand in AJAX requests.

Available parameters are as follows:

• name (required)
  
Unique name of the chooser. If you have multiple choosers on the same page then they must have different names. Must be alphanumeric.
• query (required)
  
The CGI.pm query object for this request.
• label
  
Change the label on the button which defaults to 'Choose'.
• title
  
The title on the chooser window. Defaults to 'Choose a Template'.

• $values = autocomplete_values(%args)
  
Returns an arrayref of alphabetized ``words'' that begin with the given phrase, pulled from the specifed fields of the given table.

It takes the following named arguments:

• table
  
The database table to use for the lookup. This is required.
• fields
  
An array ref of field names in the database from which to fetch ``words''. This is required.
• phrase
  
The phrase typed by the user. If none is given it will be pulled from the phrase param of the query string. This is optional.
• no_split
  
By default after we find the matching entries we split them up into individual words. But sometimes it's useful to have the whole phrase returned instead. Set this flag to true to accomplish this. This is optional
• dbh
  
The database handle to use. If none is provided it will default to the normal Krang one for the current instance. This is optional.
• where
  
Any additional logic that will added the generated SQL's WHERE clause using AND.