Custom Forum Structure

A new version is available. Please use it instead.

The third revision of Black's Custom Forum Structure script suite, now more powerful and easier to use than ever! This script allows full customization of your forum's appearance by placing control of its structure directly into your hands. It is written in JavaScript and tailored specifically for forums hosted on Jcink's hosting service, and is provided as an alternative to JAWN's Custom Board Rows script.

No credits except the ones included in the Javscript files are required.

Features

Speed Comparisons

These tests were conducted only using scripts that altered the forum index. The tests include JAWN's Custom Board Rows, the old Custom Forum Structure, and the new Custom Index module, the latter two of which were tested with both string and function inputs.

A comparison of script execution times on a Jcink forum with three categories and twelve forums. Presented are averaged values sampled from data acquired by repeated testing.
J's CBR CFS(string) CFS(function) CIm(string) CIm(function)
Mozilla Firefox 59.59ms 5.92ms 12.36ms 4.09ms 4.15ms
Google Chrome 75.00ms 5.50ms 13.50ms 5.50ms 6.00ms
A comparison of script execution times on Jcink forum markup padded to include 41 categories and 390 forums. File size for the page came to around 594KB. Presented are averaged values sampled from data acquired by repeated testing.
J's CBR CFS(string) CFS(function) CIm(string) CIm(function)
Mozilla Firefox 56360.19ms 86.49ms 87.82ms 57.19ms 62.90ms
Google Chrome 155953.66ms 88.00ms 95.00ms 87.66ms 96.33ms

What's New

The script has been completely overhauled to make it easier to install and configure. Features that were not available in previous releases have been added to this version of the script.

  1. Forum moderator information(Forum Led by: ...) is now available in the Custom Index module.
  2. <span> tags in forum descriptions no longer break the Custom Index module.
  3. Calendar-related statistics are now fully supported in the Custom Stats module.
  4. The personal portal-style profile and IPB1.3.1's default profile are both supported by the Custom Profile module.

Several completely new features have been included as well.

  1. Only the Custom Index module still requires the <!-- |input_act| --> wrapper variable.
  2. The Custom Index module now works on forums set to display like categories.
  3. Custom profile fields are now enumerated automatically.
  4. Forums are now assigned an id attribute that corresponds to their forum id.
  5. Forums with new posts in them have an additional class attribute, .has-new-posts, added to them.
  6. Pagination has been added to the Custom Topics module.

Installation

Place the following in the document header.

<script src="http://elegantexpressions.us/black/cfs.min.js"></script>

Wrap your <% BOARD %> wrapper tag in a <div> with an id of #board. This id may be changed if it causes conflict with a skin.

<div id="board"><% BOARD %></div>

Initialize the desired modules immediately after the new #board wrapper. If you don't want to use a specific module, don't call its init() method.

<script>
customIndex.init({
	page: "<!-- |input_act| -->",
	html: ""
});
customStats.init({
	html: ""
});
customProfile.init({
	html: ""
});
customTopics.init({
	html: ""
});
</script>

However, this script is a tool, not a magic wand- and tools are for building. Put your hard hats on and let's learn about some of the unseen changes the script makes behind the scenes and then the various config options and output values available to you.

Output Reference

Each module automatically makes certain additions to the HTML markup of the page aside from what you place in the html property of each module's init() method. These are shown here, in bold, to help with styling.

Output Reference - Custom Index module

<div id="board">
	<div class="tableborder">
	(Repeat for each category)
		<div id="cat_#">
			<div id="section-#">
				<div class="section-before">
					(Only appears if addBefore is defined)
				</div>
				<div id="row-#" class="new-row has-new-posts">
					(contents of the "html" property here)
					(Repeat for each forum row)
				</div>
				<div class="section-after">
					(Only appears if addAfter is defined)
				</div>
			</div>
		</div>
	</div>
</div>

Configuration

All configuration settings may be adjusted by passing an optional JavaScript object named conf to any module's init() method. Properties of this object are used to override each module's default configuration options, which are described below. If you are not changing any of the default configuration settings, you do not need to include it.

As an example, to change the id that is used to read the <% BOARD %> wrapper tag in the Custom Index module from #board to #a-different-id, you would override the target configuration property like so:

customIndex.init({
	page: "<!-- |input_act| -->",
	html: "",
	conf: {
		target: "a-different-id"
	}
});

Configuration - Custom Index module

The default configuration options for the Custom Index module would appear as follows if they were to be called in its init() method.

customIndex.init({
	page: "<!-- |input_act| -->",
	html: "",
	conf: {
		target:			"board",
		subforumSeperator:	", ",
		subforumNone:		"This forum has no subforums.",
		addBefore:		false,
		addAfter:		false,
		dateDefault:		"--",
		titleDefault:		"----",
		authorDefault:		""
	}
});
target
The id of the element used to read the <% BOARD %> wrapper tag. Set to "board" by default.
subforumSeperator
A string used to seperate links to subforums in {%subforumlist}. Set to ", " by default.
subforumNone
A string used in place of {%subforums} when there are no subforums to display. Set to "This forum has no subforums." by default.
addBefore
HTML markup inserted inside a <div> element with a class attribute of .section-before at the beginning of each category. Set to false by default.
addAfter
HTML markup inserted inside a <div> element with a class attribute of .section-after at the end of each category. Set to false by default.
dateDefault
A string used by the forum software to indicate that the most recent post does not exist, e.g., that there is no date to display. Set to "--" by default.
titleDefault
A string used by the forum software to indicate that the most recent post does not exist, e.g., that there is no title to display. Set to "----" by default.
authorDefault
A string used by the forum software to indicate that the most recent post does not exist, e.g., that there is no author to display. Set to "" by default.

Configuration - Custom Stats module

The Custom Stats module does not have any configuration options.

Configuration - Custom Profile module

The default configuration options for the Custom Profile module would appear as follows if they were to be called in its init() method.

customProfile.init({
	html: "",
	conf: {
		target:			"board",
		photoDefault:		"No Photo",
		avatarDefault:		"",
		reputationDefault:	"0",
		htmlEnabled:		false,
		interestsDefault:	"No Information",
		messageText:		"Send Message",
		emailText:		"Email"
	}
});
target
The id of the element used to read the <% BOARD %> wrapper tag. Set to "board" by default.
photoDefault
HTML markup used in place of a missing profile photograph. Set to "No Photo" by default.
avatarDefault
HTML markup used in place of a missing avatar. Set to "" by default.
reputationDefault
A string used in place of a reputation value of "none". Set to "0" by default.
htmlEnabled
A flag used to determine if this module should parse the Interests section of the profile for HTML. Set to false by default.
interestsDefault
A string used in place of an empty interests field. Set to "No Information" by default.
messageText
A string used as the text in the profile's PM link. Set to "Send Message" by default.
emailText
A string used as the text in the profile's Email link. Set to "Email" by default.

Configuration - Custom Topics module

The default configuration options for the Custom Topics module would appear as follows if they were to be called in its init() method.

customTopics.init({
	html: "",
	conf: {
		target:			"board",
		announcementsDefault:	"Announcements",
		pinnedDefault:		"Important Topics",
		regularDefault:		"Forum Topics",
		noTopics:		"No topics were found. This is either because there are no topics in this forum, or the topics are older than the current age cut-off."
	}
});
target
The id of the element used to read the <% BOARD %> wrapper tag. Set to "board" by default.
announcementsDefault
A string used by the forum software to label board-wide announcements in the topic list. Set to "Announcements" by default.
pinnedDefault
A string used by the forum software to label pinned topics in the topic list. Set to "Important Topics" by default.
regularDefault
A string used by the forum software to label regular topics in the topic list. Set to "Regular Topics" by default.
noTopics
A string used by the forum software to indicate that there are no topics in the topic list. Set to "No topics were found. This is either because there are no topics in this forum, or the topics are older than the current age cut-off." by default.

Values

This is where the script has changed the most. Each module now comes with a bult-in string parser that searches for values and replaces them with information extracted from the forum markup, removing the necessity of messy string concatenation.

Values follow a simple pattern, {%valuename}, and are included inline in the html property of the init() method. As an example, using the Custom Index module each forum's link and description can be output on separate lines by using the {%link} and {%description} values like so.

customIndex.init({
	page: "<!-- |input_act| -->",
	html: "{%link}<br />{%description}"
});

Values - Custom Index module

{%marker}
The forum's marker.
{%link}
A link to the forum, including the forum's title.
{%id}
The forum's numerical id, as displayed in {%link}'s URL(/index.php?showforum={%id}).
{%description}
The forum's description.
{%moderators}
A list of the forum's moderators.
{%subforums}
The contents of the forum's subforum listing, including "Forum Led by:" notice.
{%subforumlist}
A standalone list of links to each of the forum's subforums, seperated by subforumSeperator.
{%topics}
The number of topics.
{%replies}
The number of replies.
{%lp-date}
The date of the forum's latest post.
{%lp-title}
A link to the forum's latest post, including the title of the topic.
{%lp-title#link}
The URL of the forum's latest post.
{%lp-author}
A link to the author of the forum's latest post, including the author's name. If the author was unregistered, returns a string with the author's name instead.

Values - Custom Stats module

{%users}
The total number of users online.
{%users#guests}
The number of unregistered users online.
{%users#registered}
The number of registered, non-anonymous users online.
{%users#anonymous}
The number of registered, anonymous users online.
{%users#list}
A list of online users, with links to their user profiles.
{%sort#activity}
A link to the online list, sorting by activity.
{%sort#username}
A link to the online list, sorting by username.
{%birthdays}
The number of birthdays currently displayed on the statistics.
{%birthdays#list}
A list of the usernames celebrating a birthday today and their age.
{%events}
A list of forthcoming calendar events.
{%stats#posts}
The total number of posts on the forum.
{%stats#members}
The total number of members on the forum.
{%stats#newest}
A link to the profile of the newest registered member, including their username.
{%stats#most}
The most users ever online at once.
{%stats#date}
The date the most users ever online at once record was set.
{%online-today#total}
The number of users who have logged in today.
{%online-today#most}
The most users ever online in one day.
{%online-today#date}
The date the most users ever online in one day record was set.
{%online-today#list}
The list of users who have logged in today.

Values - Custom Profile module

{%id}
The user's numerical id, as displayed in the URL(/index.php?showuser={%id}).
{%avatar}
The user's avatar.
{%name}
The user's name.
{%group}
The user's group.
{%photo}
The user's profile photograph.
{%reputation}
The user's reputation value.
{%title}
The user's title.
{%location}
The user's location.
{%birthday}
The user's birthday.
{%website}
A link to the user's website.
{%interests}
The user's interests.
{%joined}
The user's join date.
{%status}
The user's status, either online or offline.
{%activity}
If the user is online, what the user was doing last.
{%last-active}
The date of the user's last activity.
{%posts}
The user's post count.
{%aim}
The user's AIM contact information.
{%yahoo}
The user's Yahoo! contact information.
{%gtalk}
The user's Google Talk contact information.
{%msn}
The user's MSN contact information.
{%skype}
The user's Skype contact information.
{%pm}
A link to send the user a personal message.
{%email}
A link to email the user.
{%signature}
The user's signature.
{%visitors}
The profile's latest visitors.
{%comments}
The profile's latest comments.
{%comment-form}
The profile's comment form.
{%friends}
The profile's latest friends.

Custom Profile Fields

Custom profile fields are a special case. They may be used by including {%field#_} values, where the underscore is a number representing that custom field. For example, {%field#1} would be the first custom profile field.

Values - Custom Topics module

{%id}
The numerical id of the topic, not the forum.
{%folder}
The topic's folder icon.
{%marker}
The topic's marker icon.
{%title}
A link to the topic, including the topic's title.
{%title#link}
The URL of the topic link.
{%pagination}
Topic pagination controls(Pages: 1, 2, etc.).
{%description}
The topic's description.
{%starter}
A link to the profile of the topic's starter, including the starter's name. If the starter is unregistered, returns a string with the starter's name instead.
{%replies}
The number of replies the topic has received.
{%views}
The number of times the topic has been read.
{%date}
The date of the most recent post.
{%author}
A link to the author of the most recent post in the topic, including the author's name. If the author is unregistered, returns a string with the author's name instead.
{%checkbox}
For moderator controls. Not including this in some form makes moderating topics on the topic view impossible.

Functions & Conditionals

The html property of the init() method accepts both strings of regular text and functions. The following two codes result in the same output.

customIndex.init({
	page: "<!-- |input_act| -->",
	html: "{%link}<br />{%description}"
});
customIndex.init({
	page: "<!-- |input_act| -->",
	html: function() {
		var output = "{%link}<br />{%description}";
		return output;
	}
});

It is not currently possible to parse strings for conditional statements, but individuals with some knowledge of JavaScript can utilize simple functions to achieve the same effect. If a value is not extracted from the forum markup, it is automatically assigned a false or falsey value. One can therefore determine if that part of the markup exists by checking if its corresponding value exists. For example, to output the value of {%subforumlist} only if there are actually subforum links to list, you could use the following function.

customIndex.init({
	page: "<!-- |input_act| -->",
	html: function() {
		var output = "{%link}<br />{%description}";
		if(this.vals["{%subforumlist}"]) {
			output += "<br />{%subforumlist}";
		}
		return output;
	}
});

This is especially useful for values that may or may not appear in forum markup, like subforums, pagination controls, and custom profile fields.