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 base directory which is specified by the constructor base_dir argument. The current application page is identified by the path to the page module relative to the module base directory. Page identifiers consist of an optional path component followed by a module name without extension. For example "login", "user/list", "home-page/default".

Page modules are loaded into a dummy __alpage__ namespace to avoid conflicts with python modules, so loading "user/list" actually imports the module as __alpage__.user.list.

To support pickling of instances defined in a page module, a dummy hierarchy of modules needs to be created. In the __alpage__.user.list case mentioned above, a temporary dummy module called __alpage__.user is registered. This will be replaced by the real user module later if it is loaded.

Note also that the SessionBase mixin uses an import hook while decoding the session to redirects attempts to load page modules (those that being with __alpage__) to the load_page_module() method.

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.