PageRenderTime 191ms CodeModel.GetById 67ms app.highlight 51ms RepoModel.GetById 1ms app.codeStats 0ms

/bundles/plugins-trunk/XInsert/xinsert.html

#
HTML | 505 lines | 321 code | 110 blank | 74 comment | 0 complexity | e84c4fd8f0b61932fddae22b576a1cd3 MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2
  3<html>
  4<head>
  5<meta name="generator" content="HTML Tidy, see www.w3.org">
  6
  7<title>XInsert Plugin</title>
  8
  9<style type="text/css">
 10<!--
 11.syntax0 {}
 12
 13.syntax1 {
 14	color: #990033;
 15	}
 16
 17.syntax2 {
 18	color: #990033;
 19	font-style: italic;
 20	}
 21
 22.syntax3 {
 23	color: #650099;
 24	}
 25
 26.syntax4 {
 27	color: #650099;
 28	font-weight: bold;
 29	}
 30
 31.syntax5 {
 32	color: #3366ff;
 33	font-weight: bold;
 34	}
 35
 36.syntax6 {
 37	color: #000000;
 38	font-weight: bold;
 39	}
 40
 41.syntax7 {
 42	color: #0033ff;
 43	}
 44
 45.syntax8 {
 46	color: #009600;
 47	}
 48
 49.syntax9 {
 50	color: #990033;
 51	}
 52
 53.syntax10 {
 54	color: #5e5e5e;
 55	font-weight: bold;
 56	}
 57
 58.syntax11 {
 59	color: #000000;
 60	font-weight: bold;
 61	}
 62
 63.syntax12 {
 64	color: #009191;
 65	}
 66
 67.syntax13 {
 68	color: #ff0000;
 69	font-weight: bold;
 70	}
 71
 72.gutter {
 73	background: #ffffff;
 74	color: #8080c0;
 75	width: 2em
 76	}
 77
 78.gutterH {
 79	background: #ffffff;
 80	color: #000000;
 81	}
 82
 83-->
 84
 85</style>
 86</head>
 87<body>
 88<table style="background:#ccccff" border="0" width="100%" cellspacing="0" cellpadding="0">
 89<tr width="100%">
 90	<td><h1>XInsert Plugin</h1></td>
 91	<td align="right">
 92	<font size="-1">By Dominic Stolerman and Romain Guy<br>
 93	<i>dstolerman@jedit.org and guy.romain@bigfoot.com</i></font>
 94	</td>
 95</tr>
 96</table>
 97
 98<hr>
 99<h2>Introduction</h2>
100
101<p>XInsert is a plugin that will insert a section of code/text
102from a library into the current buffer, using a graphical tree
103view. It also has the ability to run simple scripts in a native
104format as well as BeanShell scripts.</p>
105
106<p>XInsert started off as an adition to/part of the Jext text
107editor written by Romain Guy. It was then modified to form a
108plugin for jEdit by Romain as version 1.0.</p>
109
110<p>Since then it has evolved into a plugin that is has a much
111higher level of integration with jEdit through the work of
112Dominic Stolerman.</p>
113
114<p>Actions for easy navigation and inserting with the keyboard were
115added by Martin Raspe (hertzhaft@biblhertz.it). He added
116node references and re-styled the code. Martin is the current 
117maintainer of the plugin.</p>
118
119<h2>Inserting clips</h2>
120
121<p>XInsert clips can be added in two ways: Either double click on
122the desired item in the expanded branch, or select the desired
123item in the tree and hit Enter or Space while the XInsert pane is
124focused. For convenience two actions were added that can be bound to keystroke
125combinations using the Utilities/Global Options/Shortcuts menu (A+F12).</p>
126
127<ul>
128<li><b>Focus XInsert</b> - focuses the XInsert pane, allowing
129tree navigation by keyboard. Recommended shortcut:
130CS-Insert.</li>
131
132<li><b>Insert Selected Item</b> - Inserts the currently selected
133item from the XInsert tree. Multiple inserts of the
134same item are possible without having to re-enter the XInsert
135pane. This action works even if the XInsert pane is not visible
136or focused (it must be docked, though). Recommended shortcut: C-Insert 
137(if you don't use this key combination for pasting from the clipboard).</li>
138</ul>
139
140<p>This way you have to remember just one keyboard shortcut to insert an item
141or run a macro. Bring the XInsert pane into focus, then navigate
142to the desired clip using the arrow keys. Press Enter or Space to reset the 
143focus to the text area and insert the item. The selected item can be inserted
144over again using another keyboard shortcut.</p>
145
146<h2>XInsert Files</h2>
147
148<p>Some XInsert files are supplied with XInsert, these include
149Java, HTML, JavaScript and SSI inserts. These catagories appear
150in the tree view by default but can be turned off using the
151plugin options dialog box.Also all files with the name
152*.insert.xml are loaded from the directory specified in the
153plugin options. The default directory is .jedit/XInsert, although
154this can be changed from the plugin settings dialog.</p>
155
156<p><b>For settings set in the plugin options to take effect the
157reload button on the tree view must be pressed</b></p>
158
159<h2>Options</h2>
160
161<h3>From the Plugin Options--&gt;XInsert Dialog:</h3>
162
163<p><b>Display Default Inserts</b> - Enable/Disable displaying the
164inserts in the jar file. Pressing "None" will hide them all
165without losing your current settings.</p>
166
167<p><b>Inserts directory</b> - The directory that will be searched
168for additional insert files.</p>
169
170<p><b>Global Variables</b> - Variables that will be used
171throughout all of XInsert. I recomend you set these variables:
172author, email webaddress</p>
173
174<h3>On the XInsert Dialog</h3>
175
176<p><b>Carriage Return</b> - If selected will add a new line after
177all inserts.</p>
178
179<p><b>Execute Scripts</b> - If selected will cause all inserts
180with the <code>script</code> attribute to be executed. If it is
181not selected script source will be inserted.</p>
182
183<h2>XInsert File Format</h2>
184
185<pre><font color="#000000"><font color="#0099ff"><strong>&lt;?</strong></font><font color="#0099ff"><strong>xml</strong></font><font color="#0099ff"><strong> </strong></font><font color="#0099ff"><strong>version=</strong></font><font color="#0099ff"><strong> </strong></font><font color="#0099ff"><strong>&quot;1.0&quot;</strong></font><font color="#0099ff"><strong> </strong></font><font color="#0099ff"><strong>encoding=</strong></font><font color="#0099ff"><strong> </strong></font><font color="#0099ff"><strong>&quot;ISO-8859-1&quot;?</strong></font><font color="#0099ff"><strong>&gt;</strong></font>
186<font color="#009966"><strong>&lt;!</strong></font><font color="#009966"><strong>DOCTYPE</strong></font><font color="#009966"><strong> </strong></font><font color="#009966"><strong>xinsert</strong></font><font color="#009966"><strong> </strong></font><font color="#009966"><strong>SYSTEM</strong></font><font color="#009966"><strong> </strong></font><font color="#ff00cc">&quot;</font><font color="#ff00cc">jeditresource:/XInsert.jar!/xinsert.dtd</font><font color="#ff00cc">&quot;</font><font color="#009966"><strong>&gt;</strong></font>
187<font color="#0000ff">&lt;</font><font color="#0000ff">xinsert</font><font color="#0000ff">&gt;</font>
188  <font color="#0000ff">&lt;</font><font color="#0000ff">menu</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">[menu</font><font color="#ff00cc"> </font><font color="#ff00cc">name]</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>
189    <font color="#0000ff">&lt;</font><font color="#0000ff">variable</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">foo</font><font color="#ff00cc">&quot;</font><font color="#0000ff"> </font><font color="#0000ff">value</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">bar</font><font color="#ff00cc">&quot;</font><font color="#0000ff">/</font><font color="#0000ff">&gt;</font>
190    <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">[Item</font><font color="#ff00cc"> </font><font color="#ff00cc">name]</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>[contents]<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
191    <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">foo</font><font color="#ff00cc"> </font><font color="#ff00cc">value</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>$foo<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
192    <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">[script</font><font color="#ff00cc"> </font><font color="#ff00cc">name]</font><font color="#ff00cc">&quot;</font><font color="#0000ff"> </font><font color="#0000ff">type</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">xinsert_script</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>[contents]<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
193    <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">[macro</font><font color="#ff00cc"> </font><font color="#ff00cc">name]</font><font color="#ff00cc">&quot;</font><font color="#0000ff"> </font><font color="#0000ff">type</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">macro</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>[contents]<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
194    <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">[macro</font><font color="#ff00cc"> </font><font color="#ff00cc">file</font><font color="#ff00cc"> </font><font color="#ff00cc">name]</font><font color="#ff00cc">&quot;</font><font color="#0000ff"> </font><font color="#0000ff">type</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">named_macro</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>[file_name]<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
195    <font color="#0000ff">&lt;</font><font color="#0000ff">menu</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">sub</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>
196      <font color="#0000ff">&lt;</font><font color="#0000ff">variable</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">foo</font><font color="#ff00cc">&quot;</font><font color="#0000ff"> </font><font color="#0000ff">value</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">bar2</font><font color="#ff00cc">&quot;</font><font color="#0000ff">/</font><font color="#0000ff">&gt;</font>
197      <font color="#0000ff">&lt;</font><font color="#0000ff">item</font><font color="#0000ff"> </font><font color="#0000ff">name</font><font color="#0000ff">=</font><font color="#ff00cc">&quot;</font><font color="#ff00cc">foo</font><font color="#ff00cc"> </font><font color="#ff00cc">value</font><font color="#ff00cc">&quot;</font><font color="#0000ff">&gt;</font>$foo<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">item</font><font color="#0000ff">&gt;</font>
198    <font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">menu</font><font color="#0000ff">&gt;</font>
199  <font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">menu</font><font color="#0000ff">&gt;</font>
200<font color="#0000ff">&lt;</font><font color="#0000ff">/</font><font color="#0000ff">xinsert</font><font color="#0000ff">&gt;</font> 
201</font></pre>
202
203<p>XInsert files can have more than one <code>&lt;menu&gt;</code>
204tag per file, can have <code>&lt;item&gt;</code> tags in the
205<code>&lt;menu&gt;</code> tag. Unlimited nesting of
206<code>&lt;menu&gt;</code> tags is supported.</p>
207
208<p>Menu tags can also contain "variable" tags. When variables are
209substituted into the insert the closest variable tag in the tree
210hierachy is used.</p>
211
212<p>Item tags can have one of five types (specified with the type
213attribute):</p>
214
215<dl compact>
216<dt>text (default)</dt>
217
218<dd>The text is inserted normally, with variable replacement etc.</dd>
219
220<dt>macro</dt>
221
222<dd>The content is run as a BeanShell macro script.</dd>
223
224<dt>named_macro</dt>
225
226<dd>The content is the name of a file that is run as a BeanShell script.</dd>
227
228<dt>xinsert_script</dt>
229
230<dd>The content is treated as an <a href="#script">xinsert script</a>.</dd>
231
232<dt>action</dt>
233
234<dd>The content is treated as the name of a jEdit action.</dd>
235
236<dt>reference</dt>
237
238<dd>The content is a path to another entry in the XInsert tree. It is constructed by 
239concatenating the node names with slashes. The tree root is represented by "/". 
240Example: "/Java/Javadoc/author". In this way you can reference a single item from plusieurs
241places in the hierarchy. Chained or circular references are detected and do not work.
242</dd>
243</dl>
244
245<p>When a named_macro item is encountered, XInsert searches for
246the script file using the following protocol:</p>
247
248<blockquote>
249<p>1.&nbsp; If the file name has no extension, XInsert adds the
250conventional BeanShell extension ".bsh";</p>
251
252<p>2.&nbsp; If the full path name is not specified, XInsert
253treats the file name as a relative path specification and looks
254for the file in (a) the current working directory, (b) the
255"macros" subdirectory of the jEdit home directory and (c) the
256"macros" subdirectory of the jEdit user settings directory.</p>
257</blockquote>
258
259<p>If you make your own XInsert files, or if you copy the default
260data files contained in the .jar file to the "Inserts Directory"
261specified in the "Options" dialog, you can add the following
262macro item to allow for easy editing of an XInsert file within
263jEdit:</p>
264
265<pre>
266<span class="gutter">&nbsp;1:</span> <span class="syntax11">&lt;</span>item name="Open XInsert file" type="macro"&gt;
267
268<span class="gutter">&nbsp;2:</span> jEdit.openFile(view,
269
270<span class="gutter">&nbsp;3:</span>               jEdit.getProperty("xinsert.inserts-directory")
271
272<span class="gutter">&nbsp;4:</span>                  + File.separator
273
274<span class="gutter">&nbsp;5:</span>                  + "foo.insert.xml");
275
276<span class="gutter">&nbsp;6:</span> <span class="syntax11">&lt;/</span>item&gt;
277
278</pre>
279
280<p>After making any changes to the file, save it within jEdit and
281press the reload button on the XInsert tree view.&nbsp; The
282changes will be immediately available.</p>
283
284<p>As the XInsert files are xml the item contents and names must
285not contain &lt; or &amp; symbols, but the HTML codescan be used,
286<code>&amp;lt;,&amp;amp;</code>. Some special characters can be
287used in the <code>ITEM_CONTENTS</code></p>
288
289<dl>
290<dt>\n</dt>
291
292<dd>Inserts a new line.</dd>
293
294<dt>\t</dt>
295
296<dd>Inserts a tab (or spaces) of length set in the buffer
297options.</dd>
298
299<dt>|</dt>
300
301<dd>Positions the cursor at this point, or inserts any text
302selected at this point. If text is selected but there is no |
303character then the selected text is replaced.</dd>
304
305<dt>||</dt>
306
307<dd>Inserts a | character.</dd>
308
309<dt>\$</dt>
310
311<dd>Inserts a $ character.</dd>
312
313<dt>$foo</dt>
314
315<dd>Inserts the variable neamed foo.</dd>
316
317<dd>
318<p>There are also some special variables:</p>
319
320<dl compact>
321<dt>$path</dt>
322
323<dd>The path of the current buffer.</dd>
324
325<dt>$filename</dt>
326
327<dd>The filname of the current buffer.</dd>
328
329<dt>$date</dt>
330
331<dd>The current date.</dd>
332
333<dt>$time</dt>
334
335<dd>The current time.</dd>
336
337<dt>$datetime</dt>
338
339<dd>The current date and time.</dd>
340
341<dt>$selected</dt>
342
343<dd>The currently selected text in the buffer.</dd>
344</dl>
345</dd>
346</dl>
347
348<h2>XInsert Scripts</h2>
349
350<p>XInsert has a built-in scripting language designed to add
351certain functionality to text inserts such as showing dialog
352boxes for inputs. It is not designed as a complete scripting
353language.</p>
354
355<p>All text in an &lt;item&gt; of type "xinsert_script" will be inserted
356into the active buffer, except for embedded commands. Commands are just run,
357their results are not inserted into the buffer.</p>
358
359<p>Commands are surrounded by curly braces. The opening brace 
360must be followed immediately by a "$", "@", "%", or "!", otherwise the text
361is inserted literally. If you need to use a closing brace 
362inside a command, escape it with a backslash. 
363If all you want is to execute a command without inserting any 
364additional text, be sure to leave no space between the &lt;item&gt; tags 
365and the braces.</p>
366
367<p>Note that all the commands are run in the order that
368they appear in the script. This means you must set any variables 
369before you attempt to use them.</p>
370
371<p>For more help with XInsert scripts look at the scripts used in
372the built-in insert files in
373$jEditHome/jars/xinsert/net/sourceforge/jedit/xinsert</p>
374
375<h3>Insert Variable <code>{$.....}</code></h3>
376
377<blockquote>
378<p>This command inserts variables similar to just
379<code>$[variable name]</code> in a plain text insert.</p>
380
381<p>This command has three forms:<br>
382 <code>{$$[variable name]}</code> - the variable value is
383inserted if found. Otherwise $[variable name] is inserted.<br>
384 <code>{$=[variable name]}</code> - the variable value is
385inserted if found. Otherwise nothing is inserted.<br>
386 <code>{$?[variable name]}</code> - the variable value is
387inserted if found. Otherwise a dialog box is displayed, prompting the
388user to enter a value.</p>
389</blockquote>
390
391<h3>Set Variable <code>{%.....}</code></h3>
392
393<blockquote>
394<p>This is used to set a variable valid for the &lt;item&gt; it
395is in. The general syntax is {%[variable name] ..... }. There are
396two main variations:</p>
397
398<p><code>{%[name] %set [value]}</code> - sets the variable to the
399variable [name] to [value].</p>
400
401<p>The other variation shows a prompt box to the user:<br>
402 <code>{%[name] [list]}</code> - where [list] is a list of terms
403in double quotes. The order and number of terms is important.</p>
404
405<blockquote>
406<table width="95%" border="1" cellspacing="0" cellpadding="0">
407<tr>
408<td width="19%"><b>No Of Terms</b></td>
409<td width="81%"><b>Effect</b></td>
410</tr>
411
412<tr>
413<td width="19%">none</td>
414<td width="81%">Dialog box with default message shown</td>
415</tr>
416
417<tr>
418<td width="19%">one</td>
419<td width="81%">The term is used as a message to show the user
420(e.g "Enter email address:"). The first term is always used for
421this purpose if present.</td>
422</tr>
423
424<tr>
425<td width="19%">two</td>
426<td width="81%">The second term is used as a default value in the
427dialog box<br>
428 (e.g. "Enter email address:" "dds26@cam.ac.uk")</td>
429</tr>
430
431<tr>
432<td width="19%">more than two</td>
433<td width="81%">
434<p>A dialog box with a choice of values is shown.<br>
435 (e.g. "Enter email address:" "dds26@cam.ac.uk"
436"another@email.com" "another email")<br>
437 If after the last term there is a "?" then the user will be
438allowed to enter thier own value as well.<br>
439 (e.g. "Enter email address:" "dds26@cam.ac.uk"
440"another@email.com" "another email" ?)</p>
441</td>
442</tr>
443</table>
444</blockquote>
445</blockquote>
446
447<h3>Run BeanShell Macro Command
448<code>{@.....}</code></h1>
449
450<blockquote>
451<p>This runs the content of the braces as a BeanShell macro command.
452<code>{@ jEdit.getAction("plugin-manager").invoke(view) }</code>
453Multiple commands can be put into a single pair of braces, separated
454by semicolons, or chained, e.g.: 
455<code>{@ buffer.setMode("xml") }{@ textArea.setCaretPosition(0) }</code></p>
456
457<p>Note that as the commands are run in order you can use a macro
458command that will modify text inserted before it but not after
459it.</p>
460</blockquote>
461
462<h3>Run Java Method Command
463<code>{!.....}</code></h3>
464
465<blockquote>
466<p>This will run any <b>public static</b> java function in a
467class that is in the classpath when jEdit is run. If the function
468returns a string it will be inserted into the buffer. This
469command allows the scripts to become as complicated as you may
470wish, by writing the action you wish the script to perform in
471Java, using all the features of Java, then calling it from
472XInsert.</p>
473
474<p>e.g:<br>
475 <code>{!com.mypackage.MyClass.MyMethod()}</code> will invoke the
476method <i>MyMethod()</i> in class
477<i>com.mypackage.MyClass</i>.<br>
478 <code>{!com.mypackage.MyClass.MyMethod([some text})}</code> will
479invoke the method <i>MyMethod(String arg)</i> in class
480<i>com.mypackage.MyClass</i> where the argument is [some
481text].</p>
482</blockquote>
483
484<h2>Feedback</h2>
485
486<ul>
487<li>For bug reports use the Sourceforge Bug Tracker -
488<a href="http://www.sourceforge.net/bugs/?group_id=588">http://www.sourceforge.net/bugs/?group_id=588</a>,
489</li>
490
491<li>or email the current maintainer Martin Raspe
492(hertzhaft@biblhertz.it),
493</li>
494
495<li>or jEdit-users mailing-list
496&lt;jedit-users@lists.sourceforge.net&gt;,
497</li>
498
499<li>or jEdit-devel mailing.list
500&lt;jedit-devel@lists.sourceforge.net&gt;.
501</li>
502</ul>
503</body>
504</html>
505