7.10.1 PageModuleMixin

##
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.