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);

  # event handler as HTML attribute is deprecated
  $url_html = format_url(url => 'http://my.host/some/long/url.html',
                         linkto => "javascript:Krang.preview('media','" . $id . "')");

  # make DOM2 event handler instead, see the behaviors
  # 'media-preview-link' and 'story-preview-link' in
  # F<htdocs/js/krang.js>
  #
  # For media
  $url_html = format_url(url   => 'http://my.host/some/long/media.html',
                         class => 'media-preview-link',
                         name  => 'media_$id');

  # For stories
  $url_html = format_url(url   => 'http://my.host/some/long/media.html',
                         class => 'story-preview-link',
                         name  => 'story_$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.

  The optional new_window parameter, when combined with the linkto parameter will open the link in a new window/tab.

• $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.