Chapter 4.26:  Caucus 5.0 Functions

[TOP] [UP] [PREV]

In Caucus 5.0, the underlying proprietary flat-file database is replaced by MySQL, a full-featured, open-source, relational database management system ("RDBMS").  When Caucus 5.0 is released, there will be a new version of the CML reference guide; in the meantime, new functions in 5.0 will be documented here, along with an indication of which functions they replace.

Note: even when new functions are meant to entirely replace the equivalent old functions, the old functions (at least for now) are still operational.  The old functions should only be used for conversion purposes, e.g. as part of a script used to read the old data and write it in the new database.

See the Caucus 5.0 Schema for detailed descriptions of the MySQL tables used in Caucus 5.0.

1. User Information

   Personal information about all users are stored in a single table (called user_info), and referenced by field name (aka "column name").  The three functions that follow provide direct access to the user_info table.  (The $sql_query_open() function may also be used to run queries against this table.)

   $add_user_info (field type)        {protected}

   Creates a new column called field, of a given type.  Type must be one of the following:

   string	arbitrary text, up to 255 characters long
   text	arbitrary text, any length (up to 16MB)
   date	Date and time, in the form "YYYY-MM-DD HH:MM:SS"
   number	an integer number
   dollars	a number with two decimal points

   Evaluates to 1 if successful, else 0.

   The user_info table initially has the pre-defined fields shown below.  Only 'lname' is required to have a value for a user to exist.

   lname	string	"Last" name
   fname	string	First (& middle, etc.) name
   prefix	string	Prefix or salutation
   suffix	string	Suffix or organization
   intro	text	"Brief introduction"
   phone	string	Telephone(s)
   email	string	e-mail address
   active **	number	is user active?
   laston **	date	date last on Caucus

   The fields marked with "**" are automatically maintained by Caucus, and generally should not be set with $set_user_info().

   $set_user_info (userid field value)        {protected}

   Assigns value to field for user userid.

   $user_info (userid field)

   Evaluates to the value of field for userid.

   These three functions effectively replace most of the "$per" and "$my" functions, specifically:

   • $per_name(id)
   • $per_intro(id)
   • $per_phone(id)
   • $per_laston(id)
   • $set_per_name(id name)
   • $set_per_phone(id phone)
   • $set_per_intro(id text)
   • $my_name()
   • $my_phone()
   • $my_intro()
   • $my_laston()
   • $set_my_name(name)
   • $set_my_phone(number)
   • $set_my_intro(text)

   They also replace any instances of $user_var() and $set_user_var() that are used for personal information -- such as the fields that a manager may add on the "modify the XYZ registration interface" page.

   Example
   The new user_info functions are meant as simple "drop-in" replacements for the old functions listed above.  In cases where CML code is displaying many user fields at once, building a regular SQL query may be simpler and more efficient.  For example, consider the following CML code fragment for displaying a list of all users, sorted alphabetically by last name:

      "<table>
      set query SELECT prefix, fname, lname, suffix, userid, email \
                  FROM user_info ORDER BY lname
      set h $sql_query_open($(query))
      while $sql_query_row ($(h))
         "<tr>
         "<td>$(prefix) $(fname) $(lname) $(suffix) ($(userid))</td>
         "<td>$(email)</td>
      end
      eval $sql_query_close($(h))
      "</table>
   

   'Magic' Fields
   Certain fields are 'magic', in that they have some special behaviour, and should not be written to from any kind of SQL query.

   • lname.  To create a new user, evaluate $set_user_info (userid lname lastname).  You must do this first, before attempting to call $set_user_info() to set any other values for that userid.

   • laston.  This field is set automatically by Caucus when a user logs in, and when they log out.  Calling $set_user_info (userid laston xyz) sets the "laston" field to the current date and time (ignoring the value of xyz), and only if userid is same as the current user.

2. User Data

   Even with the new user_info table, there is still a need for user data such as the "variables" provided by the old $user_var() function.  This data is often "sparse", in the sense that only a few variables may have data for most users.  It is also frequently used for managing the user interface, rather than representing any "personal" information about a user.

   In Caucus 5.0, this data is stored in a new table called user_data, which has only three columns:

   • userid
   • name (of data field)
   • value (always a string, any size up to 16MB)

   This data is accessed in a manner exactly parallel to the old "user variables", except that there is no cache and thus no $clear_user_data(), and there are no locking issues (no need to call $lock() when writing user data).

   $user_data(user vname)

   Evaluates to the value of userid user's variable called vname.

   $set_user_data(user vname value)        {protected}

   Sets userid user's variable vname to value.

   $list_user_data(user str)        {protected}

   Evaluates to a blank-separated list of user's variable names that begin with str.  If str is not supplied, lists all of user's variables.