User Tools

Site Tools


guide:ionthemer

Theme Editor (ionthemer)

About

IonFalls Theme Editor also referred to as ionthemer (executable filename) is a window mode text editor that provides shortcuts and syntax highlighting features to ease the creation and modification of output templates used in IonFalls themes.

Features include:

  • Graphical mode application (currently tested on KDE-qt5 and MacOS-cocoa toolkits)
  • Loading and Saving template files from disc
  • Syntax Highlighter within the editor to distinguish colors and known variables
  • XML based highlighter rules to provide customization and easy future expansion
  • Colors & Text effect selectors via radio buttons to quickly insert the correct variable
  • Insert Variable feature to inject a properly formatted placeholder variable.
  • Compiled and tested on MacOS and Linux desktops.

Authors

ionthemer was written by Chris Tusa prior to the 1.0 release of IonFalls.

Getting

ionthemer ships with the binary distributions and with the source code.

Compiling

Most users will not need to compile the ionthemer source code as it ships with all releases.

Should you still need to compile the application, a Rakefile has been provided to automate the build. It has currently been tested on Linux and MacOS. You will need the FreePascal (fpc) compiler with the fcl-units as well as Lazarus and the lcl-units. You must also have a proper JRuby environment configured as described in the installation guide.

To start the build

cd tgthemer/
rake clean
rake build

This will create a temporary build directory, compile the libraries and assemble the binary file 'tgthemere'. Lastly, the executable is copied into the tgthemer directory.

The 'tgtpl.xml' file will need to be copied into /opt/telegard/conf in order for syntax highlighting to work. Issuing the install command to rake will do this for you as well as place the binary.

rake install

When completed, cleanup the directory.

rake clean

Using

:!: IMPORTANT

Before using the editor, you are strongly encouraged to use a copy of the default theme and take a backup of your system. Editing the default theme could break the functionality of your system.

Loading a File

Click the “Folder” icon. Use the Open Dialog to select a file.

Saving a File

Click the “Disk” icon. Use the Save Dialog to save the loaded file.

Where is 'NEW' and 'SAVE-AS'?

These two features were purposely omitted. Adding a new template file from scratch should only be performed by developers who are working on the project. There is no reason template files would need to be renamed or created from the editor. If you need to use “save-as” for backup reasons, you should use the command line or file manager of your OS, or better yet, use revision control.

Selecting Colors

Because IonFalls uses a limited 16 color palette with ANSI color codes, the toolbar to select colors is limited to the variable names made available by the program's template engine.

Background

The default background color is selected as “none” when the program starts. None is a special option in the editor, as it does not have an equivalent variable. This means that if you are NOT changing the background color, you should leave it set to none.

For example. If you want to change the background color from the standard color to “red”, you would select the “on_red”. Once you click “Apply Color Changes”, it will insert the value for both the foreground and background variables into the editor. If you want to keep the background red, but change the foreground, you could leave it as “on_red”; however clicking the apply button will again inject both variables. This has the effect of inserting the variable twice, which can reduce performance, but also means the ANSI sequence will be inserted into the output console where it is not necessary. You should always change the background color back to “none” as a best practice.

Foreground

Setting the Foreground is straightforward. The colors are either normal or bright. Select the color and click “Apply Color Changes”. See the example in Background about leaving it set to “none” as a best practice when not changing it.

Text Effects

You can apply text effects such as “blink”, “rapid”, “norm”, and “reset”. These are selected in the Effects toolbar.

Inserting Variables

You can insert a placeholder variable using the “Insert Variable” button. This will drop a placeholder at the cursor for you to modify. Replace 'var' with the actual variable name. Most variables will be recognized by the syntax highlighter.

<#if var?has_content>${var}<#/if> 

8-) Tip: You can refer to the iontpl.xml file that ships with ionthemer for a list of variables.

Learning More

There are other conventions that are made available by the template engine. For example, iterating over lists, adding padding spaces, etc. The editor does not support highlighting these, or accounting for them at this time. Please refer to the Template Guide and Freemarker documentation.

guide/ionthemer.txt · Last modified: 2018/10/25 13:55 by Leafscale Administrator