XInsert Plugin By Dominic Stolerman and Romain Guy
dstolerman@jedit.org and guy.romain@bigfoot.com

Change Log

Introduction

XInsert is a plugin that will insert a section of code/text from a library into the current buffer, using a graphical tree view. It also has the ability to run simple scripts in a native format as well as BeanShell scripts.

XInsert started off as an adition to/part of the Jext text editor written by Romain Guy. It was then modified to form a plugin for jEdit by Romain as version 1.0. Since then it has evolved into a plugin that is has a much higher level of integration with jEdit. It is currently maintained by Dominic Stolerman.

XInsert Files

Some XInsert files are supplied with XInsert, these include Java, HTML, JavaScript and SSI inserts. These catagories appear in the tree view by default but can be turned off using the plugin options dialog box.Also all files with the name *.insert.xml are loaded from the directory specified in the plugin options. The default directory is .jedit/XInsert, although this can be changed from the plugin settings dialog.

For settings set in the plugin options to take effect the reload button on the tree view must be pressed

Options

From the Plugin Options-->XInsert Dialog:

Display Default Inserts - Enable/Disable displaying the inserts in the jar file. Pressing "None" will hide them all without losing your current settings.
Inserts directory - The directory that will be searched for additional insert files.
Global Variables - Variables that will be used throughout all of XInsert. I recomend you set these variables: author, email webaddress

On the XInsert Dialog

Carriage Return - If selected will add a new line after all inserts.
Execute Scripts - If selected will cause all inserts with the script attribute to be executed. If it is not selected script source will be inserted.

XInsert File Format

 1:<?xml version="1.0" encoding="ISO-8859-1"?>
 2:<!DOCTYPE xinsert SYSTEM "xinsert.dtd">
 3:<xinsert>
 4:  <menu name="[menu name]">
 5:    <variable name="foo" value="bar">
 6:    <item name="[Item name]">[contents]</item>
 7:    <item name="foo value">$foo</item>
 8:    <item name="[script name]" type="xinsert_script">[contents]</item>
 9:    <item name="[macro name]" type="macro">[contents]</item>
10:    <item name="[macro file name]" type="named_macro">[file_name]</item>
11:    <menu name="sub">
12:      <variable name="foo" value="bar2">
13:      <item name="foo value">$foo</item>
14:    </menu>
15:  </menu>
16:</xinsert>
XInsert files can have more than one <menu> tag per file, can have <item> tags in the <menu> tag. Unlimited nesting of <menu> tags is supported. Menu tags can also contain "variable" tags. When variables are substituted into the insert the closest variable tag in the tree hierachy is used. Item tags can be four types (specified with the type attribute):
text (default)
The text is inserted normally, with variable replacement etc.
macro
The contents is run as a BeanShell macro script.
named_macro
The contents is the name of a file that is run as a BeanShell script.  
xinsert_script
The contents is treated as an xinsert script.

When a named_macro item is encountered, XInsert searches for the script file using the following protocol:

1.  If the file name has no extension, XInsert adds the conventional BeanShell extension ".bsh";

2.  If the full path name is not specified, XInsert treats the file name as a relative path specification and looks for the file in (a) the current working directory, (b) the "macros" subdirectory of the jEdit home directory and (c) the "macros" subdirectory of the jEdit user settings directory.

If you make your own XInsert files, or if you copy the default data files contained in the .jar file to the "Inserts Directory" specified in the "Options" dialog, you can add the following macro item to allow for easy editing of an XInsert file within jEdit:

 1:<item name="Open XInsert file" type="macro">
 2:jEdit.openFile(view,
 3:               jEdit.getProperty("xinsert.inserts-directory")
 4:                  + File.separator
 5:                  + "foo.insert.xml");
 6:</item>

After making any changes to the file, save it within jEdit and press the reload button on the XInsert tree view.  The changes will be immediately available.

As the XInsert files are xml the item contents and names must not contain < or > symbols, but the HTML codescan be used, &lt;,&gt;. Some special characters can be used in the ITEM_CONTENTS

\n
Inserts a new line.
\t
Inserts a tab (or spaces) of length set in the buffer options.
|
Positions the cursor at this point, or inserts any text selected at this point. If text is selected but there is no | character then the selected text is replaced.
||
Inserts a | character.
\$
Inserts a $ character.
$foo
Inserts the variable neamed foo. There are also some special variables:
$path
The path of the current buffer.
$filename
The filname of the current buffer.
$date
The date.
$time
The time.
$datetime
The date and time.
$selected
The currently selected text in the buffer.

XInsert Scripts

XInsert has a built in scripting language designed to add certain functionality to text inserts such as showing dialog boxes for inputs. It is not designed as a complete scripting language.

The text in a script is inserted into a buffer except for certain commands. The commands are always surrounded by curly braces. Note that all the commands are run ion the order that they appear in the script so you must set any variables before you atempt to use them.

For more help with writing scripts look at the scripts used in the built-in insert files in $jEditHome/jars/xinsert/net/sourceforge/jedit/xinsert

Insert Variable {$.....}

This command inserts variables similar to just $[variable name] in a plain text insert.

This command has three forms:
{$$[variable name]} - the variable value is inserted if found else $[variable name] is inserted.
{$=[variable name]} - the variable value is inserted if found else nothing is inserted.
{$?[variable name]} - the variable value is inserted if found else a dialog box is displayed to prompt the user for a value.

Set Variable {%.....}

This is used to set a variable valid for the <item> it is in. The general syntax is {%[variable name] ..... }. There are two main variations:

{%[name] %set [value]} - sets the variable to the variable [name] to [value].

The other variation shows a prompt box to the user:
{%[name] [list]} - where [list] is a list of terms in double quotes. The order and number of terms is important.

No Of Terms Effect
none Dialog box with default message shown
one The term is used as a message to show the user (e.g "Enter email address:"). The first term is always used for this purpose if present.
two The second term is used as a default value in the dialog box
(e.g. "Enter email address:" "dds26@cam.ac.uk")
more than two

A dialog box with a choice of values is shown.
(e.g. "Enter email address:" "dds26@cam.ac.uk" "another@email.com" "another email")
If after the last term there is a "?" then the user will be allowed to enter thier own value as well.
(e.g. "Enter email address:" "dds26@cam.ac.uk" "another@email.com" "another email" ?)

Run Macro Command {@.....}

This runs the contents of the braces as a macro command. Only one command can be put in each set of braces.
e.g {@indent-on-enter}{@insert-char@something to insert}

Note that as the commands are run in order you can use a macro command that will modify text inserted before it but not after it.

Run Java Method Command {!.....}

This will run any public static java function in a class that is in the classpath when jEdit is run. If the function returns a string it will be inserted into the buffer. This command allows the scripts to become as complicated as you may wish, by writing the action you wish the script to perform in Java, using all the features of Java, then calling it from XInsert.

e.g:
{!com.mypackage.MyClass.MyMethod()} will invoke the method MyMethod() in class com.mypackage.MyClass.
{!com.mypackage.MyClass.MyMethod([some text})} will invoke the method MyMethod(String arg) in class com.mypackage.MyClass where the argument is [some text].

Feedback