Templates

ETP Templates

To use ETP, or in fact to effectively use OpenACS 4, it's essential that you become familiar with the OpenACS Templating System. ETP's support for rapid application development includes procedures for creating the data sources that will be used by your page templates. You can copy code from the examples in the packages/editthispage/templates directory to get started, but here's an overview of what you need to know.

Providing the "Edit this page" link

As demonstrated in packages/editthispage/www/master.tcl, you should call the procedure etp::get_etp_link from your own master template, in order to determine whether or not to present the user with the "Edit this page" option. The procedure returns the html link only within an instance of the ETP package, and then only if the user has write access. Otherwise an empty string is returned.

Retrieving page attributes for the template to display

Every ETP template will make use of the etp::get_page_attributes procedure. It creates an array variable called pa in the caller's stack frame, containing all the attributes necessary to render the current page. These attributes include the standard elements from the cr_revisions table such as title, description, and content. If the page is using a custom content type, any extended page attributes that correspond to it will be included.

The complete list of standard attributes in the pa array is as follows:

item_id
name
revision_id
title
context_bar
description
publish_date
content
extended attributes, if any, defined by etp::make_content_type

The procedure is designed to be efficient under heavy load. The database is accessed once to retrieve the attributes, and a second time to generate the page's context bar. The resulting array is then cached in the server's memory until someone edits it.

Once the pa array variable has been created as a template data source, the template itself may reference the values it contains using the standard syntax for "onerow" data sources; for example, @pa.content@.

Retrieving the list of pages in a content section

ETP templates used for the index page will almost always make use of the etp::get_content_items procedure. It creates a variable called content_items in the caller's stack frame. This is a multirow result set suitable for passing to an index template, containing all the structured data necessary to present a list of links to content pages, folders, extlinks, or symlinks. By making use of the procedure's switches you may modify the query results it produces:



 -attributes [list] - list of additional page attributes to return (when required for display)
 -orderby [list] - list of columns on which to sort.
 -where [list] - list of SQL where clauses to restrict the query.

Each row in the result set always contains values for the following page attributes:

name
url (use this to generate a link to this item)
title
description
object_type
publish_date
item_id

Additionally, you may name additional attributes that will be returned, either from the standard page attributes stored in cr_revisions, or extended page attributes defined with etp::make_content_type.

The content_items variable is created with a single db query, and currently is never cached.

luke@museatech.net