Snippets plugin: Difference between revisions

From Bluefish Wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(4 intermediate revisions by one other user not shown)
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. The first time you open Bluefish 2 you have no snippets. You have to create them, or import a set of snippets.
;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 no snippets. You have to create them, 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''.


{{tip|text=SVN Rev 5862: add a default snippets file.}}
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 =
|valign="bottom" align="center"|[[File:Man2 import snippets.png|none|frame|import item in snippets menu]]
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 snippets2.png|none|frame|import a xml snippets file]]
|}


{|
== Creating an Insert String ==
|valign="bottom" align="center"|[[File:Man2 import snippets3.png|none|frame|mediawiki(en) snippets are imported]]
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.
|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}}
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.
=== Snippets usage ===
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]]


== 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.


By double-clicking a snippet item the code is inserted at the cursor position in the edit area.<br />
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.
We place the cursor in edit area under the line <tt><nowiki>=== Snippets usage ===</nowiki></tt> to insert a <tt>framed image</tt><br />
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:
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:
[[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}}
# Entire document
# Forward from cursor position
# Selection
# All open files


==== Replace snippets ====
And there are two otions for the match pattern:
Some snippets make replace in a selected text. Select text before use them!


=== Export snippets ===
# Normal
# PERL


*you can export:
Furthermore, you can check wether the search and replace pattern should be case sensitive and wether to use escape chars.
** a branch
** 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 ==
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.


=== Branch ===
= Editing snippets =
All snippets should be placed in a branch. If your snippets file is empty, the first thing to create is the first branch.
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.
=== 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]]
|}


[[File:Man2 create snippet4.png|right|frame|Before text and variables]]
= Reorder snippets =
Here we use to variables, one for the name of the image, the other for the text under the image.
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.


{{tip|text=If <tt>Is File path</tt> is used, a Browse button is added to the dialog}}
== Import snippets ==
[[File:Man2 snippet file path.png|none|frame|<tt>Is File path</tt> Browse button can give relative path.]]
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.  
 
<br style="clear:both"/>
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.
 
 
 
[[File:Man2_snippet_after_before.png|right|frame|Before text and After text]]
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.
 
 
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 ===
== Export snippets ==
[[File:Man2 snippet accelerator key.png|left|frame|snippet accelerator key]]
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.  
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.
== Snippets repository ==
<br style="clear:both"/>
In the Bluefish wiki a [[:Category:Snippets repository]] of predefined snippets is provided.


== 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 18:01, 23 April 2015


 

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[edit]

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

Using snippets[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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

Import snippets[edit]

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[edit]

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[edit]

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

Set snippet accelerator[edit]

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[edit]

see Snippets syntax


Top.png