# File Templates

## Introduction

The File Templates plugin allows you to create files based on other files. You can use any file as a template, which will create a copy of the file with an empty URL, or use a special template file which may contain macros to fill in information like your name and email address, the current date and environment variables, and position the cursor at a convenient position in the new file.

Furthermore, templates located in the template directories will be presented in the menu item File From Template...

The plugin also provides a method to easily create a new template from an open document.

The template directories is part of the &kde; file system, and consists of at least KDEDIR/share/applications/kate/plugins/katefiletemplates/templates and KDEHOME/share/applications/kate/plugins/katefiletemplates/templates. If your K DEDIRS enviroment variable contains additional directories, those are searched for a similar subdirectory as well. If equally named templates are found, the one in the local (KDEHOME) directory is chosen.

## Menu Structure

File New From Template Any File...

- Presents you with Open File dialog that allows you to use any file as a template. If the chosen file has the extension `katetemplate` it will be parsed for template information and macros.

File New From Template Use Recent

- Presents a list of files recently used as templates, represented by their URL.

File New From Template

- The remainder of submenus contains links to templates. Click a menuitem to create a file as described by the menu item text.

Settings Manage Templates

- This will launch a dialog with a list of all templates found within the template directories, along with options to add, edit or remove templates.

## Creating your own templates

To create a new template, use the Settings Manage Templates Item to launch the template management dialog. In that, click New... to l aunch the File Template Wizard. You will be asked for an optional file to turn into a template and prompted for template information settings, and a template file will be created for you.

Alternatively, you can create a template manually by adding template information to the top of any file, add text, macros and cursor position marker, and save it with the `katetemplate` extension.

The template menu gets automatically updated if you chose to store your template in the template directory.

## Editing templates

To edit a template, use the Settings Manage Templates.... Select the template you want to work on and click Edit..., and the template file will be opened. Close the dialog, edit the template file as desired, save it and close it. Changes to templates takes immediate effect, you can activate the template to test your changes after saving it.

## The Kate Template Format

If you use files with the extension `katetemplate`, they will be parsed for template information, macros and a cursor position.

### Template information

While reading in the file, the parser keeps lines beginning with the phrase `katetemplate:` and searches them for template information in the form VARIABLENAME=VALUE. The first line not sta rting with `katetemplate:` will be taken as the start of the template contents. VALUE may contain any character but euqal sign (=). Legal variable names are:

`Template`

- This is the template name, displayed in the File From Template menu.

`Group`

- The group places the template in a submenu of the File From Template menu.

`Name`

- This is the name that will be set for the document, and displayed in the file list and title bar. If the name contains `%N` that will be replaced with a number, increasing if more documents has the same name.

`Highlight`

- The plugin will try to set the Highlight for the new document to the value of this variable. The value should be the name, as found in the Tools Highlight .

`Description`

- A short informative description of the template. This is currently used to set a Whatsthis string for the menu item, but may be used for more purposes in the future.

Author

- A string identifying the author, for example in the form `Name <email address>`. This is currently used to set a Whatsthis string for the menu item, but may be used for more purposes in the future.

### Template Macros

While parsing the template contents, macros in the form `%STRING` are expanded. The following macros are supported:

%time

- Expands to the current time in your locale format, as returned by `QTime::currentTime().toString()`.

%date

- Expands to the current date in long format, as returned by `QDate::currentDate().toString()`.

%datetime

- Expands to the current date and time, formatted as a string according to your locale by `QDateTime::currentDateTime().toString()`.

%year

- The current year as a four digit number.

%month

- The full name of the current month, according to your locale.

%{date(FORMATSTRING)}

- This will expand to a date/time string as defined by `FORMATSTRING`. FORMATSTRING is a text string, within which the following substitutions will be performed:

  ### Date formatting entities

  h | the hour without a leading zero (0..23 or 1..12 if AM/PM display)
  hh | the hour with a leading zero (00..23 or 01..12 if AM/PM display)
  m | the minute without a leading zero (0..59)
  mm | the minute with a leading zero (00..59)
  s | the second whithout a leading zero (0..59)
  ss | the second whith a leading zero (00..59)
  z | the milliseconds without leading zeroes (0..999)
  zzz | the milliseconds with leading zeroes (000..999)
  AP | use AM/PM display. AP will be replaced by either "AM" or "PM".
  ap | use am/pm display. ap will be replaced by either "am" or "pm".
  d | the day as number without a leading zero (1-31)
  dd | the day as number with a leading zero (01-31)
  ddd | the abbreviated localized day name (e.g. 'Mon'..'Sun').
  dddd | the long localized day name (e.g. 'Monday'..'Sunday').
  M | the month as number without a leading zero (1-12)
  MM | the month as number with a leading zero (01-12)
  MMM | the abbreviated localized month name (e.g. 'Jan'..'Dec').
  MMMM | the long localized month name (e.g. 'January'..'December').
  YY | The year as a two digit number (00-99).
  YYYY | The year as a four digit number (1752-8000).

  This allows you to control the displayed date very detailled, using common separators between the items, for example: `h:m:s ap`.

%realname

- Expands to Your full name, if it can be found. The parser will first try the KDE Email settings from the KDE control center, then the user account information. If a full name can not be found, your user name is filled in.

%username

- Expands to your username.

%email

- Expands to your email address, if it can be found. The parer will look for it in the KDE Email settings from the KDE control center, and if not found it will use `$USER@$HOST` instead.

%organisation

- This is your organisation, if present in the KDE Email settings from the KDE control center. If not found, an empty string is returned.

%VARIABLE

- Any other string will be interpreted as an environment variable, and expands to the value of that variable. If the If no variable by that name is set, it expands to "WARNING <VARIBALE> is not set".

### Setting the cursor position

The parser looks for a caret character (^) that is not preceeded by a backslash (\) to decide where to position the cursor. If found, it is removed and the cursor is positioned where is was. If more unescaped carets are found, all will be removed, and the position of the last one will be used.

If any escaped caret characters (preceeded by a backslash character) are found, the backslash will be removed.

## Thanks and Acknowledgments

&kate; Plugin File Templates copyright 2004 Anders Lund anders@alweb.dk.

Documentation copyright 2004 Anders Lund

&underGPL;