Frontier Tutorials / Indexing a Website / Display The Keyword Directory

Display The Keyword Directory

This page is a Fat Page. It includes the TopicsDirectory script, encoded by and for Frontier. To retrieve the script(s), save the page as source text and open it using the File->Open command.

To get the information out of the index and onto a page, we need to create a macro.

The Indexer Suite contains several example macros, which are useful as demonstrations, but they aren't complete. Still, we can copy one of them as the starting point for our own macro.

The TopicsDirectory Macro

So let's create the TopicsDirectory macro in the #tools table. We'll start with an example script from the Indexer Suite, then modify it to get the display we want.

Copy An Example Script

Copy indexer.examples.IndexToHtml to your #tools table, and rename it "TopicsDirectory". Don't forget to change the name of the eponymous script, as well.

Create a page named "Topics" at the top level of your website, with the following content:

#title "Topics Index" {TopicsDirectory(@indices^.topic,"ALL")}

Render the "Topics" page. You should get a hierarchical display of ODB addresses; it will resemble the following (yours will, of course, have your own keywords and addresses in it, not mine):

keywords where tutorials.indexsite.p03addkeywords script BuildTitleAlphaIndex tutorials.indexsite.p06buildindexalpha ClearPageFromIndex tutorials.indexsite.p09tips TitleAlphaDirectory tutorials.indexsite.p07showdiralpha TopicsDirectory tutorials.indexsite.p05showdir tutorial objectNotFoundHandler tutorials.indexsite.p11author site index building blocks tutorials.indexsite.p01buildingBlocks keywords tutorials.indexsite.p03addkeywords planning tutorials.indexsite.p02theplan tools tutorials.indexsite.p01buildingBlocks tutorials.indexsite.index summary tutorials.indexsite.p08summary tutorials.indexsite.p08summary

The leaf-level items are the ODB addresses of the indexed pages. The items above them are the keywords specified for the leaf pages.

So now we're halfway there: we have the display structure. View the page source; you'll see that it uses <blockquote> to create the indented blocks. Other techniques are, of course, possible; we'll look at some of them later.

The Indexer Suite function that makes this happen is Indexer.VisitIndexExt.

Indexer.VisitIndexExt

There are several variants of the visitIndex script in the Indexer Suite: visitIndex walks the index and calls a user-provided callback function for each actual indexed entry that matches a specified keyword or keywords. It does not pass any information about the structure of the index to the callback function. visitIndexResult works exactly like visitIndex, but expects the callback function to return a string. It accumulates these strings, and returns the aggregate string as its function return value. visitIndexExt walks the index and calls a user-provided callback function for each keyword that matches a specified keyword or keywords and for each actual indexed entry that matches a specified keyword or keywords. It passes information about the structure of the index as visitPhase to the callback function as described in the text. visitIndexExtResult works exactly like visitIndexExt, but expects the callback function to return a string. It accumulates these strings, and returns the aggregate string as its function return value.

VisitIndexExt walks the specified index table, and calls a user-provided callback function for each entry in the index table that corresponds to the specified keyword(s). The callback function is supposed to do whatever processing is needed, and should not produce a return value.

VisitIndexExt expects the callback function to accept the following parameters:

• itemAdr: The address of the current item in the index. Note that this is an address within the index, not the address of what the index item refers to!

• visitPhase: Information about the location of the index item within the index. Possible values for visitPhase (from Indexer.VisitIndexExt) are:
  • "cat_start": The current index entry is a table with sub-entries.
    itemAdr is the address of a category or subcategory table within the index (a category whose name matches one or more of the keywords specified in the inKeywords parameter to VisitIndexExt.

  • "item": The current index entry is the address of something elsewhere in the ODB (a page or table that was indexed by BuildPageIndex or BuildTableIndex).
    itemAdr is the address of an actual index entry.

  • "cat_end": VisitIndexExt has finished scanning an index table or subtable, and is exiting the table.
    itemAdr is the same address (of a category or subcategory table) as was passed with the most-recent "cat_start" code.

  • "finish": VisitIndexExt has finished scanning the index table where it started, and is exiting the table.
    itemAdr contains nil. Indicates that the index scan has been completed. This is the last call before VisitIndexExt returns to the caller.

Open the TopicsDirectory script again. Notice that it has a case visitPhase block to handle the different visit phases:

• When visitPhase is "cat_start", it renders the name of the current item (a keyword), and starts a new indented block immediately under the current item.

• When visitPhase is "cat_end", it closes the current indented block.

• When visitPhase is "item", it renders a link to the indexed item in the ODB.

• When visitPhase is "finish", it does nothing, since it already closed the last indented block when it received the last "cat_end".

Modify The Script

Now we will modify the TopicsDirectory macro to replace the plain address string in each entry with a link to the page, using the page title as the link text.

Open up the TopicsDirectory macro. Double-click the first summit to collapse it, then double-click again to expand it one level.

Expand the line that begins "on VisitCBFuncExt".

Expand the line that reads "case visitPhase", then the line that reads "item".

Locate the line that reads:

Add( nameOf( itemAdr^ ) + "<br>\r" )

Replace it with:

AddOneItem()

And finally, add the following nested script just above the case visitPhase block:

on AddOneItem() local pageAdr = itemAdr^ pageTbl = html.getPageTableAddress() pageUrl = html.getPath( pageTbl^.adrObject, pageAdr, pageTbl ) pageTitle if ( typeOf( pageAdr^ ) == tableType ) pageTitle = html.getOneDirective( "title", html.data.standardMacros.renderObject( pageAdr^ ) ) else pageTitle = html.getOneDirective( "title", string( pageAdr^ ) ) Add( "<a href='" + pageUrl + "'>" + pageTitle + "</a><br>\r" )

Using a nested AddOneItem script to generate the information block for each entry makes it easy to modify the script to display the entry in a different way.

Notice that we've dereferenced itemAdr to get the actual image entry address. The indexer.visit verbs call the callback function with the address of the index entry, not the address of whatever is being indexed.

Render the "Topics" page again. You should get a hierarchical display of page titles linked to the pages; it will resemble the following (yours will, of course, have your own keywords and titles in it, not mine):

keywords where Add Keywords script BuildTitleAlphaIndex Build the Alphabetical Index ClearPageFromIndex Hints and Tips TitleAlphaDirectory Display The Alphabetical Directory TopicsDirectory Display The Keyword Directory tutorial objectNotFoundHandler About the Author site index building blocks Bricks and Mortar keywords Add Keywords planning Plan the Project tools Bricks and Mortar Indexing a Website summary Summary Summary

Voila--a single-page keyword directory of the entire website. It wastes quite a bit of screen real-estate; we'll look at how to improve its display later.