&Anders.Lund; &Anders.Lund.mail;

# Working with Plugins

Kate is using two different forms of plugins, namely plugins for the &kate; application and plugins for the &kate; editor component. The latter are available to any application using the editor component, such as KDevelop, Quanta, Kile, Kwrite and many others, while application plugins are specific to the &kate; application.

You can enable both types of plugins in the configuration dialog, which also provides access to additional configuration options for plugins that requires that.

There are many plugins for various purposes available and you can search the web for more. A few plugins are shipped with the editor component, for inserting automatic braces, insert files, data tools and exporting text as &HTML;.

## Editor Component Plugins

The Plugins tab on the Extensions page lists all available plugins and you can check those you want to use. Click on the Information button to open the About dialog of this plugin.

Once a configurable plugin is checked, the Configure button is enabled and you can click it in order to configure the highlighted plugin.

AutoBrace

  The autobrace plugin supersedes the &kate; internal Auto Brackets feature. It automatically inserts a closing brace } at the beginning of the next line after ending a line with an opening one { and pressing the &Enter; key.

Data Tools

  Enables data tools like thesaurus and spell check (if installed). Data tools are only available when text is selected, or when the right mouse button is clicked over a word. If no data tools are offered even when text is selected, you need to install them. Some data tools are part of the &koffice; package. If this plugin is enabled and data tools are installed, additional items appear at the end of the context menu.

Exporter

  This command allows you to export the current document with all highlighting information into a HTML document using File Export as HTML. Additionally you can use Edit Copy as HTML to copy the currently selected text as HTML to the system clipboard.

IconInserter

  The icon inserter plugin is only of use for &kde; developers: It adds an item Insert KIcon-Code into the context menu of the editor. If activated, the &kde;'s icon chooser opens (showing application icons, action icons &etc;..). If you click on it, the file name without file extension will be inserted as text. Useful only for setting icons via &kde;'s framework through the KIcon() class.

Insane (not ZEN) HTML coding (light edition)

  A plugin, which does zen-coding like selector completion. For more information see Zen Coding.

Insert File

  This plugin allows you to insert any readable file at the cursor position. If enabled, the Tools menu has an additional menu item Insert File.

## &kate; Application Plugins

&kate; plugins are additional functions for the &kate; editor. They can add extra menus and shortcuts, and extend &kate;'s features. You can install as many or as few as you like, from within &kate;. Open &kate;'s configuration dialog with Settings Configure &kate;... Select Application Plugins to choose the wanted plugins.

The available application plugins are:

- Find in files tool view - Toolview allowing to search in all open files or files in the filesystem

- Backtrace Browser - Backtrace navigation tool view

- Quick Document switcher - Quickly switch to another already opened document

- Tab Bar - Adds a tab bar to &kate;'s main window

- Text Filter - Easy text filtering

- Symbol Viewer - Extract and show reference symbols from source

- File system browser - File system browser tool view

- Terminal tool view - Toolview embedding a terminal widget

- CTags Plugin - Look up definitions/declarations with CTags

- File Templates - Create new files from templates

- Open Header - Opens the corresponding .h/[.cpp|.c] file

- External Tools

- Build Plugin - Compile or Make and parse error messages

- Mail files - Send files via email

- Kate Snippets - Snippets plugin with code completion support

- KTextEditor Jovie Plugin - Adds a menu entry for speaking the text

- &XML; Validation- Validates &XML; files using xmllint

- &XML;Completetion - Lists &XML; elements, attributes, attribute values and entities allowed by DTD

- Tabify - Adds a tab bar to Kate's main window

&Anders.Lund; &Anders.Lund.mail;

## File Templates

The File Templates plugin allows you to create files based on other files.

When you first install Kate, you need to enable the plugin:

1. Click Settings Configure Kate

2. In the tree on the left of the screen, click Plugins.

3. In the Plugin Manager panel on the right, select File Templates, and then click OK.

You can now use any file as a template (this creates a copy of the file with an empty &URL;.) Special template files can contain macros to fill in information such as your name, email address, the current date, and position the cursor at a convenient position in the new file.

You can easily create a new template from an open document.

Templates that you save to the template folder are listed under the menu item File New from Template.

The template folder is part of the &kde; file system, and consists of at least

- `$`KDEDIR`/share/applications/kate/plugins/katefiletemplates/templates`

- `$`KDEHOME`/share/applications/kate/plugins/katefiletemplates/templates.`

If your `KDEDIRS` environment 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) folder 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

  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.

### Using a &kate; Template

When creating a file from a template that contain template macros, some macros appears as editable variables in the text. Such variables appears as underlined words in the text.

The first variable will be selected, so you just have to type to edit it. If the document text contains more instances of the same variable, they are changed as you edit. To move to the next editable variable, press the TAB key. When the last variable is edited, the list is dropped, and your TAB key works as normal.

### 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 launch 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 and macros, 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 starting with `katetemplate:` will be taken as the start of the template contents. VALUE may contain any character but equal sign (=). Legal variable names are:

`Template`

  This is the template name, displayed in the File New from Template menu.

`Group`

  The group places the template in a submenu of the File New 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 plug-in 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 Highlighting .

`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 `%{NAME}` or `${NAME}` are expanded. If you use the `$` prefix, the expanded macro will be treated as a editable variable when a document is created from the template, whereas if you use `%` it is not, unless expanding failed.

The following macros are expanded:

time

  Expands to the current time in your locale format.

date

  Expands to the current date in short format.

datetime

  Expands to the current date and time, formatted as a string according to your locale.

year

  The current year as a four digit number.

month

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

day

  Expands to the current day of the month.

hostname

  Expands to the 'hostname' of your computer.

index

  Expands to 'i'.

fullname

  Expands to your full name, as defined by the owner addressee in your standard &kde; addressbook.

firstname

  Expands to your first name, as defined in the owner addressee in your standard &kde; addressbook.

lastname

  Expands to your last name, as defined in the owner addressee in your standard &kde; addressbook.

email

  Expands to your email address, as defined by the owner address in your standard &kde; addressbook.

Any macro not in the above list is treated as a editable variable no matter the prefix. If the same variable occurs multiple times in the template, they can be edited at once after creating a document from the template.

#### Setting the cursor position

The special macro `${cursor}` will be replaced with a vertical bar and added to the end of the list of editable variables, independent on its location in the text.

### Thanks and Acknowledgments

&kate; Plugin File Templates copyright 2004 &Anders.Lund; &Anders.Lund.mail;.

Documentation copyright 2004 &Anders.Lund;

Daniel
Naber

    &Daniel.Naber.mail;

## &XML; Validation

This plugin checks &XML; files for well-formedness and validity.

This plugin checks the current file. A list of warnings and errors will appears at the bottom of &kate;'s main window. You can click on an error message to jump to the corresponding place in the file. If the file has a DOCTYPE the DTD given with this doctype will be used to check the file for validity. The DTD is expected at a position relative to the current file, &eg; if the doctype refers to DTD/xhtml1-transitional.dtd and the file is `/home/peter/test.xml` the DTD is expected to be located at `/home/peter/DTD/xhtml1-transitional.dtd`. However, remote DTDs specified via http are supported.

If the file has no doctype it will be checked for well-formedness.

To learn more about &XML; check out the official W3C &XML; pages.

Internally this plugin calls the external command `xmllint`, which is part of libxml2. If this command is not correctly installed on your system, the plugin will not work.

A temporary file needs to be written to the same folder as the file that should be checked, so you need to have write access to that folder.

To load this plugin open &kate;s configuration dialog under Settings Configure &kate;.... Then select XML Validation which will appear in the Application / Plugins section and close the dialog.

### Menu Structure

XML Validate XML

  This will start the check, as described above.

### Thanks and Acknowledgments

&kate; Plugin XML Validation copyright 2002 &Daniel.Naber; &Daniel.Naber.mail;.

Documentation copyright 2002 &Daniel.Naber;

Daniel
Naber

    &Daniel.Naber.mail;

## &XML; Completion

This plugin gives hints about what is allowed at a certain position in an &XML; file, according to the file's DTD. It will list possible elements, attributes, attribute values or entities, depending on the cursor position (&eg; all entities are listed if the character on the left of the cursor is &). It's also possible to close the nearest open tag on the left.

The DTD must exist in &XML; format, as produced by the Perl program `dtdparse`. We will call a DTD in this format meta DTD. Some meta DTDs are supplied. They are installed in `$KDEDIR/share/apps/katexmltools/`, which is also the default folder when you choose Assign Meta DTD.... To produce your own meta DTDs, get `dtdparse` from http://dtdparse.sourceforge.net.

### How to Use

Start &kate; and open the configuration dialog under Settings Configure &kate;.... Then select XML Completion which will appear in the Application/Plugins section and close the dialog. After that, select XML Assign Meta DTD.... If your document contains no DOCTYPE or the doctype is unknown, you'll have to select a meta DTD from the file system. Otherwise the meta DTD that matches the current document's DOCTYPE will be loaded automatically.

You can now use the plugin while typing your text:

< (less than key)

  This will trigger a list of possible elements unless the cursor is inside a tag already. Note that you currently cannot use this to insert the top level element (&eg; <html>).

</(less than key + slash)

  Entering these characters will offer closing the current element (nearest open one to the left of the cursor). Press &Enter; to accept the suggestion. Unlike the Close Element menu item, this works only with a DTD assigned.

" (quote key)

  The quote key will trigger a list of possible attribute values (if there are some) if you are inside a tag.

(space key)

  This key will trigger a list of possible attributes for the current element if you are inside a tag.

& (ampersand key)

  This key will trigger a list of named entities.

### Features and Limitations

You can test all functions and limitations by loading `$KDEDIR/share/apps/katexmltools/testcases.xml` into &kate; and following the instructions.

### Menu Structure

&Ctrl;Return XML Insert Element...

  This will open a dialog that lets you insert an &XML; element. The <, > characters and the closing tag will be inserted automatically. If you have selected text when this menu item is selected, the selected text will be surrounded by the opening and the closing tag. The dialog also offers completion of all elements that may be inserted at the current cursor position if you have assigned a meta DTD by using Assign Meta DTD....

&Ctrl;< XML Close Element

  This will search your text for a tag that is not yet closed and will close it by inserting the corresponding closing tag. The search starts at the cursor position and goes left. If it cannot find an open tag nothing will happen.

XML Assign Meta DTD...

  This will tell the plugin which meta DTD to use for the current document. Note that this assignment will not be saved. You will have to repeat it when you start &kate; the next time.

### Thanks and Acknowledgments

&kate; Plugin &XML; Completion copyright 2001,2002 &Daniel.Naber; &Daniel.Naber.mail;.

KDE SC 4 version copyright 2010 Tomáš Trnka

Documentation copyright 2001,2002 &Daniel.Naber;