Introduction
DBabble allows the system administrator to customize the web pages that the users
see when using the web browser interface to DBabble, to include anything you want
such as advertising images and links. Each page a user views when using DBabble
is generated from a template page that is stored in the tpl directory within
the DBabble installation directory. To find which source file a page you are viewing
is generated from, make sure the tpl_names
setting is true, and view the page source. There will be a comment at the start with
the source filename. For a list of what each page is used for, see
template usage by filename.
Each template page is made up of standard
html text, with the addition of a variable reference scheme to allow the content
of the pages to change depending on what the user does.
If you are using versions 1.2n or later, before you start customizing the templates,
you might want to change the tpl_sets
setting to something like "Custom,Original". In this way, DBabble provides links
on the login page for you to switch between using your templates and our provided
templates. You can specify as many template sets as you want with this setting,
and DBabble looks in the directory tpl/name (e.g tpl/Original) for the needed
templates, and uses
the ones in the tpl directory if it can't find the specified name.
If you are wanting to change just the colors of the web pages, you might want
to start by looking in tpl/define.txt. This file defines a list of variables
(starting with colors) that are used throughout the DBabble template web pages.
If you are using 1.3b or later, you should probably turn off the
tpl_cache setting before customizing
the pages. In this way, you can modify the template source pages, and the
DBabble server will read the template page from disk every time it is needed
instead of caching them in memory. Alternatively you can just type
dbabblesvr -reload to tell DBabble to reload all template
pages from disk.
To get started, you might want to begin by editing the file tpl/login.htm, which
is the page users first see in which they enter their login information. Make sure
you do a reload command after editing the page for the changes to take effect.
Variables
Each variable is referenced
by surrounding the name of the variable with double bars (||). For example, on the
message viewing page (message.htm) there is a variable send_date to represent
the date the message the user is currently viewing was sent. This is referenced in
the template page as ||send_date||. To avoid problems with variable references
being confused with JavaScript or symbols, it is necessary to use the JavaScript
or symbol with a space character on either side of it. To actually display
two bars in a web page, use ||.
Most of the variables that are references in existing template pages are only
available on that particular page. However, there are a number of variables
that are defined for all template pages.
Phrase Identifiers
To facilitate translating DBabble into other languages, every piece of English text
is surrounded by pairs of dollar signs ($$). Whenever a page is displayed to
a user, any text between pairs of dollar signs is looked up in the language
translation table for the current language and replaced with it's translation.
If you want to change a piece of text, you should change it's translation
in the server language file "lang/English.txt" instead of modifying it directly
on the web page. For further instructions on changing the language or English
phrases, see Customizing the Languages.
Standard Variables
A list of variables that are defined on every page can be found
at Standard Template Variables
Custom Variables
DBabble also allows you to
define custom variables in the file tpl/define.txt. See the comments at the
start of that file for more details.
Comments
Any line in the template file starting with a # is considered a comment
line, and ignored when reading the file, unless that second character is also a #,
in which case the first # is ignored, and the remainder of the line is interpreted normally.
Html tags and references within variables
In some cases, the variables may happen to contain
html tags when they really should not. For example a user may send another user a message
containing html tags. In this case, it is not desirable for these tags to be interpreted
as standard html tags. To avoid this, any variable reference can be prefixed by the
text html_encode_ so that characters within the variable content appear exactly
as they should. Additionally, it is nice to make any http references into usable links.
This is done be prefixing the variable name with html_ref_encode_. For example, in
in the message viewing page (message.htm) there is a variable message to
reference the content of the message the user is currently viewing. This is referenced
using ||html_ref_encode_message||. In versions 1.2m and later, there are
also two tag prefixes called html_encode2_ and html_ref_encode2_
which function identically to html_encode and html_ref_encode, but with the
addition of encoding spaces (" ") into " ".
If versions 2.1i and later, there is now a separate prefix for encoding contents that will
appear in textareas. All such variables should be prefixed by textarea_encode_. This
replaces the values ", &, <, and >
with ", &, <, and > respectively.
Limiting Length of variables
In some cases it is desirable to limit the
displayed length of a variable's content. For example when viewing a list of recent messages (messages.htm)
the first 50 characters of each message is displayed. This is done by prefixing the
variable name with length_50_. This can be combined with the html_encode
reference. For example html_encode_length_50_message is used in messages.htm to reference
the variable named "message".
Referencing Configuration File Settings
You can also access the value of configuration
file settings
(dbabblesvr.ini) by prefixing the name of the configuration value by ini_. For example,
||ini_domain|| would give the domain setting value. For values that need
to be interpreted as integers (for example time intervals and byte counts) you can prefix
the name by ini_int_ to return the value as an integer in seconds or bytes.
If statements
You can also provide conditional content based on the value of
a template variable. In all cases, the ||else|| clause is optional.
- ||ifdef||variable_name||Content to display if the variable value has length greater than 0||else||Content to display otherwise||endif||
- ||ifndef||variable_name||Content to display if the variable value has length equal 0||else||Content to display otherwise||endif||
- ||ifeq||variable_name||value||Content to display if the variable value is equal to value||else||Content to display otherwise||endif||
- ||ifneq||variable_name||value||Content to display if the variable value is not equal to value||else||Content to display otherwise||endif||
Including other files
You can also include other template files within a template by using the ||include|| option. For example,
||include||advert.htm|| Would include another template page (advert.htm) at that point in the page.
By default, the page head.htm is included between the <head> and </head> tags of all pages.
The page top.htm is included after the <body> tag of all pages that have visible content. Edit
either of these pages to have fixed content appearing in all pages. For example, to change
the font, you could add
to head.htm. However, this may not work perfectly in some web
browsers (e.g. Netscape 4 which has a bug causing it to revert to the default font part way through pages sometimes).
Repeating sections of the page
In some cases some html text may need to be displayed multiple
times within a single page. For example when a user is listing all their old messages, we want to display each
message using the same html code. This is done by placing the tag ||begin_line|| at the point where
the first line will begin, and placing the tag ||end_line|| at the end of the template for a single line.
This html code is then repeated with the values of the variables changed each time to reflect the different
contents for each line. Note that the html code between the two tags can span multiple lines. See tpl/messages.htm
for an example which shows a user all their old messages. Note that in some pages where there may be multiple
sets lines that may be displayed, different tags may be used to terminate the line definition. These include
end_sub, end_msg, end_ignore.
Help Files
The templates for the user help files are found in the help directory rather
than the tpl directory. If you modify any of the help files, these will not be updated until
you either restart the server, reload the configuration file, or perform a manager
"reload template definitions file" command.
Other Languages
You should not change the template pages directly to translate into other languages,
Rather, you should use DBabble's language translation feature..
However, if you do want to change the templates for each language, you can create
an alternative copy of the templates for each language by creating sub directories
within the tpl directory for each language.
For example tpl/English/login.htm
Alternative Template Sets
DBabble 1.2i and later supports having multiple template sets available within each language for
your users to choose from.
See tpl_sets for details.
When DBabble tries to load a template page x.htm, it searches for the file
in the following order:
- tpl/current_language/current_template/x.htm
- tpl/current_language/x.htm
- tpl/current_template/x.htm
- tpl/x.htm
until it finds one, and uses that template. So if you want to just
override the login page for the language UPPERCASE, you
can just create a copy of tpl/login.htm in tpl/UPPERCASE/login.htm,
and edit that. This also applies to define.txt, which allows
you to define custom variables. In this way, you can have make
different styles available for the users to choose from. For example,
set the tpl_sets setting
to "Standard,Blue", and it uses tpl/Blue/define.txt (which comes
with DBabble) to generate
an alternative look to all the web pages, and the login screen
will automatically provide the user with links to choose which
style they prefer.
For DBabble version 1.2m and later, you can also choose to use alternative
template page names when showing any DBabble page. This is achieved by
adding &tpl_page=page_name.htm to any command. For example
"dbabble?cmd=cmd_friends&tok=xxxxx&tpl_page=friends3.htm"
would show the users friends list using the page friends3.htm instead of
the default of friends.htm.
Adding your own pages
In versions 1.4k and later, there is support for adding your own new template
pages that can be displayed wherever you want. Create a pages sub-directory
within your DBabble server directory, and create your own template files
within there. For example, you might create a page like:
pages/test.htm:
---------------------