Skip to content
Snippets Groups Projects
Commit 73378c5b authored by runemaster's avatar runemaster
Browse files

Added some documentation on the default layout and SSJS.

parent d93cddb3
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 284 additions and 80 deletions
docs/websrvr.txt
+ 284
− 80
View file @ 73378c5b
......@@ -23,97 +23,301 @@ documented elsewhere)
2.1. INI file web configuration [Web] section keys
--------------------------------------------------
RootDirectory=../web/html
This is the root directory of your web server... a request to
http://yourbbs.synchro.net/index.html will be served out of this dir.
This is the root directory of your web server... a request to
http://yourbbs.synchro.net/index.html will be served out of this dir.
ErrorDirectory=error
The directory relative to RootDirectory where the various error
messages are located. The error messages are named by the error code
they will be displayed on and may be either .html or .ssjs files.
(.ssjs files are displayed if they exist, .html files if they do not)
The directory relative to RootDirectory where the various error
messages are located. The error messages are named by the error code
they will be displayed on and may be either .html or .ssjs files.
(.ssjs files are displayed if they exist, .html files if they do not)
IndexFileNames=index.html,index.ssjs
A comma-separated list of filenames in order of preference to serve as
the default document in a directory. Many SysOps change this to:
IndexFileNames=index.html,index.htm,index.ssjs
Do not renove the index.ssjs unless you are not using the stock
web pages at all.
A comma-separated list of filenames in order of preference to serve as
the default document in a directory. Many SysOps change this to:
IndexFileNames=index.html,index.htm,index.ssjs
Do not remove the index.ssjs unless you are not using the stock
web pages at all.
CGIExtensions=.cgi
Files with this extension will be considered CGI files. On *nix
systems, the web server will attempt to execute them as such. CGI
files on Win32 systems will currently always return an error.
Files with this extension will be considered CGI files. On *nix
systems, the web server will attempt to execute them as such. CGI
files on Win32 systems will currently always return an error.
JavaScriptExtension=.ssjs
Files with this extension will be considered SSJS files. On all
systems, this will be attempted to run with the JavaScript interpreter.
Files with this extension will be considered SSJS files. On all
systems, this will be attempted to run with the JavaScript interpreter.
MaxInactivity=120
If a client holds a connection open for this many seconds without a
request, the web server will shut down the connection.
If a client holds a connection open for this many seconds without a
request, the web server will shut down the connection.
MaxCgiInactivity=120
If a CGI script runs for more than this many seconds without any
output, it will be terminated and the connection will be shut down.
If a CGI script runs for more than this many seconds without any
output, it will be terminated and the connection will be shut down.
HttpLogFile=../data/logs/http-
The prefix of log files if HTTP_LOGGING is enabled (See next item) to
store Common Logfile Format logs in. The current virtual host
(if enabled, see next item), date, and .log are appended to this. ie:
http-2005-03-12.log
The prefix of log files if HTTP_LOGGING is enabled (See next item) to
store Common Logfile Format logs in. The current virtual host
(if enabled, see next item), date, and .log are appended to this. ie:
http-2005-03-12.log
Options=NO_HOST_LOOKUP
The | separated list of options to enable. In addition to the standard
options, the web server also supports the following:
DEBUG_RX
Log all received data to the console log, as well as various
extra bits related to receiving data.
DEBUG_TX
Log all transmitted data except the reply body itself, as well
as various extra bits of information related to transmitted
data.
VIRTUAL_HOSTS
Supports name-based virtual hosts. If your system has multiple
host names, you can have each host name return unique content
depending on which hostname is used. ie: if
freebsd.synchro.net and nix.synchro.net both resolved to your
system, you could have FreeBSD-sepcific pages on one, and
general *nix stuff on the other.
A virtual host is added by simply putting the desired content
into a sub-directory of RootDirectory with the desired hostname
ie: web/html/freebsd.synchro.net/ if the browser doesn't send
the request host name (very old browsers, or some automated
tools) they will be served out of document root.
It is therefore a good idea to put links to your various
virtual hosts in an index.html page in RootDirectory something
like this:
<html>
<head>
<title>Old Browser</title>
</head>
<body>
Your browser is either too old to support
name-based virtual hosts, or you have visited a
virtual hosts that is not yet configured. The
following are hosted here:<br>
<a href="freebsd.synchro.net">freebsd.synchro.net
</a><br>
<a href="nix.synchro.net">nix.synchro.net</a><br>
</body>
</html>
NO_CGI
Disable CGI script execution.
HTTP_LOGGING
Enable logging to a Common Logfile Format log as described in
the HttpLogFile section. Usefull for running log analysis
programs (like Webalizer: http://www.mrunix.net/webalizer/)
NO_JAVASCRIPT
Disable SSJS execution.
The | separated list of options to enable. In addition to the standard
options, the web server also supports the following:
DEBUG_RX
Log all received data to the console log, as well as various
extra bits related to receiving data.
DEBUG_TX
Log all transmitted data except the reply body itself, as well
as various extra bits of information related to transmitted
data.
VIRTUAL_HOSTS
Supports name-based virtual hosts. If your system has multiple
host names, you can have each host name return unique content
depending on which hostname is used. ie: if
freebsd.synchro.net and nix.synchro.net both resolved to your
system, you could have FreeBSD-specific pages on one, and
general *nix stuff on the other.
A virtual host is added by simply putting the desired content
into a sub-directory of RootDirectory with the desired hostname
ie: web/html/freebsd.synchro.net/ if the browser doesn't send
the request host name (very old browsers, or some automated
tools) they will be served out of document root.
It is therefore a good idea to put links to your various
virtual hosts in an index.html page in RootDirectory something
like this:
<html>
<head>
<title>Old Browser</title>
</head>
<body>
Your browser is either too old to support
name-based virtual hosts, or you have visited a
virtual hosts that is not yet configured. The
following are hosted here:<br>
<a href="freebsd.synchro.net">freebsd.synchro.net
</a><br>
<a href="nix.synchro.net">nix.synchro.net</a><br>
</body>
</html>
NO_CGI
Disable CGI script execution.
HTTP_LOGGING
Enable logging to a Common Logfile Format log as described in
the HttpLogFile section. Usefull for running log analysis
programs (like Webalizer: http://www.mrunix.net/webalizer/)
NO_JAVASCRIPT
Disable SSJS execution.
2.2. Other web-related configuration files
------------------------------------------
In addition to the keys in the INI file, the web server also, by default, uses
two other configuration files.
ctrl/mime_types.ini
Contains the file extension to mime-type mapping. Each line
is in the format "extension = mime-type" ie: "html = text/html"
The extensions are case-insensitive.
ctrl/webicons.ini
Contains the URLs to the icons used by the default 404.ssjs
script for each file type. Format is "extension = URL" ie:
"html=/icons/layout.gif". Two "magical" extensions exist:
DIRECTORY which is used for directories and DefaultIcon which
is used for extensions which don't exist in the list.
ctrl/mime_types.ini
Contains the file extension to mime-type mapping. Each line
is in the format "extension = mime-type" ie: "html = text/html"
The extensions are case-insensitive.
ctrl/webicons.ini
Contains the URLs to the icons used by the default 404.ssjs
script for each file type. Format is "extension = URL" ie:
"html=/icons/layout.gif". Two "magical" extensions exist:
DIRECTORY which is used for directories and DefaultIcon which
is used for extensions which don't exist in the list.
3.0 The Template System
--------------------------
The default web pages use a Template engine which also allows for Theme
support.
3.1 The Template Scheme
-------------------------
Each page consists of four parts:
The Header (../web/templates/default/header.inc)
This file contains the basic requirements for the HTML page.
The opening HTML, doctype, title, CSS file link, etc. The
header file includes the open body, System Name, and User
greeting plus the initial page layout table start. The rest
of the layout is continued in the next files.
Top Navigation (../web/templates/default/topnav.inc &
../web/lib/topnav_html.ssjs)
The topnav.inc file contains the basic design of the "breadcrumbs"
The links are dynamically generated by topnav_html.ssjs so both
files need to be addressed when modifying or creating themes.
In the case of the default layout, topnav.inc has a left and right
graphic and a middle section that the dynamic content goes. The
background image is handled by CSS. You can change this to anything
you like.
The topnav_html.ssjs file may seem daunting at first, but it is
pretty straight forward. It has a series of if statements that
check the current page location and sets up the breadcrumbs based
on what you want it to say.
For example:
You want to add a Links page called links.html in the main
directory. You would add a check for the path to links.html
as:
if(http_request.virtual_path=="/links.html")
template.topnav.push({html: '<span class="tlink">Some Links</span>'});
Left Side Navigation (../web/templates/default/leftnav.inc &
../web/lib/leftnav_nodelist.ssjs) This starts the main table layout in the
default layout and also provides two other things -- the main navigation links
and a brief nodelisting that displays when users are online via telnet.
Here there are some new things to understand. There is some @@JS: ... stuff in
there. Anything contained within @@JS: @@ is processed by the Server side
Javascript engine.
In the case of the default layout, it checks if the user is Guest or an actual
user with this line:
@@JS:if(user.number==0 || user.security.restrictions&UFLAG_G)'<html code for Guest>'; \
else '<html code for registered user>';@@
What this does is display links specific for Registered Users only to them and
not Guest. There are many things that can be done with @@JS: @@ code.
Note, it also can be used to display HTML based on location as in the Nodelisting stuff.
In this case, it checks for whether or not a user is online, or if the user is anywhere
but the Who's Online page before displaying the Left side Nodelisting.
IMPORTANT! Anything contained within @@JS: @@ MUST be on one line or there will
be errors in parsing.
Main Content (various files)
This is where the layout of the main content is created. It is best to look at the
various files in ../web/templates/default & ../web/templates/default/msgs to see how
the code is dispayed for the various functions of the Web side of Synchronet. Some
details on what each of the special codes contained in those files do will follow.
Footer (../web/templates/default/footer.inc)
This file contains the closing HTML and whatever bottom information you would like.
In the case of the default layout, the Webserver/Synchronet versions and the XHTML 1.0
logo. Links to privacy statements or anything else can be placed here and they will
be displayed at the bottom of each page.
3.2 Theme Support
-----------------
Theme Layouts can be added to Synchronet by creating them and placing the *.inc files in
their own directory under ../web/templates/
Themes are activated by editing the ../web/templates/html_themes.ssjs file. This file contains:
/* Set default theme name */
var DefaultTheme="Default";
/* Edit this bit to add/remove/modify theme descriptions and dirs */
Themes["Default"]=new Object;
Themes["Default"].desc="Default Synchronet Theme";
Themes["Default"].dir="default";
Themes["Default"].css="/synchronet.css";
Themes are added by editing below the Default Theme such as:
Themes["CoolTheme"]=new Object;
Themes["CoolTheme"].desc="My Cool Theme";
Themes["CoolTheme"].dir="cooltheme";
Themes["CoolTheme"].css="/cooltheme.css";
To change the Default Theme, change:
var DefaultTheme="Default";
to:
var DefaultTheme="CoolTheme";
3.3 Special Codes Used in Template System
-------------------------------------------
By looking at at the message related files located in ../web/templates/default/msgs,
it can be seen that some special codes are used to display dynamically created content.
It is very important to maintain the information EXACTLY as seen in each file or else
the messaging system will fail. While how it is displayed can be changed, the correct
information will only be dispayed by following the format in the *.inc files.
For example the groups.inc:
<!-- Main Content -->
<td class="main" valign="top"><br />
<table class="grouplist" border="0" cellpadding="2" cellspacing="2">
<tr>
<th class="grouplist">Message Group</th><th class="grouplist">Subs</th>
</tr>
<<REPEAT groups>>
<tr>
<td class="grouplist"><a class="grouplist" href="subs.ssjs?msg_grp=^^groups:name^^">%%groups:description%%</a></td>
<td class="grouplist" align="right">@@JS:msg_area.grp_list['@@groups:index@@'].sub_list.length@@</td>
</tr>
<<END REPEAT groups>>
</table>
<br />
<!-- end Main Content -->
While the table layout can be changed or even eliminated, the information within the
<<REPEAT groups>> and <<END REPEAT groups>> must remain intact. To remove the table yet keep
the correct infomation, the resulting groups.inc would be changed to (while maintaining
the main table layout in this case) to:
<!-- Main Content -->
<td class="main" valign="top"><br />
<<REPEAT groups>>
<a class="grouplist" href="subs.ssjs?msg_grp=^^groups:name^^">%%groups:description%%</a>
@@JS:msg_area.grp_list['@@groups:index@@'].sub_list.length@@<br />
<<END REPEAT groups>>
<br />
<!-- end Main Content -->
This principle applies to all the .inc files in msgs respectively.
3.4 The SSJS Template Library
-------------------------------
%%name%% is replaced with the HTML encoded value of template.name
i.e.; Spaces are replaced with: this&nbsp;is&nbsp;html
^^name^^ is replaced with the URI encoded value of template.name
i.e.; Spaces are replaced with: this%20is%20URI
@@name@@ is replaced with the value if template.name
No changes or encoding is performed.
@@name:sname@@ is replaced with the value of template.name.sname
(^^ and %% are also supported)
@@JS:js_expression@@ is replaced with the return value of js_expression
(^^ and %% are also supported)
<<REPEAT name>>
... @@name:sname@@ ...
<<END REPEAT name>>
Iterates over the array/object template.name and replaces name:sname with
the value of template.name.sname.
(^^ and %% are also supported)
3.5 Message Configuration
--------------------------
Configuration settings for the SSJS Messaging system is located in the
../web/lib/msgsconfig.ssjs file:
max_messages=20;
max_pages=30;
next_msg_html="Next Message";
prev_msg_html="Previous Message";
next_page_html="NEXT";
prev_page_html="PREV";
showall_subs_enable_html="Show all subs";
showall_subs_disable_html="Show subs in new scan only";
show_messages_all_html="Show all messages";
show_messages_yours_html="Show messages to you only";
show_messages_your_unread_html="Show unread messages to you only";
show_messages_spacer_html="&nbsp;<b>|</b>&nbsp;";
anon_only_message="Message will be posted anonymously";
anon_allowed_message='<input type="checkbox" name="anonymous" value="Yes" /> \
Post message anonymously';
anon_reply_message='<input type="checkbox" name="anonymous" value="Yes" checked /> \
Post message anonymously';
private_only_message="Message will be marked private";
private_allowed_message='<input type="checkbox" name="private" value="Yes" /> \
Mark message as private';
private_reply_message='<input type="checkbox" name="private" value="Yes" checked /> \
Mark message as private';
Each of these are configurable. NOTE: Lines ending in "\" indicate the line below
is part of the line above. The "\" is not part of the configuration as it too be
removed.
See the actual file for the defaults currently in use.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment