cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/

To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".

Our package will have two visible pages. The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object. The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.

Figure 9.5. Page Map

Each user-visible page in your package has, typically, three parts. The tcl file holds the procedural logic for the page, including TCL and database-independent SQL code, and does things like check permissions, invoke the database queries, and modify variables, and the adp page holds html. The -postgres.xql and -oracle.xql files contains database-specific SQL. The default page in any directory is index, so we'll build that first, starting with the tcl file:

[$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
[$OPENACS_SERVICE_NAME www]$ emacs index.tcl

Paste this into the file.

ad_page_contract {
    This is the main page for the package.  It displays all of the Notes and provides links to edit them and to create new Notes.

    @author Your Name (you@example.com)
    @cvs-id $Id: tutorial-pages.html,v 1.37 2006/07/17 05:38:32 torbenb Exp $
}

set page_title [ad_conn instance_name]
set context [list]

Now index.adp:

<master>
  <property name="title">@page_title;noquote@</property>
  <property name="context">@context;noquote@</property>
<include src="/packages/myfirstpackage/lib/note-list">

You can test your work by viewing the page /myfirstpackage on your installation.

The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.

[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl

template::list::create \
    -name notes \
    -multirow notes \
    -actions { "Add a Note" note-edit} \
    -elements {
	edit {
	    link_url_col edit_url
	    display_template {
		<img src="/resources/acs-subsite/Edit16.gif" width="16" height="16" border="0">
	    }
	    sub_class narrow
	}
	title {
	    label "Title"
	}
	delete {
	    link_url_col delete_url 
	    display_template {
		<img src="/resources/acs-subsite/Delete16.gif" width="16" height="16" border="0">
	    }
	    sub_class narrow
	}
    }

db_multirow \
    -extend {
	edit_url
	delete_url
    } notes notes_select {
	select ci.item_id,
	       n.title
        from   cr_items ci,
               mfp_notesx n
        where  n.revision_id = ci.live_revision
    } {
	set edit_url [export_vars -base "note-edit" {item_id}]
	set delete_url [export_vars -base "note-delete" {item_id}]
    }

[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp

<listtemplate name="notes"></listtemplate>

Create the add/edit page. If note_id is passed in, it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.

[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www
[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl

ad_page_contract {
    This is the view-edit page for notes.

    @author Your Name (you@example.com)
    @cvs-id $Id: tutorial-pages.html,v 1.37 2006/07/17 05:38:32 torbenb Exp $
 
    @param item_id If present, assume we are editing that note.  Otherwise, we are creating a new note.
} {
    item_id:integer,optional
}

ad_form -name note -form {
    {item_id:key}
    {title:text {label Title}}
} -new_request {
    auth::require_login
    permission::require_permission -object_id [ad_conn package_id] -privilege create
    set page_title "Add a Note"
    set context [list $page_title]
} -edit_request {
    auth::require_login
    permission::require_write_permission -object_id $item_id
    mfp::note::get \
	-item_id $item_id \
	-array note_array 

    set title $note_array(title)

    set page_title "Edit a Note"
    set context [list $page_title]
} -new_data {
    mfp::note::add \
	-title $title
} -edit_data {
    mfp::note::edit \
	-item_id $item_id \
	-title $title
} -after_submit {
    ad_returnredirect "."
    ad_script_abort
}

[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp

<master>
  <property name="title">@page_title;noquote@</property>
  <property name="context">@context;noquote@</property>
  <property name="focus">note.title</property>
  
<formtemplate id="note"></formtemplate>

And the delete page. Since it has no UI, there is only a tcl page, and no adp page.

[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl

ad_page_contract {
    This deletes a note

    @author Your Name (you@example.com)
    @cvs-id $Id: tutorial-pages.html,v 1.37 2006/07/17 05:38:32 torbenb Exp $
 
    @param item_id The item_id of the note to delete
} {
    item_id:integer
}

permission::require_write_permission -object_id $item_id
set title [item::get_title $item_id]
mfp::note::delete -item_id $item_id

ad_returnredirect "."
# stop running this code, since we're redirecting
abort

The easiest way is to install the Edit-This-Page package.

Go to /admin/permissions and grant Create to Registered Users

Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.

Every page within an OpenACS site is part of a subsiteMore information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:

Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:

Figure4.1.Site Templates

The request processor is the set of procs that responds to every HTTP request made to the OpenACS. The request processor must authenticate the connecting user, and make sure that he is authorized to perform the given request. If these steps succeed, then the request processor must locate the file that is associated with the specified URL, and serve the content it provides to the browser.

Package Lookup

One of the first things the request processor must do is to determine which package instance a given request references, and based on this information, which pageroot to use when searching for a file to serve. During this process the request processor divides the URL into two pieces. The first portion identifies the package instance. The rest identifies the path into the package pageroot. For example if the news package is mounted on /offices/boston/announcements/, then a request for /offices/boston/announcements/index would be split into the package_url (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be able to figure out which package_id is associated with a given package_url, and package mountings must be persistent across server restarts and users must be able to manipulate the mountings on a live site, therefore this mapping is stored in the database.

Authentication and Authorization

Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the session security system. After authentication has been performed the user is authorized to have read access for the given package by the OpenACS 4 Permissions Design. If authorization succeeds then the request is served, otherwise it is aborted.

Concrete File Search

To actually serve a file, the request processor generates an ordered list of abstract paths and searches each path for a concrete file. The first path searched is composed of the package pageroot with the extra portion of the URL appended. The second abstract path consists of the global pageroot with the full URL appended. This means that if an instance of the news package is mounted on /offices/boston/announcements/, then any requests that are not matched by something in the news package pageroot could be matched by something under the global pageroot in the /offices/boston/announcements/ directory. Files take precedence over directory listings, so an index file in the global pageroot will be served instead of a directory listing in the package pageroot, even though the global pageroot is searched later. If a file is found at any of the searched locations then it is served.

Virtual URL Handlers

If no file is found during the concrete file search, then the request processor searches the filesystem for a virtual url handler (.vuh) file. This file contains normal tcl code, and is in fact handled by the same extension handling procedure that handles .tcl files. The only way this file is treated differently is in how the request processor searches for it. When a lookup fails, the request processor generates each valid prefix of all the abstract paths considered in the concrete file search, and searches these prefixes in order from most specific to least specific for a matching .vuh file. If a file is found then the ad_conn variable path_info is set to the portion of the url not matched by the .vuh script, and the script is sourced. This facility is intended to replace the concept of registered procs, since no special distinction is required between sitewide procs and package specific procs when using this facility. It is also much less prone to overlap and confusion than the use of registered procs, especially in an environment with many packages installed.

The request processor manages the mappings from URL patterns to package instances with the site_nodes data model. Every row in the site_nodes table represents a fully qualified URL. A package can be mounted on any node in this data model. When the request processor performs a URL lookup, it determines which node matches the longest possible prefix of the request URI. In order to make this lookup operation as fast as possible, the rows in the site_nodes table are pulled out of the database at server startup, and stored in memory.

The memory structure used to store the site_nodes mapping is a hash table that maps from the fully qualified URL of the node, to the package_id and package_key of the package instance mounted on the node. A lookup is performed by starting with the full request URI and successively stripping off the rightmost path components until a match is reached. This way the time required to lookup a URL is proportional to the length of the URL, not to the number of entries in the mapping.

The request environment is managed by the procedure ad_conn. Variables can be set and retrieved through use of the ad_conn procedure. The following variables are available for public use. If the ad_conn procedure doesn't recognize a variable being passed to it for a lookup, it tries to get a value using ns_conn. This guarantees that ad_conn subsumes the functionality of ns_conn.

A sample of the HTML code (full source)

<table border="0" width="100%">
  <tr>
    <td valign="top" width="50%">
      <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
        <tr>
          <td colspan=3 class="element-header-text">
            <bold>Groups</bold>
         </td>
       </tr>
       <tr>
         <td colspan=3 class="dark-line" height="0"><img src="/resources/acs-subsite/spacer.gif"></td></tr>
          <tr>
            <td class="light-line" width="1">
              <img src="/resources/acs-subsite/spacer.gif" width="1">
            </td>
            <td class="element-text" width="100%">
            <table cellspacing="0" cellpadding="0" class="element-content" width="100%">
              <tr>
                <td>
                  <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
                    <tr>
                      <td class=element-text>
                        MBA 101

A sample of the HTML code (full source)

<div class="left">
  <div class="portlet-wrap-shadow">
    <div class="portlet-wrap-bl">
      <div class="portlet-wrap-tr">
        <div class="portlet">
          <h2>Groups</h2>
          <ul>
            <li>
              <a href="#">Class MBA 101</a>

If the CSS is removed from the file, it looks somewhat different: