If you do not want to learn about the gory details of the message skins, feel free to skip ahead to the variable lists.

Introduction

This document describes how to customize the appearance of message lists for a board running Discus 4.0 or higher. Here, you will learn what variables can be used, find out what elements of your message list are important to the program, and view some examples of possible customizations.

This document also assumes you understand how skins work and how to regenerate your board after you have made changes to a skin. This procedure is briefly summarized here:

1. The skin file you need to edit is normally found in the "skins" subdirectory of your administration directory. You can see what skin you've selected by clicking the "Skins" tab in the appearance manager.

2. Your skin should be edited using a plain text editor, NEVER an HTML editor such as Front Page. Or, you can use the built-in editor through the Appearance Manager interface.

3. When you upload an edited skin to your server, transfer the file in ASCII mode.

4. For your changes to show up on your board, after uploading your skin, you must regenerate your board through Appearance Manager.

5. WARNING: Improper customization or editing of skins can result in unrecoverable data loss. Therefore, it is strongly suggested that you make a complete backup of all data on your discussion board before editing skins. In the Backup Manager (Discus Pro only), create a minimal backup.

About Messages in the Skin

1. Message Placement in Skin

Messages are defined for each discussion page, placing them in the "page" part of a skin (explain parts of skins). For simplicity, DiscusWare-distributed skins have an "include" of a part of the skin called "individual_message" that is called from within the "page" part of the skin. Most customization of messages, therefore, is accomplished through editing of the "individual_message" part.

The general structure for the list of messages within the "page" part is:

<#if $head->{param} =~ match(Messages)#>
  Any "header" information for messages
  <#if $general->{messages_raw} == 1#>
    $pginfo->{messages_raw}
  <#else#>
    <#foreach $message (@messages)#>
      <#insert part ($head->{topic_number}) "individual_message"#>
    <#endloop#>
  <#endif#>
<#endif#>
Any "footer" information for messages

If messages are enabled on the page in question, the variable $head->{param} will contain "Messages" and the code you put in this section will be executed.

2. Two Ways to Write Messages

Generating a list of messages through a template requires significantly more computational resources than simply writing out text onto the template. Thus, when a list of messages has not changed but a page is regenerated, Discus will not iterate through your messages, but will instead simply write the exact same "raw" data that was in place before.

If Discus is writing "raw" message data, the variable $general->{messages_raw} is guaranteed to be 1, and the "raw" data itself is found in the variable $pginfo->{messages_raw}. There is no guarantee about @messages when raw data is being written.

If Discus is regenerating the messages from your template, the variable $general->{messages_raw} is guaranteed to be 0.

Typically, you will be customizing the "header" and "footer" portion noted above, as well as the "individual_message" part of the skin, which is repeated over and over again. We have also documented a way to format the first message in a thread differently from all of the others.

The @messages array will contain each message in the order on which the messages are to be displayed on the page. Assuming the element is called $message, as in the example code above, the following may be defined for any particular message:

Variable/Code Description of Value $message->{number} The post identifier for the message. This is a unique index used in may cases, internally, to refer to this particular message. $message->{time} Time, in unix time format, that the message was posted.

How Discus Reads Messages

This is a very important section! It is important that your changes to the skins do not corrupt or interfere with the ability of Discus to read the data on your page. If you do corrupt the internal data structure, the next time that the message list is regenerated, all of your messages may disappear!

All regular messages start with the following code:

<!--Post: $message->{number}--><!--Time: $message->{time}-->

This indicates to Discus that there is a message, identified by a unique number, and posted at a particular time, starting in this position.

To enable storing a profile link or e-mail address with posts, the following comment tag is used to set this value apart:

<!--email-->(e-mail address or profile link)<!--/email-->

The author of the message is identified with a comment tag as well. Typically the following structure will be used without alteration:

<!--name-->$message->{author}<!--/name-->

The actual text of a message is set apart with a comment tag. Typically the following structure will be used without alteration:

<!--Text-->$message->{text}<!--/Text-->

In some skins, one or more "fields" is stored with a message. Fields can contain such displayed information as the author's cumulative number of posts. Sometimes they contain hidden values that are used to generate a human-readable string, such as an author's status. Fields are set apart in comment tags like so:

<!--field:FIELDNAME-->(some value)<!--/field-->

In the above example, the name of the field is "FIELDNAME." On all regenerations of the page, this would set the variable $message->{field_FIELDNAME} to whatever was found in the field when the message was read. Capitalization is important when you're naming fields - in the above example, $message->{field_fieldname} or $message->{field_fIEldnAme} would be undefined.

In some cases it is necessary to hide an "internal" value of a field, while displaying something based on that internal value to the end-user. In that case, a special "use" comment tag can be used within a field comment tag, like so:

<!--field:FIELDNAME--><!--use: xxx--><!--/field-->

As you can see, the actual HTML code above will display nothing to the end-user, but it will store a value of xxx for the field name. It is assumed that, later on, you will do something based on the value that is found in the field name. An example of this is how the author's status is looked up in the tables2/tables3 skins.

Fields can be introduced onto a page in one of two ways:

• Placed there automatically by the program or template, hard-coded. For example, a poster's browser can be stored permanently in a field called "browser" with the following code snippet, which checks to see if the field was previously defined, and if not, attempts to read something from the environment.

  <#if $message->{field_browser} eq ""#>
    <#if $ENV{HTTP_USER_AGENT} ne ""#>
      <!--field:browser-->$ENV{HTTP_USER_AGENT}<!--/field-->
    <#endif#>
  <#else#>
    <!--field:browser-->$message->{field_browser}<!--/field-->
  <#endif#>
  

• Placed there by virtue of a customized add-a-message box. Consult the message box documentation for details, but be aware that a form field named (for example) "FORMNAME" from a message box will become available as $message->{field_FORMNAME} to the final message, and $preview->{field_FORMNAME} when the message is being previewed.

A post is always ended with:

<!--/Post: $message->{number}-->