Configure and Customize ecWeb

ecWeb is a replacement for Synchronet's stock web interface. It offers a modern look, easy customization, and a threaded web forum-like view of a BBSs message boards and sub-boards.

The components of ecWeb are available from the Synchronet CVS. You'll need the latest copies of the following files & directories in order to proceed:

• ctrl/modopts.ini
• exec/load/webInit.ssjs
• web/lib/forum.ssjs
• web/lib/captchaLib.ssjs
• web/lib/captchaAnsis/
• web/root/ecwebv3/

Certain configuration values for ecWeb are stored in the [web] section of ctrl/modopts.ini:

[web]
;ecWeb config options
RootDirectory = /sbbs/web/root/ecwebv3
WebGuest = Guest
appendURL = /ecwebv3/
sessionTimeout = 43200
captchaLength = 5
maxMessages = 0

• The “RootDirectory” key specifies the location of the web-accessible components of ecWeb.

• The “WebGuest” key defines the alias of the account to be used for all unauthenticated browsing. Most Synchronet BBSs have an account named “Guest” which has a limited amount of access to the system. If you do not have such an account, or wish to define a set of restrictions specific to your web interface, then create a new user on your BBS. Grant this account only those permissions that you wish to extend to anonymous visitors to your BBS website. It's strongly recommended that this account not have the ability to post new messages on any sub-boards, for example.

• The appendURL key is a kludge that's required to make ecWeb's forum function properly during testing. Leave it alone for now - we'll come back to it later.

• The sessionTimeout key defines, in seconds, how long a user will remain logged in during periods of inactivity.

• The captchaLength key determines how many characters will be shown in the ANSI/ASCII art CAPTCHA on the new-user signup page.

• The maxMessages key specifies how many of a sub-board's messages will be loaded and sorted into threads. If you have thousands of messages in each sub and find that it's taking too long for the list of threads to appear after opening a sub-board in the forum, adjusting this value can help to speed things up. The default value of 0 means that all of the messages in a given sub-board will be loaded.

(You can ignore this section if you don't want to offer fTelnet or lightIRC on your website.)

ecWeb includes fTelnet by Rick Parrish and lightIRC by Valentin Manthei. Both of these Flash applications require a socket policy server to be running on your BBS. If you don't already have it, fetch exec/flashpolicyserver.js from the Synchronet CVS, and then add the following section to ctrl/services.ini:

[FlashPolicy]
Port=843
MaxClients=10
Options=NO_HOST_LOOKUP
Command=flashpolicyserver.js

This means that connections to port 843 of your BBS host will be handled by the script 'flashpolicyserver.js', so you'll want to make sure that port 843 is forwarded accordingly.

Now return to ctrl/modopts.ini and scroll to the [flashpolicyserver] section. Here you'll find a key called 'extra_ports'. If you plan on keeping lightIRC on your website, set this value to 6667. (Additional ports such as 513 for RLogin can be added here in a comma-delimited list.)

fTelnet also includes HTMLTerm, which is an HTML5 telnet application. If fTelnet fails to load or if you do not have a Flash socket policy service enabled, an attempt will be made to load HTMLTerm. HTMLTerm requires a WebSockets server to be running on your BBS to forward connections on to your telnet server. Synchronet also includes exec/websocketservice.js for this purpose. To enable it, add the following section to your ctrl/services.ini file:

[WebSocket]
Port=1123
Options=NO_HOST_LOOKUP
Command=websocketservice.js

(And don't forget to forward port 1123 to your BBS machine.)

Recycle your services (or simply restart your BBS) so that these configuration changes will take effect.

At this point in the configuration, ecWeb has not yet replaced your BBS' web interface. You're encouraged to test it for a while and see if it meets your needs before switching over.

To begin, navigate to:

http://your-bbs-host.whatever/ecwebv3/

If all goes well, you'll see the ecWeb interface in its most plain and basic form. Now it's time to start customizing ecWeb and adding content to your site.

All paths referenced in this section are relative to ecWeb's root directory, eg. /sbbs/web/root/ecwebv3.

This file is your ecWeb stylesheet. Once I'm fairly confident that I won't need to add more rules to this file, I'll provide a few alternate versions for users to pick and choose from.

If you want to change the colours, borders, spacing and certain aspects of the layout of your ecWeb installation, this is the place to begin. A brief description of the rules defined in style/style.css follows.

• body

The overall page. “color”, “background-color”, “font-*” etc. specified here will apply to the rest of the page, but will be overridden by styles applied to certain elements.

• a
• a:link
• a:visited
• a:hover
• a:active

The style of links (except for in the forum) by default, when visited, when being hovered over, when being clicked upon, etc.

• .ulLink
• .ulLink:link
• .ulLink:visited
• .ulLink:hover
• .ulLink:active

Same as 'a', but these rules are applied to all links in the forum.

• #container

This ruleset is applied to the element that holds all other elements on the page (the header, sidebar, main content and footer.) If you adjust its width, you'll need to adjust these other elements accordingly.

• #header

These rules are applied to the header (ie. where the name of your BBS appears at the top of the page by default.) You could define a background image here, for example.

• #content

This is the main content section of the page. If you want to use a different font or background colour here for some reason, you could define some rules herein.

• #sidebar

This is the box that contains the sidebar widgets (an important distinction.) By default it is an invisible container that holds <div> elements with the .sidebarItem rule (see below) applied to them.

• #footer

This is the footer of the page, where by default the version notice for your system appears.

• .font

I opted to define a .font class so that I could apply it to everything, including input boxes and textareas. This class contains the font rules that will be applied throughout your site unless otherwise overridden.

• .border

This is the border that's placed around various types of elements. You can make the width thicker if you want, or set it to zero to make it disappear, or just change the colour if you like.

• .box

The 'box' rules are applied to all of the various boxes on your pages. This is basically a way of keeping padding and margins uniform throughout your site.

• .indentBox1
• .indentBox2
• .indentBox3

The indentBox rules (1, 2, and 3) are used in the message forum to specify indentation of sub-board titles, message threads, and the messages within threads. Increase or decrease the 'margin' value as desired.

• .background

This rule is applied to all boxes on your site with the exception of the ones in the message forum. You could define all kinds of rules here, but the primary purpose is to give the boxes a different colour than the 'backdrop' (body background colour) of the overall page.

• .msg

Like 'background', but for the boxes in the message forum. Good if you want to define a higher-contrast colour combination for more comfortable message reading.

• .sidebarItem

This rule applies to each sidebar widget individually.

• .title

Page titles such as “Forum”, “Email”, “Telnet”, “IRC Chat” and so on use this class. If you want those titles to be bigger, smaller, bolder, italicized, etc., then set your preferences here.

You can add any number of sidebar widgets to your page by placing .xjs, .html, .txt or .ssjs files to the sidebar/ directory. By convention, the filenames of sidebar widgets begin with three digits, followed by a hyphen, followed by an arbitrary filename, followed by one of the aforementioned extensions. Sidebar widgets will load in ascending order based on filename, so you can change the first three digits of each file in order to alter their positions within the sidebar container.

Default sidebar modules include:

• 000-pages.ssjs

Scans the pages/ directory and generates a list of links to any non-hidden files therein

• 001-login.ssjs

Provides a login form and a link to the registration page for unauthenticated users, a logout link and an email link to logged-in users.

• 002-whosOnline.ssjs

A list of who's online on your BBS's terminal server.

• 003-systemStats.xjs

A table of BBS info.

The pages/ directory may contain any number of .xjs, .html, .txt or .ssjs files. Like the sidebar modules, these will be listed in ascending order based on filename. With the exception of the following simple rules, the contents of these files may be anything you wish.

The first comment line of an XJS or HTML file will be used as its title, and will determine how (or if) it is listed in the “pages” sidebar module. If you wanted to your page to show up in the list as “The Phil File”, then you would add a comment line near the top of the document reading:

<!--The Phil File-->

On the other hand, if you didn't want your page to show up in the list at all, you could put the word “HIDDEN” in the first comment line of the file, like so:

<!--HIDDEN-->

Of course, now if you want to share the link to this page with others, you'll need to reference it somehow. The way to do that is like this:

http://your-bbs-hostname.whatever/index.xjs?page=005-thePhilFile.html

This tells the main layout script of the site (index.xjs) that the user has requested a “page” with the filename “005-thePhilFile.html”. That file will be loaded into the main content box of the page.

In an SSJS file, the first comment line will determine its page title, so in this case you would make the first comment in the file read:

//The Phil File

or

//HIDDEN

In a .txt file, the first line of the document is treated as its title. If the first line reads “HIDDEN”, the text file will not be shown in the list of pages, and in this case when the file *is* loaded by index.xjs, the first line will be omitted.

See the pages/Templates/ subdirectory for some template files that you can use to create your own XJS, HTML, SSJS or TXT content to include in your website.

As mentioned previously, the file index.xjs is, in conjunction with style/style.css, responsible for most of the layout of items on the page. While a lot of customization can be made by modifying the stylesheet, there are some site-wide changes that you may wish to make (removing the sidebar; removing the name of your BBS from the header; removing the version notice from the footer, etc.) that can only be accomplished by editing index.xjs.

However, the purpose of this article is not to teach you how to write or modify HTML & XJS files. Back up your index.xjs before you start making modifications, and good luck with that. :D :D :D

Okay, so http://your-bbs-host.whatever/ still displays the stock Synchronet web interface, and you don't want to have to tell people to browse to http://your-bbs-host.whatever/ecwebv3/ in order to see your shiny new customized ecWeb install. There's a solution for that.

In ctrl/sbbs.ini, scroll to the [Web] section and change the value of the “RootDirectory” line to read:

RootDirectory = /sbbs/web/root/ecwebv3

(Alter that path according to where Synchronet is installed on your system, of course.)

Then open ctrl/modopts.ini and scroll down to the [web] section, and change the “appendURL” line to read:

appendURL = /

With this done, create an 'errors' subdirectory inside of your /sbbs/web/root/ecwebv3/ directory, and then copy the contents of /sbbs/web/root/errors/ into it.

Recycle your webserver or restart your BBS. ecWeb should now be configured as your standard web interface.

• howto index