sws 0.4

data/lib/sws/component.rb

@@ -0,0 +1,656 @@
+#!/usr/bin/env ruby
+
+module SWS
+
+	
+	# Represents a HTML page or its part. Probably most important class of SWS -
+	# it is used to build pages and to create reusable parts. It consists of a few
+	# files, which define the component object - Ruby class file (.rb), HTML
+	# template (.html), slot definition file (.api) and bindings file (.sws).
+	class Component
+
+		# Request object the receiver is handling
+		attr_reader :request
+		
+		# The Component up the hierarchy, eg. for SubmitButton it can be Form. For
+		# the topmost component see #page
+		attr_reader :parent
+		
+		# Array of components contained within the receiver. Opposite to #parent
+		attr_reader :subcomponents
+		
+		# Array of Slot objects defined for the receiver
+		attr_accessor :slots
+		
+		# Method of the receiver that will be called during #perform_action phase
+		attr_accessor :method_to_call
+		
+		# Component that defines bindings for the receiver. Usually parent, but not
+		# always.
+		attr_accessor :definition_component
+		
+		# Name of the receiver
+		attr_accessor :name 
+		
+		# The Request (HTTP) parameters that conform to the receiver
+		attr_accessor :parameters
+
+		# HTML tag attributes
+		attr_accessor :html_attrs
+
+		# Action subcomponents for page
+		attr_reader :action_components
+
+		# Number of requests processed by this component - necessary when handling
+		# backtracking
+		attr_reader :request_number
+	
+		# Character encoding - defaults to Application.default_encoding
+		attr_accessor :encoding
+
+		attr_accessor :tokens
+		# Cache for component filenames
+		@@component_infos = Hash.new do |hash,component|
+			hash[component] = Application.instance.get_component( component )
+		end
+
+		#List of slots synchronized with instance variables
+		@@synchronized_slots = Hash.new do |hash,component|
+			hash[component] = Array.new
+		end
+
+		# Create new Component. If you want to create new page (toplevel
+		# component), the only argument is a Request object. If you want to create
+		# another component (which you shouldn't need to), the arguments are:
+		# named of the component, Request object, parent component and slots Hash		
+		def initialize ( request, name, parent, slots )
+
+			#use this if you are creating new page (no slots, parent or name)...
+			# TODO: create child class Page
+			if ( parent == nil)
+				initialize_page( request )
+				#...and this when creating new component (but in such case Component.create is probably better)
+			else
+				initialize_component( request, name, parent, slots )
+			end
+			#common initialization for both "constructors"
+			initialize_common()
+
+		end
+	
+		
+		protected
+		def initialize_common ()
+			
+			@parameters = Hash.new
+			#TODO: reconsider if necessary - is initialized in remove_subcomponents anyway
+			#(which is always called when parsing component definition)
+			@subcomponents = Array.new
+
+		end
+	
+		
+		def initialize_page ( request = nil )		
+
+			@request = request	
+			@request_number = 0
+			@action_components = Hash.new
+			@request_subcomponents = Array.new
+			@encoding = app().default_encoding
+
+		end
+		
+	
+		def initialize_component ( request, name, parent, slots )
+			
+			@request = request
+			@slots = slots
+			@parent = parent
+			@name = name
+			
+		end
+		
+		
+		public
+	
+		# Defines a slot (symbol or name) that should be synchronized with instance
+		# variable of the same name
+		def Component.synchronize_slot ( *args )
+			args.each { |slot_name|	@@synchronized_slots[self.to_s] << slot_name.to_s }
+		end
+
+		# Returns the name of the instance variable the slot should be synchronized
+		# with or nil if it should not be synchronized
+		def synchronize_slot? ( slot_name )
+			return @@synchronized_slots[self.class.to_s].include?( slot_name.to_s )
+		end
+		
+		# Synchronizes variable with slots
+		def synchronize_slots ()
+			
+			@@synchronized_slots[self.class.to_s].each do |slot_name|
+				slot = @slots[slot_name]
+				unless slot
+					raise NameError.new( "Synchronized slot '#{slot_name}' not found in #{self}" )
+				else
+					# Slots are synchronized in Slot.value, so it's enough to call it
+					slot.value
+				end
+			end
+			
+		end
+		
+		# Returns filename for HTML template of this component
+		def template_filename ()
+			return @@component_infos[self.class.to_s].template
+		end
+	
+	
+		# Returns filename for component definition (.sws file)
+		def definition_filename () 
+			return @@component_infos[self.class.to_s].definition
+		end
+	
+
+		# Return filename for slot definition (.api file)
+		def api_filename ()
+			return @@component_infos[self.class.to_s].api
+		end
+
+	
+		# Shortcut for Application instance
+		def app ()
+			return Application.instance
+		end
+	
+	
+		# Session object accessor
+		def session ()
+			return @request.session
+		end
+	
+	
+		# Returns most top-level component
+		def page () 
+	
+			return self if ( @parent == nil )
+	
+			component = @parent
+			while ( component.parent != nil )
+				component = component.parent 				
+			end
+			return component
+			
+		end
+		
+		
+		def set_request_subcomponents ()
+			$log_sws_component.debug( "#{self.class.name} #{object_id}: Storing subcomponents for request #{@request_number}" )
+			@request_subcomponents [@request_number] = @subcomponents
+		end
+		
+		# A string to be added to URL to indicate this component will handle the
+		# request
+		def url_string
+			return "#{object_id}.#{@request_number}"
+		end
+		
+		# Return new component of that name for given request. Can be used instead
+		# of constructor if you have class_name for the component as string and
+		# not the Class object itself - this method is used for components in order
+		# to require them dynamically.
+		def Component.create ( class_name, request, name = nil, parent = nil, slots = Hash.new )
+
+			klass = @@component_infos[class_name].component_class
+
+			# TODO: why was this here?
+			#name = class_name if ( name == nil )
+			component = klass.new( request, name, parent, slots )				
+			return component
+			
+		end
+	
+	
+		# Clears subcomponents array
+		def remove_subcomponents ()	
+			@subcomponents.clear()			
+		end
+
+		# Main component procedure - performs all phases of request handling.
+		# Returns component object which will process next request
+		def process_request ( request, request_number = nil )
+			
+			# TODO: check here if backtracked and omit some initial phases if so
+			@request = request
+			$log_sws_component.debug( "Request number in process_request: #{request_number}" )
+			request_number ||= @request_number
+			$log_sws_component.debug( "#{self.class.name} #{object_id}: Subcomponents for request #{request_number}" )
+			@subcomponents = @request_subcomponents[request_number] || Array.new
+			unless request_number == @request_number
+				$log_sws_component.debug( "---------BACKTRACK from #{@request_number} to #{request_number}" )
+			end
+			@request_number += 1
+			$log_sws_component.debug( "#{self.class.name} #{object_id}: request number is now #{@request_number}" )
+			awake()
+			process_parameters()
+			new_component = perform_action() || self
+			
+			# If below is true variable new_component is used as response.
+			# It replaces standard return [SWS::Component, SWS::Response]
+			# with [SWS::Response, nil].
+			if( new_component.instance_of?( SWS::Response ) )
+				return new_component, nil
+			end
+			
+			response = Response.new( request )
+			@subcomponents = Array.new
+			new_component.create_component_tree()
+			new_component.set_request_subcomponents()
+			new_component.append_to_response( response )
+		
+			response.cookies << @request.session.to_cookie
+			response.headers["Content-type"] = "text/html;charset=#{@encoding}"
+			#response.headers["Pragma"] = "no-cache"
+			#response.headers["Expires"] = "0"
+			#response.headers["Cache-control"] = "private, no-cache, no-store, must-revalidate, max-age = 0"
+
+			sleep()
+			return new_component,response
+			
+		end
+	
+		
+		# A generic method used for per-request initialization of the component.
+		# Called at the very begining of response process handling . Default
+		# implementation does recursively nothing :) - that is, it calls the
+		# awake() method for all subcomponents and their subcomponents and
+		# their...
+		def awake ()
+			@subcomponents.each { |com| com.awake() }
+		end
+
+		
+		# A generic method used for per-request deinitialization of the component.
+		# Called at the very end of handling response process.  Default
+		# implementation does recursively nothing :) - that is, it calls the
+		# sleep() method for all subcomponents and their subcomponents and
+		# their...
+		def sleep ()
+			@subcomponents.each { |com| com.sleep() }
+		end
+	
+
+		# Takes values from request (HTTP parameters) and binds them to slots.
+		# Component to bind to is determined by splitting the parameter name. Each
+		# parameter is passed to #tokenize_binding( key, value ) method.  After
+		# processing the parameters #process_bindings() is called. 
+		def process_parameters ()
+			
+			@request.params.each do |key,value|
+				stripped_key = key.sub( /^[^.]*?\./,"" )	
+				$log_sws_component.debug( "Received key #{key}, stripped #{stripped_key} with value #{value}" )
+				tokenize_binding( stripped_key, value )
+			end
+			process_bindings()
+			
+		end
+	
+
+		# Takes parameters and binds them to slots - recursively for
+		# subcomponents. Default implementation (overriden in several Component
+		# subclasses) just calls #update_binding( key,value )
+		def process_bindings ()
+			
+			@subcomponents.each do |subcomponent|
+				subcomponent.process_bindings()
+			end
+			@parameters.each { |key,value| update_binding( key,value ) }
+			
+		end
+	
+		
+		# Updates @parameters Hash or calls the same method recursively on proper
+		# subcomponent (the name of which is determined by the parameter name to
+		# the first dot).
+		def tokenize_binding ( key,value )
+			
+			if ( md = /^([^.]*?)\.(.*)$/.match( key ) )	#contains dot - extract component name and rest of binding
+				#TODO: what if the same component is present twice in template?
+				#but probably using form elements twice is not a good idea :)
+				component = subcomponent_for_name( md[1] )
+				if ( component == nil )
+					$log_sws_component.debug( "Ignoring key #{key}, component #{self}" )
+				else
+					component.tokenize_binding( md[2],value )
+				end
+			else	#no dot - only slot name left - parameter belongs to self
+				@parameters[key] = value
+			end
+			
+		end
+	
+		
+		# Updates binding described by key to value.  Default implementation
+		# (often overriden in specific Component subclasses to perform custom
+		# initialization) just updates proper Slot value
+		def update_binding ( key, value )
+			
+			slot = @slots[key]
+			$log_sws_component.debug( "slot #{key}: binding #{slot}, component: #{self}" )
+			if slot
+				slot.value = value
+			else
+				# This happens in cases like submitting INPUT type=image in Firefox,
+				# which (besides usual name.x and name.y parameters) additionaly submits
+				# "name" parameter (without any suffix) :(. So in order to avoid
+				# exception we need to ignore the parameter. TODO: refactor the whole
+				# parameter processing logic, as this workaround introduces some
+				# overhead.
+				subcomponent = subcomponent_for_name( key )
+				if subcomponent 
+					$log_sws_component.debug( "Ignoring parameter #{key} with value #{value} as it refers directly to subcomponent of component #{self}" )
+				else
+					$log_sws_component.debug( "Ignoring bogus parameter #{key} with value #{value} for component #{self}" )
+				end
+			end
+				
+		end
+
+
+		# Returns subcomponent of the receiver for given name, or nil if not found
+		def subcomponent_for_name ( name )
+			return @subcomponents.find { |subcomponent| subcomponent.name == name }
+		end
+	
+
+		# Performs the selected action recursively on all subcomponents. This is
+		# the phase of response handling process where the topmost component can
+		# change - it is changed to the return value of first action that returns
+		# other value than nil
+		def perform_action ()
+			
+			next_page = nil
+			@subcomponents.each do |subcomponent|
+				next_page = subcomponent.perform_action()
+				$log_sws_component.debug( "PERFORM: #{next_page} for component #{subcomponent}" )
+				return next_page if ( next_page )
+			end
+			return next_page
+			
+		end
+	
+
+		# Recursively generates HTML code for all subcomponents and adds it to the
+		# Response object		
+		def append_to_response ( response )
+	
+			@subcomponents.each do |child| 
+				child.append_to_response( response )
+			end
+			
+		end
+			
+
+		# Parses template file for the receiver and uses generated token tree to
+		# create component tree. Is called even if the same component is still used
+		# after #perform_action() (but in this case it has old subcomponents removed
+		# before)
+		def create_component_tree ()
+
+			$log_sws_component.debug( "Creating component tree for #{self}" )
+
+			if ( content? )	# If the receiver is Content, expand content tokens
+				definition_component.tokens.each { |token| @parent.expand_token( token ) }
+			else
+				template_parser = TemplateParser.new( template_filename() )
+				root_tokens = template_parser.parse()
+				root_tokens.each { |token| expand_token( token ) }
+			end
+
+		end
+	
+		
+		protected
+
+		# Strongly coupled with #create_component_tree - expands a token: determines
+		# its type and creates coresponding component object
+		def expand_token ( token )
+
+			$log_sws_component.debug( "expanding #{token}, #{token.text?}, #{token.data.nil?}" )
+			
+			if ( token.comment? )
+
+				$log_sws_component.debug( "Comment: #{token.data}" )
+				# TODO: comments should be appended conditionally
+				append_text_component( token.data )
+
+			elsif ( token.text? )
+
+				$log_sws_component.debug( "Text: #{token.data}" )
+				append_text_component( token.data )
+
+			elsif ( token.tag? )
+
+				if ( token.standalone? )
+					append_text_component( token.data )
+				else
+					$log_sws_component.debug( "Tag - container" )
+					append_text_component( token.data )	# opening tag						
+					token.children.each { |child| expand_token( child ) }
+					append_text_component( "</#{token.name}>" ) # closing tag
+				end
+
+			elsif ( token.sws? )
+
+				child_component = DefinitionParser.instance.component_for_token_with_parent( token,self )
+				$log_sws_component.debug( "Added child #{child_component.name} for component #{self}" )
+				if ( child_component.container? )
+					$log_sws_component.debug( "found container component: #{token.children}" )
+					child_component.tokens = token.children
+					child_component.create_component_tree()
+				elsif ( child_component.content? )
+					$log_sws_component.debug( "found content component" )
+					child_component.create_component_tree()
+				end
+				@subcomponents << child_component
+
+			end
+			
+			$log_sws_component.debug( "closing #{token}, #{token.text?}" )
+				
+		end
+		
+
+		# Appends a TextComponent to the component tree		
+		def append_text_component ( data )
+
+			unless ( data )
+				raise( "NULL text component!!!!!!" )
+			end
+			
+			child_component = TextComponent.new( @request,nil,self,nil )
+			child_component.content = data
+			@subcomponents << child_component
+			
+		end
+
+
+		# Returns "other_tag_string" and html_attrs in form of tag attributes
+		def generic_attr_string ()
+			
+			result = ""
+			other_tag_slot = @slots["other_tag_string"]
+			if ( other_tag_slot && other_tag_slot.bound_string )
+				result << " #{other_tag_slot.value()}"
+			end
+			if ( @html_attrs )
+				@html_attrs.each_pair { |name,value| result << " #{name}=\"#{value}\"" }
+			end
+			return result
+
+		end
+
+
+		# Returns HTML tag attribute string for those parameters, which are the
+		# names of bound slots
+		def bound_slot_string ( *args )
+
+			bound_slots =  args.find_all { |slot| slot_bound?( slot ) }
+		  return bound_slots.empty? ? "" : " " + bound_slots.collect { |slot| @slots[slot].to_tag_attribute }.join( " " )
+			
+		end
+
+		public
+
+		# Returns true if Slot for given name is bound.
+		def slot_bound? ( slot_name )
+			return @slots[slot_name].bound_string != nil
+		end
+
+		
+		# Returns true if the receiver is a container component - only containers
+		# can contain a content.
+		def container? ()
+			return true
+		end
+		
+
+		# Returns true if the component is content - it will be replaced by the
+		# content of the parent component. Currently only SWS::Component::Content 
+		# return true here.
+		def content? ()
+			return false
+		end
+			
+	end
+	
+	
+	# Represents pure text - component representation of text token. Used to
+	# append text tokens from parsed tree to the Response object
+	class TextComponent < Component
+	
+		# HTML content
+		attr_accessor :content
+		
+
+		# Appends HTML content to the Response
+		def append_to_response ( response )
+			response << @content
+		end
+	
+	end
+	
+	
+	# Base class for all components being the part of a form
+	class FormElement < Component
+	
+		
+		# Returns  base name attribute of HTML tag created from names of all
+		# parents separated by '.'. Used for creating HTTP parameters containing
+		# values entered by user.
+		def element_name ()
+			
+			name = @name
+			component = @parent
+			while ( component != nil )
+				name = "#{component.name}.#{name}"
+				component = component.parent
+			end
+			return name
+	
+		end
+	
+		
+		# All form parts are not container components - they do not contains other
+		# components or HTML content
+		def container? ()
+			return false
+		end
+	
+	end
+			
+		
+	# Base class for RadioButtonList and MultipleSelectionList
+	class ListElement < FormElement
+	
+		
+		# Returns value of "list" slot
+		def list ()
+			return @slots["list"].value()
+		end
+	
+
+		# Returns value of "item" slot
+		def item ()
+			return @slots["item"].value()
+		end
+	
+		
+		def append_to_response ( response )
+			response << generate_html()
+		end
+	
+	end
+	
+	
+	# Base class for lists with multiple selections allowed: CheckBoxList and Select
+	class MultipleSelectionList < ListElement
+	
+
+		# Returns value of "selections" slot or empty Array instead of nil
+		def selections ()
+			@selections ||= (@slots["selections"].value() || Array.new )
+			return @selections
+		end
+	
+
+		# Sets the value of the "selections" slot
+		def selections= ( selections )
+			
+			if ( selections == nil ) 
+				
+				@slots["selections"].value = []
+				
+			elsif ( selections.is_a?( Array ) )
+				
+				#in the selections array we have indices of elements in "list" array
+				selected = selections.collect { |sel| list[sel.to_i] }
+				@slots["selections"].value = selected
+				
+			else #single value - create an Array containing it
+				
+				if ( selections == "__empty_string" )
+					@slots["selections"].value = nil
+				else
+					@slots["selections"].value = [ list[selections.to_i] ]
+				end
+				
+			end
+			
+		end
+		
+				
+		#		#if ( selections == nil ) #nothing is selected - return empty array
+		#		#@slots["selections"].value = Array.new()
+		#		#else
+		#			#WARNING: selections will be an Array if multiple and a single object if not
+		#			selected = Array.new()
+		#			#if we have single selection, make it an Array
+		#			selections = [selections] unless ( selections.is_a? (Array) )
+		#			#in the selections array we have indices of elements in "list" array
+		#			selections.each { |sel|	selected << list[sel.to_i] }
+		#			@slots["selections"].value = selected
+		#		end
+		#	end
+		def process_bindings ()
+			if ( @parameters["selections"] )
+				self.selections = @parameters["selections"]
+			else
+				self.selections = nil
+			end
+		end
+	
+	end
+	
+
+end