Kate

The insertion template system is one of the hidden gems of KatePart, modelled after a similar feature in the eclipse IDE by Joseph Wenninger.

Insertion templates allows to insert a text snippet into the editor that contains variables like user name, date and similar, or fields that may be filled out by the user. Such fields can be repeated within the template text and can then be edited at once, they are highlighted in a special way (underlined) and are navigated between simply by pressing the TAB key.

Insertion templates aren’t widely used yet, as far as I know two functions use them:

• Kate’s file templates plug-in which allows template authors to use them to facilitate easy continuation of template based files
• The insertion template enabled snippet plug-in for kate, which only appeared on the kwrite-devel mailing list uses the system to allow users to define easily editable snippets.

KatePart with an insertion template inserted.

My name and email address as well as the year are expanded variables, and the underlined strings are due to be edited. The inserted text (by the Kate file templates plug-in) is

  ---
  Copyright (C) %{year}, %{fullname} <%{email}>
*/

#ifndef _${ClassName}_h_
#define _${ClassName}_h_

class ${ClassName} : public ${Super} {
  public:
    ${ClassName}( ${cursor} );
    ~${ClassName}();

You can see the template string ClassName repeated several times, the benefit of having to type the final class name should be obvious.

Insertion Templates — From a Users View

From a user point of view, insertion templates should hopefully make life a bit easier: the template strings can automatically insert trivial data like your name, email address, the date and time and others. And editable template fields provides a hint about what to put in a certain place.

The worst problem is that we do not have a help popup that informs you about what to do after a insertion template is inserted, so that must be a feature to come (something like the small help messages in kpdf).

Insertion Templates — From a Developers View

As a developer, all you need to do is to insert a text containing template text using a special function in the editor API.

Since the feature is implemented as a KTextEditor interface KTextEditor::TemplateInterface, it is easy to use from plug-ins. The code in the patched version snippet plug-in responsible for inserting the template text looks like this:

Kate::View *kv = win->viewManager()->activeView();
...

KTextEditor::TemplateInterface *ti = KTextEditor::templateInterface(kv->document());
if (ti) 
{
    uint line; uint col;
    kv->cursorPosition(&line,&col);
    QMap<QString,QString> initVal;
    if (!sSelection.isEmpty())
        initVal.insert("selection",sSelection);
    ti->insertTemplateText(line,col,sText,initVal);
 } 
 else 
     kv->insertText(sText);

Template Text Format

Templates in the inserted string have two formats, one in which variables are expanded, but that is not added to the list of editable strings:

%{variable name}

You should of course only use known variable for those. The other form is

${variable name}

and is added to the list of editable strings, after variables have been expanded.

Known Variables

Here is a list of the variables known by the template system and their values:

• index: “i” (for use in loop constructs)
• loginname: The current users’s loginname
• firstname: The current user’s first name retrieved from KAddressBook
• lastname: The current user’s last name retrieved from KAddressBook
• fullname: The current user’s first and last name retrieved from KAddressBook
• email: The current user’s primary email adress retrieved from KAddressBook
• date: current date
• time: current time
• year: current year
• month: current month
• day: current day
• hostname: hostname of the computer
• cursor: at this position the cursor will be after editing of the template has finished, this has to be taken care of by the actual implementation. The placeholder gets a value of “|” assigned.

The variable retrieved from KAddressBook are taken from the personal entry of your KDE addressbook, and you will be prompted to fill it in the first time it’s required.

The cursor variable is special in that it is always the last in the order, and when tabbed to, it’s replaced with an empty string. The idea is to put it where you want the cursor after editing the other template fields.

Conclusion

The insertion template system provides a way of aiding insertion of text snippets in a very efficient an unobtrusive manner, with no extra prompts or other abstractions. Just activate a function that inserts a template and continue typing.

Developers can easily extend the set of variables to be expanded, all there is to do is to pass a prefilled QMap<QString,QString> to the insertTemplateText function.

Possible improvements includes providing a generic variable interface to KTextEditor allowing applications as well as users to define additional variables, and a context sensitive help system that could inform the user about how to deal with the templates would be nice. But the system is allready fully functional — go ahead and use it!