Macrobyte Resources Conversant Developer Central
Internet groupware development platform
What is Conversant? The Long Version


What is Conversant?

The Long Version

Over the years, many people have asked the question, "What is Conversant? What does it do?"

If this little bit of light reading doesn't answer that question, perhaps nothing ever will.

This document is an interactive outline. Usage guide:

  • Any underlined headline can be collapsed (or re-expanded) with a single click.
  • Shift-click to fully collapse (close) an "expanded" (open) headline, and all of it's sub-heads.
  • Shift-click to fully expand (open) a "collapsed" (closed) headline, and all of it's sub-heads.
  • Alt-click (option-click on mac) an expanded headline to fully expand all subheads.
  • Try it out!

Collapse Outline
Expand Outline

  1. Conversant's Feature List
    1. Note that this is not a marketing document. It's a description of the software.
    2. Some of it is technical, some is not.
    3. It's not exhaustive.
  2. A conversant "server" is the root of everything. The server is made up of the following:
    1. System preferences
      1. These settings generally control how the server operates, such was what plugins are enabled.
    2. Server Administrators
      1. These are user accounts that have full control over everything on the server. Sysops.
    3. Twine
      1. Twine is our "abstraction layer" for nearly everything. It lets us change where our data is stored and how it is accessed without having to rewrite any part of Conversant itself.
      2. For example, Twine makes it possible store all of one site's content within a Frontier database (a .root file), another site's content in the file system, and yet another site's content in a sql database. The same is true for membership data and preferences.
    4. The Conversant software itself
      1. Conversant is basically a programming interface for interacting with various parts of the data and the plugins.
      2. Conversant has no user interface except for the administrative preferences system, which is a web site.
    5. Conversant plugins
      1. This is where all of the real features are implemented.
      2. There are currently more than 30 plugins for Conversant.
      3. Conversant is like an operating system, or a "platform." The plugins are the applications written for it.
      4. More on plugins, below.
    6. Zones
      1. Zones are containers. They don't have a user interface, there's no web site or email address for a zone. They exist simply to provide a grouping for related sites and user accounts.
      2. A Conversant server can contain any number of zones.
      3. More on zones, below.
    7. Overview
      1. The following graphic/table is intended only to help you visualize the containment (or hierarchy) of data in Conversant.
        Server Admins
        System Preferences
        Zone "marketing"
        • carol@yourcompanycom
        • etc...
        • marketing department
        • main blog editors
        • public
        • sales support
        • project a
        Zone "infotech"
        • etc...
        • it department
        • help desk editors
        • main blog editors
        • public
        • help desk
        • migration project

  3. Zones are containers for everything else, including:
    1. Conversations (individual sites)
      1. Conversations are where you find the user interface. Web sites, mailing lists, nntp news groups, etc., etc. These things are all "Conversant conversations."
      2. A zone can have any number of conversations (sites).
      3. Conversations are for the content.
      4. More on conversations, below.
    2. Membership Accounts (users)
      1. A zone can have any number of members, from 0 to infinity.
      2. Can post and edit their own messages.
      3. Can set their own preferences through a conversation's preferences page
    3. Zone Administrators
      1. Members (see above) which have been given administrative privileges.
      2. Can administer anything in the zone, including users, groups, and conversations, plugins, etc.
    4. Groups (of users)
      1. Where would a groupware system like Conversant be, without groups?
      2. A zone can contain any number of groups.
      3. Collections (lists, subsets) of the users in a zone.
      4. Can be used in many places that a single user might be used.
        1. For example, a weblog's "editor" can be a single user, or an entire group. When it's a group, everyone in the group has the ability to post to the weblog.
    5. Plugins
      1. Plugins which are enabled at the server level can be enabled or disabled at the zone level.
      2. More on plugins, below.
    6. Preferences database.
      1. Zones have a dedicated preferences database to track all of the settings for everything in the zone.
      2. Most preferences are provided by plugins, to customize the features provided those plugins.
      3. Some preferences are general to a zone, others are specific to each conversation, each member, or even a specific member when interacting with a specific conversation.
  4. Conversations
    1. Conversations are contained with a zone.
    2. offer security options for controlling:
      1. Can new members sign up on their own?
      2. Guest access (can anyone who is not a member, or not logged in, access the site?)
      3. Cookie vs. "Password Dialog" (HTTP-Auth) login requirements
      4. There's more on security, below.
    3. Conversations are thought of in a number of different ways, all of which are accurate:
      1. a web site with a flat or threaded discussion group
      2. a weblog
      3. a mailing list
      4. a NNTP newsgroup
    4. Conversations contain:
      1. A message database
        1. the basic unit of content in Conversant
        2. messages are indexed as soon as they are posted to the database, for the built-in search engine
        3. More on messages, below
      2. Custom fields
        1. Any number of additional fields can be added to your message database.
        2. Fields (built-in and custom) always have unique names.
        3. Different types of fields are available:
          1. text fields
          2. dates
          3. numbers
          4. lists of pre-defined values (where you choose one, or more than one)
          5. boolean fields (true or false values)
        4. Data is stored in the message database, with each message.
        5. Indexed for the search engine, automatically.
      3. A web site
        1. Can have any number of web pages
          1. Traditional web pages, just "static" content built from a message.
          2. Dynamic pages like weblogs, search engines, discussion boards, message posting / editing forms, etc.
          3. More on web pages, below.
        2. Messages can be posted through the web site.
        3. Messages can be accessed at their own URL, within a web site, as if they were web pages.
        4. Stylesheets
        5. Nearly everything can be served as an RSS feed, including search engine queries, weblogs, discussion threads, and more.
        6. Javascripts
        7. Several built-in, permanent web pages:
          1. logon
          2. logoff
          3. signup
          4. /[msgnum] (messages all have numbers)
          5. /[msgnum]/reply
          6. /[msgnum]/edit
      4. A mailing list
        1. Also known as an email discussion list
        2. Dedicated email addresses for posting messages, subscribing, and unsubscribing.
        3. Members can post messages by sending an email to the conversation
          1. If the message is a reply to another message, it's "threaded" properly
        4. Members can "subscribe" to a conversation's mailing list, so new messages are mailed to them automatically.
        5. Messages sent to the mailing list from the conversation can be in plain text or html format
        6. Can be controlled by external mailing list software like majordomo
          1. When a mailing list has many members, this option is more efficient.
      5. A NNTP newsgroup
        1. Similar to email, messages are posted, replied to, and read by "NNTP clients".
          1. Mozilla and Outlook are both very good NNTP clients, and there are many others for all operating systems.
      6. Templates
        1. Generally used for designing the structure and display of content
        2. Templates have different "types." Some examples:
          1. web page templates
          2. message templates for the web
          3. message templates for email
          4. various weblog templates
          5. many others
        3. Template "typing" makes them easier to organize and manage.
        4. Templates use "macros" to import content. (More on macros, below.)
      7. Resources
        1. bits of simple, pluggable content, such as image tags, links to web pages, or boiler-plate text
        2. resources are inserted into templates or messages by entering the name of the resource within |vertical pipes|
        3. whenever a resource is encountered in a message or template, it is replaced with its value from the resource database
        4. for a simple example:
          1. this text:
            1. Please contact |me by email| with any questions.
          2. might have it's resource replaced and end up looking like this:
            1. Please contact <a href="">me by email</a> with any questions.
          3. Later, if you decide that you don't want to publish your email address, you could change the resource so that the link points to a contact form on a web page. So, you change the URL in the resource, and the link is instantly changed everywhere that the resource has been used.
      8. An administrative web site
        1. Attach and detach members to/from the conversation (using the pool of members in the zone)
        2. Manage your web site's files and folders
        3. Manage the mailing list
        4. Manage templates
        5. Manage resources
        6. Change conversation preferences (settings)
      9. Wizards
        1. Group administrative tasks together into simple, web-based wizards.
        2. Only available to administrators.
        3. Existing wizards include:
          1. Bulk membership management
            1. use a tab-delimited text file to create or change many members at once
          2. Look and Feel
            1. set some basic preferences for the web site's HTML
          3. New Conversation
            1. makes it easy to create new conversations with pre-defined features
          4. Site Security
            1. set access restrictions for a conversation
        4. (There are other wizards, too.)
      10. Conversation (site) administrators.
        1. Similar to zone admins, they are members of the zone.
        2. Can administer only the site, not the entire zone.
        3. No control over member preferences, or groups.
        4. Limited access to the administrative site.
      11. A member-preferences web site
        1. Any logged-on member can access the members page.
        2. Allows members to set their own preferences, such as:
          1. full name
          2. password
          3. subscribed to the mailing list?
          4. (many more)
  5. Plugins
    1. What are plugins?
      1. Plugins are mini-programs designed to work within and to enhance Conversant
      2. They provide features, some very small, some quite large
      3. Nearly all features in Conversant are written in plugins because Conversant itself is designed mainly to provide a stable, standard API
      4. Conversant is like an operating system, or a "platform." The plugins are the applications written for it.
    2. Conversant's plugins provide much of the functionality seen by users:
      1. web server itself is implemented as a plugin.
      2. mailing list service is a plugin
      3. newsgroup is a plugin
      4. xml-rpc service is a plugin
    3. Almost all of the web pages are actually provided by plugins
      1. the search engine interface (not the indexer), weblogs, message thread pages, wizards, event calendars, etc.
      2. More on pages, below.
    4. 99.9% of macros are actually scripts contained in the plugins.
      1. (More on macros, below.)
    5. Read-only templates.
      1. can be used anywhere, and copied, but can not be edited
      2. gives the user something to start with when customizing a site
    6. Plugins can easily provide extend Conversant's xml-rpc interface (great for web programming)
    7. Callbacks
      1. Almost every function in the Conversant API provides at least one callback for overriding or enhancing the default behavior.
      2. Make it very easy to write simple plugins, and possible to write very powerful plugins.
    8. Can be enabled or disabled on a zone-by-zone and conversation-by-conversation
    9. Can specify preferences for zones, members, conversations, groups, and combinations thereof.
      1. Combinations?
        1. A good example is the email plugin. It provides preferences which are specific to members that are attached to a conversation. Subscription to a conversation's mailing list is a "plugin-member-conversation" preference. This means the preference is provided by the plugin, belongs to the user, and is specific to a single conversation. (Specific to a single conversation because the user can subscribe to one conversation's mailing list, but that doesn't mean he wants to subscribe to the mailing lists for all of them.)
  6. Messages
    1. The basic unit of content
    2. Nearly all pages are built from at least one message
    3. Can contain HTML, macros, and resources (or just plain text)
    4. edit with a wysiwyg editor
    5. have their own, unique URLs
    6. can have any number of attachments, just like email
      1. a.k.a. "enclosures"
      2. pictures, word documents, PDFs, quicktime movies, whatever
      3. every attachment is given a unique URL, automatically
    7. edit a message by adding "/edit" to the URL
    8. reply to a message by adding "/reply" to the URL
    9. once in the conversation, you can do anything with a message: post it to a weblog, find it in the search engine, reply to it, publish it to a "traditional" web page, delete it
  7. Macros
    1. Conversant's very own, very simple scripting language.
    2. Syntax is based on the format for HTML comments. Every macro begins with "<!--#" and ends with "-->"
    3. Macros are usually the names of special scripts provided by plugins.
      1. When a web page or email is being served, the macro scripts are called, and the macro (in the content) is replaced with the result.
      2. So, for example, <!--#msgsubject--> could be rendered as What is Conversant? The Long Version
        1. and <!--#msgsubject link="true"--> could be rendered as What is Conversant? The Long Version
    4. There are hundreds of macros.
      1. Some are general purpose, like the #msgSubject and #member macros.
      2. Others are specific to particular types of pages, such as weblogs and search engines.
    5. Conditional macros (branching)
      1. if / elseif / else / endif
      2. special type of macros (not found in many other systems).
      3. allow conditions (at the time the macro is being processed) to dictate what parts of a page are included, and what parts are eliminated entirely
      4. example use: hide admin-only links on a web page from anyone who is not an administrator
  8. Web pages
    1. the most basic web page is a message, at a url like
      1. uses a "message template" to describe the contents of the page (where to put the subject, the author, the body text, etc.)
      2. message template is rendered into html, and then embedded in the overall page template
      3. message pages are "built in"
        1. you don't have to create a special page to view them in a browser
        2. Just add the message number to the site's URL.
      4. See above for more on messages.
    2. other built-in web pages:
      1. /signup: allow new members to sign up by providing at least an email address and password
      2. /logon: allow members to provide their username (email address) and password so that the server will recognize them
        1. logging on is required for posting messages through the browser
        2. some conversations don't allow any access at all without first logging on
        3. a cookie is stored in your browser after you log on, so that when you return to the site you don't have to log on again
      3. /logoff: deletes your membership cookie
        1. mainly useful when you've logged on from a public terminal (so that others can't use your account)
      4. /__NewThread__: for posting a new message that is not a reply to another message
    3. The rest of this section lists the other types of pages provided by Conversant's plugins.
    4. Search Engine pages (2)
      1. Queries can be cached, so that the same search runs every time the page is loaded. Very good way to list all the pages in a certain category (for example)
      2. If the query is cached, the search results can be cached also, for performance.
      3. A macro allows you to insert the results of a query anywhere else in a conversation.
      4. Search results can be in RSS (or Atom) instead of HTML
    5. Published messages
      1. a message can be published to a url with a filename like "mypage.html" instead of just the message number
    6. Discussion Forum pages:
      1. a "DG Calendar" page shows what messages were posted on a given day, and offers a calendar for browsing by date
      2. "full thread" page shows all of the messages in a thread
        1. starts with the first message, and then shows every reply, and all replies of replies, etc.
        2. can be sorted by replies, or chronologically (chrono is better for "flat" message boards)
      3. "HTMLArea" page makes wysiwyg editing possible in Mozilla and IE (and Safari under Tiger)
      4. Topics page lists all of the disucssion topics (threads) in a conversation, chronologically
      5. The query pages can also be used as tools to enhance the discussion group
    7. Directory mirror
      1. Makes it easy to create another version of a page (or all the pages in a folder), such as a "printer friendly" page
    8. Enclosure page
      1. Publish a message's enclosure (an attachment) to any URL in your conversation's web site, so that the same file is available in both places.
      2. So, a file which was originally available here:
      3. Can be served from here:
      4. Note that this is really serving the enclosure, as the name implies. If you change the enclosure, the "enclosure pages" will automatically serve the new file. This is great for pictures which occasionally change.
    9. Event calendar
      1. supports month, week, and day views
      2. Events can be categorized. categories are shown by coloring the events and/or adding an icon
      3. event descriptions are stored as messages!
        1. So, members have a natural place to discuss an event on the calendar.
    10. Mailform Page
      1. If you don't want to give out your email address, this is the next best thing.
      2. User enters his/her email, a subject, and a body. When submitted, message is sent.
      3. Will only send email to the member(s) specified in the admin settings (spammers can't use it to broadcast their junk mail)
    11. Redirect page
      1. when the browser sends a request to this page, they're redirected to a different URL
      2. more powerful than it sounds
      3. can be used to redirect all requests for a directory to some other directory
      4. (mainly useful when a directory or file has been deleted)
    12. Weblogs
      1. Old weblog page served us well for almost four years
      2. new weblog page is unbelievable. "Is there anything it doesn't do?"
      3. unfortunately, it seems the new weblog page will never be "soup"
      4. multiple editors (group weblogs)
      5. categories ("channels")
      6. automatically produces rss feed
      7. produces rss feeds for individual channels, combined channels, and even "query" feeds
        1. for example, an rss feed could contain "only the posts which contain the words macrobyte or conversant"
    13. Web Outline
      1. Create a hierarchical display of the entire site, or just a given directory
      2. depth is variable, so it can show the contents of sub folders to any level
      3. very useful as a sort of "table of contents"
      4. there's a macro for doing something very similar, which you can see in action here
        1. the benefit of the macro is that it can be put into any page, instead of requiring a dedicated page
  9. Security
    1. IP Banning - block a single address or an entire range
    2. Three membership levels:
      1. Guest - anyone who does not have an account or has not logged in
      2. Member - anyone with an account any who is logged in (so the server knows who this is)
      3. Administrator - a member who has been given sysop privileges
    3. Options based on membership level:
      1. Allow everybody to view the whole site
      2. Prevent guests (anyone not "logged in") from viewing the discussion group
      3. Prevent guests from seeing except the logon form
      4. Use "HTTP-Auth", so logon uses a challenge dialog instead of an HTML form, so guests will see nothing (and users are forced to log on every time they visit)

    4. Labels allow message-by-message restrictions
      1. Viewable by anybody
      2. Viewable only by members
      3. Viewable only by administrators
      4. Plus, labels are inherited by new replies that are added to the message after the label is set.
      5. Setting a label is as easy selecting from a popup menu when editing the message
  10. Other stuff
    1. RSS client features
      1. There's a macro that can be used to download RSS feeds from anywhere on the internet, and display the contents (through custom templates) on any web page. You can even put the results into an email template!

Last update: 1/18/2005; 12:08 PM

© 2002 Macrobyte Resources. All rights reserved.