ePortal::HTML::Dialog - A widget for generating HTML code for Dialogs.

- NAME
- SYNOPSIS
- METHODS

- `new()`
- `initialize()`
- `handle_request(%hash)`
- `isButtonPressed($button_name)`
- `dialog_start()`
- `dialog_end()`
- `row()`
- `field($field_name,%parameters)`
- `buttons()`

- DIALOG ATTRIBUTES
- AUTHOR

# NAME

ePortal::HTML::Dialog - A widget for generating HTML code for Dialogs.

# SYNOPSIS

This module is used to make a dialog windows. All drawing methods returns the HTML in scalar or array context or output it with $m->print in void context.

        # Typical example:
        &nbsp;
        <% $dlg->dialog_start( title => 'Dialog's title', width => 400) %>
        <% $dlg->field( "field1", RO => 1) %>
        <% $dlg->field( "hidden_field", hidden=>1)  %>
        <% $dlg->field( "field")  %>
        <% $dlg->row('&nbsp;') %>
        <% $dlg->buttons(delete_button => 1) %>
        <% $dlg->dialog_end %>
        <p>

        <%method onStartRequest><%perl>
            $obj = new ePortal::ThePersistent::SupportObject;
            $dlg = new ePortal::HTML::Dialog( obj => $obj);

            my $location = try {
              $dlg->handle_request( );
            } catch ePortal::Exception::DataNotValid with {
              my $E = shift;
              $session{ErrorMessage} = $E->text;
              '';
            };

            if ($dlg->isButtonPressed('ok') { ... }
            return $location if $location;
        </%perl></%method>

        %#=== @metags once =========================================================
        <%once>
        my ($dlg, $obj);
        </%once>

        %#=== @metags cleanup =========================================================
        <%cleanup>
        ($dlg, $obj) = ();
        </%cleanup>

# METHODS

## `new()`

Object contructor. Maintain the same parameters as `initialize()`. Initializes all internal attributes to their default values.

     my $d = new ePortal::HTML::Dialog( obj => $object );
     my $location = $d->handle_reqest();
     ...

## `initialize()`

Accept many parameters to configure visual representation of dialog and its internal logic.

See Dialog attributes for details.

## `handle_request(%hash)`

Responsible for handling request from dialog events. This function processes button presses, does object preservation, deletion, copying, etc.

As result it returns an URL for external redirect. It does not do redirect itself.

## `isButtonPressed($button_name)`

Checks is a button was pressed. Use this function only after call to handle_request().

button_name is one of: qw/q max min edit delete copy x ok cancel more/

## `dialog_start()`

Start a dialog. Output its caption and start <FORM> tag.

## `dialog_end()`

Output closing tags for <TABLE> and <FORM>, focus the cursor

## `row()`

Generates a row for dialog's table. Parameters are passed in two modes:

     row(text, -colspan=>2, -align=>"center", option => xxx)
     row(label, value, option => xxx)

text is shown in 2 cells colspan. label,value is shown in 2 cells. Options are passed directly to CGI module.

## `field($field_name,%parameters)`

Display an input field for an attribute of the object. Field label and it's dialog control is determined via `htmlLabel()` and `htmlField()`.

Parameters are:

- label
  Override default label

- value
  Set this value for the field

- vertical=>1
  if true then input control displayed under the label. Else result is like label : control.

- RO=>1
  `htmlValue()` is used instead of `htmlField()` to display read-only value. Read-only field also assumes hidden field too.

- hidden=>1
  make hidden field

## `buttons()`

Draw a row with a buttons. By default only 2 buttons are shown: ok_button and cancel_button. See initialize() for details.

# DIALOG ATTRIBUTES

This attributes may be used in ant call to handle_request, initialize, or any call to dialog.mc method.

- obj
  This is ThePersistent object to edit

- objid,objtype
  This attributes are set automaticaly from obj

- action,formname,multipart_form
  These attributes are form specific. Defaults:

              action = $ENV{SCRIPT_NAME}
              formname = "dialog"

  If undef passed then no FORM tags generated.

- bgcolor,color,width
  Display attributes

- title,title_popup,title_url
  The title of dialog

- align
  Align the table

- focus
  Item name to focus the cursor. Set automaticaly

- xxx_button, xxx_button_title
  A button at top of dialog. xxx may be (q edit min max x copy )

  Set xxx_button=1 to make default action or set to any URL

- yyy_button,yyy_label
  Usual buttons at bottom of dialog. yyy may be (ok cancel more delete)

  Default is ok and cancel

# AUTHOR

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