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/action.py" ). 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.

Property setting: this is the first thing, after session setting; for each parameter a property on your object is set. If no property is found, it then looks for the "variableFormProperties" value of the action. If set to True it will add it to your action's "_form" property, otherwise it will fail
Authentication: in this phase the "auth" method of action is called. This method should return True if it's ok to execute the action or False otherwise. By default returns True. Here PyWork also looks at the redirectUri property.
Pre-execution: Just before calling execute or your event method, PyWork will perform a call on "preExecute". Here you could define generic setup for your actions. Here PyWork also looks at the redirectUri property.
Execution: Here the "execute" method is called or other method defined by a call to "bind". It then processes the view returned or redirects to the uri specified in the redirectUri property.
Post-execution: After calling the "execute" method, or the event binded method, PyWork calls "postExecute". Here it will not look for the redirect uri. Here you may define finalization or closing procedures for your actions.

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):
		super(IndexAction,self).__init__()
		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"
		else:
			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/descriptor.py" ). 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).

name , the URL specified in the configuration file
moduleName
className
classObject, a reference to the Class object represented by this descriptor.
views, a dictionary containgin all the views available to this action, with the view name as the key and a "ViewDescriptor"as the value
context, a reference to the controlling processing this request. It will serve you, for example, to access a configuration value like this:
```
	self._descriptor.context.getconf( "dbuser" )
```

6.5 Suggestions

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

When possible try always to write a base action specific for your application and then extend it from your real action classes. This will give you the ease of maintaining all common code in one place, and to enhance your already written actions with no work at all.
Try to keep your actions simple, and delegate any business logic to more specialized python classes. Alwasy keep in mind that an Action is just the controller for the user interface, keep there any form validation, data formatting and place in business classes all your application specific code, like accessing a database, calling webservices, writing files, etc. It will permit you more code reuse , less bugs, and at the long run less and faster code.
With PyWork, you can (and we strongly suggest you) write unittest for your actions. That is setting the proper parameters and calling the execute method, and then examining the results. You would also may write unit test for other methods living in your action classes.

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