CML Reference Guide
The "it_" and "set_it_" functions provide
or manipulate information about an item, or items, in a conference,
or the user's participation in a conference. Cnum always
refers to the conference number. Inum is a particular
item number. Rnum is a particular response number.
- $it_member(cnum)
-
Evaluates to "1" if the current user is a member of
the conference.
- $it_join(cnum)
-
Make the current user a member of the conference. Evaluates
to "1" if joining is successful, and "0" otherwise.
- $it_resign(cnum userid)
-
Resign (remove) user userid from the conference.
Evaluates to nothing.
(If userid is not supplied, assumes the current user.
Only organizers may successfully "resign" other users.)
- $it_last(cnum)
-
Evaluates to the number of the last item in a conference, i.e.,
the number of items.
- $it_icount(cnum)
-
Evaluates to the actual number of (non-deleted) items in a conference.
- $it_inew(cnum)
-
Evaluates to the number of new (and undeleted) items in a conference.
- $it_rnew(cnum)
-
Evaluates to the total number of new responses in a conference.
- $it_iforgot(cnum)
-
Evaluates to the number of forgotten items in a conference.
- $it_wnew(cnum)
-
Evaluates to the number of items that have 1 or more new responses.
- $it_iunseen(cnum)
-
Evaluates to the number of unseen items.
- $it_listinew(cnum)
-
Evaluates to a space-separated list of the new items in a conference.
This list appears in "triplet" form. This means that
each item is represented by three numbers: a conference number,
an item number, and the number of the first relevant response.
For example, if conference 17 has two new items, 5 and 6, $it_listinew()
would produce the string "17 5 0 17 6 0". To parse
triplet lists, use the functions $word() and $rest().
- $it_listrnew(cnum)
-
Evaluates to a "triplet" list of the new responses
in a conference. The response number in a triplet is the first
new response in the relevant item.
- $it_listiunseen(cnum)
-
Evaluates to a "triplet" list of the unseen items in
a conference. The response number is always 0.
- $it_exists(cnum inum)
-
Evaluates to "1" if the item exists and the
user is a member of the conference, and "0"
otherwise.
- $it_visib(cnum inum)
-
Evaluates to "1" if the item is visible to the user,
i.e. has not been deleted or "forgotten". Otherwise
"0".
- $it_new(cnum inum)
-
Evaluates to "1" if the item is new to this user, i.e.
it has a higher number than the highest item the user has seen.
Otherwise "0".
- $it_unseen(cnum inum)
-
Evalutates to "1" if this item is not new but has not
been seen by the user. Otherwise "0".
- $it_resps(cnum inum)
-
Evaluates to the number of responses. If the item does not exist
(or was deleted), evaluates to -1. An item without any responses
evaluates to "0".
- $it_lastresp(cnum inum)
-
Evaluates to the number of the last (undeleted) response
to the item. If the item does not exist
(or was deleted), evaluates to -1.
- $it_newr(cnum inum)
-
Evaluates to the number of the first response on this item that
is new to this user. If no responses are new, evaluates
to the number of responses + 1.
- $set_it_seen(cnum inum rnum)
-
Marks all responses through rnum as "seen" by
this user. To mark an item as "unseen", use an rnum
of -1. To mark an item as "forgotten", use an rnum
of -2.
- $it_frozen(cnum inum)
-
Evaluates to "1" if the item is frozen, and "0"
otherwise.
- $set_it_frozen(cnum inum value)
-
A value of 1 freezes the item.
A value of 0 "thaws" it.
- $it_howmuch(cnum inum userid)
-
Evaluates to the number of responses seen by user userid
to item inum in conference cnum. A value of -1
means the item is new to that user; -2 means the user has forgotten
that item.
- $it_parse(cnum text)
-
Evaluates to a triplet list of item/response numbers in conference
cnum that match, in some form, text. Text
may contain a variety of forms of listing items, separated by
commas, including the example shown below.
The result is an "or"
match, i.e. all the items that match all the entries in text.
5
7-20
key words in an item title
"words in one item title", "words in another item title"
author "charles roth"
since 5/23/95
since -4
- $it_pack(cnum comma triplet(s))
-
Acts as the inverse of $it_parse(), i.e. it converts a triplet list
of items into text representing item ranges. Items in triplets
that are not in conference cnum are ignored.
A comma value of 1 means add a comma and a space between items
or item ranges; 0 means just use a space.
Example: $it_pack (3 1 3 12 0 3 13 0
3 14 0
2 5 1 3 1 5)
produces "1, 12-14".
Note: to ease the writing (and reading) of CML pages, all of the
$it_ functions that take two arguments (such as
it_visib(),
it_resps(), and
it_newr())
may be written with no arguments. This
means "re-use the exact same arguments as in a previous instance
of one of these functions". Warning: results may
be unpredictable if other $it_...() functions (those with more
than two arguments) are called in between.