Caucus How-To: Using Macros
(Revised 7 August 1998)
[People][>Caucus<][Conversations][Screen Porch]

I. Introduction

Caucus 4.0 introduces a new feature to the CML scripting language, called "macros".  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.)

Product Information
   Documentation
   Caucus FAQs
   Features
   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 4.0 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,  and file upload.

1. Simple text manipulation (HTML) macros:

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

3. Macros about people

4. File Upload Macros

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.

 

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, check out the CML bug fixes item in the Technical Support 4.0 conference.  (If you cannot get to this item, contact support@screenporch.com for details on how to become a member of this conference.)  You can also download a compressed tar file containing the latest CML bug fixes.