6. Actions

6.1 Intro

This chapter intends to give a more detailed description of what Actions are , how they should be used and what services they expose.

Actions are the main component of a PyWork Application, you can find the most important source code in the module ( "pywork/" ). An Action is a python component that process a user request , generates a result and returns an identifier of the view to be displayed. All application actions must directly or indirectly extend from "pywork.action.Action". PyWork has a main controller object that handles all the requests. The controller will call different methods of the action, on each phase. Furthermore, as seen in the HTTP chapter you can define specific bindings for your action, i.e.: define your own methods instead of using the default execute. Below are the steps/phases that PyWork identifies, for each one, it will call a correspondant method of action.

The action api provides to ways of access, the "execute"method, or a special method binded, by a call to "bind". If no parameter is present that identifies a binding, then execute will be called. In this method you should either return a proper configured view name, or set the redirect uri by setting the "_redirectUri" attribute. When PyWork executes the action it then examines the redirect uri of the action, if is not None then a redirect is sent to the browser with this URL, otherwize it will try to load and display the proper view. Also, if your action intends to process input parameters sent via GET/POST it must define one writeable property for each one and must name it with the same name of the parameter, that is, you will have to name your parameters "python" oriented. When PyWork receives a parameter it searches for writeable properties with that name, when it finds it, it sets it, if no property is found it goes in error and does not process the request. This is a security feature so you are sure of what are you processing, and you expose a clean interface via python default properties. Furthermore parameters starting with the character "_" are NOT processed. (This is a simple and useful issue specially with submit buttons). Normally it is recommended to use parameters startng "_" for event driven methods. When a parameter with a significant value and is binded to a specific method, this method will be called.

From this release, 3 new things had been added to parameters: List, Dicts and file uploads. List parameters are those that end with [], all parameters with the same name ended in [] will be packed in to a list and then setted. This also applies to dictionaries, (by now only 1 level dictionaries are supported), when a parameter ends with [<somekey>] they are all inserted into a dict for you and passed like this. For file uploads a fileupload object is created with a "filename" property and a "fileObject"property with a file opened for reading. Attention that to post files from a browser a form with enctype="multipart
form-data" must be defined.

The other important thing is how you return your results. We recommend the use of readable properties or public attributes so that the corresponding view will process them.

6.2 Example

Here is a simple example that accepts two parameters: name and surname.

from pywork.action import Action

class IndexAction(Action):
	def __init__(self):
		self.__name = None
		self.__surname = None
		self.__welcome = None
        self.bind( "_bye", self.bye )

	def __setName(self,n):
		self.__name = n

	def __setSurname(self,n):
		self.__surname = n

	def __getWelcome(self):
		return self.__welcome

	name = property(None,__setName)
	surname = property(None,__setSurname)
	welcome = property(__getWelcome)

	def execute(self):
		if not self.__name and not self.__surname:
			return "error"
			self.__welcome = "Hello %s %s and welcome to PyWork" % ( self.__name, self.__surname )
			return "success"

    def bye(self):
        self.__welcome = "Ok bye!"
        return "success"

In this piece of code you see how by defining properties you are ready to receive GET/POST http parameters, and then process them and expose the result in another property. Of course in a real world app you would normally access other python objects that in turn they may access an RDBMS to obtain some results. Also notice that we binded the "_bye" parameter to the "bye" method, so if the browser passes a "_bye" parameter with a significant value (1 for example) PyWork will call "bye" instead of execute.

6.3 Session

You can also access the user's session to store and retrieve session information. PyWork uses the standard mod_python session classes, but you can also configure them via the global PyWork configuration file. The session object is just a dictionary where you can store and retrieve values like any other dictionary object. You can access the dictionary via, the "_session"attribute. All the values that you store or delete will be saved at the end of the request. This is a simple example of session access, I don't print all the code for simplicity.

	class IndexAction(Action)
		# ....

		def execute(self):
			if self.__username:
				# store something
				self._session[ "username" ] = self.__username
				self._session[ "info" ] = [ "other", "info" ]
		# ....

6.4 Metadata

All actions are constructed from the configuration file. This information is first stored on a metadata class named "ActionDescriptor" ( "pywork/" ). You can access it from within your Action to this data by accessing the "_descriptor" attribute. An "ActionDescriptor" contains the following data exposed as an attribute (any way in the api chapters you will find this info).

6.5 Suggestions

The PyWork team would like to give you some advice on writing your action classes.

See About this document... for information on suggesting changes.