/ 
HTML-GUI-0.04
River stage zero No dependents
/ HTML::GUI::widget

NAME

HTML::GUI::widget - Create and control GUI for web application

VERSION

Version 0.01

WIDGET

base class for HTML widgets

PUBLIC METHODS

new

   Parameters :
      params : hash ref : Contains the properties of the widget :
				-type : text, select, checkbox
				-value : the value of the widget
				-id : the id of the widget (mandatory)
				-display : if false, the fied has the propertie style="display:none"
				-constraints : array ref of contraints names
				-label : text associated with the fiel
				-title : title to display when the mouse cursor is over the widget
				-class : css class to associate with the widget
				-disabled : the widget is disabled or not

   Return : 
      

   Description : 
      create a new html widget.
      It can be feed with data manually or automatically with a hash.

FACTORY

instantiante any widget previously serialized

instantiate

  Create widgets from the data structure $data
	This is a class method so it should be use like this :
				HTML::GUI::widget->instantiate($myString)

  Parameters :
	  -$data : the data structure which describe the widgets 
		-$path : the path (used to name the screen objects)

	Return :
		a widget or undef if the $data is not correct

instantiateFromYAML

  Instantiante a widget from a yaml string
	This is a class method so it should be use like this :
				HTML::GUI::widget->instantiateFromYAML($myString)

	parameters :
	- $class : the className
	- $yamlString : the yaml string describing the widget
	- $path : the path (used to name the screen objects)

	returns :
	-the new widget or undef if the yaml does not describe a widget

setParent

   Return : 
				nothing

   Description : 
				set the reference to the parent of the widget in the widget tree

top

   Return : 
     the root of the widget tree or itself if the widget doesn't belong to 
		 any container

setRootDirectory

   Description : 
				Define the root Directory of the screen definitions

getRootAncestor

Description : 
   search the root of the current widget tree.

Return : 
   The root object of the current tree

getHtml

Parameters :

Return : 
   string

Description : 
   Return the html of the widget.

getId

   Return : 
				string  

   Description : 
      return the id of the widget.

getIds

   Return : 
				array

   Description : 
      return an array of the ids of the widget. 
			For simple widget, it's the same thing as getId
			but it's different for container which can have many widgets.

getTempId

Return a new widget id who is unique for the current screen.

getElementById

   Parameters :
      id : string : id of the object to find.

   Description : 
				return the widget whose id is $id or undef if no object has this id

getStyleContent

Description : 
  return the content of the html 'style' attribute
Parameters :
   style : hashref : reference to a hash containing all styles attributs ; if not defined, the function use $self->style to generate a html content

setProp

Parameters :
   params : hash ref : defines params value

Return : 
   

Description :

getProp

   Parameters :
      $propName : the name of the property we want to read

   Return : 
		   - the value of the property if it exists
			 - undef if the property doesn't exists

getDefinitionData

  This method is the miror of the "new" method it generate a data structure that defines the widget, calling the "new" function with this hash ref will create the same widget. It is usefull for serialing a widget.
  With no parameters it works for a generic widget, but it is possible to specify paramters in order to specialise the behavior for a particular class.
	The expression "definition data" means the data that are specified when calling the 'new' function. Exemple :

my $definitionData = {id => "textObject", value=> '2'};

my $textInputWidget = HTML::GUI::text->new($definitionData);

  Parameters :
		- $paramPublicProp : the hash to feed with the public properties, if undef a new hash is created
		- $paramDefaultValue : an ARRAY ref containing a list of the default values (if a propertie is set to a default value, il is not specified as a "definition data"), if undef the default values of generic widgets is used
		- $paramPublicPropList : the list of properties that can be "definition data", if undef the list of public properties of a generic widget is used 

  Return :
		- a ref to the hash that define the public properties of the widget

serializeToYAML

return a string describing the current widget in YAML format

writeToFile

  write the seralization of the current objet into the file $fileName.
	Currently, only the YAML is available, so $fileName MUST be like "*.yaml"
	Parameters :
	 - $fileName : the name of the file to write into
  returns :
	 - 1 if the operation terminates normally
	 - 0 if a problem occurs

instantiateFromFile

  Instantiate widgets from a file
	Currently, only the YAML format is available, so $fileName MUST be like "*.yaml"
	Parameters :
	 - $fileName : the name of the file to read
	 - $baseDir (optional) : the base Directory (this path is added befaor $fileName 
														to effectively locate the file on the filesystem)
  returns :
	 - the widgets object newly created if the operation terminates normally
	 - undef if a problem occurs

clone

Parameters :
   params : hash ref : params to overload the params of the current objet (changing the id is a good idea)

Return : 
   widget

Description :

error

Parameters :
   type : string : Visibility of the error (pub/priv)
   params :  hashref : params of the error
Description :
              record one error in the current objet

printTime

   Parameters :
      $time : string : a value returned by the function time
   Description :
		  return a human readable string of the date $time

dumpStack

   Parameters :
      stackName : string : name of the stack to convert to string
   Description :
		  return a human readable string of the stack $stackName

getCurrentStack

   Description :
		  return a array of the current stack

alert

   Description :
		  store an alert message in the current objet

debug

   Parameters :
      message : string : message to debug
   Description :
		  record one debug in the current objet

getLabel

   Description :
		  return the label of the current obj

getLabelHtml

   Description :
		  return the html of the label of the current obj
			If the label is a void string, return ''

METHODS FOR SUBCLASSING

PRIVATE METHODS

getPubPropHash

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

getPath

Return : 
   a string containing the actual path of the module

validate

   Description :
		  All widgets are OK by default. The input widgets have custom 
			validate function to implements constraints.

   Return : 
      always 1

getValueHash

Description : 
		Default method for all non-input and non-container widgets
Return : 
	undef

fired

	 Parameters :
		 $params : the hash ref containing the POST key-value pairs.

   Decription :
		this function aims to be specialized for buttons.

   Returns :
      - true if the current object was fired
			- false otherwise

getNodeSession

   Decription :
		 return a hash ref to the session. This is a low level API to
		 manage multiple user session in multiple windows.
		 This function MUST be refined by the choosen engine.

   Returns :
      - a hash ref to the session corresponding to the user agent cookie
			- a void hash ref if no session can be found

getSession

   Decription :
		 return a hash ref to the session corresponding to one window of the browser. If a user opens two windows of the same brower, he will need to connect two times, getSession will return two different sessions.
		 This method MUST be implemented by the engine

   Returns :
      - a hash ref to the session corresponding to the user agent cookie
			- a void hash ref if no session can be found

getFunctionFromName

Description :
		Find the function whose name is $functionName 
		If the module of the function not loaded, it will be loaded automatically.

Returns :
		- a ref to the function whose name is $functionName if it exists
		- undef if no function of this name exists

AUTHOR

Jean-Christian Hassler, <jhassler at free.fr>

BUGS

Please report any bugs or feature requests to bug-gui-libhtml-screen at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-GUI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc HTML::GUI::widget

You can also look for information at:

ACKNOWLEDGEMENTS

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.