Caucus How-To: Uploading Files
I. The Good News

It's easy to upload a single file, of any type, into a Caucus item or response.  (If you're an organizer, you can also upload a file into a conference greeting or introduction.)

You can also upload many files into a single item or response.  But you can only do this one file at a time. 

(For security reasons, the people who designed the HTML file upload feature restricted it to a single file at a time.  There is a way around this, by uploading a single 'zip' archive that contains many files.  See the zip file description below.)

When you're adding a response to an item (or editing a response), look for the upload button, near the upper right corner of the response box.  

Press this button (even in the middle of entering or editing your response), and you will see a new page that does the actual file uploading.  When you're done with this page, you'll be returned to your response, and you can keep entering or editing text as you see fit (or even upload another file). 

When you're done entering your response, press one of the Post buttons, and your text and your uploaded files will be posted as your response.

 

II. For more help

When you see the "upload" page (i.e., after you've pressed the upload button), press the Help button at the very top of the page.  This will cause a "pop-up" help window to appear.  Click on the very first link in this window to learn more about using the upload page.

 

III. The Bad News

Just because you can upload a file doesn't mean that people will see what you wanted them to see!

For example, if you upload a Microsoft Word document into your response and check the "plain text" or "HTML" radio button, your response will be filled with gobbledygook.

When dealing with files on the web (whether through Caucus or some other means), you must be careful about matching the type of file to how the user sees that file.  You don't want, for example, to try and display an image as text, nor would you want to display a Word document as an image!  Caucus tries to make that as easy as possible -- that's why the radio buttons "plain text", "HTML", "image", etc. appear on the upload page.

The next section describes what each of the radio buttons mean, and what files to use them with.  It also goes the other way: given a particular file type, it tells you the best approach(es) to uploading that file.

 

IV. File Types and the Upload Radio Butons

The upload page supplies 6 radio buttons that tell Caucus how to treat the uploaded file:

  1. Plain text means the file is just text -- no formatting.  The text is added to the end of your response as though you had typed it yourself in the response box.  "Plain text" files can be created with pure text editors, such as vi, pico, Microsoft Write, emacs, credit, BBEDIT, brief, and so on. 

    You can also create "plain text" files with Microsoft Word (and other applications), but you must use "Save As Text" or "Save as Text (with line breaks)", and then upload that file.  (In Word, chose "Save As", and then "text" from the list of possibilities.)

  2. HTML means the file is an HTML page (or HTML "fragment" -- it doesn't have to be a complete HTML page).  The contents of the file are added onto the end of your response, and your entire response is treated as HTML text. 

    If you do upload an entire HTML page, note that everything between the <HEAD> and </HEAD> tags is ignored by Caucus -- since the response is already inside the <BODY> part of an HTML page, any <HEAD> or <TITLE> tags are irrelevant.  Usually this will not matter, unless you've put some JavaScript between those tags. 

    Remember that HTML pages are a form of plain text!  If you write up an HTML page in, say, Microsoft Word, you must use "Save As Text" to save the file.

  3. Image means you've uploaded an image file (a gif or a jpeg file), and you want the image to appear inside your response.  If you've uploaded a really big image, it's often a good idea to make it a link, rather than show the whole image every time (see URL and "Link named" below).  Otherwise, your colleagues who are reading your response over a slower modem connection may be less than appreciative!  (The coolest approach is to put a "thumbnail" image in your response which in turn points to the full-sized image -- but that's beyond the scope of this document.)

  4. URL saves the file on the host web server, and puts a link to it in the response.  The link appears as the full URL of the file.  Then a person reading your response can click on the link to download the file to their browser, which will take some appropriate action.  (E.g., if the file is an HTML page, the browser will open a window and display that page.  If it's an image, it will display the image, and so on.)

  5. Link named (aka "named link") is the same as the URL method, except that you get to name the link whatever you want.  Since the names produced by the URL method are pretty long (and don't have much meaning), most people prefer this method.

  6. Zip file means that you are uploading a zip archive that contains many files.  Because the archive is itself a single file, this is the best way around the "one-file-at-a-time" limit imposed by the web.

    Caucus automatically unzips the archive, and lets you choose what to do with the unzipped files.  This is a good way, for example, to upload an entire web page, complete with HTML and graphics and anything else that is part of the page.

    The other way of looking at file uploading is to start with the particular type of file, and decide what you want Caucus to do with it.

    1. Plain text.  A small plain text file (for example, a short e-mail message) might appear directly in the response.  A very large plain text file is probably better off as a named link -- people can get it when they want, but don't have to see it every time they read your response.

    2. HTML.  Much like plain text, short HTML pages (or HTML fragments) are probably best off inserted directly in the response; larger HTML pages are best pointed to with a link.  Remember that uploading a file as HTML treats your entire response as HTML -- including any other text you've typed into the response.

    3. Images.  See the Image radio button description, above.  Note that some browsers may support newer image formats (such as PNG), and some may not -- when in doubt make the file a link.  (Remember!  Most browsers directly support only the .gif and .jpeg image types.  Other types of image files, such as .bmp, pict, .pcx, .tiff, .xbm, etc., must either be uploaded as a link, or the user must have an appropriate plug-in to see the file.)

    4. Microsoft Word or other word-processor documents contain formatting codes that browsers simply cannot understand, and will display as gobbledygook.  So you can't just upload the file and have it appear in your response, as is.  But you do have several options:

      • Translate it into HTML.  Recent versions of Word (and other applications) have a "Save As HTML" option that automatically translates the document formatting into HTML codes.  You can then upload the translated file as HTML (directly into the response) or as a link, and your colleagues can see the result immediately in their browser.  Warning: translators vary in the quality of the translation, although they are getting better all the time.

      • Upload it as a URL or named link.  Then people can click on it, their browser will download the file, and they can (usually) open the file in Word and view it.  (Usually your browser can be configured to automatically start Word and open the downloaded file.)

        BUT... there's a problem with this.  If you create your document, say, in Word 7 on a Macintosh, and someone is trying to read it in Word 6 on a PC... they may still see gobbledygook. 

      • Save as RTF and upload as a link.  This is the universal solution to the above problem.  All modern word processors allow you to save a document as an RTF file.  (RTF stands for "Rich Text Format" -- see What is RTF?) 

        RTF files are plain text files that contain special tags (like HTML but more precise) that preserve all of your formatting information.  Any word processor can read and interpret an RTF file written by any other word processor on any other platform.

        So, coming back to Caucus, if you have a large Word document that you want everyone in a conference to be able to read, your best bet is to "save as" RTF, and upload the RTF file as a named link.  The other people in the conference can click on the link, and read it with their local word processor (which will often be started up automatically by the browser).

    5. Spreadsheets and other application data files.  For the most part, any kind of data file that must be run with a specific application should be uploaded as a (usually named) link.  The reader can click on the link to download the file, and read it (either manually or automatically, depending on how their browser is configured) with that application.

      More and more applications have some sort of "Save as HTML" option that also allows you to save the data as an HTML page, which lets you post the HTML instead.  Which choice makes the most sense depends on how you expect people to use the data -- if they're just going to view it, HTML is fine.  If they have to edit it or work with it, you're probably better off keeping the data in its original form.

    6. PDF and other "embeddable" file types, including video clips (AVI) and audio streams.  The newest browsers support an HTML tag called <EMBED>, which allows you to embed certain kinds of files directly inside a response. 

      This is very much like the <IMG> tag, which browsers have always used to "embed" an image in the middle of HTML text.  Except in this case, unlike images, the browser must typically have a "plug-in" that provides the special functionality to display the file.

      Caucus does not directly support EMBED'able files in responses.  (You can, however, do it yourself by writing your own HTML response, of course.)  This technology is still new and doesn't work very well; as the browser support for EMBED improves, we expect to add a "Embed" radio button to the list of file types on the upload page.

     

    V. Macro ("%") codes for uploaded files

    You will notice that when you upload a file into a response (as an image or as a link), that some text beginning with "%" is added to your response. 

    These "%" codes are Caucus "macros".  The macros are automatically expanded, when the response is displayed, into the appropriate HTML codes to produce the <IMG> tag or <A HREF> tags needed to show the image or link.  The macros provide a compact and flexible way of representing your uploaded file, without forcing the entire response to be treated as HTML.

    For more information, see the Get Help link that appears just to the upper right of the Caucus response box.  There's also a FAQ entry on Caucus Macros. 

     

    VI. Problems

    Once you've successfully uploaded files into Caucus, there may still be circumstances in which a problem occurs when downloading that file.

    In particular, if you encounter problems downloading binary files (word documents, spreadsheets, power-point files, etc.), it may be necessary to make some changes to your web server software configuration.  This an issue for many web servers, it is not unique to Caucus.  Show this section to the administrator of your system (or whoever manages the web server).

    Possible problems include:

    • binary files appearing as text in a window (rather than being saved as a file, or automatically starting the appropriate application)

    • files being saved with a different extension (such as a .doc file being saved as a .exe file)

    In many cases it is necessary to tell the web server how to download certain kinds of files.  For example, it may be necessary to tell the web server that a ".ppt" file is a PowerPoint file, and should be treated appropriately.

    For many web servers, such as Apache, there is a file called mime.types that holds a list of associations between file extension and how it should be treated.  We recommend, in case of problems, that the system administrator add the following lines to that file: 

      application/PowerPoint    ppt PPT  
  application/msword        doc DOC
  application/msexcel       xls XLS
  application/octet-stream  Z bin zip exe mdb gz BIN ZIP EXE MDB GZ

    The first three lines handle specific types of files; the last line says that files ending in .Z, .bin, zip, .exe, etc. must always be treated as pure binary files.