Snippets plugin: Difference between revisions

From Bluefish Wiki
Jump to navigation Jump to search
No edit summary
 
(19 intermediate revisions by one other user not shown)
Line 2: Line 2:
|lang=en
|lang=en
|rev=2.0.0
|rev=2.0.0
|st=d
|st=u
|Title=7. Snippets plugin
|Title=7. Snippets plugin
|prev=Man 2 ch07s06
|prev=Man 2 ch07s06
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''.
{|
 
|valign="bottom" align="center"|[[File:Man2 import snippets.png|none|frame|import item in snippets 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 snippets2.png|none|frame|import a xml snippets file]]
 
|}
= 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 <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.
 
== 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:
 
# Entire document
# Forward from cursor position
# Selection
# All open files
 
And there are two otions for the match pattern:


{|
# Normal
|valign="bottom" align="center"|[[File:Man2 import snippets3.png|none|frame|mediawiki(en) snippets are imported]]
# PERL
|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}}
Furthermore, you can check wether the search and replace pattern should be case sensitive and wether to use escape chars.
=== 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]]
By double-clicking a snippet the code is inserted at the cursor position in the edit area.


Snippet can use parameters, double-clicking opens a dialog box.
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.
[[File:Man2_snippet_insert_dialog.png|none|frame|snippet insert dialog]]
Here is the result:
[[File:Man2_snippet_insert_result.png|none|frame|snippet insert result]]
{{top}}
==== Replace snippets ====
Some snippets make replace in a selected text. Select text before use them!


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


*you can export:
= Reorder snippets =
** a branch
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.)
** 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 ==
= Import and export snippets =
Bluefish snippets can easily exported and imported, so that they can be provided on different machines.


=== Branch ===
== Import 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 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.  
=== Insert strings ===
To insert a snippet, choose a branch, right click on its name to open the snippets menu.
{|
|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]]
|}


{|
== Export snippets ==
|valign="bottom" align="center"|[[File:Man2 create snippet4.png|left|frame|Before text and variables]]
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.  
|valign="bottom" align="center"|[[File:Man2_snippet_after_before.png|left|frame|Before text and After text<br />The ''before'' text is inserted before the cursor or the selection. The ''after'' text is inserted after the selection]]
|}


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.
== Snippets repository ==
In the Bluefish wiki a [[:Category:Snippets repository]] of predefined snippets is provided.


=== Search and replace patterns ===
= 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.
|valign="bottom" align="center"|[[File:Man2_create_replace_snippet.png|none|frame|lorem ipsum]]
|valign="bottom" align="center"|[[File:Man2_create_replace_snippet2.png|none|frame|lorem ipsum]]<br />
[[File:Man2_create_replace_snippet3.png|none|frame|lorem ipsum]]
|}
{{top}}
== Edit snippets ==


== Reorder snippets ==
== Snippets syntax ==
[[File:Man2 move snippet.png|left|frame|lorem ipsum]]
see [[Snippets syntax]]
lorem ipsum
{{clear}}


== Set snippet accelerator ==


== Delete branch/snippet==


== Show as menu ==
{{top}}
{{top}}
{{Man2bottom
{{Man2bottom

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