File Coverage

blib/lib/HTML/GUI/screen.pm

Criterion	Covered	Total	%
statement	10	12	83.3
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	14	16	87.5

package HTML::GUI::screen;

use warnings;
use strict;

=head1 NAME

HTML::GUI::screen - Create and control a whole screen for web application

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

use HTML::Template;
use HTML::GUI::container;
use HTML::GUI::hidden;
use HTML::GUI::log::eventList;
use UNIVERSAL qw(isa);
our @ISA = qw(HTML::GUI::container);
use JSON;
use Log::Log4perl qw(:easy);



=head1 SCREEN

Manage a screen : it loads its definition with a YAML file and create all the widgets it contains.
It can generate javascript code to check constraints on the web page.
It can test if constraints of each widget are OK.
It can generate the HTML of each widget for use with HTML::Template.


=cut

# array of string : list of all public properties specific to a screen
my @publicPropList = qw/ path actionUrl nextScreen nextScreenParams
												nextScreenType nextScreenValues session hsession
												counter lastCounter parentScreenDesc loadNextScreen
												dialogCallBack openCallBack/;


=head1 PUBLIC METHODS

=pod

=head3 new

  create a new screen

=cut

sub new
{
  my($class,$params,$path) = @_;

	my $this = $class->SUPER::new($params);
  return undef unless defined $this;

  $this->{type} = "screen";
  $this->{dialogCallBackFunc} = undef;
  $this->{openCallBackFunc} = undef;
	#default path to a screen is '/' (root directory)
  $this->setProp({	'path'=> defined $path ? $path : '/',
                    'nextScreen' => '',
                    'nextScreenParams' => {},
                    'nextScreenValues' => {},
										'parentScreenDesc' => $params->{parentScreenDesc} || '',
                    'session' => {},
                    'hsession' => {},
										'loadNextScreen' => 0,
										'dialogCallBack' => $params->{dialogCallBack} || '',
										'openCallBack' => $params->{openCallBack} || '',
								});
  if (!$this->getProp('actionUrl')){
		#default form action
		$this->setProp({'actionUrl'=>'/'})
	}

  bless($this, $class);
}


=pod

=head3 setProp

   Description :
      specialized version of widget::setProp for managing
			functions associated with the screen

=cut
sub setProp
{
  my($self,
     $params, # hash ref : defines params value
    ) = @_;

		if (exists $params->{dialogCallBack}){
				$self->{dialogCallBackFunc} = $self->getFunctionFromName($params->{dialogCallBack});
		}
		if (exists $params->{openCallBack}){
				$self->{openCallBackFunc} = $self->getFunctionFromName($params->{openCallBack});
		}
		$self->SUPER::setProp($params);
}

=pod

=head3 getJscript

   Parameters :

   Return :
      string

   Description :
      Return the javascript code to enforce the constraints of the widgets (describe each constraint for each widget); this code must be inserted in the header of the HTML page.

=cut

sub getJscript
{
  my($self    ) = @_;
#UML_MODELER_BEGIN_PERSONAL_CODE_getJscript
#UML_MODELER_END_PERSONAL_CODE_getJscript
}

=head3 getDescriptionDataFromParams

	 Description:
			Retrieve from the http form data the data describing the current screen

   Parameters :
      params : the hash containing the params retrieve from the HTTP form submit

   Return :
      a hash ref containing the description data (screen name...)

=cut

sub getDescriptionDataFromParams
{
  my ($self,$params)=@_;

	my $descDataString = exists $params->{'GHW:screenDescription'} ?
												$params->{'GHW:screenDescription'} : '{}';

	return  JSON::decode_json($descDataString);
}

=head3 getDescriptionFieldsHtml

   Return :
      a string containing the html of the hidden fields containing usefull
			data for describing the screen (for example, the name of the screen)
			To generate a valid Html document, we insert the the hidden field into
			an invisible div.

=cut

sub getDescriptionFieldsHtml
{
	my ($self)=@_;

	#we create a JSON string that contain all the usefull data we need for this screen
	my $descDataString = JSON::encode_json({screenName => $self->getProp('path'),
																		  counter		 => $self->getProp('counter')||'0'});

	my $descField = HTML::GUI::hidden->new({id		=> 'GHW:screenDescription',
																						value	=> $descDataString  });
	if (!$descField){
		return '';
	}else{
		return $self->getHtmlTag("div",{style=>'display:none'},
								$descField->getHtml());
	}
}

=head3 getHtml

   Return :
      a string containing the html of the webpage for the screen.

=cut

sub getHtml
{
  my($self    ) = @_;
	my $filename = $self->getPath()."templates/main.html";
	my $template = HTML::Template->new(filename => $filename);
  my $eventList = HTML::GUI::log::eventList::getCurrentEventList();
  my $screenHtml = $eventList->getHtml()
					.$self->SUPER::getHtml()
					.$self->getDescriptionFieldsHtml();
  $template->param( screen => $self->getHtmlTag('form',
										{action=> $self->getProp('actionUrl'),
										 method=>'post'},
										$screenHtml),
		css_path => [{url =>"/static/css/base.css"}]	);

	return $template->output;

}

=pod

=head3 validate
   Description :
				Validate all the fields of a screen and store the result of
				the validation

   Return :
				return 1 if no field of the screen break no constraint
				return 0 if one or more field break constraint

=cut

sub validate
{
  my($self) = @_;
  my $eventList = HTML::GUI::log::eventList::getCurrentEventList();
	$eventList->forget();
	return $self->SUPER::validate();
}

=pod

=head3 getPubPropHash

   Returns :
      propHash : hash : a hash containing the value '1' pour each public propertie

=cut

my $pubPropHash = undef;
sub getPubPropHash{
 my($self    ) = @_;

 return $pubPropHash if (defined $pubPropHash);
 foreach my $propName(@publicPropList){
			$pubPropHash->{$propName} = 1;
 }
 return $pubPropHash;
}

=pod

=head3 executeAction

   Parameters :
		- $actionFunction : the function to execute
		- $session : a hash ref to the session

   Description :
				Execute the function $actionFunction with the values of the screen

   Returns :



=cut
sub executeAction{
 my($self,$actionFunction) = @_;


 if (defined $actionFunction){
		&$actionFunction($self);
 }
 return $self;
}



=pod

=head3 processHttpRequest

   Parameters :
		- $params : hash ref containing the POST data

   Description :
		- do all the stuff when a user press a buton

   Returns :
	 - the screen to display to the user ; it can be a new one if needed


=cut
sub processHttpRequest{
 my($self,$params) = @_;

		$self->setValueFromParams($params);

		my $btnFired = $self->getFiredBtn($params);
		if ($btnFired){
				my $nextScreenName = $btnFired->getProp('nextScreen');
				if ($nextScreenName){
						$self->setNextScreen($nextScreenName,undef,undef);
				}

				if ($btnFired->getProp('btnAction')){
						#We want to process data => we first validate it
						if ($self->validate()){
								#Data are OK for the GUI => call the controller
								#defined by the action button
								my $actionFunction = $btnFired->getProp('btnActionFunc');
								if ($actionFunction){
									$self->executeAction($actionFunction);
								}

						}
				}
		}
		return $self;
}

=pod

=head3 executeCallBackHandler

		Description
		 - execute the handler whose name is $handlerName on
		 the $newScreen object if the handle is defined.
		 When the handler is called, it is called with $params as parameters

=cut
sub executeCallBackHandler{
 my($self,$newScreen,$handlerName,$params) = @_;

 if ($newScreen->{$handlerName}){
		#activate the callback if it's defined
		$newScreen->{$handlerName}($newScreen,$params);
 }
}

=pod

=head3 getNextScreen

   Description :
		- determine what is the next screen to display to the user and populate it with the messages and user data

   Returns :
	 - the screen to display to the user ; it can be a new one if needed


=cut
sub getNextScreen{
 my($self) = @_;

 my $newScreen = undef;
 my $nextScreenPath = $self->getProp('nextScreen');
 my $nextScreenValues = $self->getProp('nextScreenValues');

 if ( ! $self->getProp('loadNextScreen') ){
		#we want to stay on the same screen
		return $self;
 }
 $DB::single = 1;
 if ($self->getProp('nextScreenType') eq 'closeDialog'){
		$newScreen = HTML::GUI::widget->instantiateFromYAML( $self->getProp('parentScreenDesc'));
		$self->executeCallBackHandler($newScreen,'dialogCallBackFunc',$self->getProp('nextScreenParams'));
 }else{
		$newScreen = HTML::GUI::widget->instantiateFromFile($nextScreenPath);
		$self->executeCallBackHandler($newScreen,'openCallBackFunc',$self->getProp('nextScreenParams'));
 }
 if (!$newScreen){
		$self->error("Sorry, a technical problem occured : impossible to load the next screen. Please report this issue to the support.");
		return $self;
 }
 $newScreen->setProp({counter => $self->getProp('counter')});
 if ($nextScreenValues){
		$newScreen->setValue($nextScreenValues);
 }
 if ($self->getProp('nextScreenType') eq 'openDialog'){
		$newScreen->setProp({parentScreenDesc=>$self->serializeToYAML()});
 }

 return $newScreen;
}

=pod

=head3 setNextScreen

   Parameters :
	  - $path	  : the path of the next screen
		- $params : hash ref containing the optional params to call the next screen (for example imagine the next screen is customer_info and the param is {customer_id => 254412}
		- $values : you can specify all the values you want to feed your screen (in the way you get the values from getValueHash() )

   Description :
		- determine what is the next screen to display to the user and populate it with the messages and user data

   Returns :
	 - the screen to display to the user ; it can be a new one if needed


=cut
sub setNextScreen{
 my($self,$path,$params,$values,$screenType) = @_;

  $screenType ||= 'screen';
  $self->setProp({nextScreen => $path,
								  nextScreenType => $screenType,
                  nextScreenParams => $params || {},
                  nextScreenValues => $values || {},
								  loadNextScreen		=> 1,
								});
}


=pod

=head3 openDialog

	 Description :
		- define the next dialog to show to the end user. The difference between a dialog and a screen is that a dialog can be closed (like a popup window).

   Parameters :
	  - $path	  : the path of the next screen
		- $params : hash ref containing the optional params to call the next screen (for example imagine the next screen is customer_info and the param is {customer_id => 254412}
		- $values : you can specify all the values you want to feed your screen (in the way you get the values from getValueHash() )
=cut

sub openDialog(){
 my($self,$path,$params,$values) = @_;

 $self->setNextScreen($path,$params,$values,'openDialog');
}

=pod

=head3 closeDialog

	 Description :
		- close the current dialog. MUST only be called on an dialog screen.

   Parameters :
		- $params : hash ref containing the optional params that will be used as parameters for the dialogCallBack function.

=cut
sub closeDialog(){
 my($self,$params) = @_;

 $self->setNextScreen(undef,$params,undef,'closeDialog');

}

=pod

=head3 error

   Description :
		- Specialization of the error function for all generic messages for the end user

   parameters :
		- $message : the message to display to the end user

   Returns :
	 - nothing

=cut
sub error($){
  my ($self,$message) = @_;
  $self->SUPER::error({
							  visibility => 'pub',
								'error-type' => 'business',
								'message' => $message,
								});
}

#array of properties that must be serialized
my @GHW_publicPropList = qw/parentScreenDesc dialogCallBack/;

=pod

=head3 getDefinitionData

  This method is the specialisation of the widget.pm method, refer to the widget.pm manual for more information.

=cut

sub getDefinitionData($)
{
  my ($self) = @_;

		my $publicProperties = $self->SUPER::getDefinitionData();

		return $self->SUPER::getDefinitionData($publicProperties,
														undef,\@GHW_publicPropList);
}
=head1 AUTHOR

Jean-Christian Hassler, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to
C, or through the web interface at
L.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc HTML::GUI::widget

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * RT: CPAN's request tracker

L

=item * Search CPAN

L

=back

=head1 ACKNOWLEDGEMENTS

=head1 COPYRIGHT & LICENSE

Copyright 2007 Jean-Christian Hassler, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

1; # End of HTML::GUI::screen