Different concepts associated with a page

B
efore you start writing code for a database page, you have to make several choices.

    Is this a single / multiple page?
    Each page can be a single page (display info about one record) or multiple page (display info for more than one record) or both. In case it is both, the arguments given to the page usually determine, on a per invocation basis, whether this invocation is to be processes as a single or multiple page. This decision is implemented in the is_multiple method of the DisplayClass.

    Permissions to view the results
    • If the user is not logged in, is he allowed to view the results?
    • If the user is logged in, does (s)he have permissions to view the results?

    The permissions are decided in permit_mode method of the DisplayClass. This usually is just a call to perms.may with appropriate arguments. The permit_mode method should be called in make_page and perform_action -- if this page supports actions, right in the beginning.

    How many modes does this page support?
    Does it have a display and edit mode or only one of them. The choice may also depend on whether it is a single page / multiple page. For eg. you may have a page which as a multiple page supports only display mode and as a single page supports both display and edit mode. This is also implemented in make_page and perform_action, right after the permissions are determined. Some times you may need to bounce to same page in a different mode, if the current mode does not make sense for the current page (this can depend on whether the page is currently a single database page or a multiple database page).

    Some pages may need to support more than the two basic modes. For an example, see courses/description when displaying info for a single course.

    What shape does each mode correspond to?
    Once the current user has the right permission, and is in the right mode, we need to change the current shape to suit the mode. This is also done in make_page. This need not be done in perform_action since no HTML output is generated when an action is being performed.

    For eg. in courses/description single database page, the display, retire, renumber, verify modes all correspond to the same display shape, though the HTML output varies a little with the mode.

    Which of these modes perform an action?
    Some modes after accepting some input from the user, have to make changes in the databases. These changes are implemented as actions. The input is accepted from the user through a HTML FORM. Clicking "Commit Changes" button on the form will generate a request to the same page, this time with the information the user entered. This time, the method perform_action is called instead of make_page. It is upto the perform_action method to check permissions, mode, verify the validity of the data entered (display.form_fields) and call perform_database_update or perform_database_insert depending on whether we want to add a new record or edit an existing record.