7.10.1 PageModuleMixin

This class uses a separate Python module for each page in the application. This scales very well at runtime because at most two modules will be loaded for each request; one to process the browser request, and possibly another to display the response. Page modules are cached for further efficiency. The class is designed to be used where the application controls the sequence of pages seen in a browser session so the start page is also specified in the constructor.

Application page modules are loaded from a root directory which is specified in the constructor. The current application page is identified by the path to the page module relative to the module root directory. Page identifiers consist of an optional path component followed by a module name without extension. For example "login", "user/list", "home-page/default".

To load a page module the class combines the root directory passed to the constructor with the page identifier using os.path.join(). It then checks the page module cache to see if the module needs to be imported or reloaded. If the module needs to be imported, the full module path is split into directory and filename components using os.path.split(). The standard module importer in the imp module is then used load the page module using the filename part of the full path as the module name and the directory component as the module search path. The simplified code looks like this:

path = os.path.join(self.module_base_dir, name)
dirname, name = os.path.split(path)
file, filepath, desc = imp.find_module(name, [dirname])
page = imp.load_module(name, file, filepath, desc)

Due to this load method page module identifiers are not relative to the current page, they are always relative to the module root directory specified in the base_dir argument to the PageModuleMixin constructor.

Page modules handled by this mixin have the following interface:

page_enter( ctx [, ...])
If this function is present in the new page module it will be called whenever your application code calls the execution context set_page() method. For application types which define a start page this method is called in the start page when a new session is created.

The ctx argument contains the execution context. Any extra arguments which are passed to the set_page() method are passed as optional extra arguments to this function.

page_leave( ctx)
If this function is present in the current page module it will be called whenever your application code changes to another page by calling the execution context set_page() method.

The ctx argument contains the execution context.

page_process( ctx)
If this function is present in the page module it will be called when the application object executes the process_request() method. This occurs if the browser request was successfully validated.

Refer to page in section 4.1 for an overview of the application processing sequence.

page_display( ctx)
This is the only mandatory page module function. The application object calls this function when it executes the display_response() method as the final step before saving the browser session.

Refer to page in section 4.1 for an overview of the application processing sequence.

The PageModuleMixin class has the following interface.

__init__( base_dir, start_page)
When you inherit from the PageModuleMixin class you must call this constructor.

The base_dir argument specifies the path of the root directory where page modules are loaded from. When deploying your application as a CGI program you can specify a relative path from the location of the application mainline. Apache sets the current directory to root so when using mod_python deployment you will need to specify a path relative to the root.

The start_page argument is a page identifier which specifies the first page that new browser session will see.

module_path( )
Returns the base_dir which was passed to the constructor.

start_page( )
Returns the start_page which was passed to the constructor.

load_page( ctx)
This method implements part of the standard application processing sequence. It is called immediately after restoring the browser session. The ctx argument is the execution context for the current browser request.

If no current page is defined in ctx then the method will invoke ctx.set_page() passing the page specified as the start_page argument to the application constructor.

The actual page module load is performed via the load_page_module() method.

Refer to page in section 4.1 for an overview of the application processing sequence.

load_page_module( ctx, name)
Loads the page module identified by the name argument and saves a reference to the module in the page member.

page_enter( ctx, args)
Called when your application code calls the execution context set_page() method. The ctx argument is the execution context for the current browser request. The args argument is a tuple which contains all optional extra arguments which were passed to the set_page() method.

The page module page_enter() function is called by this method.

page_leave( ctx)
Called before changing pages when your application code calls the execution context set_page() method. The ctx argument is the execution context for the current browser request.

The page module page_leave() function is called by this method.

process_request( ctx)
This method implements part of the standard application processing sequence. It is called if the browser request is successfully validated. The ctx argument is the execution context for the current browser request.

The page module page_process() function is called by this method.

Refer to page in section 4.1 for an overview of the application processing sequence.

display_response( ctx)
This method implements part of the standard application processing sequence. It is called as the final stage just before the session is saved. The ctx argument is the execution context for the current browser request.

The page module page_display() function is called by this method.

Refer to page in section 4.1 for an overview of the application processing sequence.