Caucus How-To: Using Macros
Last revised: 25 October 2004
Caucus 4.0 introduced the "macro" feature to the CML scripting language. A macro is simply a shortcut, a way to replace a lot of HTML text (or CML function calls) with a special code (the macro) that "expands" into the CML or HTML text.
You may have seen these macros in use if you've uploaded a file into a Caucus response. After you've uploaded a file (but before you press a Post button), you'll see the original text of your response in the large pink text box. This box contains any text you typed, plus a special code like %liburl(...). That code is the macro.
(If you wish, you can skip directly to the list of defined macros.)
II. Purpose -- for site administrators and CML writers
The main purpose of the Caucus macro is to expand the capabilities of the CML language. Macros make it easier for the person writing or customizing CML to extend the local Caucus interface. Each macro acts like a pre-programmed "chunk" of HTML or CML text; by writing or using such chunks, creating new CML becomes much more efficient, compact, readable -- and powerful.
Here are two simple examples of macros:
- %bold(text) -- marks text as "boldface", equivalent to putting the HTML <B> and </B> tags around the text.
- %conference(name item) -- expands into an HTML link to a conference name, item number item.
The first example is very simple -- and may seem pointless, since the HTML tags for making text bold are just as easy. But the advantage of the macro is that it can be used in any context -- such as a Caucus "word wrapped" response, which does not normally process HTML tags.
The second example shows more of the power of a macro. It becomes an HTML link to the Caucus conference called name, with an optional item number item. To write the equivalent CML and HTML text would require code that looked like this:$if ($not ($cl_access($cl_list(name))) <U>name</U> \ <A HREF="http:/caucus/name\ $if ($not_empty (item) /item)">\ $upper1($replace(_ 32 name))\ $if ($not_empty (item) Item item))
For more detailed information about writing macros, see the macros chapter in the CML Reference Guide.
III. Purpose -- for Users
Macros can also be very helpful to regular Caucus users. With a small handful of macros, you can make your items and responses much more powerful, visually interesting, and make your use of Caucus much more effective -- all without having to write your entire response in HTML.
You can type a Caucus macro in any Caucus text -- items, responses, conference greetings, conference introductions, etc. And macros work no matter what "type" of text you select -- whether "word wrapped", "literal", HTML or CML.
The next section describes the "default" Caucus macros -- those that are supplied with Caucus as it comes out of the box. (Your local site administrator may have added other macros as well.) The macros are grouped by purpose, to make it easier to find a macro, given that you know what kind of thing you want to do.
IV. List of Caucus Macros
This list is grouped by function: text manipulation, "go to" (a conference, item, response), people, file upload, interface customization, and deep magic (internal) macros. Within each group, the macros are listed alphabetically.
Note: this list is meant as a complete reference to all of the Caucus macros. As such it can be a bit bewildering to the ordinary Caucus user. If you're just learning about Caucus macros, a good place to start would be the Get Help link, by the upper right-hand corner of the Caucus response box (that you see when you view an item). Then if you're hungry for more <g>, come back here.
1. Simple text manipulation (HTML) macros:
- makes text appear one font size bigger.
- makes text appear indented left and right, as a "block quote".
- %bold(text) or %b(text)
- makes text appear in boldface.
- makes text appear in a bulletted, indented paragraph. For example, %bullet(This is a bulletted paragraph.) appears as:
- This is a bulletted paragraph.
- %color(colorname text)
- makes text appear in color, e.g. %color(red Hello, world) displays Hello, world.
- %italic(text) or %i(text)
- makes text appear in italics.
- %ol(n text)
- makes text appear as a numbered, indented paragraph. For example, %ol(5 This is paragraph five.) appears as:
- This is paragraph five.
- "Right trim" -- removes any trailing spaces from text.
- makes text appear one font size smaller.
- makes text appear
- %strip_http (url)
- strips off leading "http://", if present, from url.
- makes text appear subscripted in relation to text around it.
- makes text appear super-scripted in relation to text around it.
- Evaluates to mathematical symbol symname. See the list of symbols in CML file main/mathsym.i.
- %trimtext (chars text)
- evaluates to the first chars (number of characters) of text. If text is truncated, a trailing "..." is appended.
- %tt(text) or %mono(text)
- makes text appear in a fixed pitch font (also known as mono-spacing).
- %under(text) or %u(text)
- makes text appear underlined.
2. "Go to" macros -- reference another conference, item, response, or URL.
- Makes a link to the Caucus Center page. If text is supplied, it is used as the text of the link; otherwise the default name for the Caucus Center is used.
- %conference(conf_name [inum [rnum]])
- Makes a link to conference conf_name (item inum, response rnum). The item and response numbers are optional. Typing %conference(demonstration) into any text in Caucus creates a link Demonstration to the home page for that conference. Typing %conference(tech_support 3 20) creates a link Tech Support Item 3:20. Note that the conference name must use underscores in place of blanks.
- %confname_response_new(conf_name inum text)
- Makes a link called text to the first new response on item inum in conference conf_name. If there are no new responses on that item, nothing appears (there is no link). Note that the conference name must use underscores in place of blanks.
- %iframe (url reserved [optwidth [optheight [options]]])
- Displays an in-line frame, showing the contents of url. Reserved must be 0. Optwidth is the optional frame width in pixels, optheight is the optional frame height in pixels, options are any other iframe options you wish to supply. On Netscape 4, %iframe() displays a link which opens a new window containing url.
- %item(inum [rnum])
- Makes a link to item inum (response rnum) in the current conference. (The square brackets [ ] just mean the response number is optional; you don't actually type them. If the response number is left out, the link just points to the top of the item.) Typing %item (5) into any item, response, greeting, or introduction in a conference creates a link Item 5 to that item.
- Makes a link to item inum in the current conference. The text of the link is the title of the item. (This is often a more meaningful way to link to an item in a conference, since it conveys the purpose of the item.)
- %login_gme (url text)
- Displays a link "text" to a pop-up page that automatically logs the user into a GroupMind Express application (located at url). This macro is an example of how to integrate another web application with Caucus, and is worth careful study if you are interested in application integration.
- %readrange(itemfirst itemlast text)
- Makes a link called text. Clicking on the link takes the reader through all of the items from itemfirst to itemlast (one at a time). Often used by conference organizers, on a conference home page, to remind members to read certain items before diving into the rest of the conference.
- Makes a link to response rnum in the current Caucus item. Typing %response(17) into a response displays as Response 17, and clicking on that link takes a person directly to response 17 in the same item.
- %response_new(inum text)
- Makes a link called text to the first new response on item inum in the current conference. If there are no new responses on that item, nothing appears (there is no link).
- %telnet(host_address [name])
- Makes a 'telnet' link to a host host_address, and optionally calls the link name. Clicking on the link opens a window with a 'telnet' session to that host.
- %url(address text)
- Shows text as a link to the URL address. E.g. %url(http://caucuscare.com Caucus Care) displays as Caucus Care. Clicking on the link opens up a new window.
3. Macros about people
- Displays a link handle that opens an AIM (AOL instant messenger) window to talk to handle.
- "First" name (more precisely, everything but the last name) of user uid.
- "Last" name of user uid.
- %listpeople(separator userid1 [userid2...])
- Displays a list of clickable people (as in %person), separated by separator. For example,%listpeople (<br> $peo_members($arg(3)))would display a clickable list of the members of a conference, one person per line.
- %mailto(address [name])
- Displays a "mailto" link to the e-mail address for person name. Typing %mailto(firstname.lastname@example.org Caucus Care Support) creates a link Caucus Care Support that sends e-mail to email@example.com. (If name is not supplied, the e-mail address appears instead as the text of the link.)
- Displays a list of all of the people who are logged into Caucus right now. The options include:
If no options are supplied, all options (except "center" and "conf") are turned on. If only "conf" is supplied, all other options (except "center") are turned on.
summary display total number of users now display current date/time header display table headers name show users' names (as links) userid show users' userids active show date/time "active since" show users' email addresses (as links) center center table indent indent table conf only list people in current conference
- Displays a link to a page that displays the list of everyone logged on now. Uses text as the text of the link.
- Call this at the start of a CML page before using %onnow_user(), below.
- %onnow_user (uid)
- If user uid is on-now, evaluates to "(now)". Use this in preference to the $per_laston() function to determine if someone is really on now.
- %person(userid [text])
- Displays a link to the Caucus page about a person userid. Typing %person(roth) creates a link Charles Roth to the page for userid roth. If you specify the optional text, that is used as the text of the link, instead of the person's name.
- %person_noclick(userid [text])
- Acts like %person(), but clicking on the link does nothing.
- %photo(userid [options])
- Displays the picture of person userid. Clicking on the image pops-up a window with that user's personal information. If there is no such person, or they have no picture, evaluates to nothing. Currently the only options are anything that can go inside an HTML <img> tag, e.g. any of
- alt="jim's picture"
4. Files: upload, FILES area, and FileSafe
Generally, you will not type a file upload macro into an item or a response -- Caucus generates them automatically when you upload a file. But it may be useful to know what the macros are and how they work, especially if you want to change how an uploaded file appears in your response.
- Generates a 4 digit number (including leading zeroes) from n. This is a lower-level service macro used by the upload macros.
- %libimg2(userid 1 filename [options])
- Creates an HTML <IMG...> tag pointing to a filename uploaded by user userid, so that the image actually appears in the response. You can also insert additional image tag options, such as "height=200" -- but they must appear precisely as they would in an HTML image tag.
- %libimg2r(userid 1 filename [options])
- Same as %libimg2, but right-aligns the image so that text flows around it nicely.
- %liblink2(userid 1 filename)
- Creates a link to a filename uploaded by user userid. The text of the link is the full URL of the file in the Caucus file library. Clicking on the link opens up a new window.
- %libname2(userid 1 filename linkname)
- Creates a link to a filename uploaded by user userid. The text of the link is linkname. Clicking on the link opens up a new window.
- %liburl2(userid 1 filename)
- Actually generates the URL (non-clickable) of the uploaded file filename. %liburl2() is really a lower-level service macro, used by %libimg2(), %liblink2(), and %libname2() for simplicity.
- %liburl_at (conf item resp filename [options])
- Generates the URL (non-clickable) of an uploaded file named filename, in conference conf, item item, response resp. Conf must be the exact name of the conference, with underscores replacing any spaces in the name. If the current user cannot view conf, the macro is a no-op, i.e. it evaluates to nothing. Options are additional valid HTML image tag options, such as "height=200" or "hspace=5".
- %libimg_at (conf item resp filename)
- Generates an HTML <IMG...> tag pointing to file filename, as in %liburl_at() above.
The FILES area is a place for a sysadmin or Caucus manager to place files, usually via FTP or some other mechanism outside the usual Caucus file upload procedure. To reference those files from inside Caucus, use these macros:
- %files (name [text])
- Display a link to file name in the FILES area, and use text as the text of the link. (If no text is supplied, uses name as the link text.) Name may include subdirectories, as long as it is relative to the FILES directory.
- %files_url (name)
- Evaluates to the full URL of file name in the FILES area. Useful for building HTML, such as an <IMG> tag, that points to a file.
The FileSafe, new in Caucus 4.4, is an access-controlled, hierarchical directory of files that can be uploaded and downloaded. These macros provide links to filesafes and filesafe files.
- %filesafe (name [text])
- If the current user is allowed in filesafe name, displays a link to the filesafe. Uses text as the link text, or name if no text is supplied.
- %filesafes (prefix)
- Displays a list of links to all filesafes accessible by the current user, whose names begin with prefix. If no prefix, list all accessible filesafes.
- %filesafefile (name section file)
- Display a link to file in section of filesafe name. Use underscores instead of blanks in the section name.
- %filesafefileurl (name section file)
- Evaluates to the URL of file in section of filesafe name. Use underscores instead of blanks in the section name.
- %filesafesec (name section [link text])
- Evaluates to a link to section in filesafe name. If link text is supplied, that is used as the text of the link; otherwise the text is name / section.
- %filesafesecurl (name section)
- Evaluates to the URL of section in filesafe name.
- %filesafethumb (name section small big [width height])
- Evaluates to a clickable image. The image is the file small in section in filesafe name. Clicking on the image pops up a new window, containing image file big in section in filesafe name. If width and height are specified, they determine the size of the new window. Otherwise a (large) default-sized window is used.
5. Interface Customization Macros
There is a large collection of macros that are intended for Caucus administrators who are customizing the look and feel of the Caucus interface. In particular, these macros may be useful when customizing the the Caucus Center page (from the Caucus managers page, see "Customizing the Caucus Center").
Note that in many of the macros below, text can be anything -- actual text, or an image, or even another macro. Also, the name of a conference (e.g. conf_name) must always be one word -- use underscores instead of blanks.
The "IFS" macros below refer to the "Interface Storage" conference. For each Caucus interface, the Caucus manager(s) may create a dedicated "interface storage" conference, which is used to hold specific text or images or other elements used in customizing the interface. For example, for the default interface CC44, the conference is called Interface_Storage_CC44.
- %conf_is_allowed (conf_name text)
- Displays text (can be anything, including an image, a link, or another macro) if the user is allowed in conference conf_name. Otherwise, displays nothing.
- %conf_nonmember (confname text)
- Displays text (can be anything) if user is allowed in confname but is not already a member.
- %conf_has_new (conf_name text)
- Displays text (can be anything) if conf_name has new material. Otherwise, displays nothing.
- %conf_has_new_br (conf_name text)
- Same as %conf_has_new(), but puts an HTML line break (<BR>) after the link.
- %conf_link (conf_name text)
- Displays text as a link to conference conf_name.
- %conf_link_br (conf_name text)
- Same as %conf_link(), but puts an HTML line break (<BR>) after the link.
- %conf_url (conf_name)
- Evaluates to the full URL for conference conf_name.
- %conf_item_url (conf_name item)
- Evaluates to the full URL for conference conf_name, item item.
- %conf_name_with_new (conf_name text)
- If user is allowed in conf_name, displays a link (text) to the conference, followed by a "New" icon if the conference has new material. (This is really just a combination of several other macros: %conf_is_allowed, %conf_link, %conf_has_new, and %icon_new.)
- %conf_name_with_new_br (conf_name text)
- Same as %conf_name_with_new(), but puts an HTML line break (<BR>) after the link.
- %conf_file_url (conf_name user item resp filename)
- Evaluates to the full URL for file filename uploaded by user user into response resp of item item in conference conf_name.
- %courselist (options)
- Display a list of "course" type conferences available to the user. (New in Caucus 4.6, there is a new type of conference called a "course". The type is designated when the conference is created.) This macro is typically used on the Caucus Center home page to display the courses a person has joined, or can join. It displays a personal-conference-like table of courses, with detailed information about each course. A variety of options control precisely what appears in the display. Options are separated by blanks, and are of the form "option=value". Current options include:
The precise appearance of the course table is controlled by the following CSS classes:
Option Value Meaning header yes Show column headers (default) both Show separate headers for member and non-member courses no Don't show headers show all Show member and non-member course member Show member courses only (default) nonmember Show non-member courses only desc N Show N (number) characters of course description (default=10,000) 0 Don't show description column at all nobr yes Don't break conference or person names (default) no Wrap ("break") names as needed to make table fit w/o horizontal scrolling
- courses - overall table
- courses_hdr - column headers
- courses_row0 - "even" member course list rows
- courses_row1 - "odd" member course list rows
- courses_non0 - "even" non-member course list rows
- courses_non1 - "odd" non-member course list rows
- course_longfield - "long fields" in a course list row (currently conference name and instructor's name)
- Displays the Caucus "new" icon (image).
- Displays the list of userids assigned to the "instructors" column in a course conference.
- %interface (dir [text]) (Interface revision i53 or higher)
- "Change to interface dir." Evaluates to a link to the center page, but using interface dir. Clicking on the link takes the user to the center page, but changes the current interface to dir. (Dir must be an actual 4.4 interface directory name, such as "CC44".)
The text of the link is text, or dir if there is no text. If dir does not exist, the link is not active (just appears underlined but not "blued").
- %mainwindow (url linktext])
- Used in a pop-up window to redirect the main window to a new location. Creates a link with linktext (can be text, an image, another macro, anything) that, when clicked on, redirects the main window to url. Typically this would be used with some other macro that generates a URL that points to another location in Caucus, e.g. %conf_item_url() or similar.
- %ifs_page_link (item resp text)
- Displays a link "text" to a special "IFS page". This page contains the normal Caucus header (buttons and compass bar), plus the contents of the interface storage conference item item, response resp.
An "ifs page" is a simple way to provide new kinds of Caucus pages that may look or act differently than the usual conference / item / response pages. For example, one common use of an ifs page is to provide a "bookstore" that contains links to books (often at amazon.com) that relate to the conference(s) discussions.
- %ifs_popup (item resp text)
- Displays a link "text" to a pop-up IFS page. The resulting page contains only the contents of the IFS item, resp -- no headers or other buttons.
- %ifs_resp (item [resp])
- Evaluates to the text of the interface storage conference item item, response resp. All macros and CML functions in that response are expanded and evaluated. If resp is not supplied, 0 is used (i.e. the item text is used).
- %image (url [width height [alt_text]])
- Displays the image located at url, with the optional width and height and alt tag text alt_text.
- %imagelink (url target [width [height]])
- Displays the image located at url as a link pointing to URL target, with optional width and height. Clicking on the link pops-up a new window containing target.
6. Internal Macros (aka deep magic)
These macros are closely intertwined with the structure of the Caucus interface. They are not meant for casual use! They are described here for developers who are writing or rewriting the deeper structure of the user interface. Caveat Implementor!
- %_caucus_url(cnum inum rnum)
- Certain CML functions, such as $t2url() and $wrap2html(), automatically detect "special" Caucus URLs (e.g. http://yourhost.com/caucus/some_conference/some_item) and make them a link to the appropriate conference, item, etc. Those functions generate macro calls to %_caucus_url() for conference # cnum, item inum, response rnum.
- %_new_target_window (newx, newy)
- Certain CML functions, such as $t2url() and $wrap2html(), that detect URLs in text and make them "hot", automatically call this macro to open a new window for the target URL. Normally the macro is defined similarly to %js_open_window(). Obsolete browsers may require a specific size for newly opened windows, newx and newy.
- Make a link (with text) that does a browser BACK action.
- %bad_email_address (x)
- Heuristic for "is e-mail address x obviously bad?". Evaluates to 1 (bad) or 0 (possibly good). Obviously bad things include: no @, more than one word, really funky chars (;)...
- %datetz (date | time)
- Evaluates to a date (as returned by $re_time() or $dateof() ) or a time (as returned by $time() ), modified to display in the current time zone, as set by the global variables $(timezonehrs) and $(timezonename).
- %displayed_conf_name (cnum)
- Evaluates to "display" form of conference name for conference number cnum. Default version handles conversion from "my_conf" to "My Conf", for example.
- %epoch_of (x)
- X is either an epoch time, or a date string as returned by $dateof(). Evaluates to epoch time. Useful when working with a time that could be either a date string or an epoch time.
- %implemented (call)
- Is a specific function call (e.g. $my_favorite_cml_function()) implemented in this version of Caucus? Evaluates to 0 (no) or 1 (yes). Useful in the rare case requiring backward compatibility with older versions of swebs.
- %is_class (cnum)
- Is conference cnum a "class" type conference?
- %js_open_win (name)
- %location (url)
- Just a replacement for the HTTP "Location:" directive. Not all CML code uses this, but it probably should. Can help provide workarounds for strange browser behaviour (like some ugly bugs in IE 4 that we now cheerfully ignore).
- Leaving Caucus entirely to go to another url. The real thing is defined in the registration interface register.cml, there's a no-op dummy in the regular user interface.
- %mset (c i r)
- Set the "magic" variables m_cnum, m_inum, and m_rnum, (that declare to viewitem.cml and other heavy pages, just where we are in an item), to c, i, and r.
- %mpush (c i r)
- Push the current values of the magic variables m_cnum, m_inum, and m_rnum onto a stack; then set them to c, i, and r.
- Set the magic variables m_cnum, m_inum, m_rnum to the top of the stack (created by %mpush), and pop the stack.
- %monthDayYear (date)
- Convert date (yyyy-mm-dd format) to "Mon dd, yyyy".
- Make a link (with text) that does nothing. Useful for consistency with some displays, e.g. the compass or "location" bar.
- Increment variable x by 1, and return its new value. Equivalent to the 'C' statement "++x;".
- Evaluates to auto-incremented 'tabindex="n"', for use in defining tabbing order for <input> objects. %tab(x) starts sequence over again at 'x'. %tab() increments current value of variable tabindex.
- %to_parent (url)
- Used to generate <a href=""> links in pop-up windows. If the variable target_switch is true, clicking on the generated link sends the parent window to url. Otherwise the current window goes to url.
- %userxs(popup defaultx), %userys(popup defaultx),
- Used to define x and y sizes of popup windows (see CML file popup.js).
- %yyyymmddOf (date)
- Converts date, in any of the common date formats "mm/dd/yy", "mm/dd/yyyy", "mon dd[,] yyyy", "yyyy-mm-dd", to "yyyy-mm-dd".
There are a few warning notes you should know about using macros:
- If you want a $ or % character to appear unchanged inside a macro (such as in the text of %bold()), you must "escape" it, by preceeding it with a \ (backslash).
- The specific list of macros that come with Caucus is probably the fastest-changing part of the software. New macros are frequently being added, and old ones may be 'tweaked' (or have a bug fixed).
If you are a Caucus administrator and are experiencing any difficulty with macro use, join us in the Technical Support conference.