Caucus How-To: Using Macros
Last revised: 25 October 2004
I. Introduction

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:

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) &nbsp;Item&nbsp;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:

2. "Go to" macros -- reference another conference, item, response, or URL.

3. Macros about people

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.

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:

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.

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.

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!

 

V. Caveats

There are a few warning notes you should know about using macros:

  1. 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).

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