Difference between revisions of "Snippets plugin"

From Bluefish Wiki
Jump to: navigation, search
m
 
Line 10: Line 10:
  
 
{{toc}}
 
{{toc}}
The snippets plugin allows you to record reusable pieces of code. There are two categories of snippets:
+
The snippets plugin enables you to reuse often used code fragments through a few clicks. Snippets are of two kinds, '''insert string''' and '''search and replace pattern'''. In addition to that, snippets can be organized '''branches'''.
* insert strings
 
* search and replace patterns
 
Snippets are organized in branches.
 
;Bluefish 1.3 users:
 
: you can copy your old snippets to Bluefish 2<br /><tt>'''$''' cp ~/.bluefish-unstable/snippets  ~/.bluefish/</tt>
 
;Bluefish 1.0 users:
 
: to import your Bluefish 1 Custom menu in snippets you can use Olivier's python script [[convert_custom_menu_to_snippets.py]].
 
:*put convert_custom_menu_to_snippets.py in ~/.bluefish/ directory
 
:*make the script executable: <tt>'''$''' chmod a+x convert_custom_menu_to_snippets.py</tt>
 
:*run the script: <tt>'''$''' ./convert_custom_menu_to_snippets.py > mysnippets.xml</tt>
 
:* import mysnippets.xml in your snippets plugin.
 
; You also can find useful snippets in [[:Category:Snippets repository|Snippets repository ]]
 
{{clear}}
 
  
 +
= Enabling the snippets plugin =
 +
The snippets plugin is activated by default in Bluefish. Otherwise it can be enabled through ''Edit > Preferences > Plugins''.
  
== Import snippets ==
+
= Using snippets =
The first time you open Bluefish 2 you have default snippets. You can create new snippets, or import a set of snippets. Right click in the snippets area open the snippets menu.
+
Snippets can be accessed in two ways. Either through the top bar above the editing area or through the snippets browser in the side panel. If the snippets are not seen at the top bar, right-click in the snippet browser and check ''Show as menu''.
  
{|
+
For using insert strings, put the cursor where you need the code fragment, click on the specific snippet or group of snippets you need at the top bar or at the side bar. Depending on the specific snippet, you may should input requested data.
|valign="bottom" align="center"|[[File:Man2 import snippets.png|none|frame|import item in snippets menu]]
 
|valign="bottom" align="center"|[[File:Man2 import snippets2.png|none|frame|import a xml snippets file]]
 
|}
 
  
{|
+
= Creating new snippets =
|valign="bottom" align="center"|[[File:Man2 import snippets3.png|none|frame|mediawiki(en) snippets are imported]]
+
New snippets can be created in the snippets browser at the side panel. Snippets must be within branches. Therefore you may must create a branch at first. Right click in the snippets browser and select ''New Snippet''. Outside a branch you are forced to create a new branch. Only the name of the branch is required. A right-click on the branch enables to create an ''Insert string'' or a ''Replace pattern''.
|valign="bottom" align="center"|[[File:Man2 import snippets4.png|none|frame|click on the arrow of the branch title to expand it.]]
 
|valign="bottom"|{{note|text=see [[#Snippets usage|Snippets usage]] to learn how to use snippets.}}<br />{{tip|text=You can find snippets to import in the [[:Category:Snippets repository]]}}
 
|}
 
  
{{top}}
+
== Creating an Insert String ==
=== Snippets usage ===
+
Right-click on the branch, where you want to create a new snippet and select ''New snippet'' in the context menu. A dialog will open, select ''Insert string'' at first and click forward. In the next dialog, you have to name your snippet. Optionally, you can give a description of your snippet. It will be shown, when you hover over snippet. Otherwise, the insert string itself will appear.
There are two kinds of snippets, insert snippets and replace snippets.
 
==== Insert snippets ====
 
Snippets are organized in branches (chapters) and possibly sub-branches. In mediawiki branch there is a sub-branche called ''man bf'' where are usefull snippets to edit Bluefish manual. The title of the snippet gives an idea of what it does. By moving the mouse over the title of the snippet appears a tooltip giving details.
 
[[File:Man2_snippet_tooltip.png|none|frame|snippet tooltip]]
 
  
 +
Next, you have to fill in the ''Insert string'' itself. Two text-boxes are provided for the string. The first one is for the string before the cursor, the second after the cursor. In addition to that, you can define parameters with the text-fields right-hand. These will be requested using that snippet. In the snippet itself they are numbered like '%1'. Please use %% if you need literal % in your string! eg: use <tt>style="width:20%%"</tt> to have '''''style="width:20%"''''' Furthermore, you can check if it is a file path. This will provide a file choose dialog.
  
By double-clicking a snippet item the code is inserted at the cursor position in the edit area.<br />
+
== Creating a Search and Replace pattern ==
We place the cursor in edit area under the line <tt><nowiki>=== Snippets usage ===</nowiki></tt> to insert a <tt>framed image</tt><br />
+
Right-click on the branch, where you want to create a new snippet and select ''New snippet'' in the context menu. A dialog will open, select ''Search and Replace pattern'' at first and click forward. In the next dialog, you have to name your snippet. Optionally, you can give a description of your snippet. It will be shown, when you hover over snippet. Otherwise nothing appears.
This snippet use 2 parameters, double-clicking opens a dialog box.
 
[[File:Man2_snippet_insert_dialog.png|none|frame|snippet insert dialog]]
 
  
Here is the result:
+
Next, you have to define the search and replace pattern. The '''search string '''and the '''replace string''' have to be given. As in insert strings, you can define parameters requested when using that snippets. Likewise in insert strings, they are named like '%1' in the search or replace strings. Names for the dialog can be assigned to them.
[[File:Man2_snippet_insert_result.png|none|frame|snippet insert result]]
 
The ''before'' text is inserted before the cursor in edit area, the cursor is now after the text inserted by the snippet.
 
  
{{top}}
+
In addition to that, the scope and the match pattern of the search and replace pattern can be assigned. There are four options for the scope:
  
==== Replace snippets ====
+
# Entire document
Some snippets make replace in a selected text. Select text before use them!
+
# Forward from cursor position
 +
# Selection
 +
# All open files
  
=== Export snippets ===
+
And there are two otions for the match pattern:
  
*you can export:
+
# Normal
** a branch
+
# PERL
** a single snippet
 
*to export your entire snippets file just copy ~/.bluefish/snippets to mysnippets.xml
 
*to export a selection of branches, you have to create a new branch, move wanted branches into it and export the new branch.
 
{{top}}
 
  
== Create snippets ==
+
Furthermore, you can check wether the search and replace pattern should be case sensitive and wether to use escape chars.
  
=== Branch ===
+
Search and replace snippets are very powerful. See [[Man 2 ch05s10|Basic Find and Replace]] and [[Man 2 ch06s05#5.3. Find and Replace Using Regular Expressions|Find and Replace Using Regular Expressions]] for general infos about Bluefish find and replace.
All snippets should be placed in a branch. If your snippets file is empty, the first thing to create is the first branch.
 
=== Insert strings ===
 
To insert a snippet, choose a branch, right click on its name to open the snippets menu.
 
In this example we add a snippet in <tt>mediawiki(en)</tt> branch:
 
{|
 
|valign="bottom" align="center"|[[File:Man2 create snippet.png|none|frame|New snippet]]
 
|valign="bottom" align="center"|[[File:Man2 create snippet2.png|none|frame|Insert string]]
 
|valign="bottom" align="center"|[[File:Man2 create snippet3.png|none|frame|Name of the snippet and description for the tooltip]]
 
|}
 
==== variables ====
 
[[File:Man2 create snippet4.png|none|frame|Before text and variables]]
 
Here we use two variables, one for the name of the image, the other for the text under the image.
 
  
Please use %% if you need literal % in your string! eg: use <tt>style="width:20%%"<tt> to have '''''style="width:20%"'''''
+
= Editing snippets =
 +
To edit an existing snippet, right click on the snippet in the snippet browser and select ''edit snippet. ''Then, you have the same process as in creating a new snippet.
  
==== Is File path ====
+
= Reorder snippets =
{{tip|text=If <tt>Is File path</tt> is used, a Browse button is added to the dialog}}
+
Use drag and drop to reorder snippets. You can reorder single snippet or branches. To create a new top level branch you have to right-click on the empty part at the end of the snippets pannel. (actually bug: if you have too many snippets for the height of the window, there is no empty line at the end of the snippets list.)
[[File:Man2 snippet file path.png|none|frame|<tt>Is File path</tt> Browse button can give relative path.]]
 
  
<br style="clear:both"/>
+
= Import and export snippets =
The new snippet take place at the end of its branch. You can move it using drag and drop. You can also re-edit it or delete it.
+
Bluefish snippets can easily exported and imported, so that they can be provided on different machines.
  
 +
== Import snippets ==
 +
To import snippets, right-click on the snippet in the snippet browser or, more usefully, a branch of snippets and select ''import''. Navigate through the dialog to the snippet file to be imported.
  
 +
== Export snippets ==
 +
To export snippets, right-click on the snippet in the snippet browser or, more usefully, a branch of snippets and select ''export''. Use the save dialog to navigate to your specific place for saving it and to name that file.
  
[[File:Man2_snippet_after_before.png|right|frame|Before text and After text]]
+
== Snippets repository ==
In this other example we use a snippet that use both ''before'' and ''after'' text.<br />first we select text in edit area, then we double click on the <tt>includeonly</tt> snippet.
+
In the Bluefish wiki a [[:Category:Snippets repository]] of predefined snippets is provided.
 
 
 
 
The ''before'' text is inserted before the cursor or the selection. The ''after'' text is inserted after the cursor or the selection.
 
<br style="clear:both"/>
 
 
 
=== Search and replace snippets ===
 
Search and replace snippets are very powerfull. See [[Man 2 ch05s10|Basic Find and Replace]] and [[Man 2 ch06s05#5.3. Find and Replace Using Regular Expressions|Find and Replace Using Regular Expressions]] for general infos about Bluefish find and replace. Here will be considered only on the specific substitutions in the snippets.
 
{|
 
|valign="bottom" align="center"|[[File:Man2_create_replace_snippet.png|none|frame|Search and replace snippets can use regex and variables]]
 
|valign="bottom" align="center"|[[File:Man2_create_replace_snippet2.png|none|frame|Scope:]]<br />
 
[[File:Man2_create_replace_snippet3.png|none|frame|Match Pattern:]]
 
|}
 
 
 
<small>todo: example using both snippets variables and regex variables.</small>
 
{{top}}
 
 
 
== Edit snippets ==
 
Right click on an item open the snippets menu, <tt>Edit snippet</tt>. If the item is a branch use also <tt>Edit snippet</tt> to change its name.
 
 
If the item is a snippet we can re-edit it,  firt name and description, and in second step ''before'' and ''after'' text and parameter(s) name(s).
 
 
 
== Reorder snippets ==
 
[[File:Man2 move snippet.png|left|frame|Reorder snippets]]
 
Use drag and drop to reorder snippets. You can reorder single snippet or branches. To create a new top level branch you have to right-click on the empty part at the end of the snippets pannel. (actually bug: if you have too many snippets for the height of the window, there is no empty line at the end of the snippets list.)
 
{{clear}}
 
 
 
== Navigation between snippets ==
 
When a mouse is over the snippet pannel typing a letter select the first entry (from the top) witch name begin with this letter.<br />
 
e.g. if you have to entries, bbcode and bash, typing '''b''' select bbcode, typing '''ba''' select bash. This works only with item that are visibles not for items that are in collapsed branches.
 
 
 
=== Set snippet accelerator ===
 
[[File:Man2 snippet accelerator key.png|left|frame|snippet accelerator key]]
 
Select a snippet item, right click to open the menu, choose <tt>Set snippet accelerator</tt>.
 
 
 
For example if you type '''Ctrl''' + '''f''' for framed image, you can now open the frame image snippet dialog by typing '''Ctrl''' + '''f''' when mouse is over the snippet pannel, even if the mediawiki branch is collapsed.
 
<br style="clear:both"/>
 
  
== Delete branch/snippet==
+
= Set snippet accelerator =
You can delete a snippet and also a branch with all its sub-branches and snippets in one click. Be aware that there is no undo method.
+
With the Set snippet accelerator keyboard shortcuts can be assigned to a specific snippet. Right-click on the snippet to which a shortcut should be assigned and select ''Set snippet accelerator''. A dialog will ask you for the key combination. ''Crtl'', ''shift'' or ''alt'' can be used. With ''esc'' the Set snippet accelerator can be be canceled, deleted or removed.
== Show as menu ==
 
You can have snippets as a [[Man_2_ch04s02#Custom_Tool_Bar|top bar]]. Be aware that if you have to many top level entries in snippets for the width of your window, the last top level entries are not displayed in snippets top bar.
 
[[File:Man2_custom_toolbar.png|none|frame|Bluefish Custom Tool Bar]]
 
  
 
== Snippets syntax ==
 
== Snippets syntax ==

Latest revision as of 19:01, 23 April 2015

this page is updated for Manual 2. It needs to be verified! once you have verified this page (and corrected if necessary) please modify the status to v (verified), i.e. st=v (see Guidelines for Writing this Manual)

Man2 icon 48.png
Chapter VII. More than a Text Editor
Prev 
7. Snippets plugin
 Next
 

The snippets plugin enables you to reuse often used code fragments through a few clicks. Snippets are of two kinds, insert string and search and replace pattern. In addition to that, snippets can be organized branches.

Enabling the snippets plugin

The snippets plugin is activated by default in Bluefish. Otherwise it can be enabled through Edit > Preferences > Plugins.

Using snippets

Snippets can be accessed in two ways. Either through the top bar above the editing area or through the snippets browser in the side panel. If the snippets are not seen at the top bar, right-click in the snippet browser and check Show as menu.

For using insert strings, put the cursor where you need the code fragment, click on the specific snippet or group of snippets you need at the top bar or at the side bar. Depending on the specific snippet, you may should input requested data.

Creating new snippets

New snippets can be created in the snippets browser at the side panel. Snippets must be within branches. Therefore you may must create a branch at first. Right click in the snippets browser and select New Snippet. Outside a branch you are forced to create a new branch. Only the name of the branch is required. A right-click on the branch enables to create an Insert string or a Replace pattern.

Creating an Insert String

Right-click on the branch, where you want to create a new snippet and select New snippet in the context menu. A dialog will open, select Insert string at first and click forward. In the next dialog, you have to name your snippet. Optionally, you can give a description of your snippet. It will be shown, when you hover over snippet. Otherwise, the insert string itself will appear.

Next, you have to fill in the Insert string itself. Two text-boxes are provided for the string. The first one is for the string before the cursor, the second after the cursor. In addition to that, you can define parameters with the text-fields right-hand. These will be requested using that snippet. In the snippet itself they are numbered like '%1'. Please use %% if you need literal % in your string! eg: use style="width:20%%" to have style="width:20%" Furthermore, you can check if it is a file path. This will provide a file choose dialog.

Creating a Search and Replace pattern

Right-click on the branch, where you want to create a new snippet and select New snippet in the context menu. A dialog will open, select Search and Replace pattern at first and click forward. In the next dialog, you have to name your snippet. Optionally, you can give a description of your snippet. It will be shown, when you hover over snippet. Otherwise nothing appears.

Next, you have to define the search and replace pattern. The search string and the replace string have to be given. As in insert strings, you can define parameters requested when using that snippets. Likewise in insert strings, they are named like '%1' in the search or replace strings. Names for the dialog can be assigned to them.

In addition to that, the scope and the match pattern of the search and replace pattern can be assigned. There are four options for the scope:

  1. Entire document
  2. Forward from cursor position
  3. Selection
  4. All open files

And there are two otions for the match pattern:

  1. Normal
  2. PERL

Furthermore, you can check wether the search and replace pattern should be case sensitive and wether to use escape chars.

Search and replace snippets are very powerful. See Basic Find and Replace and Find and Replace Using Regular Expressions for general infos about Bluefish find and replace.

Editing snippets

To edit an existing snippet, right click on the snippet in the snippet browser and select edit snippet. Then, you have the same process as in creating a new snippet.

Reorder snippets

Use drag and drop to reorder snippets. You can reorder single snippet or branches. To create a new top level branch you have to right-click on the empty part at the end of the snippets pannel. (actually bug: if you have too many snippets for the height of the window, there is no empty line at the end of the snippets list.)

Import and export snippets

Bluefish snippets can easily exported and imported, so that they can be provided on different machines.

Import snippets

To import snippets, right-click on the snippet in the snippet browser or, more usefully, a branch of snippets and select import. Navigate through the dialog to the snippet file to be imported.

Export snippets

To export snippets, right-click on the snippet in the snippet browser or, more usefully, a branch of snippets and select export. Use the save dialog to navigate to your specific place for saving it and to name that file.

Snippets repository

In the Bluefish wiki a Category:Snippets repository of predefined snippets is provided.

Set snippet accelerator

With the Set snippet accelerator keyboard shortcuts can be assigned to a specific snippet. Right-click on the snippet to which a shortcut should be assigned and select Set snippet accelerator. A dialog will ask you for the key combination. Crtl, shift or alt can be used. With esc the Set snippet accelerator can be be canceled, deleted or removed.

Snippets syntax

see Snippets syntax


Top.png

Prev 
Up
 Next
6. Customizing the Quick bar
Home | ToC
 8. External programs, filters