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

This document describes how to customize the appearance of subtopic 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 subtopic 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.

1. Subtopic Placement in Skin

Subtopics are defined for each discussion page, placing them in the "page" part of a skin (explain parts of skins). DiscusWare-distributed skins note this location within comments in the skin. The general structure for the list of subtopics is:

<#if $head->{param} =~ match(Sublist)#>
  Code that defines how the list of subtopics looks
<#endif#>

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

2. Two Types of Subtopics

Discus recognizes two separate types of entries in the subtopic list. There are ordinary discussion board pages (referred to as "subtopics" in this document) that contain messages, other subtopics, about messages, and other content within the board. There are also links to external URLs (referred to as "external links" in this document) that appear within the subtopic list but that are not themselves actual discussion board pages. The vast majority of entries in a subtopic list in a typical Discus implementation are subtopics. Most Discus implementations don't use external links at all.

3. Two Ways to Write Subtopics

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

If Discus is writing "raw" subtopic data, the variable $general->{subtopic_raw} is guaranteed to be 1, and the "raw" data itself is found in the variable $pginfo->{sublist_raw}.

If Discus is regenerating the list of subtopics from your template, the variable $general->{subtopic_raw} is guaranteed to be 0. Thus, well-written skins will always follow this structure:

<#if $head->{param} =~ match(Sublist)#>
  Code appearing before subtopics (e.g., opening tables)
  <#if $general->{subtopic_raw} == 1#>
    $pginfo->{sublist_raw}
  <#else#>
    <#foreach $subtopic (@subtopics)#>
      <#if $subtopic->{type} == 0#>
        Code for regular subtopics
      <#else#>
        Code for links to external pages
      <#endif#>
    <#endloop#>
  <#endif#>
  Code appearing after subtopics (e.g., closing tables)
<#endif#>

You will be customizing only the code that appears in red italics. The other code should be left alone (we can't think of a single instance where the non-italicized code above should be edited).

For regular subtopics (not links to external URLs), the following variable substitutions are available in a subtopic list:

Variable Result $subtopic->{type} 0 (it's always 0 for a regular subtopic) $subtopic->{number} Unique identifying page number for subtopic $subtopic->{property_emot} Emoticon (e.g., 'happy.gif') $subtopic->{icon} Subtopic icon (e.g., 'tree_n.gif') $subtopic->{descr} Subtopic description $subtopic->{last_poster} Name of last poster $subtopic->{msg_count} Message count (number of messages in and under) $subtopic->{subs} Page count (number of pages under, plus 1 for the page itself) $subtopic->{originator} First poster for the subtopic $subtopic->{lastmod} Last modified date (unix time format)

For links to external documents, the following variable substitutions are available in a subtopic list:

Variable Result $subtopic->{type} 1 (it's always 1 for a link to external document) $subtopic->{number} Unique identifying page number for link $subtopic->{property_emot} Emoticon (e.g., 'happy.gif') $subtopic->{icon} Link icon (e.g., 'tree_m.gif') $subtopic->{descr} Link description $subtopic->{url} URL that's linked to $subtopic->{target} Target frame (e.g., '_blank' or 'Main') $subtopic->{name} Name for the link $subtopic->{properties} Properties (intended for storage, not display)

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 subtopic list is regenerated, all of your subtopics may disappear!

All regular subtopics start with the following code:

<!--Top: $subtopic->{number}-->

This indicates to Discus that there is a subtopic with a certain number linked from that position.

To enable subtopic descriptions, the following code must be used (the HTML comment tags indicate to Discus exactly what text is part of the description:

<!--Descr-->$subtopic->{descr}<!--/Descr-->

If your subtopic list spans more than one line, the following line must be present to indicate to Discus that it is done reading that subtopic:

<!--/Top-->

In all DiscusWare-distributed skins, we set apart the first and last identifier tags within comments in hopes that you will not edit them:

## ----- \/ Do not change \/ -----
<!--Top: $subtopic->{number}-->
## ----- /\ Do not change /\ -----

You customize this code

## ----- \/ Do not change \/ -----
<!--/Top-->
## ----- /\ Do not change /\ -----

Links to external documents have a similar structure. They all begin with:

<!--URL: $subtopic->{number}-->

Links to external documents have their data stored in escaped format (this is because there is no actual page on the board where this data can be stored as a primary source):

<!--Data: <#escape "$subtopic->{url}"#>-<#escape "$subtopic->{target}"#>-<#escape "$subtopic->{properties}"#> -->

Again, any descriptions for the link are stored within comment tags:

<!--Descr-->$subtopic->{descr}<!--/Descr-->

And, links to external documents end with:

<!--/URL-->

In DiscusWare-distributed skins, the parts you can and can't edit are again set forth with comments. We strongly encourage you to respect our suggestions within the comments -- you have absolutely no reason to edit the portions of the code that we put in comments and say that you should not edit.