Chapter 4.13:  Item Information

[TOP] [UP] [PREV] [NEXT]

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_cnums(userid)

Evaluates to a list of conference numbers that userid is a member of. 

Note that, due to some old bugs, some users may appear in $peo_members() that do not have the corresponding conference number in $it_cnums().  The latter is the "most correct" indication of membership.

$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, not "forgotten", and not "hidden".  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)        {protected}

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)        {protected}

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".

$it_hidden(cnum inum)

Is conference cnum item inum hidden (aka retired)?  Evaluates to 1 if hidden, 0 if not hidden or does not exist, not accessible, etc.

$set_it_hidden(cnum inum hide)        {protected}

Sets conference cnum item inum to "hidden" if hide is true, and to "visible" if hide is false.

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.