NAME

dialog.mc - Dialog contruction module.

SYNOPSIS

This Mason component replaces obsoleted ePortal::HTML::Dialog package.

dialog.mc is used to draw a dialog like windows. Some methods are used for easy creation of dialogs to edit ThePersistent objects.

Usage

 <&| /dialog.mc, parameters ... &>
  content of the dialog
 </&>

 <%method onStartRequest><%perl>
  $obj = new ePortal::Catalog;
  $m->comp('/dialog.mc:handle_request', obj => $obj);
 </%perl></%method>

Parameters

• width,align

  These parameters are passed to <table> tag.

• color,bgcolor

  Colors used

• title, title_url, title_popup, title_class

  The title of dialog

• icons

  ArrayRef to HASHes with infomation about icons to place on the right side of the title. This HASH is passed directly to img() global function.

   icons => [
      { src => '/images/image.gif',
        href => 'some.where.htm',
        title => 'alt description for icons' }
   ]

• xxx_icon

  Some of icons are known to dialog.mc. No need for them to pass image source url. Icon names are edit q copy min max x

  xxx_icon - URL for the icon

  xxx_icon_title - popup title for the icon

  where xxx is a name of icon.

METHODS

edit_dialog

This method used to construct "Edit an object" dialog with a submit form iside.

WARNING! This method generates

 <table cols="2">
  Your content here
 </table>

Parameters:

• obj

  ThePersistent object to edit.

• xxx_icon

  For predefined icons enough to pass parameter

   xxx_icon => 1

  to construct an icons with all needed parameters. Call isButtonPressed('xxx') to check what button or icon was actually clicked.

• focus

  Name of the field to be focused when dialog apeears on screen

form

Generate HTML form. See field methods for details how to generate HTML fields.

 <& /dialog.mc:form, parameters, ... &>

• formname

  Name of the form. Default is 'theForm'

• method

  Method of the form. Default is 'POST'

• action

  Action of the form. Default is $ENV{SCRIPT_NAME}

• multipart,multipart_form

  If true generate multipart form.

DIALOG FORM FIELDS

Most of dialog field creation method accepts the following parameters:

• obj

  Base ThePersistent object to be edited. The $obj object may contain some useful attributes: fieldtype, value, label, etc...

• label

  What label to attach for the field. Default is label attribute of the object.

• value

  Default value of the field. Default is value attribute of the object.

• class,align

  These parameters are applied to canvas property.

cell

Draw a cell for edit_dialog. That is is <td colspan="2">. All -xxx like parameters are passed to CGI::td() function.

label_value_row

Draw a row with two cells: label and value

• label

• value

canvas

Display content inside a canvas.

 <&| /dialog.mc:canvas, label => ..., parameters, ... &>
  dialog value
 </&>

 <canvas>
  <% optional label %>
  <% $m->content %>
 </canvas>

• label

  Optional label for content. Styled with class="dlglabel".

• canvas

  Type of canvas. May be one of the following: tr td div span none

• vertical

  Align label and content vertically. Not possible for tr canvas.

   <canvas>
    label
    content
   </canvas>

field

Discover field type with a help of fieldtype attribute of the object and call appropriate method of dialog.mc. Default field type is textfield.

This is default method to produce a dialog field. This method created a row of table

 <tr>
   <td>label:</td> <td>field</td>
 </tr>

• obj

  The object to edit.

• name,id

  Mandatory. The name of the field to generate.

hidden

/dialog.mc:hidden - generate hidden field

• name

  Name of the field

• value

  Value of the field

popup_menu

Generates list box aka popup_menu.

• values

  Array ref of values

• labels

  Hash ref of labels for values. Every HASH label is decoded with pick_lang().

• popup_menu

  Callback function. Called with the object as argument. Should return array

   ($values_array, $labels_hash)

radio_group

Generates radio button group.

• values

  Array ref of values

• labels

  Hash ref of labels for values. Every HASH label is decoded with pick_lang().

textfield

Generate text field.

• size

  Visible size of text field

• maxlength

  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

password

Generate password input field.

• size

  Visible size of text field

• maxlength

  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

textarea

Generate text area field.

• rows,cols

  Visible size of text area field

• maxlength

  Maximum length of input string

See DIALOG FORM FIELDS for other parameters.

xacl_field

Generate ACL property field.

See DIALOG FORM FIELDS for other parameters.

upload

Generate file upload field.

See DIALOG FORM FIELDS for other parameters.

yes_no

Generates list box or checkbox to input YES or NO.

checkbox

Generates checkbox tag.

date

Generates date input field.

read_only

Generate text read only field.

See DIALOG FORM FIELDS for other parameters.

buttons

Display dialog buttons.

 <& /dialog.mc:buttons, parameters, ... &>

Possible button names are: ok, cancel, more, delete, apply.

To diplay a button pass parameter xxx_button => 1

To change predefined label of a button pass parameter xxx_label => "..."

ok and cancel buttons are displayed by default.

_table3td

Internal method. Do not use it! Used to produce one row table with three cells. This is the correct way to align a table.

 td1     td2     td3

• td1

  Content of cell td1

• td2

  Content of cell td2

• td3

  Content of cell td3

• align

  Where to place "main" content. Left is td1, center is td2, right is td3.

• extra

  Extra info. Placed in opposite of main content (left or right). Not used if main content is aligned at center or none.

REQUEST HANDLING METHODS

handle_request

This the engine of dialog. Call it from onStartupRequest method for proper redirect handling.

This method does the following:

1. restore_or_throw object to edit

2. htmlSave parameters from request

3. if ok button is pressed then save the object and redirect to back_url

4. if cancel button is pressed then just redirect to back_url

• obj

  Required. The object to work on it.

• objid

  This parameter usually passed as request parameter. The ID of object to edit.

• callback_htmlSave

  Code reference. Called after SELF:htmlSave

   callback_htmlSave => sub {
    my $obj = shift;
    my $args = shift;
   }

• callback_validate

  Code reference. Called just before updating the object

   callback_validate => sub {
    my $obj = shift;
   }

• callback_aftersave

  Code reference. Called after the object has been updated or inserted.

   callback_aftersave => sub {
    my $obj = shift;
    my $args = shift;
   }

htmlSave

Safely get attributes values from request and apply them to the object with object->htmlSave2(). This method does not updates the object in database. Do it yourself.

This method does extra processing for special multipart attributes like DateTime, xacl_field, etc...

This method does not updates ID attributes.

• obj

  Object to update.

isButtonPressed

Check is a button was pressed on dialog.

Every standard dialog button named as dlgb_NAME. If no dlgb_NAME parameter exists in request then isButtonPressed('ok') returns true on dialog submit.

• button

  A button name to check.

   icons: q max min edit x
   buttons: ok cancel copy delete apply more

back_url

Calculates URL where to return (redirect) from Dialog when a button will pressed.

DATA FLOW

 handle_request()     dialog.mc     
  htmlSave()          dialog.mc      handler DateTime, xacl fields
  htmlSave2()         Support.pm     this called 
  value_from_req()    Support.pm     for each attribute to save
  value()
 update() or insert() Base.pm
  validate()

AUTHOR

Sergey Rusakov, <rusakov_sa@users.sourceforge.net>

cpanm ePortal

perl -MCPAN -e shell
install ePortal