User Tools

Site Tools


guide:templates

Template Guide

Introduction

Templates are used to generate the output placed on the screen. This ensures a separation of code from text making the software easier to maintain. Templates are also intended to be used for Language Translations by providing a different set for other character sets and spoken languages.

The OpenTG template system is used to render the ANSI screens and other text output. The Engine is called FreeMarker+TG. “FreeMarker is a 'template engine'; a generic tool to generate text output.” OpenTG incorporates the FreeMarker engine by wrapping the library into its own Tgtemplate:Template class and ensuring that an available set of variables and constants are always available to the template designer. This includes the ANSI color set, a set of global variables, and of course any variables passed prior to rendering. Thus, the +TG is appended to the engine name.

Template files are located in the /tpls directory in the top level of the software installation. Files are named based on the calling function/section of the BBS session and the filename ends with a '.ftl' extension. Template files are pure text files themselves. During runtime, the engine will compile the text version into a cached version for faster parsing of future calls.


Creating your own Theme

It is never recommended to modify the default 'opentg' theme that ships with the software. The default theme should be kept in-tact and used as a fallback. Leaving the default theme stock will also make future upgrades easier. However, if you wish to change the look and feel of your system (which is why templates are used to begin with), it is recommended you start by copying the default theme folder to a new folder, and start from a working set.

Modifying a Template

Modifying templates is relatively simple, but can be time intensive when tweaking colors and trying to perfect a layout. OpenTG ships with a reasonable set of pre-defined layouts for the average user. Others are encouraged to design and share “Template Sets”, similar to themes for many popular web blogging software such as wordpress.

Template filenames are relative to the section of the system and the calling function in the source code. Therefore, you should refer to the API docs or use the “default” template set as a guide. Templates are located in the /tpls directory of the BBS root installation (ex: /opt/telegard/bbs/tpls/ ).

You can use any preferred text-editor or IDE that can save files in UTF-8 encoding. Saving in other encodings is NOT recommended and unsupported. A list of editors recommended buy the FreeMarker developers can be found at: http://freemarker.sourceforge.net/editors.html

OpenTG also ships with a specialized editor for working with Templates, called TgThemer. While not a fully featured text editor, it does provide shortcuts and syntax highlighting easier.

The example template in the next section illustrates the use of colors and variables within a template. Substitution occurs on instances of ${somevar} where somevar is either a known globally available template variable or constant, or a variable handed off by the calling system function.

Example Template

Welcome, ${color.lightblue}${user}${color.norm}! 
You have entered ${color.lightcyan}${bbsname}
${color.white}${color.on_red}(${tagline})${color.reset}

Using Colors & Text Changes

As demonstrated in the above example, colors are added during the rendering of the template through the color variable called in the markup. Colors are defined as template constants. Color names always start with a prefix of 'color.' within the variable name. The list of color suffixes is shown below:

Modifiers

The following names are modifiers to the text:

  • reset
  • norm
  • bold
  • dark
  • italic
  • underline
  • blink
  • rapid
  • negative
  • concealed
  • strike

Normal Color & Reset

The following values set the text to a light grey:

  • norm
  • gray
  • grey
  • reset

Dark (non-bold) colors

The following are nonbolded or dark colors:

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan

Bright (bold) colors

The following are bolded or bright colors:

  • lightred
  • lightgreen
  • lightyellow
  • lightblue
  • lightmagenta
  • lightcyan
  • white
  • darkgray
  • darkgrey

Background colors

The following set the background color:

  • on_black
  • on_red
  • on_green
  • on_yellow
  • on_blue
  • on_magenta
  • on_cyan
  • on_white

Important Notes

  • “grey” == “gray”
  • “darkgrey” == “darkgray”.

These color words have the same value. They are aliases to the same color code but may be used interchangeably.

“reset” will also set the background color to black, but “norm” will only change the foreground color to normal.

Setting a background color will change the background for an entire block of text until a ${color.reset} is found, it is changed within the template by another background color, or until another template is called that changes the value.

Constants & Globals in Templates

There are some constants and global variables that are available in all templates. * note, these may change in a future release, so always refer to the documentation.

  • bbs.name
  • bbs.tagline
  • username
  • session_expires
  • session_timeremain

See Also

guide/templates.txt · Last modified: 2018/10/23 21:25 (external edit)