Frontier Tutorials / Writing an ObjectNotFoundHandler / ONFH Overview

ONFH Overview

When The Walk Fails

MainResponder.respond assumes that the #objectNotFoundHander entry is the address of something it can render as a page. The gatherAttributes sub-script in mainResponder.respond puts the address of an outline, script, menubar, binary, wptext, or table entry in the page table. If your handler is of any of these types (#renderTableWith must be defined if it's a table), then #objectNotFoundHandler can be either the actual item or the address of the item.

When mainResponder.respond has followed The Walk as far as it can, but is unable to find a matching item, it looks in the page table for an entry named objectNotFoundHandler. If found, it assumes this entry is the address of an item in the website table, and attempts to render that item and return it in place of the missing item.

So if all you want is a prettier File Not Found page, you can simply create such a page and name it #objectNotFoundHandler, or make #objectNotFoundHandler the address of such a page in your website.

Using a Script

A more general solution is to create an ObjectNotFoundHandler script. This gives you all the flexibility of the UserTalk scripting language. You can either place it in your #tools table, and set #objectNotFoundHandler to the address of the script, or simply name the script #objectNotFoundHandler. If you do the latter, make sure it doesn't have an eponymous script, and do not put it in the #tools table.

The script is simply rendered as a website page, just like any other script that mainResponder finds in the course of The Walk.

The Information You Get

MainResponder inserts two values into the page table, as hints to your ObjectNotFoundHandler script:

• lastNomad is the address of the nearest ODB item mainResponder.respond was able to resolve from the URL. This is the table that (according to the URL) should contain the requested page.

• remainingPath is the portion of the URL that mainResponder.respond was unable to resolve.

For example, if you have a section in your site at http://yoursite/places/ but no subsite http://yoursite/places/colo/, and a user requests the page http://yoursite/places/colo/denver, lastNomad would be set to @yoursite.places and remainingPath would be set to "colo/denver".

In addition to these two values, you have the entire page table available to you. Among other things, this means you can retrieve the entire URL of the current page from the URI field of the page table.

What Your Script Does

The ObjectNotFoundHandler script must do the following:

1. Using the lastNomad and remainingPath values (and optionally any other values available in the page table), determine the proper data to be returned for inclusion in the page.

2. If necessary, process the data (using a table or outline renderer, html.processMacros, or whatever) to generate HTML text for the page body.

3. Return the information to mainResponder, for return to the user.

Your script can return information to mainResponder in one of several ways:

• Render (if necessary) and return the page content, which mainResponder will insert into the template defined at the lastNomad point in your website.

• Redirect to another page (presumably, one that actually exists).

• Stuff data directly into the page table, and bypass remaining page rendering processing to avoid using the template.

These actions, or operating modes, are detailed on the next page of this tutorial.

Rendering Flags

MainResponder looks at three flags when it is asked to render a script: flRender, allowScriptsToRun, and allowScriptListings.

If flRender is TRUE, mainResponder will run the script and insert the result in to the template, as with any other page.

If flRender is FALSE, but allowScriptsToRun is TRUE, mainResponder will run the script and return the result as the page content, without inserting it into the template.

If both flRender and allowScriptsToRun are FALSE, but allowScriptListings is TRUE, mainResponder will return the script as verbatim text, without attempting to run it and without inserting it into the template.

If all these flags are FALSE, mainResponder will return an error page, with the error "The attribute "allowScriptListings" must be true."

For the techniques described in this tutorial to work, you will need to set either flRender or allowScriptsToRun to TRUE.

In particular, in a site that is serving pre-rendered pages from the ODB, flRender will be set to FALSE. In this case, for the techniques described in this tutorial to work, you will need to set allowScriptsToRun to TRUE.