SSI_Center

SSI Center v1.0 beta 5

This version for YaBB 1 Gold SP 1.3 only.

This is a beta mod. As with any mod, please backup your files before applying this mod.

Please read BEFORE installing and using this mod.

Features:

This mod creates a control center for creating content for Server Side Include statements (SSI statements) in the YaBB Admin Center.

The Admin may create SSI content files and then insert them into regular HTML pages on the same server as the forum. The mod supports SSI content using standard HTML or using YaBBC codes.

The use of YaBB's <yabb tag> tags are also supported.

All <yabb tag> tags provided by other mods should work as well. I tried to structure the mod so that <yabb tags> provided by future mods also work.

There are also options to create random rotating content for the SSI statements.

Most Whoson SSI tags have been converted to <yabb tags> to work inside SSI content files and the forum template.

To Install:

1. Modify your YaBB files manually or using BoardMod.
2. Load the new and modified script files to your server in ASCII mode.

Modified files:

SubList.pl
Subs.pl
Admin.pl
AdminEdit.pl
english.lng
NewcalIndex.pl (If you are using the Newcalendar mod, version 3.7a or higher, and you want to use the Whoson style upcoming events tag in SSI content files or the forum template then swap out your existing NewcalIndex.pl with the one provided with this mod.)

New files:

Variables/ssi_center.txt
Sources/SSI_Center.pl
Sources/SSI_Whoson.pl
YaBBHelp/SSI_Center_Help.html

3. Chmod Variables/ssi_center.txt to 666.

4. Load the gif files to your YaBBHelp directory in binary mode.

SSI_panel.gif
SSI_tutorial01.gif
SSI_tutorial02.gif
SSI_tutorial03.gif
SSI_tutorial04.gif

See FAQ at www.boardmod.org to learn more about installing mods.

How to Use

In addition to the instructions below, this help file includes a tutorial which shows step-by-step how to use this mod.

Definitions of terms used in this help file:

Below is a list of definitions of terms used in this help file. It is necessary to understand a few terms in order to understand the features/limitations of this mod and how to make the most of its use.

SSI statement: This is a Server Side Include tag that is added to an HTML file that is used to call content from another file or script. SSI statements are usually in the form: . While these statements are usually referred to as "SSI tags", for the purpose of this help file they will be called SSI statements to help differentiate them from the other types of tags discussed below.
HTML page: For the purpose of this help file, an HTML page is defined as any normal webpage not generated within the YaBB script.
SSI content: This is the stuff that is output when an SSI statement is invoked on an HTML page. It can be the output of a script or the contents of a file.
SSI content file: This mod creates files where the contents to be used by SSI statements are stored. When an SSI statement is invoked on a HTML page, the SSI content file is processed by the mod script and the output is included in the HTML page sent to the reader's browser.
YaBB tag: These are the <yabb menu>, <yabb im>, etc. tags generally used to place YaBB script output into the YaBB template. This mod provides a method of utilizing these tags as SSI content so they can be used on HTML pages. This mod also provides a method for SSI content to be used as new YaBB tags.
YaBBC code: These are the special formatting codes YaBB allows posters to use when composing messages. They include smilie codes :), text formatting codes [b]bold[/b], and object codes [img]http://www.mysite.com/myimage.gif[/img].
HTML format: This is SSI content written using standard HTML tags such as <b>, <br>, <a href...>.
YaBBC format: This is SSI content written using YaBBC codes such as [b], [hr], and [img].
Rotating format (HTML-R or YaBBC-R): This is SSI content written such that each line of content will be accessed idependently. This content will be displayed, one line per SSI call, as random - rotating content. Each time the SSI statement is invoked, a random line of content is taken from the particular SSI content file and output to the HTML page. HTML format and YaBBC formats are both allowed in Rotating format SSI content files however each content file can use only HTML format or YaBBC format (don't mix formats in a single SSI content file).

How to set up an SSI Content File:

Go to the SSI Center in the Admin Center. Here you will find a form similar to the one below.

When you load this page for the first time you will see that the "Edit Existing SSI Content Files Here" section of the form is empty. Beneath this is the "Add New SSI Files Here" section of the form where you will see a column of blank text boxes. Enter the name(s) you want to use for one or more SSI content files that you will create. All content file names must be a single word, no spaces or special characters; underscore_characters are okay. Note: If you use the same name twice, the file name will appear in the list twice but there will be only a single file. Deleting a duplicate file name will have the effect of wiping out the contents of that file. See the text box below for a list of reserved names that may not be used as SSI Content File names. Click the "Update File List" button.

Now you should see the file names you entered in the top portion of the form. Next to each file name you will see the Current Edit Format which shows the format (HTML, YaBBC, HTML-R, or YaBBC-R) the content file was last edited. The default is HTML. The next column offers two links: HTML or YaBBC. Clicking the HTML link opens the content file for editing in HTML format. Clicking the YaBBC link opens the content file for editing in YaBBC format. Files can be edited in any format and switching from one editing format to another is allowed but the finished content file must contain either HTML formatting or YaBBC formatting but not both.

The names of standard <yabb tags> may not be used to name your SSI content files. Below is a list of names that are not allowed.
Standard <yabb tags> are: <yabb main> <yabb menu> <yabb news> <yabb title> <yabb boardname> <yabb position> <yabb time> <yabb images> <yabb im> <yabb charset> <yabb uname> <yabb copyright>	Whoson-style <yabb tags> are: <yabb whosonpoll> <yabb whosonlatestmember> <yabb whosonusers> <yabb whosontime> <yabb whosonIM> <yabb whosonstats> <yabb whosonnewcal> <yabb whosonrecent> <yabb whosonchat> <yabb whosonbirth>
Other names not allowed are: SetLocation ext SetCookies1 SetCookies2 template copyin

Editing in HTML Format:
This is simply a text box where you can insert and edit HTML. YaBB tags may be entered here if desired (Remember YaBB tags are of the form <yabb tag> and should not be confused with YaBBC formatting codes. Check the "Save SSI content in HTML-Rotating Format?" box if you wish to save the SSI content as rotating content (see below). Click the "Save Info for SSI Content File" button when done.

Editing in YaBBC Format:
This is a message area similar to the YaBB Post page with YaBBC buttons available for formatting your message. YaBB tags may be entered here if desired. Check the "Save SSI content in YaBBC-Rotating Format?" box if you wish to save the SSI content as rotating content (see below). Click the "Save Info for SSI Content File" button when done.

Using Rotating Format (HTML-R or YaBBC-R):
Rotating content can be created in either of the two editors as long as the one item per line, one line per item convention is followed. Line wrapping is okay, line returns define the end of a line. Leave no blank lines if using rotating format.

Adding SSI Statements to your HTML Pages

Once you have created SSI content files in the SSI Center you can access them as you would most other SSI statements. Add the SSI statement below to the HTML page where you want the content to appear. Correct the statement to reflect the path to your YaBB forum from your root web directory. Note that many servers require that an HTML page carrying SSI statements have an .shtml extension instead of an .html or .htm extension.

Use these SSI statements to add the SSI content to your HTML page.

or, for YaBB.cgi users:

Using SSI Content as Yabb Tags <yabb tags> in your forum template:

Once you have created an SSI content file you can use it as a custom <yabb tag> tag in your forum template. Simply insert a <yabb name_of_your_SSI_content_file> tag where you want the content to appear in your forum template. Then go to the SSI Center and check the "Make YaBB Tag?" box for the tag you want to use. In order to minimize resource use by your forum, it is recommended that you only check the boxes for tags that you are actually using as <yabb tags> and leave the rest unchecked.

NOTE: Before using SSI Content based YaBB tags the "Activate SSI Center YaBB Tags?" checkbox must be checked in the Settings/Prefs section of the Admin Center. These tags are turned off by default in order to conserve server resources.

Nesting of SSI content:

Nesting occurs when one SSI content file contains a <yabb tag> derived from another SSI content file. One deep nesting is supported. In most cases the referenced content will work, however there may be cases where nested content fails to be processed. Experimentation may be needed to ensure that nested tags behave as you intend.

Using Whoson <yabb tags>

The SSI Center mod borrows routines from the popular Whoson mod by LooneyPandora to provide similar features as <yabb tag> tags. It is not necessary to have the Whoson mod installed on your forum to take advantage of these tags. To activate these tags go to the Admin Center => Forum Preferences & Settings page and place a check in the box next to "Activate SSI Center Whoson Tags?".

Here is a list of the tags and a brief description of what they do:

<yabb whosonpoll> Works with the showcase poll mod to place poll on page. Note: this tag is untested in this version of the SSI Center mod as I don't have the poll mod installed.
<yabb whosonlatestmember> Provided the name of the latest member to join and links to the Members list.
<yabb whosonusers> Provides a list of members currently using the forum and the number of guests.
<yabb whosontime> Provides the time and date in a table format.
<yabb whosonIM> Provides a login screen for guests or lets members know if they have any IMs.
<yabb whosonstats> Provides statistics about the forum (total members, posts, topics).
<yabb whosonnewcal> Provides the "Upcoming Events" information from the Newcalendar mod. Note: the Newcalendar mod and a special version of the NewcalIndex.pl file must be installed in order to use this tag (see installation instructions above).
<yabb whosonrecent> Provides a list of the most recent posts. Note: set number of posts to display in Admin Center >> Forum Prefs and Settings.
<yabb whosonchat> Provides a list of members and guests currently in the YaBBChat chatroom. Note: the YaBBChat mod, version 1.95 or higher, must be installed on the forum in order to use this tag. Also, this tag will not honor any access restrictions on joining the chatroom other than the allow/disallow guest chatting setting so use with care if you restrict your chatroom to specific member groups.
<yabb whosonbirth> Provides a list of members who have a birthday on the current date. Note: For forums with large memberships this tag can require a large server load.

The Whoson-style tags' output is in the form of tables. CSS style definitions are provided at the table cell level for each tag. In order to alter the appearance of the Whoson output it is necessary to add CSS style definitions to the calling HTML page for SSI statements or to the forum template if using these tags in your forum template. Here a list of the CSS style definitions that may be added/edited to suit. Only the CSS definitions for the tags you are actually using need to be added.

<style>

<style>

Using PHP Includes:

To use php includes, your server must have php installed and available to your hosting account, and most require that the html pages be named with a .php extension instead of .html or .htm.

To use PHP statements to include the SSI content to your page, add one of the following lines until you find one that works for you.

<?php virtual("./cgi-bin/yabb/YaBB.pl?action=ssic&ssicname=name_of_your_SSI_content_file"); ?>
<?php include('http://www.yoursite.com/cgi-bin/yabb/YaBB.pl?action=ssic&ssicname=name_of_your_SSI_content_file'); ?>
<?php @readfile("http://www.yourdomain.com/cgi-bin/yabb/YaBB.pl?action=ssic&ssicname=name_of_your_SSI_content_file"); ?>

You may have to replace "./cgi-bin/yabb/YaBB.pl" by your board path. If none of these php include methods work, use one of the other SSI methods.

Tutorial

The following is a brief tutorial designed to work on most YaBB forums. In this tutorial we will create four SSI Content files and then use them on an HTML page and as <yabb tags> in the forum template. This tutorial assumes that the reader has already properly installed the mod.

Lesson One: Creating New SSI Content Files
Go to the SSI Center page in your forum Admin Center. We are going to create four new SSI Content Files, the first named "pangolin", the second named "armadillo", the third named "coate_mundi", and the fourth will be called "gila_monster". To create these files enter pangolin in the first text box in the "Add New SSI Files Here" section of the form and armadillo in the second, and so on. Save these new files by clicking the "Update File List" button. You should now see the files we entered appear in the upper portion of the form as shown. Note that the default format for new files is HTML. We can change this default when we edit the files.

Lesson Two: Editing SSI Content Files in HTML Format
Next we are going to edit the pangolin SSI Content file using HTML format. Open the pangolin file in the HTML editor by clicking the HTML link in the "Select Edit Format" column. You will see a large text box to enter the HTML, a check box, and a Save button. For this file, let's create a very simple table and also see how to use YaBB's <yabb time> tag in an SSI content file. Copy and paste the following text into the HTML editor text box.

<table border="3" bgcolor="#FFFFCC">
<tr>
<td>This is the pangolin file contents.</td>
</tr>
<tr>
<td><yabb time></td>
</tr>
</table>

Click the Save button to save this file. Leave the checkbox un-checked. We'll discuss that option in the next step. When you click the Save button you will return to the SSI Center.

Lesson Three: Editing SSI Content Files in HTML-R Format
Now, le'ts edit the armadillo SSI Content file. We are going to use the HTML editor again so go ahead and click the HTML link for the armadillo file. This time we are going to use HTML Rotating format. When Rotating format is used, each line of the SSI content file is treated as a separate, stand-alone item. Scroll down to the bottom of the input form and place a check in the "Save SSI content in HTML-Rotating Format?" checkbox. Copy and paste the following text into the HTML editor text box.

This is the armadillo file contents.
<table border="3" bgcolor="#FFFFCC"><tr><td>This is the armadillo file contents.</td></tr></table>
<table border="2" bgcolor="#FFCCFF"><tr><td>This is the armadillo file contents.</td></tr></table>
<table border="1" bgcolor="#CCFFFF"><tr><td>This is the armadillo file contents.</td></tr></table>
<table border="3" bgcolor="#CCFFCC"><tr><td><yabb time></td></tr></table>

When we enter contents for Rotating format the basic rules to remember are "one item per line, one line per item, no blank lines". This means that each line of the file contains a single freestanding hunk of html. Lines can wrap and still be a single entry. The end of a line is marked by a line return. A single item can be plain unformatted text, a table, a hyperlink or an an extremely complicated nested table structure with lots of hyperlinks and formatting. As long as the three basic rules are followed there is virtually no limit to the complexity of html code you can enter as an item.

Be sure there are no blank lines in your file and click the Save button. You will return to the SSI Center. Note that the Current Edit Mode for the file armadillo is now HTML-R.

Lesson Four: Editing SSI Content Files in YaBBC Format
It is time to take a look at the YaBBC editor so lets edit the coati_mundi file. Open up the coati_mundi SSI Content file in the YaBBC editor by clicking the YaBBC link. The YaBBC editor should look familiar to you. The YaBBC buttons provide quick access to YaBBC formatting codes. All YaBBC formatting codes and smilies are allowed here. For folks using the Add More Smilies mod, the smilies format for those smilies is also supported but the buttons are not available yet. HTML tags may not be used in YaBBC format SSI Content files. Copy and paste the following text into the YaBBC editor text box.

[b]This is the coati_mundi file content.[/b]
[glow=red,2,300]Coatis are cool![/glow]
Here is the YaBB menu:
<yabb menu>
[quote]This text is in a quote block.[/quote]

Click the Save button at the bottom of the form. You will return to the SSI Center. Note that the Current Edit Mode for the file coati_mundi is now YaBBC.

Lesson Five: Editing SSI Content Files in YaBBC-R Format
Now we will edit a file in YaBBC Rotating format. Open the gila_monster SSI Content file in the YaBBC editor. Scroll down to the bottom of the input form and place a check in the "Save SSI content in YaBBC-Rotating Format?" checkbox. YaBBC Rotating format uses the same rules as HTML Rotating format: "one item per line, one line per item, no blank lines". Copy and paste the following text into the YaBBC editor text box.

[glow=red,2,300]Here be the gila_monster SSI content file[/glow]
[glow=green,2,300]Here be the gila_monster SSI content file[/glow]
The current YaBB time is <yabb time> :)

Click the Save button at the bottom of the form. You will return to the SSI Center. Note that the Current Edit Mode for the file gila_monster is now YaBBC-R.

We have created four SSI Content files and edited them using each of the four different formats. Next we will see how to use these files in generating an HTML page.

Lesson Six: Creating an HTML File which Includes SSI Statements
We will now create an HTML page incorporating the SSI Content files we created above. Open a new text file in a text editor such as Notepad. Copy and paste the following lines into the file:

<html>
<head>
<title>SSI Center Tutorial</title>
</head>
<body>
<h1>SSI Center Tutorial Page</h1>
<hr>
Below this line of text will be the output of the pangolin SSI Content file.
<br>

<br>
<hr>
Below this line of text will be the output of the armadillo SSI Content file.
<br>

<br>
<hr>
Below this line of text will be the output of the coati_mundi SSI Content file.
<br>

<br>
<hr>
Below this line of text will be the output of the gila_monster SSI Content file.
<br>

<br>
<hr>
<br>
End of SSI Content.
</body>
</html>

Save the file as SSI_Tutorial.shtml. The SSI statements in this HTML file are designed to work with many servers/forum setups but your setup may be different. You may need to edit the file to correct the SSI statements to work with your server. The directory path from your webroot directory to your YaBB.pl file may be different than the one given above. Also, if you use YaBB.cgi instead of YaBB.pl then you will need to correct the SSI statements to reflect this. Once you have corrected the SSI statements to work with your server, save the file again.

Let's see what we have created so far. Load this file to a web directory on your server and then open the file in a web browser. You should see something similar to this:

If you click the "Refresh" or "Reload Page" button on your web browser you should see that the contents displayed for the armadillo and gila_monster SSI statements changes. Click the "Refresh" or "Reload Page" button several times and watch how this content changes. This is called random rotation in that there is no particular order to when the different lines from these two content files are displayed.

Note that the YaBB menu produced by the coati_mundi SSI statement will look different on your page as my forum uses a different menu layout from most. You may have noticed that the menu shows the Admin link. This is because the SSI statements are processed via the main YaBB script so user cookie information is available when the SSI statements are processed. If a non-forum member were to view this page they would see the menu provided to guests instead of what you see.

Notes (the fine print):

When using multiple SSI statements on a single HTML page it is important to test your page to ensure that the SSI statements are not introducing conflicting HTML code. For example: If two content files contain differing CSS definitons for page properties then the results may not be as you expected.
If you wish to maintain consistency of appearance with your forum you may wish to include the CSS definitions section (style section) of your forum template in the <head> section the HTML page or in one of the SSI content files called by the page.
If you want to use a link in your SSI content that normally requires a javascript in the forum template you will need to provide that javascript either in the HTML page or in one of the SSI content files called by the page. For example the YaBBChat mod requires a javascript to open the chatroom window.
The SSI content is inserted as bare output. Use CSS and HTML formatting tags on your HTML page to position the output as you desire.

Lesson Seven: Using SSI Content Files as <yabb tags>
YaBB tags are special formating tags that allow the Admin to add, remove, and rearrange various parts of their forum template. An example of a YaBB tag that we have already seen is the <yabb time> tag. This is the tag that adds the date/time to the top of your forum. If you look at your forum template in the Admin Center you will find this tag. If you were to move this tag to somewhere else in your forum template, then the date/time would appear in that spot on every forum page. The SSI Center mod allows you to use the contents of an SSI Content file as a new YaBB tag. Let's try it!

We are going to activate the pangolin SSI Content file as a YaBB tag. First we must tell YaBB that we want to allow the use of YaBB tags generated from SSI Content files. To do this we go to the Admin Center>>Forum Preferences and Setting page. There we scroll down until we find the "Activate SSI Center YaBB Tags?" checkbox and place a check there. Scroll to the bottom of the page and click Save.

Now we will activate the pangolin SSI Content file as a YaBB tag. Go to the SSI Center. There is a column of checkboxs labeled "Make YaBB Tag?". Place a check in the box for the pangolin SSI Content file and click "Update File List". The pangolin file is now ready for use as a YaBB tag in the forum template. The format of this new YaBB tag is <yabb pangolin>.

Open the forum template editor in the Admin Center. Find the <yabb time> tag and add the new <yabb pangolin> tag right after it. Scroll down to the bottom of the page and click the Save button. The contents of the pangolin file should now apear next to (or just below) the date/time at the top of your forum. If you surf around your forum you will see that the pangolin stuff is at the top of every forum page.

Edit your forum template again to replace the <yabb pangolin> tag with a <yabb armadillo> tag. Click Save. You will see that the contents of the armadillo file don't show up at the top of the page! Remember that we have to activate the armadillo file as a tag before we can use it. Go to the SSI Center and check the "Make YaBB Tag?" box for the armadillo file and click the "Update File List" button. Now you should see the armadillo file content appearing next to the date/time at the top of the page. Surf around your forum to see how the armadillo contents change as different lines of the file are randomly displayed.

At this point you may wish to remove the <yabb armadillo> tag from your template so your users don't start posting questions about this strange new addition to your forum.

You may be wondering why the mod requires you to activate first the SSI Center YaBB tags and then each SSI Content file you want to use as a YaBB tag. Generating YaBB tags from SSI Content files places an extra load on your server in terms of processing time. The more tags that need to be processed, the more load on the server. The way the YaBB script works, the SSI Center YaBB tags need to be generated before the script knows if the Admin has even used them in the forum template. By checking the "Make YaBB Tag?" boxes for only the SSI Content files you are actually using as YaBB tags, you can reduce server load. If you are not using any SSI Center YaBB tags then leaving the "Activate SSI Center YaBB Tags?" setting in the Prefs/Settings section unchecked deactivates the entire routine and further reduces server load.

Lesson 8: Nesting SSI Content
The new YaBB tags we created in the last lesson can be used as content in other SSI Content files. In this lesson we will use the <yabb coati_mundi> tag to add the contents of the coati_mundi file to the pangolin file. Go to the SSI Center and open the pangolin content file in the HTML editor. Change the <yabb time> tag to <yabb coati_mundi> and click Save. In the SSI Center, check the "Make YaBB Tag?" box for the coati_mundi file and click the "Update File List" button.

Now open the SSI_Tutorial.shtml file on your server (or click "Refresh" if you already had the page open). The contents of the coati_mundi file should appear in the table created by the pangolin file where the YaBB time/date used to appear. Note that the coati_mundi YaBBC format codes work correctly even though the pangolin file is in HTML format. Nesting SSI Content is a way to use use mixed YaBBC and HTML formatting within a single SSI Content.

Summary:
We have used the SSI Center to create SSI content files in a variety of formats, making use of standard <yabb tags>. We have used SSI statements to add those content files to an HTML page. We have activated and used custom <yabb tags> based on SSI Content files. We have used nested SSI content to apply HTML and YaBBC formatting to a single SSI statement. This covers all the features of this mod.

Credits:

Author: Ironwing
http://www.mineralarts.com/cgi/yabbsp1/YaBB.pl

Thank you to LooneyPandora for providing the Whoson mod routines.
Thank you to Jake for extensive beta testing.
Thank you to ms_ukyankee for supplying the php instructions.