XInsert Plugin |
By Dominic Stolerman and Romain Guy dstolerman@jedit.org and guy.romain@bigfoot.com |
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 through the work of Dominic Stolerman.
Actions for easy navigation and inserting with the keyboard were added by Martin Raspe (hertzhaft@biblhertz.it). He added node references and re-styled the code. Martin is the current maintainer of the plugin.
XInsert clips can be added in two ways: Either double click on the desired item in the expanded branch, or select the desired item in the tree and hit Enter or Space while the XInsert pane is focused. For convenience two actions were added that can be bound to keystroke combinations using the Utilities/Global Options/Shortcuts menu (A+F12).
This way you have to remember just one keyboard shortcut to insert an item or run a macro. Bring the XInsert pane into focus, then navigate to the desired clip using the arrow keys. Press Enter or Space to reset the focus to the text area and insert the item. The selected item can be inserted over again using another keyboard shortcut.
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
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
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.
<?xml version= "1.0" encoding= "ISO-8859-1"?> <!DOCTYPE xinsert SYSTEM "jeditresource:/XInsert.jar!/xinsert.dtd"> <xinsert> <menu name="[menu name]"> <variable name="foo" value="bar"/> <item name="[Item name]">[contents]</item> <item name="foo value">$foo</item> <item name="[script name]" type="xinsert_script">[contents]</item> <item name="[macro name]" type="macro">[contents]</item> <item name="[macro file name]" type="named_macro">[file_name]</item> <menu name="sub"> <variable name="foo" value="bar2"/> <item name="foo value">$foo</item> </menu> </menu> </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 have one of five types (specified with the type attribute):
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,
<,&
. Some special characters can be
used in the ITEM_CONTENTS
There are also some special variables:
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.
All text in an <item> of type "xinsert_script" will be inserted into the active buffer, except for embedded commands. Commands are just run, their results are not inserted into the buffer.
Commands are surrounded by curly braces. The opening brace must be followed immediately by a "$", "@", "%", or "!", otherwise the text is inserted literally. If you need to use a closing brace inside a command, escape it with a backslash. If all you want is to execute a command without inserting any additional text, be sure to leave no space between the <item> tags and the braces.
Note that all the commands are run in the order that they appear in the script. This means you must set any variables before you attempt to use them.
For more help with XInsert scripts look at the scripts used in the built-in insert files in $jEditHome/jars/xinsert/net/sourceforge/jedit/xinsert
{$.....}
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. Otherwise $[variable name] is inserted.
{$=[variable name]}
- the variable value is inserted if found. Otherwise nothing is inserted.
{$?[variable name]}
- the variable value is inserted if found. Otherwise a dialog box is displayed, prompting the user to enter a value.
{%.....}
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" ?)
{@.....}
This runs the content of the braces as a BeanShell macro command.
{@ jEdit.getAction("plugin-manager").invoke(view) }
Multiple commands can be put into a single pair of braces, separated by semicolons, or chained, e.g.:{@ buffer.setMode("xml") }{@ textArea.setCaretPosition(0) }
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.
{!.....}
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].