Forum OpenACS Q&A: Re: xql

When you write OpenACS packages you have the following package structure:

mypackage/
mypackage/sql
mypackage/tcl
mypackage/www

These three subfolders contain your code.

sql contains at least the two files
mypackage-create.sql
mypackage-drop.sql

For initial installation of your package in OpenACS so that all database tables, sequences, sql functions ... are created and of course deleted when you want to have a clean removal of that package.

tcl contains at least a file called
mypackage-procs.tcl
that contains all the procedures/functions you would like to reuse over you whole package. To have a proc

myapi::myproc

that does something you define in the above file the following:

namespace eval myapi {

ad_proc -public myproc {
....
}

the www folder contains all your actual pages. In accordance to the model view controller (MVC) pattern each pages consists of three files:

mypage.adp        view
mypage.tcl        controller
mypage.xql        model

The adp page is for designers who can take care of layouting the content you create in the controller. The tcl page takes care of the workflow, defines variables, makes database calls ...the xql files simple outsources the sql queries that are used in the tcl file.

Here an example for creating a list from the database that also returns csv results if requested.

mypage.xql:

<?xml version="1.0"?>
<queryset>
<fullquery name="file_name">
      <querytext>
    select user_id, username, screen_name from users</querytext>
</fullquery>

mypage.tcl:

ad_page_contract {

      A simple list
      @author Nima Mazloumi (mailto:nima.mazloumi@gmx.de)
      @creation-date 15/09/2004

} {
  csv:optional
} -properties {
      mylist:multirow
}

# Listendefinition
template::list::create \
  -name mylist \
  -key  user_id \
  -multirow mylist \
  -actions  [list "CSV" "mypage" "Create CSV"] \
  -sub_class {
      tiny
  } -elements {
        username {
          label "Applet"
          html "align left"
      } screenname {
          label "Valuation"
          html "align left"
      }
          sub_class narrow
      }
  } -selected_format csv -formats {
      csv { output csv }
  }

# Actuall database call
db_multirow mylist get_user_list {}

# dealing with csv requests
if { [exists_and_not_null csv] } {
  template::list::write_output -name mylist
}

mypage.adp:
<!-- we embed our list in the site master template -->
<master>
<listtemplate name="mylist"></listtemplate>

Now where to go from here:
- you have the api-browser that can explain to you procs used in the tcl files.
- you can simply browse an openacs test server and view different packages and if you find something useful for your purpose take a look that the adp, tcl and xql file of that page. This is the best way to learn.

Greetings,
Nima