DBabble - Customizing the Web Pages

DBabble Customizing the Web Pages

DBabble Links

Download Now

FAQ

Email Support

Features

Manual

Prices

Buy Now

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

<STYLE TYPE="text/css">  </STYLE> 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:
--------------------- <html> <body ||u_body_tags||> Test Page<br> <a href="||program||?tok=||tok||&cmd=read_old_messages">Read Your Old Messages</a> </body> </html> --------------------- In an existing template page, you would create a reference to this page using a link like: <a href="/pages/test.htm?tok=||tok||">Test Page</a> The tok (token) parameter is only necessary if your test page contains links that require the user to be logged in to be valid.

Adding Custom Preferences

In 1.4m and later there is support for adding your own custom preferences. For example, maybe you want a preference for changing the colors of certain pages. To add the preferences to the preferences page (prefs.htm) you would add lines like: <tr><td><input type="checkbox" ||custom_check_1|| name="custom_check_1" value="true"> <input type="hidden" name="is_custom_check_1" value="true">Custom Check Box</td></tr> <tr><td>Custom Text Field <input type="text" name="custom_text_1" value="||custom_text_1||" size=30> <input type="hidden" name="is_custom_text_1" value="true"></td></tr> In any other template page, you could add text like: ||ifdef||pref_value_custom_check_1||Pref Text 1=||pref_value_custom_text_1||||endif|| There is support for adding up to 5 text and 5 checkbox preferences (custom_check_1 to custom_check_5 and custom_text_1 to custom_text_5)

Running DBabble within a frame in a window

DBabble assumes it will be running in the top frame of the web browser window. However, by changing a few variables you can make DBabble run within a frame. Edit tpl/define.txt and change these 5 variables (they are near the end of the file)
dot_top=.top window_top=window||u_dot_top|| main_window_name=mainframe top="_top" is_main_window=window.top.name=="||u_main_window_name||"
For example, if you have DBabble running in the second frame of the top level browser window, with the name of the DBabble frame as "dbabbleframe", you could use this:
dot_top=.top.frames[1] window_top=window||u_dot_top|| main_window_name=dbabbbleframe top="dbabbbleframe" is_main_window=window.length>1 && window.top.frames[1].name=="||u_main_window_name||"

Upgrading

When you upgrade DBabble, you have the choice of replacing or keeping your old copies of your existing template pages. Usually our old template pages will still work with newer versions (but without any new features we have added), but in some cases they may not. In order to assist in working out what has changed within the templates between versions, DBabble (version 1.2n and later) will automatically install copies of templates into sub directories called "Original", so that when it upgrades to future versions, comparisons are automatically made with between the old and new templates, and a list of changes generated. If you are upgrading from a version prior to 1.2n to version 1.2n or later, then this is not automatically done. If you have copies of the original templates still available, you can generate a list of changes yourself using the "dbabblesvr -changes" command. For example, if you have the original templates in the dbabble/tpl_old, and the new templates in dbabble/tpl, then use the command "dbabblesvr -changes tpl_old tpl changes.txt" to generate a list of changes.

Performance

You should not be worried about making extensive use of comments and custom variables within your template pages as this will have no effect on performance. All pages are cached in memory with custom variables replaced with their values and all comments removed the first time the page is accessed. Additionally, a different copy of the page is cached for each language, so you do not need to worry about performance effects from translating all the phrases each time a page is viewed.

Miscellaneous Prefixes

Prefix	Description	Example
comma_	Formats an integer value using commas every 3 digits	\|\|comma_num_messages\|\| = 1,234
td_	If the following variable does not exist or is empty, inserts   instead. Useful within table data elements where color does not appear in some browsers unless there is some content.	\|\|td_group_nntp_name\|\| = netwin.test or

Examples

Here are some examples of how to make certain changes that we have been asked about. If there is something else you want to do that you can't work out, ask us at support-dbabble@netwinsite.com.

How can I make some template variable references that are only defined in one particular page work in other pages. For example "old_messages_ref" is only defined in q_menu.htm? View the page source of the page where it is defined to find out what it actually translates into, and insert that code directly into another template page. For example viewing the frame source of q_menu.htm in your web browser would show: Here "/dbabble?tok=3_6_217072462_998533725" is what is referred to by ||base_ref|| in all template pages, so you could insert directly into your alternative page.
How do I make the state changing links work in pages other than q_menu.htm?
Normally clicking on the links to change what state a user appears in will show q_menu.htm again afterwards. To get around this, you can target the state change link to the invisible frame called "update", and reload the current frame again if you want to show to the user that their state has indeed changed. Insert this into your alternative template page:
How can I remove the friends frame and quick menu (the frame of on the left with the links) frame?
There is a user preference for whether or not the friends frame is shown. Users can also choose the friends frame to be a separate window in their preferences. There is also a user preference to make the links appear at the top of the window rather than on the left. You can set the defaults for all user preferences from the server administration default preferences page.

However, if you really want to remove the friends frame and links frame, you can do the following: Edit main_frame.htm and change the line: to Also edit popup_sub.htm and remove these 7 lines, which assume the existence of the friends and quickmenu frames: Note: In case you want to know the reason for these changes, here they are. Many of the templates assume that the main working frame name is "vchat" (VChat was our working name for DBabble before we released it). Normally main_frame2 contains a frameset consisting of 3 frames (vchat, friends, and qmenu). If you remove "main_frame2", you must rename it to "vchat". ||main2_ref|| is a reference to the page that would return the content of main_frame2. Within main_frame2, the vchat sub-frame would normally look like ||main_ref|| displays the user's list of subscribed discussions (or new instant messages after the first time the log in)
How do I make it jump to a particular discussion group after logging in instead of showing the user's subscribed group list?
Edit the file main_frame2.htm and change: to: (you replace the gid value of 1 by the group-id of the group you want to jump to)

If you want to view a chat room instead of discussion group, use the command cmd=chat_list instead of cmd=group_items
How can I remove the hyperlinks from user names in chat rooms?
Edit the template file c_refresh.htm and change the line

Problems

If you are finding that a page is not appearing as you would expect it to after some changes you have made, try the following:

Try looking in the log file log/error.log. If there was any syntax problems with variable references, if statements etc, the problem may be mentioned there.
Check the spelling of your variable names. If a variable is not defined, then no error is generated - DBabble just assumes it has no value and ignores the reference. Remember that if your are using custom variables that you must prefix the name of the variable with u_. Eg if you had a line in tpl/define.txt like company_name=Netwin Limited Then you would reference it in the web page using ||u_company_name||