Differences

This shows you the differences between two versions of the page.

--- howto:ecweb [2014/06/25 20:57] – [Requirements] Sure, why the fuck not. ecbbs
+++ howto:ecweb [2021/05/23 17:10] (current) – deleted digital man
@@ Line 1: / Line 1: @@
-====== 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.
-=====Requirements=====
-ecWeb will work with Synchronet 3.16 or higher.
-The components of ecWeb are available from the Synchronet CVS.  You'll need the latest copies of the following files & directories (along with their contents, including all subdirectories, in case you need to be told that) in order to proceed:
-  * [[dir:ctrl]]/modopts.ini
-  * [[dir:exec]]/load/msgutils.js
-  * [[dir:exec]]/load/webInit.ssjs
-  * [[dir:exec]]/load/xjs.js
-  * [[dir:web]]/lib/forum.ssjs
-  * [[dir:web]]/lib/ecutils.js
-  * [[dir:web]]/lib/captchaLib.ssjs
-  * [[dir:web]]/lib/captchaAnsis/
-  * [[dir:web]]/root/ecwebv3/
-=====Configuration=====
-====modopts.ini====
-Certain configuration values for ecWeb are stored in the ''[ecweb]'' section of ''[[dir:ctrl]]/[[config:modopts.ini]]'':
-  [ecweb]
-  ;ecWeb config options
-  RootDirectory =../web/root/ecwebv3
-  WebGuest = Guest
-  appendURL = /ecwebv3/
-  sessionTimeout = 43200
-  captchaLength = 5
-  maxMessages = 0
-=== RootDirectory ===
-This key specifies the location of the web-accessible components of ecWeb.
-=== WebGuest ===
-This 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.
-=== appendURL ===
-This 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.
-=== sessionTimeout ===
-This key defines, in seconds, how long a user will remain logged in during periods of inactivity.
-=== captchaLength ===
-This key determines how many characters will be shown in the ANSI/ASCII art CAPTCHA on the new-user signup page.
-=== maxMessages ===
-This 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.
-====Flash Socket Policy Server====
-(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 [[:service:flashpolicyservice|Flash Socket Policy Server/Service]] to be running on your BBS.  If you don't already have it, fetch ''[[dir:exec]]/flashpolicyserver.js'' from the Synchronet CVS, and then add the following section to ''[[dir:ctrl]]/[[config: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 ''[[dir:ctrl]]/[[config: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.
-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 ''[[dir:exec]]/websocketservice.js''' for this purpose.  To enable it, add the following section to your ''[[dir:ctrl]]/[[config: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 (the [[:server:|Synchronet Services Server]] should automatically restart upon modifying your ''[[dir:ctrl]]/[[config:services.ini]]'' file, but changes to your ''[[dir:ctrl]]/[[config:sbbs.ini]]'' may require a manual recycle/restart).
-====Testing====
-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.
-=====Customization=====
-All paths referenced in this section are relative to ecWeb's root directory, eg. /sbbs/web/root/ecwebv3.
-====style/style.css====
-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.
-====The Sidebar====
-You can add any number of sidebar widgets to your page by placing [[server:web|.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.
-====Pages====
-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" at the start of the first comment line of the file, like so:
-  <!--HIDDEN:Secret Page-->
-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:Secret SSJS
-In a .txt file, the first line of the document is treated as its title.  If the first line begins with "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.
-====Layout====
-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.
-====Restricting access to content====
-You can restrict access to sidebar widgets and pages by creating [[server:web#webctrlini_per-directory_configuration_file|webctrl.ini]] files in the sidebar/ and pages/ directories, and setting AccessRequirements rules there.  Since Synchronet's webserver itself respects these controls, using [[server:web#webctrlini_per-directory_configuration_file|webctrl.ini]] files has the added benefit of preventing direct access to restricted pages on your site, should a user attempt to bypass ecWeb's mechanism for loading content into its pages.
-For example, to prevent the default System Statistics sidebar widget (sidebar/003-systemStats.xjs) from being displayed to users with a security level below 60, you could create (or edit) the file:
-  sidebar/webctrl.ini
-And add the following section to it:
-  [003-systemStats.xjs]
-  AccessRequirements=LEVEL 60
-Likewise to prevent the web forum from appearing in the list of pages, or loading for users with a security level below 55, you could create (or edit) pages/webctrl.ini and add the following to it:
-  [002-forum.ssjs]
-  AccessRequirements=LEVEL 55
-Please note that ecWeb's support for [[server:web#webctrlini_per-directory_configuration_file|webctrl.ini]] is limited to per-file AccessRequirements definitions - wildcards and other key-value pairs are not supported.
-====Setting ecWeb as your web interface====
-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 the ''[[dir:ctrl]]/[[config:sbbs.ini]]'' file, scroll to the ''[Web]'' section and change the value of the following keys:
-  RootDirectory = ../web/root/ecwebv3
-  ErrorDirectory = ../error
-Then open ''[[dir:ctrl]]/[[config:modopts.ini]]'' and scroll down to the ''[web]'' section, and change the ''appendURL'' line to read:
-  appendURL = /
-Recycle your webserver or restart your BBS.  ecWeb should now be configured as your standard web interface.
-===== See Also =====
-  * [[:howto:|howto index]]
-{{tag>}}

Trace:

Differences

Navigation

Search

Toolbox