The Template Manager interface allows the board administrator to update the look of the board and to edit template file directly through the WWW browser. The Template Manager also permits the installation of template sets, or "skins," which can provide a coherent set of integrated templates. The Template Manager is an interface that has significant functionality, and its documentation is divided into the following sections:

1. Basics of Discus Appearance "Skins"
• Introduction to Discus Appearance Skins
• The Special "None" Skin
• Security Notes for Skins
• DiscusWare's Distributed "Safe" Skins
• Previewing Skins
• Applying Skins
2. Developer's Guide to Skins and Customizations
   • Determining Which File to Edit
   • Methods of Editing Files
   • How Discus Determines Which Template to Use
   • Additional Information
3. Skin Creator
   • Read Me First
   • How to Create a Skin
4. Template Editors
   • Important Advisory
   • How to Use the Template Editors
5. Frequently Asked Questions (FAQ)
   • 5A. When I edit my templates, why don't changes appear on my board?
   • 5B. How do I change the background color of the top line in the topics table?
   • 5C. How do I change the background color of the top line in the subtopics table?
   • 5D. How do I change the alternating color scheme?

1. Basics of Discus Appearance "Skins"

This section permits the board administrator to implement pre-made template sets, or "skins," that will control the templates for the entire board. These "skins" include and supercede the following templates from the Discus administration directory:

• addmessage-private.conf
• addmessage-public.conf
• newpage.conf
• messages.conf
• subtopics.conf
• topics.conf

A Discus "skin" file has the following attributes:

• It is created with the Discus format for a skin file
• It has the extension .skin
• It is placed in the Discus administration files directory

The Special "None" Skin

One special "skin" is named "None" and is always the first entry in the table. If this skin is selected, Discus does not read the template information from any .skin file; rather, it takes its input directly from the appropriate template files. Listed in the table are all skins that are found in the Discus administration directory, and the radio button next to the currently working skin is checked for the user. The name of the skin, as well as the author, copyright information, and description are displayed.

Security Notes for Skins

Skins are template files for Discus that control aspects of how the pages are generated on the Discus board. There are several considerations that you must make when you choose to install a skin. These include:

1. The skin will be in control of files created on your web server. Just as you wouldn't give someone you didn't know permission to access your server and do whatever they want, you should not install a skin from an untrusted source without first looking it over.

2. An intentionally or accidentally miswritten skin could cause data loss on your board, and this data may not be recoverable.

3. The author attribute of the could be forged. The only skins distributed by DiscusWare, LLC that are created by DiscusWare are those available from the "Template Gallery" in the Discus Support Center. If you got the skin from anywhere else and the authors claim to be DiscusWare, or any person associated with DiscusWare, it may not be an actual skin written by DiscusWare.

4. DiscusWare recommends installing only those skins you obtain through the Discus Template Gallery, found at this location. Installing skins from other sources may result in data loss or security problems!

5. The author name is just a text attribute in the skin, and there is no guarantee that the author's name that appears on the skin is actually the person or organization who created the skin. The only skins distributed by DiscusWare, LLC that are created by DiscusWare are those available from the "Template Gallery" in the Discus Support Center, or the four skins distributed with Discus (classic, updated classic, tables, and support forum). If you got the skin from anywhere else and the authors claim to be DiscusWare, or any person associated with DiscusWare, it may not be an actual skin written by DiscusWare.

DiscusWare's Distributed "Safe" Skins

DiscusWare, LLC distributes four skins along with the Discus software package. These distributed files are indicated by the symbol *Safe* as they appear in the menu of available skins. These skins can be trusted as verified by DiscusWare, LLC even though you have not downloaded them from the Template Gallery. EXCEPTION: If you have downloaded a skin from somewhere else that is named classic.skin, updatedclassic.skin, supportforum.skin, or tables.skin, and overwrote the existing skin, the file may not be safe. However, if you have done this, we assume you know what you are doing and that you have verified the integrity of the skin you downloaded. Just because a skin is not designated as safe does not mean that it is unsafe. It merely means that the skin was not part of the Discus distribution and you should exercise due caution when installing it.

Previewing Skins

It is possible to preview your Discus Appearance Skin before saving and applying it to the board. To do so, select the skin you wish to preview and click the "Preview" button. You can preview the topics page, a list of subtopics, and a list of messages. The list of subtopics and list of messages for your preview is taken from actual data on your board (the most recently active discussion topic having a child page with between 4 and 15 subtopics or messages is chosen for the preview).

Note that previewing is a good and recommended first step toward verifying the integrity of the skin. If you see malicious code occurring when previewing the skin, you know that it should never be installed. However, malicious code or improper construction may not be apparent from your preview! You should still follow the precautions noted above before choosing to install any skin.

If you are using topic descriptions, be sure these descriptions appear in the preview of the topic list. Some topic list templates do not contain code necessary to insert topic descriptions. If you are not using topic descriptions at this time, but you believe you may in the future, look at the last topic on your topics list. A sample description is specified for that topic. If no sample description appears, the skin you are considering does not support topic descriptions.

Previews of skins are shown as if you have chosen to accept the skin's pre-defined color, font, and alternating color schemes, if such schemes are defined. If those schemes are not defined, your current settings are used in the preview.

If you have selected "None" from the list, the preview that is shown is of your current newpage.conf, topics.conf, subtopics.conf, and messages.conf files, as if you had made them into a skin and then installed it on your board. Please note that if you are designing new templates and trying them out in preview mode, you should put your board into Maintenance Mode by selecting that option in your Options Manager. If you do not, and any activity (like a post) takes place on your board while your new, untested template file is on your system, you could experience data loss, as that template will be used when regenerating the affected pages.

Applying Skins

When you have obtained a skin from a reputable source and verified by inspection that the skin is appropriate for your needs and will not corrupt your data, the skin can be installed as follows:

1. Upload the file, file.skin, using FTP to your Discus administration directory (the same directory that contains the discus.conf file). Use ASCII mode. Permissions on the file can be set to 0755 (rwxr-xr-x).

2. Log into administration as the superuser and go to the Template Manager interface.

3. Check the radio button next to the skin you wish to install and click the "Save and Apply" button.

4. Read carefully any information given on the ensuing "Skin Validator" interface.
   • Basic Information About Skin: Gives the name of the skin, the author, the copyright information, and the description of the skin. Keep in mind that the author can be forged. Specifically, do not trust any skins claiming to be from DiscusWare that you did not personally download from DiscusWare's template gallery.

   • Grant Appearance Change Request: If the skin you are installing contains a recommended color scheme, that color scheme is presented. The color scheme controls the background, text, unvisited link, visited link, and active link colors. If you want to give the skin permission to overwrite your current color scheme, check the box immediately to the left of the heading. If you do not give the skin permission, your current settings will not be changed.

   • Grant Font Change Request: If the skin you are installing contains a recommended font scheme, that font scheme is presented. The font scheme controls the font size and face. If you want to give the skin permission to overwrite your current font scheme, check the box immediately to the left of the heading. If you do not give the skin permission, your current settings will not be changed.

   • Grant Alternating Color Change Request: If the skin you are installing contains a recommended alternating color scheme, that alternating color scheme is presented. The alternating colors appear in some templates in the topics, subtopics, and messages section, and are generally used in conjunction with background colors in tables. If you want to give the skin permission to overwrite your current font scheme, check the box immediately to the left of the heading. If you do not give the skin permission, your current settings will not be changed.

   • Potential problems found with this skin: Discus provides a rough (NOT thorough) analysis of the skin, checking it for major problems. Any problem denoted as "High Risk" is probably reason enough for you not to install the skin. You should be sure that you thoroughly understand any "High Risk" error message before you choose to install a skin, as you may subject yourself to unrecoverable data loss or security vulnerabilities by using the skin with such risks. Moderate risk situations and low risk situations are also presented; these situations would not result in data loss, but malicious code could cause your board to behave in undesirable ways.

5. After you have assessed the skin for security and integrity concerns, if you decide to apply the skin to your board, click the "Save and Apply" button. Wait for the Discus board to go through the normal regeneration cycle, at which time any change requests are processed and the board is regenerated with your template settings.

   Note that the entire text file for the skin is displayed at the bottom of the page for your reference.

2. Developer's Guide to Skins and Customizations

The first step in customizing the appearance of your board is determining which file to modify. To do this, go to your Template Manager and note the radio button that is checked in the "Choose" column. If the button next to "None" is checked, then you should edit the individual *.conf files in your Discus administration directory. If any other button is checked, observe the bold file name in the "Name" column to know what skin file to edit. For example, if the button next to tables is checked, then you need to edit the "tables.skin" file.

Methods of Editing Files

You can edit files in one of two ways. The first is to use the built-in Discus template editor by clicking on the appropriate file name from the "Template Editors" section at the bottom of the Template Manager. (Hint: if you want to change the size of the text editor box, look in your Options Manager.) The second method of editing files is to use a TEXT editor (such as NotePad or UltraEdit) on your local machine (or a text editor on the server itself). If you use this method, be absolutely certain that you transfer files by FTP using ASCII mode only. Also, we strongly recommend that you do NOT use a WYSIWYG editor (such as Word, Front Page, Netscape Composer, Page Mill, etc.) when editing template files or skins.

How Discus Determines Which Template to Use

Discus determines the templates to use in the following order:

1. newpage_dynamic.conf is used if the need is for the page template, the screen is dynamic (except in previewing skins), and this file exists.

2. Any *.conf file within the topic directory (e.g., $html_dir/messages/2/newpage.conf), if the operation includes building a topic page.

3. The configuration file from the "default.skin" file within the topic directory, if the operation includes building a topic page.

4. The file is obtained from the corresponding file within the skin, if a skin is selected.

5. The original template file from the administration directory is used, if it exists.

6. Discus returns an error if you are at this point and none of the above steps worked.

Notice, in particular, that if you have selected a skin, then the individual template files in your Discus administration directory are ignored. To customize the appearance of the board, you must either customize the skin directly or stop using the skin (perhaps manually extracting the data into the individual template files). Please read Determining Which File to Edit if you need additional assistance.

Additional Information

DiscusWare maintains a library of customization documents in the Discus Support Center. The Support Center also features a search engine. You can find the Support Center at this location:

If you experience any problems in editing and applying skins, please read the FAQ section below. If you still have problems after reading this document, consult the Support Center.

3. Skin Creator

The DiscusWare Skin Creator allows you to share your customized template files with other Discus users by distributing them as skins. We suggest that you send skins to DiscusWare, LLC and let us distribute them from our site should you choose to do this. Discus users will not be likely to trust third-party skins, as we advise them not to in this document, for obvious reasons. For this, an automatic submission utility is included in the skin creator utility.

If you have selected "None" as your currently applied skin, the Skin Creator works by creating a skin from your individual template files (newpage.conf, messages.conf, ...) in your administration directory. If you have modified the look of your board by modifying another skin file and have selected a skin file for display on your board, this section will simply print out or submit the skin file you are currently using on your board. This is a slight departure from behavior in the earlier versions of Discus that included this skin creator section.

How to Create a Skin

To create a skin, fill in the following items:

• Name of Skin: We suggest a short (50 characters or less) name for your skin.

• Your Name: Enter your first and last name or the company you represent.

• Copyright Info: Enter copyright information for the skin. We suggest "Public Domain" if you are giving away the script with no copyright, or "Copyright (c) 2000, yourname" if you wish to copyright the skin.

• Description: Enter a description of the skin (500 characters or less) that describes what the user will see from the various templates.

Then decide whether the color scheme your board is currently using should be bundled with the skin. If you have hard-coded some color information into the skin, you will probably want your color scheme and alternating colors to be bundled with the skin. If you do, check the "Write my board's color scheme with this skin" box. This color scheme consists of the values you have entered in your Board Manager in the "Board Appearance" section.

Also decide whether you want your board's alternating color scheme to be distributed with the skin. If you do, check the "Write my board's alternating color settings with this skin" box. This alternating color scheme consists of the values you have entered in your Options Manager in the alternating colors section.

When you have entered the desired parameters, click the "Save to Your Computer" button. This will present the skin you created in the browser window. Click in the frame with the text and use the "Save Frame As..." command from your browser's "File" menu to save the file to your hard disk (your browser's actual commands may vary). You have now saved the skin file on your hard drive.

If you would like DiscusWare to add the skin to our template gallery, click the "Submit to DiscusWare" button. This will bring up a screen that allows you to send the skin directly to our server, where we will review it and consider making it publicly available for download. We appreciate your contributions sincerely!

4. Template Editors

The Template Manager interface allows the superuser to edit template files directly through a WWW browser rather than editing the files and transferring them to the server. DiscusWare, LLC does not support the editing of templates or configuration files. Resources describing how to edit those files are contained in the Discus Support Center.

How to Use the Template Editors

Status of files: If the file is reported as "Read/Write," you will be able to edit the file through the Template Manager and save your changes. If it is reported as "Read Only," you will be able to view the content but you will not be permitted to save your changes. To make the file have "Read/Write" privileges, if it does not already, log in by FTP and change permissions on the desired file to 0777 (rwxrwxrwx).

Editing a file: Click on the file name to edit the file. An editor box (generated by JavaScript) will pop up in a new window for editing. The size of the window that pops up and the size of the text box within that window can be changed in the Options Manager interface under "General, Miscellaneous Options." If you wish to use your own text editor, this is fine. Obtain your template files by FTP, edit them locally with a text editor, and transfer them back to your server once they are edited.

After you have edited a template file, you may need to regenerate your board from your new templates. Click on the provided link for more instructions.

5. Frequently Asked Questions

5A. When I edit my templates, why don't changes appear on my board?

This is the most frequently asked question, and it has two possible explanations. These are as follows:

Explanation 1: You did not regenerate your board

If you have changed a template file or a skin, you need to regenerate the pages on your board in order to display your changes from the template. There are several ways to regenerate your board:

• You can regenerate all parts of your board through the Template Manager by choosing to "Save and Apply" the skin you have edited, or "None" if you have edited templates directly.

• You can regenerate specific parts of your board through the Board Manager if you do not need to regenerate every portion of the board. See the Board Manager for details.

Explanation 2: You edited the wrong file

If, after regeneration, your changes still did not show up, it is likely that you edited the wrong file. For help on determining which file you need to edit, please read the section of this document entitled Determining Which File to Edit.

5B. How do I change the background color of the top line in the topics table?

This setting is hard-coded into the topics.conf file. You need to edit the topics.conf file (or the topics section of your selected skin) to change this value. See Determining Which File to Edit to determine which file needs to be edited.

5C. How do I change the background color of the top line in the subtopics table?

This setting is hard-coded into the newpage.conf file (NOT the subtopics.conf file). You need to edit the newpage.conf file (or the topics section of your selected skin) to change this value. See Determining Which File to Edit to determine which file needs to be edited.

5D. How do I change the alternating color scheme?

Read the section on alternating colors in your Options Manager documentation. In short, go to your Options Manager and set it up there. You will then need to regenerate your board as explained in explanation 1 to FAQ 5A.