Overview   Class-Group   Class   Use   Tree 
P5EEx-Blue-0.01
 PREV  NEXT FRAMES   NO FRAMES  

P5EEx::Blue::Widget

NAME

P5EEx::Blue::Widget - Interface for configurable, stateful objects

SYNOPSIS

    use P5EEx::Blue::P5EE;
    $context = P5EEx::Blue::P5EE->context();
    $widget = $context->service("Widget");  # or ...
    $widget = $context->widget();

DESCRIPTION

A Widget is an object that can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

Class Group: Widget

The following classes might be a part of the Widget Class Group.

A Widget is an object that can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

A Widget is a P5EE Service, and it inherits all of the features of P5EE Services.

  * Each Widget may be identified by a unique (text) name
  * Entity Widget are kept separate from UI Widgets by naming convention
  * Widgets are accessed by requesting them by name from the Context
  * Widgets have attributes (which may be references to complex data structures)
  * Attributes of Widgets are accessed via get()/set() methods
  * get($attribute) is equivalent to $self->{$attribute} (but not set())
  * Attributes may be defaulted in the code that first accesses the Widget,
    configured in the Config file, or overridden at runtime for the
    duration of the Session

A user interface Widget also has a display() method to display the Widget on the user agent. The values that are set are stored in the user's Session, so every user Session has a unique copy of every user interface Widget.

An entity Widget is shared between all user Sessions. It maintains its state in a shared data store such as a Repository.

Class: P5EEx::Blue::Widget

A Widget Service is a means by which an object can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

 * Throws: P5EEx::Blue::Exception::Widget
 * Since:  0.01

Constructor Methods:

new()

The constructor is inherited from P5EEx::Blue::Service.

init()

The init() method is called from within the standard Service constructor. Common to all Widget initializations, is the absorption of container attributes. ``Absorbable attributes'' from the widget are copied from the container widget to the initialized widget.

    * Signature: init($named)
    * Param:     $named      {}   [in]
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    Sample Usage:
    $service->init(\%args);

Public Methods:

handle_event()

    * Signature: $handled = $self->handle_event($widget_name,$event,@args);
    * Param:     $widget_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $handled = $widget->handle_event("app.table.sort","click","up",4,20);
    $handled = $widget->handle_event("app.table","sort","down","last_name");

set_value()

    * Signature: $self->set_value($value);
    * Param:     $value          any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $widget->set_value("hello");
    $widget->set_value(43);

get_value()

    * Signature: $value = $self->get_value();
    * Param:     void
    * Return:    $value          any
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $value = $widget->get_value();

fget_value()

    * Signature: $formatted_value = $self->fget_value();
    * Signature: $formatted_value = $self->fget_value($format);
    * Param:     $format            string
    * Return:    $formatted_value   scalar
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $formatted_date = $date_widget->fget_value();  # use default format
    $formatted_date = $date_widget->fget_value("%Y-%m-%d"); # supply format

get_values()

    * Signature: $values = $self->get_values();
    * Signature: $values = $self->get_values($default);
    * Signature: $values = $self->get_values($default,$setdefault);
    * Param:     $default        any
    * Param:     $setdefault     boolean
    * Return:    $values         []
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $values = $widget->get_values();

set()

    * Signature: $self->set($attribute,$value);
    * Param:     $attribute      string
    * Param:     $value          any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $widget->set("last_name","Jones");

get()

    * Signature: $value = $self->get($attribute);
    * Signature: $value = $self->get($attribute,$default);
    * Signature: $value = $self->get($attribute,$default,$setdefault);
    * Param:     $attribut       string
    * Param:     $default        any
    * Param:     $setdefault     boolean
    * Return:    $value          any
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $last_name = $widget->get("last_name");
    $is_adult = $widget->get("adult_ind","Y");   # assume adult
    $is_adult = $widget->get("adult_ind","Y",1); # assume adult, remember

delete()

    * Signature: $self->delete($attribute);
    * Param:     $attribute      string
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $widget->delete("voter_id");

set_default()

    * Signature: $self->set_default($attribute,$default);
    * Param:     $attribute      string
    * Param:     $default        any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $widget->set_default("adult_ind","Y");

label()

    * Signature: $label = $self->label();
    * Signature: $label = $self->label($attrib);
    * Signature: $label = $self->label($attrib,$lang);
    * Param:     $widget_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    print $w->label();           # "Allez!"  (if current lang is "fr")
    print $w->label("name");     # "Jacques" (translation of alternate attribute) (if curr lang is "fr")
    print $w->label("name","en");# "Jack"    (translation of alternate attribute) (override lang is "en")
    print $w->label("","en");    # "Go!"     (default label, overridden lang of "en")
    print $w->label("","en_ca"); # "Go! eh?" (default label, overridden lang of "en_ca")

values_labels()

    * Signature: ($values, $labels) = $self->values_labels();
    * Param:     void
    * Return:    $values       []
    * Return:    $labels       {}
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    ($values, $labels) = $gender_widget->values_labels();
    # $values = [ "M", "F" ];
    # $labels = { "M" => "Male", "F" => "Female" };

labels()

    * Signature: $labels = $self->labels();
    * Signature: $labels = $self->labels($attribute);
    * Signature: $labels = $self->labels($attribute,$lang);
    * Param:     $attribute      string
    * Param:     $lang           string
    * Return:    $labels         {}
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $labels = $w->labels();
    $labels = $w->labels("names");
    $labels = $w->labels("","en");      # English
    $labels = $w->labels("","en_ca");   # Canadian English

dump()

    * Signature: $text = $self->dump();
    * Param:     void
    * Return:    $text           text
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $text = $widget->dump();

print()

    * Signature: $self->print();
    * Param:     void
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $w->print();

Public Static Methods:

format()

    * Signature: $formatted_value = $self->format($value, $type, $format);
    * Param:     $value             scalar
    * Param:     $type              string
    * Param:     $format            string
    * Return:    $formatted_value   string
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $formatted_value = $widget->format("20020127","date","%Y-%m-%d");
    $formatted_value = $widget->format("27-Jan-02","date","%Y-%m-%d");
    $formatted_value = $widget->format("01/27/2002","date","%Y-%m-%d");
    $formatted_value = P5EEx::Blue::Widget->format("01/27/2002","date","%Y-%m-%d");

A static method.

translate()

    * Signature: $translated_label = $widget->translate($label, $lang);
    * Param:     $label               string
    * Param:     $lang                string
    * Return:    $translated_label    string
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $translated_label = $widget->translate($label, $lang);
    print $w->translate("Hello","fr");     # "Bonjour"
    print $w->translate("Hello","fr_ca");  # "Bonjour, eh" (french canadian)

Translates the label into the desired language based on the dictionary which is current in the widget at the time. This dictionary is usually a reference to a global dictionary which is absorbed from the container widget.

Protected Methods:

service_type()

Returns 'Widget';

    * Signature: $service_type = P5EEx::Blue::Widget->service_type();
    * Param:     void
    * Return:    $service_type  string
    * Since:     0.01
    $service_type = $widget->service_type();

absorbable_attribs()

Returns a list of attributes which a service of this type would like to absorb from its container service. This is a *static* method. It doesn't require an instance of the class to call it.

    * Signature: $attribs = P5EEx::Blue::Service->absorbable_attribs()
    * Param:     void
    * Return:    $attribs       []
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $attribs = $widget->absorbable_attribs();
    @attribs = @{$widget->absorbable_attribs()};

ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <stephen.adkins@officevision.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.

SEE ALSO

P5EEx::Blue::Context, P5EEx::Blue::Service